Database
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.
| Command | Does |
|---|---|
pnpm db:generate | writes a new migration from the current schema |
pnpm db:check | checks the migration lineage for collisions and out-of-order timestamps |
pnpm db:migrate:production | applies committed migrations to the database |
pnpm db:seed | inserts 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:
| Column | Value |
|---|---|
SEED_PLATFORM_ADMIN_EMAIL in preview's secret store | |
| Password | SEED_PLATFORM_ADMIN_PASSWORD in preview's secret store |
| Customer | One 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.
- Open
apps/web/scripts/seeds/<context>.ts. - 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.
- Give each row a fixed
id, so the next deploy conflicts on it instead of inserting a duplicate. - Run
pnpm typecheckfromapps/web.
Seed another Runtime Context
- Create
apps/web/scripts/seeds/<context>.ts, shaped likepreview.ts. - Add one line for the context to the
seedsmap inapps/web/scripts/seedDB.ts, such asstaging: () => import('./seeds/staging.ts'),.
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.
