Skip to main content
0 reactions

npx auth migrate vs generate: Which Better Auth Command to Use

A Terminal window showing npx auth@latest generate asking whether to generate the schema to a file in the better-auth_migrations folder, the answer yes, and the message Schema was generated successfully.
npx auth@latest generate writes the schema to a file.

Better Auth’s command-line tool has two commands for its database tables: migrate and generate. Both read your Better Auth settings and work out which tables and columns are missing. migrate creates them in your database straight away; generate writes them to a file that you, or your ORM, apply.

The short answer: with Better Auth’s built-in database support, such as a pg Pool for PostgreSQL, run npx auth@latest migrate. With Prisma or Drizzle, run npx auth@latest generate and apply the schema with that ORM’s own migration tool.

Syntax

Bash
npx auth@latest migrate [options]
npx auth@latest generate [options]

Both commands take:

  • --config <path>: the Better Auth settings file. By default the tool looks for auth.ts in the project folder, in lib or utils, or in those folders under src.
  • -y or --yes: answer yes to the confirmation, for scripts.
  • -c or --cwd <folder>: the project folder, if it isn’t the current one.

generate also takes:

  • --output <file>: where to write the schema.
  • --adapter <name>: the schema format, prisma, drizzle or kysely, when your settings don’t already say.
  • --dialect <name>: the database, such as postgresql, mysql or sqlite.

The reference: CLI (opens in a new tab) in the Better Auth documentation, and the tool’s own help, npx auth@latest generate --help and npx auth@latest migrate --help.

Prerequisites

  • a project with Better Auth set up, such as the one from Part 2 of the Better Auth Tutorial, which uses PostgreSQL through a pg Pool
  • its database running, with none of Better Auth’s tables created yet

Step 1: Generate the Schema

In your project folder, run:

Bash
npx auth@latest generate

It asks where it will write the schema. Type y and press Return:

Plain text
npm notice run bookshop@0.1.0 npx
npm notice run 'auth' generate
✔ Do you want to generate the schema to ./better-auth_migrations/2026-11-18T06-04-44.246Z.sql? … yes
🚀 Schema was generated successfully!
A Terminal window showing npx auth@latest generate asking whether to generate the schema to a file in the better-auth_migrations folder, the answer yes, and the message Schema was generated successfully.
npx auth@latest generate writes the schema to a file.

With the built-in database support, the schema is plain SQL. Here’s the file it wrote, better-auth_migrations/2026-11-18T06-04-44.246Z.sql. The name is the date and time, so yours differs:

SQL
create table "user" ("id" text not null primary key, "name" text not null, "email" text not null unique, "emailVerified" boolean not null, "image" text, "createdAt" timestamptz default CURRENT_TIMESTAMP not null, "updatedAt" timestamptz default CURRENT_TIMESTAMP not null);

create table "session" ("id" text not null primary key, "expiresAt" timestamptz not null, "token" text not null unique, "createdAt" timestamptz default CURRENT_TIMESTAMP not null, "updatedAt" timestamptz not null, "ipAddress" text, "userAgent" text, "userId" text not null references "user" ("id") on delete cascade);

create table "account" ("id" text not null primary key, "accountId" text not null, "providerId" text not null, "userId" text not null references "user" ("id") on delete cascade, "accessToken" text, "refreshToken" text, "idToken" text, "accessTokenExpiresAt" timestamptz, "refreshTokenExpiresAt" timestamptz, "scope" text, "password" text, "createdAt" timestamptz default CURRENT_TIMESTAMP not null, "updatedAt" timestamptz not null);

create table "verification" ("id" text not null primary key, "identifier" text not null, "value" text not null, "expiresAt" timestamptz not null, "createdAt" timestamptz default CURRENT_TIMESTAMP not null, "updatedAt" timestamptz default CURRENT_TIMESTAMP not null);

create index "session_userId_idx" on "session" ("userId");

create index "account_userId_idx" on "account" ("userId");

create index "verification_identifier_idx" on "verification" ("identifier");

Nothing in the database changed yet: generate only writes the file. You could apply it with any PostgreSQL tool, or keep it with your project to review what changed. To pick the file name yourself, add --output.

Step 2: Apply the Tables with migrate

migrate compares your settings with the database and creates what’s missing. Run:

Bash
npx auth@latest migrate

It lists the fields it will add and asks you to confirm. Type y and press Return:

Plain text
npm notice run bookshop@0.1.0 npx
npm notice run 'auth' migrate
🔑 The migration will affect the following:
-> name, email, emailVerified, image, createdAt, updatedAt fields on user table.
-> expiresAt, token, createdAt, updatedAt, ipAddress, userAgent, userId fields on session table.
-> accountId, providerId, userId, accessToken, refreshToken, idToken, accessTokenExpiresAt, refreshTokenExpiresAt, scope, password, createdAt, updatedAt fields on account table.
-> identifier, value, expiresAt, createdAt, updatedAt fields on verification table.
✔ Are you sure you want to run these migrations? … yes
🚀 migration was completed successfully!

The four tables now exist. Running migrate again, with nothing new in your settings, prints No migrations needed.

migrate vs generate

migrategenerate
What it doesCreates the missing tables and columns in your databaseWrites the missing schema to a file
Changes the databaseYes, after you confirmNo
Works withBetter Auth’s built-in database support (Kysely), for example a pg PoolThe built-in support (an SQL file), Prisma (a Prisma schema) and Drizzle (a Drizzle schema)
Use it whenYou want Better Auth to set up its own tablesYou use an ORM, or you want to review or apply the SQL yourself

Run one of them again whenever you change lib/auth.ts in a way that needs new tables or columns, such as adding a plugin.

Common Mistakes

MistakeWhat happensDo this instead
Running migrate with Prisma or Drizzlemigrate only works with Better Auth’s built-in database supportRun generate, then your ORM’s migration command
Expecting generate to change the databaseThe tables don’t appearApply the file, or run migrate
Forgetting to migrate after adding a pluginThe plugin’s tables are missingRun migrate or generate again

Troubleshooting

ProblemCauseFix
migrate prints ECONNREFUSEDThe database isn’t runningStart it, for example with docker compose up -d
A MODULE_TYPELESS_PACKAGE_JSON warning comes firstpackage.json has no "type" fieldAdd "type": "module" (the fix)

FAQ

Can I run migrate in a script or CI?

Yes. Add --yes, so it doesn’t wait for the confirmation.

Where does generate put the file?

In this project it wrote the SQL into a better-auth_migrations folder, named with the date and time. Use --output to choose another place.

Does migrate delete anything?

In this run it only added tables and fields, and it listed every one before asking.

Conclusion

migrate applies Better Auth’s tables for you, and generate writes them down for you or your ORM to apply. With the built-in PostgreSQL support from Part 2, migrate is the one-step choice.

Additional Resources

Better Auth, Next.js and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by Better Auth, Inc. or Vercel.

0 comments