Seeding data

Working with realistic data in your local environment makes development much smoother. Seed data allows you to pre-populate your database with data that you can use to test your app.

  • Get your development environment up and running quickly
  • Test how your app handles complex relationships
  • Create test cases that you can run again and again

Setting up seed data

Seed data is stored in SQL files within a seed directory in your project. Each .sql file in this directory runs in alphabetical order when seeding your database. This lets you control the order of data insertion by prefixing your files with numbers (e.g., 01-users.sql, 02-products.sql).

By checking in your seed files to version control, you can ensure that everyone on your team starts with the same data.

Applying seed data

Apply your seed files to the running development database with keel db seed:

keel db seed

Seeding is non-destructive by default: existing rows are left untouched, so the command is safe to run again and safe to run against a database that already has data.

⚠️

Seed data is subject to any model-level @validate rules in your schema. Seed files are plain SQL and those rules are enforced by database triggers, so a seed that leaves a record breaking a rule is refused and the statement that made the write is rolled back.

Those rules are checked at every statement boundary, which matters for a rule with a lower bound such as COUNT(order.items) > 0. A seed that inserts an order in one statement and its items in another cannot satisfy that rule, because the order exists on its own for the length of the first statement. Insert the parent and its children in the same statement, or express the invariant so it does not require the children to be present.

To update existing rows to the latest seed values, use --overwrite:

keel db seed --overwrite

To rebuild the database from scratch before seeding, use --reset:

keel db seed --reset
⚠️

Using --reset deletes all data in your local database before seeding. This cannot be undone.

Automatic seeding

When keel run creates a fresh, empty database, it seeds it automatically after applying migrations. Pass --no-seed to skip this.

Taking database snapshots

Keel can capture your current database state as a reusable seed file with keel db snapshot:

keel db snapshot

This writes the current state of your Keel tables to seed/snapshot/snapshot.sql. The snapshot is a read-only capture: it does not reset or re-seed your database.

To capture into a named scenario, pass a name:

keel db snapshot demo

This writes to seed/demo/snapshot.sql. You can build up data however you like through the UI, the API, or manual SQL, capture it, and recreate it later with --scenario:

keel db seed --scenario demo

Best practices

  1. Organize seed files: Use descriptive names for your seed files (e.g., 01-users.sql, 02-products.sql) to control the order of execution
  2. Version control: Include your seed files in version control to ensure consistent development environments
  3. Trim down snapshots: Use snapshots to quickly capture the state of your database and then remove any tables that are not relevant
TestingIntegrating Stripe