>
dbwarden
GitHub ↗
/ tool scope / seeds

Database Seeds and
Reference Data.

Deterministic baseline data for local, test, and sandbox environments: code seeds and file seeds, tracked in a seed table and independent from the migration history.

/ 01 Code seedsRead the docs ↗

Baseline data next to your models.

Code seeds live next to your models with a Seed base class and model instances. The seed declares its database, an on-conflict strategy for re-runs, and the rows to insert, so the same seed can be applied on a fresh checkout and after a rollback without duplicating rows.

Versions are auto-assigned in the C namespace (C0001, C0002, ...) from deterministic module and class ordering, so there is no manual version parameter to keep in sync with the file layout. Each version applies once until rolled back, and the seed table tracks what ran.

The on-conflict strategy decides what a re-apply does: with __seed_on_conflict__ = "update" and __seed_conflict_columns__, an existing row matching the conflict columns is updated rather than duplicated. That is what makes a code seed safe to apply on a fresh checkout and again after a partial rollback.

a code seed
from dbwarden.seed import Seed

class CountrySeed(Seed):
    __seed_database__ = "primary"
    __seed_description__ = "initial countries"
    __seed_on_conflict__ = "update"
    __seed_conflict_columns__ = ["code"]

    model = Country
    rows = [
        Country(code="UY", name="Uruguay"),
        Country(code="AR", name="Argentina"),
    ]
/ faq
Do seeds require the plugin?

Yes. Seed management ships as the official dbwarden-seeds plugin: dbwarden plugin add dbwarden-seeds. The seed commands exist in core, but each one exits with a message until the plugin is installed.

How are code seeds versioned?

Versions are auto-assigned in the C namespace (C0001, C0002, ...) based on deterministic module and class ordering, so there is no manual version parameter to keep in sync.

/ 02 File seeds and applyRead the docs ↗

SQL or Python in a seeds directory.

File seeds are plain SQL or Python in a seeds/ directory, for data that is easier to express as a script than as model rows. Both kinds are tracked in the _dbwarden_seeds table, applied with seed apply, and rolled back by removing the tracking record with seed rollback, including --count and --to-version for partial rollbacks.

Each applied seed stores a SHA-256 checksum of its file or class source. A checksum warning means the seed was modified since the last apply, so the database and the repository may disagree, and that warning is the signal to re-apply deliberately rather than silently.

apply and rollback
$ dbwarden seed apply --database primary
$ dbwarden seed rollback --database primary --count 2
/ faq
What does the checksum warning mean?

Each seed row stores a SHA-256 checksum of its file or class source. A warning means the seed was modified since the last apply, so the database and the repository may disagree.

Can seeds be rolled back?

Yes: seed rollback removes the tracking records, with --count or --to-version for a partial rollback. Each version can only be applied once until rolled back.

/ 03 Seed exportRead the docs ↗

Stateless SQL for stateless environments.

seed export renders code seeds to stateless runs-on-change SQL, for Dockerized deployments that should not carry application code. A container that only runs migrations should not need your models and their imports just to seed a few reference rows.

auto_apply_seeds runs pending seeds after every migrate, so a fresh environment comes up fully seeded in one command, with the seed history visible in the same status flow as the migration history.

the export
$ dbwarden seed export --database primary
/ faq
Why use seed export instead of applying code seeds?

Code seeds need your application environment to execute. seed export renders them to stateless runs-on-change SQL, so containers do not need the application code just to seed data.