Stacks Database Migrations
Schema change management via migration files.
Key Paths
- Migration files:
database/migrations/ (96+ files)
- Database config:
config/database.ts
- Model snapshot:
storage/framework/database/model-snapshot.<dialect>.json
CLI Commands
buddy migrate # run pending migrations
buddy migrate --diff # show SQL without running
buddy migrate --auth # include auth tables
buddy migrate:fresh # drop ALL tables and re-migrate
buddy migrate:fresh --seed # drop, migrate, then seed
buddy migrate:dns # DNS-specific migration
buddy make:migration <name> # create new migration file
buddy seed # seed database
buddy generate:migrations # generate migrations from model diffs
Creating a Migration
buddy make:migration create_orders_table
Creates a timestamped migration file in database/migrations/.
Migration Generation from Models
When you define or modify a model, generate migrations automatically:
buddy generate:migrations
This recursively loads both model roots, with app/Models/ overriding framework
models that have the same model name:
storage/framework/defaults/app/Models/
app/Models/
It diffs the merged registry against the committed dialect snapshot and
generates the necessary SQL. An application does not need an app/Models/
directory for framework model migrations to be discovered.
The snapshot is part of the schema history and must be committed with the
generated migration. It lives under storage/framework/database/, not .qb/.
Run the generator a second time before committing. A stable change reports
Nothing to migrate and Model snapshot unchanged.
Built-in Migrations (96+)
The framework includes migrations for all built-in models:
Core Tables
users — id, name, email (unique), password, timestamps
personal_access_tokens — auth tokens
passkeys — WebAuthn credentials
password_resets — password reset tokens
Content
posts — title, content, excerpt, views, status, published_at, author_id
pages, categories, tags, comments
authors — linked to users
Commerce (20+ tables)
products, product_variants, product_units
orders, order_items
carts, cart_items
coupons, gift_cards, reviews
customers, manufacturers
Payments
payments, payment_methods, payment_products, payment_transactions
subscriptions, transactions
Shipping
shipping_methods, shipping_rates, shipping_zones
delivery_routes, drivers
System
jobs, failed_jobs — queue tables
errors, logs, notifications
activities, requests, websockets
Indexes
users.email (unique), users(email, name) (composite)
subscribers.email (unique)
coupons.code (unique), gift_cards.code (unique)
payments.transaction_id (unique)
subscriptions.provider_id (unique)
Workflow
- Define/modify model in
storage/framework/defaults/app/Models/ or app/Models/
- Run
buddy generate:migrations to generate SQL diffs
- Review generated migration files
- Run
buddy generate:migrations again and confirm there is no remaining diff
- Run
buddy migrate to apply
- Commit the generated SQL and
storage/framework/database/model-snapshot.<dialect>.json
Gotchas
migrate:fresh drops ALL tables — only use in development
- Migrations run in filename order (timestamps ensure correct sequence)
- Never edit a migration that's been run in production — create a new one
- Keep the committed model snapshot in sync with every generated migration
- Do not commit a second snapshot under
.qb/; that indicates a missing snapshotDir configuration
- If a generated SQLite migration rebuilds tables, test it against a copy of the current database and run
PRAGMA integrity_check plus PRAGMA foreign_key_check
--seed flag after migrate:fresh seeds the database with factory data
- 96+ migration files exist by default for all framework models
- SQLite >= 3.47.2 is required (system requirement)
- For the database API (queries, connections), see the
stacks-database skill
1---2name: stacks-migrations-43description: Use when working with database migrations in a Stacks application — creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 96+ built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.4license: MIT5compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.26allowed-tools: Read Edit Write Bash Grep Glob7metadata:8 source: https://skillmd.com/skills/stacksjs/stacks-migrations-49---1011# Stacks Database Migrations1213Schema change management via migration files.1415## Key Paths16- Migration files: `database/migrations/` (96+ files)17- Database config: `config/database.ts`18- Model snapshot: `storage/framework/database/model-snapshot.<dialect>.json`1920## CLI Commands2122```bash23buddy migrate # run pending migrations24buddy migrate --diff # show SQL without running25buddy migrate --auth # include auth tables26buddy migrate:fresh # drop ALL tables and re-migrate27buddy migrate:fresh --seed # drop, migrate, then seed28buddy migrate:dns # DNS-specific migration29buddy make:migration <name> # create new migration file30buddy seed # seed database31buddy generate:migrations # generate migrations from model diffs32```3334## Creating a Migration3536```bash37buddy make:migration create_orders_table38```3940Creates a timestamped migration file in `database/migrations/`.4142## Migration Generation from Models4344When you define or modify a model, generate migrations automatically:4546```bash47buddy generate:migrations48```4950This recursively loads both model roots, with `app/Models/` overriding framework51models that have the same model name:5253- `storage/framework/defaults/app/Models/`54- `app/Models/`5556It diffs the merged registry against the committed dialect snapshot and57generates the necessary SQL. An application does not need an `app/Models/`58directory for framework model migrations to be discovered.5960The snapshot is part of the schema history and must be committed with the61generated migration. It lives under `storage/framework/database/`, not `.qb/`.62Run the generator a second time before committing. A stable change reports63`Nothing to migrate` and `Model snapshot unchanged`.6465## Built-in Migrations (96+)6667The framework includes migrations for all built-in models:6869### Core Tables70- `users` — id, name, email (unique), password, timestamps71- `personal_access_tokens` — auth tokens72- `passkeys` — WebAuthn credentials73- `password_resets` — password reset tokens7475### Content76- `posts` — title, content, excerpt, views, status, published_at, author_id77- `pages`, `categories`, `tags`, `comments`78- `authors` — linked to users7980### Commerce (20+ tables)81- `products`, `product_variants`, `product_units`82- `orders`, `order_items`83- `carts`, `cart_items`84- `coupons`, `gift_cards`, `reviews`85- `customers`, `manufacturers`8687### Payments88- `payments`, `payment_methods`, `payment_products`, `payment_transactions`89- `subscriptions`, `transactions`9091### Shipping92- `shipping_methods`, `shipping_rates`, `shipping_zones`93- `delivery_routes`, `drivers`9495### System96- `jobs`, `failed_jobs` — queue tables97- `errors`, `logs`, `notifications`98- `activities`, `requests`, `websockets`99100### Indexes101- `users.email` (unique), `users(email, name)` (composite)102- `subscribers.email` (unique)103- `coupons.code` (unique), `gift_cards.code` (unique)104- `payments.transaction_id` (unique)105- `subscriptions.provider_id` (unique)106107## Workflow1081091. Define/modify model in `storage/framework/defaults/app/Models/` or `app/Models/`1102. Run `buddy generate:migrations` to generate SQL diffs1113. Review generated migration files1124. Run `buddy generate:migrations` again and confirm there is no remaining diff1135. Run `buddy migrate` to apply1146. Commit the generated SQL and `storage/framework/database/model-snapshot.<dialect>.json`115116## Gotchas117- `migrate:fresh` drops ALL tables — only use in development118- Migrations run in filename order (timestamps ensure correct sequence)119- Never edit a migration that's been run in production — create a new one120- Keep the committed model snapshot in sync with every generated migration121- Do not commit a second snapshot under `.qb/`; that indicates a missing `snapshotDir` configuration122- If a generated SQLite migration rebuilds tables, test it against a copy of the current database and run `PRAGMA integrity_check` plus `PRAGMA foreign_key_check`123- `--seed` flag after `migrate:fresh` seeds the database with factory data124- 96+ migration files exist by default for all framework models125- SQLite >= 3.47.2 is required (system requirement)126- For the database API (queries, connections), see the `stacks-database` skill