Skip to content

selfauth db ​

Wraps your project's native migration tool (Prisma Migrate for PostgreSQL, MySQL and SQLite, the index script for MongoDB, the Go runner for Gin) and adds a safety review on top. SelfAuth never migrates when the server starts.

text
selfauth db <command> [--dir <dir>]

--dir is the project directory and defaults to the current folder. The commands read DATABASE_URL from the environment or from the project's .env (server/.env in a full-stack project).

Commands ​

CommandWhat it does
statusShows applied and pending migrations
planReviews pending migrations for statements that lose data and for changes to SelfAuth's own tables. Changes nothing
migrate [--approve-destructive]Applies pending migrations. Refuses anything plan flags unless you pass the flag
validateChecks the schema against the ownership manifest
rollbackExplains how to roll back. There are no automatic down migrations
generate <name>Creates a migration from changes to your schema, without applying it (Prisma projects)

Examples with real output ​

bash
npx selfauth db plan
text
Pending migrations (1):
  • 20261116085533_selfauth_init  (prisma/migrations/20261116085533_selfauth_init/migration.sql)
  ✓ Nothing here loses data or touches SelfAuth's tables.
bash
npx selfauth db migrate
text
Pending migrations (1):
  • 20261116085533_selfauth_init  (prisma/migrations/20261116085533_selfauth_init/migration.sql)
  ✓ Nothing here loses data or touches SelfAuth's tables.
  ✓ Migrations applied.
bash
npx selfauth db status
text
  ✓ Database is up to date.
bash
npx selfauth db validate
text
  ✓ Schema and ownership manifest are valid.
bash
npx selfauth db rollback
text
  • Prisma Migrate has no automatic down migrations. Restore from a backup taken before migrating, or write a new forward migration that reverts the change. To recover a failed migration, fix the database and run `prisma migrate resolve --rolled-back <name>`.

By database ​

Projectstatusplanmigrategenerate
PostgreSQL, MySQL, SQLite (Prisma)prisma migrate statusAnalyses the SQLprisma migrate deployCreates prisma/migrations/<time>_<name>/migration.sql
MongoDBRuns the index script in plan modeLists the indexes it would createCreates missing indexes, never drops onenot applicable (validate, rollback and generate just explain this)
Gin (Go), PostgreSQL, MySQL, SQLiteRuns go run ./cmd/migrate statusAnalyses the SQL in db/migrations/, the same wayReviews, then runs go run ./cmd/migrate upnot applicable: write the SQL by hand
Gin (Go), MongoDBLists the indexes migrate would createThe sameRuns go run ./cmd/migrate up, which creates missing indexesnot applicable
In-memory––––

An in-memory project just says: ✗ database commands need a database: this project uses 'memory'.

The safety review ​

db plan and db migrate read the SQL of every pending migration. migrate refuses to run when the plan has findings, unless you add --approve-destructive. What counts as a finding depends on what the statement does and whose migration it is.

Your own migrations (the ones you create with db generate) can do what they like to your own tables, as long as they don't lose data. Creating a table, adding a column or adding an index goes straight through, with nothing to approve. You're stopped for:

FindingExampleWhat it says
Dropping a table, column, type or schemaDROP TABLE, DROP COLUMNDeletes data
Removing rowsTRUNCATE, DELETEDeletes data
Changing a column in a risky waychanging a column type, SET NOT NULL, renamingExisting data may not fit, or code that uses the old name breaks
Dropping a constraint or an indexDROP CONSTRAINT, DROP INDEXRemoves a rule or slows queries down
selfauth_tableany statement on a table listed in selfauth.manifest.json under ownedResources (the auth_… tables)Changes a table SelfAuth owns, which can break selfauth upgrade
Creating an object that already exists in the databasea baseline problemNothing is applied

The data-loss findings apply to every table, yours or SelfAuth's.

SelfAuth's own migrations (listed under ownedResources.migrations in the manifest, such as the ones an upgrade adds) are held to the opposite rule: they may only change SelfAuth's tables. A SelfAuth migration that touches any other table is reported as not_owned. That's the guarantee behind "SelfAuth never touches your tables": a release can't quietly alter notes, or orders, or anything else of yours.

Each finding is printed with a sentence saying what it means. For example:

text
Changes that need explicit approval:
  ⚠ [destructive] selfauth_table auth_users — 20261119095926_user_nickname:2
      changes a table SelfAuth owns (auth_…); that can break `selfauth upgrade`

Rules ​

  • Read the SQL before you apply it, and back up before migrating production.
  • Run migrations as a deploy step, not when the app starts.
  • There are no down migrations. Restore a backup or write a new forward migration.
  • A database that wasn't created with Prisma fails with P3005. Baseline it with prisma migrate resolve --applied <migration>, and only for migrations whose objects really exist.

Troubleshooting ​

Troubleshooting covers DATABASE_URL is not set, special characters in passwords, and pooled databases such as Supabase.

SelfAuth is MIT licensed. Generated code is also offered under 0BSD.