Seed Data

Demo rows for development, reference rows for every environment, and the @env tag that scopes a migration to the environments it names.

Seed data is a migration. There is no separate seed command and no seeds directory. A migration file tagged @env development applies to your local database and never reaches production. An untagged migration applies everywhere, so rows every environment needs go in an ordinary migration.

Development Seed Rows

Create a migration and tag it in a /** */ comment before the first statement:

elements create migration "demo rows"

/** @env development */

insert into users (email, name) values
  ('ada@example.com', 'Ada'),
  ('grace@example.com', 'Grace');

insert into projects (name, ownerId)
  select 'Demo project', id from users where email = 'ada@example.com';

Save it and the build applies it to the development database, in filename order with every other migration, so it can insert into any table an earlier migration created. On a deploy machine the file is skipped: it is never applied, never pending, and leaves no record in the database.

Write the whole file, then save it once. Saving a migration that has already applied is an edit, and in development an edit restores the database from the backup taken before that migration first applied, or rebuilds it from every migration when no backup is left (see elements man migrations). Every save of a seed file resets the rows added since, and signs out anyone who signed in since. Editing a seed file five times resets the database five times.

The Tag

Build tags are JSDoc comments, and @env is no exception. It goes in a /** */ comment among the file's leading comments, before the first SQL statement. A description comment can come first:

-- demo rows for local work
/**
 * @env development
 */

insert into users (email, name) values ('ada@example.com', 'Ada');

List more than one environment with commas or spaces:

/** @env development, staging */

Names are environments of this project: development, production, and any environment with its own config/env/<name>.env file or deploy.env.<name> block (see elements man config). A name that is none of these is a build error naming the environments that exist, and no migration runs until it is fixed. An @env in a /* */ or -- comment, or with no names, is also an error rather than a tag that silently does nothing.

Which Database Gets What

File	Development app db	Production app db	Test db
untagged	applied	applied	applied
@env development	applied	skipped	skipped
@env production	skipped	applied	applied in production
@env development, production	applied	applied	skipped

The test database never gets a file tagged development. Tests seed the rows they need themselves (see elements man tests).

Reference Rows

Rows the app cannot run without, such as a lookup table's values or the single row a cache table starts with, go in an untagged migration. They apply in every environment and on the test database. elements man recipes/cron-cache inserts its starting row this way.

Changing a Migration's Environments

Do not add @env to a migration that has already applied. The tag is part of the file, so adding it changes the file's content, which is an edit. Development resets. A deploy machine rejects the changed migration as stale, or, when the tag leaves its environment out, skips the file from then on without undoing the rows it already inserted. Put the rows in a new tagged migration instead.

Removing the tag from a development seed later is allowed. Development treats it as an edit and resets. Production has no record of the file, so the next deploy applies it there for the first time.

Running the server locally with ENV=production uses the same local database as development. A development seed that already applied stays in it; the file is only skipped, never undone.

Related

• elements man migrations: how migrations apply, edit, and revert.
• elements man config: environments and env files.
• elements man database/cli: piping a one-off SQL file into elements db.