Kysely Migration Generation#

The Kysely migration generator is the engine behind better-auth migrate and the generate CLI command when targeting a Kysely adapter. Its entry point is getMigrations in packages/better-auth/src/db/get-migration.ts. The CLI-facing generateKyselySchema wrapper in packages/cli/src/generators/kysely.ts simply calls getMigrations(options) and then compileMigrations() to emit raw SQL into a timestamped .sql file.

How It Works#

1. Schema discovery. getMigrations calls getSchema(config) to obtain the full BetterAuthDBSchema derived from all active plugins 1.

2. Table diffing. The function introspects the live database via db.introspection.getTables() and compares it against the schema, splitting tables into two buckets 2:

   • toBeCreated — tables not yet present in the database
   • toBeAdded — existing tables that are missing columns

3. CREATE TABLE generation. For each toBeCreated entry, the generator calls Kysely's schema.createTable(). Every field is added with addColumn, attaching NOT NULL, foreign-key references, and — if field.unique is set — an inline .unique() constraint on the column 3.

4. ALTER TABLE generation. For each toBeAdded entry, the generator uses schema.alterTable().addColumn() with the same column-level constraints 4.

5. Deferred indexes. Both code paths collect CREATE INDEX / CREATE UNIQUE INDEX builders in a deferredIndexes array and append them after all CREATE TABLE / ALTER TABLE statements. This ensures referenced tables and columns exist before any index is created 5 6.

6. SQL compilation. compileMigrations() calls .compile().sql on every builder and joins them with ;\n\n 7.

Type Mapping#

getType maps DBFieldAttribute.type to a database-specific Kysely ColumnDataType. Key rules:

• MySQL string fields widen to varchar(255) when unique, sortable, or index is set (otherwise text) 8.
• date fields map to timestamptz (postgres), timestamp(3) (mysql), date (sqlite), or datetime2(3) (mssql) 9.
• id and foreignKeyId fields honour the advanced.database.generateId option to emit uuid, integer GENERATED BY DEFAULT AS IDENTITY, or varchar(36) 10.

The Redundant Uniqueness Bug#

A field with both unique: true and index: true triggers two independent code paths that don't coordinate:

1. Column-level UNIQUE constraint — the if (field.unique) guard at line 526 (CREATE TABLE path) and line 461 (ALTER TABLE path) unconditionally appends .unique() to the column builder.

2. Table-level unique index — the if (field.index) guard at lines 543–551 (CREATE TABLE) and lines 438–447 (ALTER TABLE) pushes a CREATE UNIQUE INDEX … ON table (column) into deferredIndexes whenever field.unique is also true.

The result is that the compiled SQL contains both a UNIQUE column constraint and a separate CREATE UNIQUE INDEX for the same column — effectively two uniqueness enforcement mechanisms for one field. A concrete real-world trigger is the organization.slug field from the organization plugin, which carries { unique: true, index: true } in the built-in schema 11.

The analogous issue was confirmed and fixed for the Drizzle schema generator in PR #10333; the fix suppresses the column-level .unique() call when a table-level uniqueIndex will already be emitted. As of writing, the Kysely get-migration.ts file has not received the same guard.

Key Files#