Reference

Database

Where the schema lives, how migrations are generated, and when they are applied.

apps/web owns the database, and its schema is assembled from three places. packages/layer-payments/server/db/schema/ declares the payments tables, packages/layer-base/server/db/schema/ supplies the shared column mixins they are built from, and @nuxtjs/better-auth generates its own tables into .nuxt/better-auth/ while Nuxt prepares the application. NuxtHub bundles all of them into the one schema drizzle-kit reads.

Commands

Run these from apps/web.

CommandDoes
pnpm db:generatewrites a new migration from the current schema
pnpm db:checkchecks the migration lineage for collisions and out-of-order timestamps
pnpm db:migrate:productionapplies committed migrations to the database
pnpm db:seedinserts the Runtime Context's seed rows, if it has a seed

Migrations are written to apps/web/server/db/migrations/postgresql/. Commit them.

When migrations are applied

The deploy workflow applies them for apps/web only, after the build and before the Worker is uploaded — so a Worker never serves against a schema that is behind it. A push migrates its Runtime Context's database. A pull request migrates only its own Preview Database.

pnpm db:migrate:production refuses to do anything unless RUN_DB_MIGRATIONS is true, and it needs DATABASE_URL to be the direct, non-pooled connection string. Hyperdrive pools connections inside the Worker runtime and does not exist outside it.

A Preview Database starts empty, so a pull request's first run applies its whole lineage, and each later push applies only what it added. A pull request's schema change shows in its own preview, and no other pull request sees it. Nothing to migrate by hand remains for preview. Pull request previews says where the database comes from and when it goes.

Seed data

Right after migrating, the deploy runs pnpm db:seed on the same database. apps/web/scripts/seedDB.ts reads the seed for APP_RUNTIME_CONTEXT from apps/web/scripts/seeds/<context>.ts, and a context with no file seeds nothing. Only preview has one, so every Preview Database holds one verified Platform Admin:

ColumnValue
EmailSEED_PLATFORM_ADMIN_EMAIL in preview's secret store
PasswordSEED_PLATFORM_ADMIN_PASSWORD in preview's secret store
CustomerOne Polar Customer every Preview Database's Platform Admin shares

The seed links the user to that Customer through the user's fixed id. The first pull request creates the Customer, and every later one reuses it.

Every deploy runs the seed again. Each seeded row has a fixed id and goes in with ON CONFLICT DO NOTHING, so a rerun inserts nothing. A seeded row you edit keeps your edit, and one you delete comes back on the next push.

Add rows or tables to a seed

A seed file's default export is an async function that returns one object. Each key is a table's export name in the schema, such as user or account, and its value is that table's rows. The function's Promise<Seed> return type checks every row against the schema, so the type check fails when a row names a column the table lacks or misses a required one.

  1. Open apps/web/scripts/seeds/<context>.ts.
  2. Add the table's key and its rows to the object the function returns. List a parent table before the tables that reference it, because rows are inserted in key order.
  3. Give each row a fixed id, so the next deploy conflicts on it instead of inserting a duplicate.
  4. Run pnpm typecheck from apps/web.

Seed another Runtime Context

  1. Create apps/web/scripts/seeds/<context>.ts, shaped like preview.ts.
  2. Add one line for the context to the seeds map in apps/web/scripts/seedDB.ts, such as staging: () => import('./seeds/staging.ts'),.
Never seed a known password into a context that holds real users. Everyone who knows the password can sign in as that account. The seed reruns on every deploy, so deleting the account lasts only until the next one.

One lineage, generated once

Generate a migration once on development, commit it, and apply it. staging, if you have it, and production apply those same committed migrations and never generate their own. Two branches generating against the same schema produce two histories that each describe a database the other never had.

Your copy has no migrations

NuxtStart ships you the schema, not its own migration history. You generate your first migration from that schema and own the lineage from there. See Migration publication for why, and for what it does to your git log.

Copyright © 2026