Customizing Schema

Convex Auth comes with a default users table and a built-in authSessions table.

Often you might not need to customize the schema of these tables. To store information related to users or sessions you can simply store the user ID or session ID as a field in one of your other tables.

Customizing the users table

You can define a custom schema for the users table. This is helpful when your sign up form includes additional fields, or when you want to store additional user information from an OAuth provider.

To define a custom schema, inline the the table definition from the library into your schema:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";
import { authTables } from "@convex-dev/auth/server";
 
const schema = defineSchema({
  ...authTables,
  users: defineTable({
    name: v.optional(v.string()),
    image: v.optional(v.string()),
    email: v.optional(v.string()),
    emailVerificationTime: v.optional(v.number()),
    phone: v.optional(v.string()),
    phoneVerificationTime: v.optional(v.number()),
    isAnonymous: v.optional(v.boolean()),
    // other "users" fields...
  }).index("email", ["email"]),
  // Your other tables...
});
 
export default schema;

You can add more optional fields and indexes to the table.

You can only change fields to be required or add new required fields to the users table if all your authentication methods will provide those fields during sign-up (see how to do this for OAuth and Passwords).

You can remove fields and take complete control over the user creation and updates by implementing the createOrUpdateUser callback, see controlling account linking behavior.

Customizing the authSessions table

We don't recommend customizing the schema of this table. Use the session ID in fields of your other tables.

See also Session document lifecycle.