---
title: "Database"
description: "Where the schema lives, how migrations are generated, and when they are applied."
canonical_url: "https://nuxtstart.com/docs/reference/database"
---

> Index of every page on this site: [llms.txt](https://nuxtstart.com/llms.txt)

`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`.

<table>
<thead>
  <tr>
    <th>
      Command
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        pnpm db:generate
      </code>
    </td>
    
    <td>
      writes a new migration from the current schema
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pnpm db:check
      </code>
    </td>
    
    <td>
      checks the migration lineage for collisions and out-of-order timestamps
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pnpm db:migrate:production
      </code>
    </td>
    
    <td>
      applies committed migrations to the database
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pnpm db:seed
      </code>
    </td>
    
    <td>
      inserts the Runtime Context's seed rows, if it has a seed
    </td>
  </tr>
</tbody>
</table>

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](https://nuxtstart.com/docs/deployment/pipeline#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:

<table>
<thead>
  <tr>
    <th>
      Column
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Email
    </td>
    
    <td>
      <code>
        SEED_PLATFORM_ADMIN_EMAIL
      </code>
      
       in preview's secret store
    </td>
  </tr>
  
  <tr>
    <td>
      Password
    </td>
    
    <td>
      <code>
        SEED_PLATFORM_ADMIN_PASSWORD
      </code>
      
       in preview's secret store
    </td>
  </tr>
  
  <tr>
    <td>
      Customer
    </td>
    
    <td>
      One Polar Customer every Preview Database's Platform Admin shares
    </td>
  </tr>
</tbody>
</table>

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'),`.

<warning>

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.

</warning>

## 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](https://nuxtstart.com/docs/reference/migration-publication) for why, and for what it does to your
`git log`.

## Sitemap

See the full [sitemap](https://nuxtstart.com/sitemap.md) for all pages.
