db:seed

Table of contents

1. Introduction
2. Seeding one feature
3. Starting over with fresh data
4. Writing a seeder
5. Seeding a product’s own content
6. Seeding on the first start
7. Reference
   1. Options
   2. Errors
8. Requirements

---

Introduction

db:seed fills the database from the seeders of the features and of the product. Each feature seeds after the features it depends on, and the product’s seeders run last. Run it after migrating, or with --reset to start over on the same schema.

splent db:seed

🌱 Seeding all features...
✔ NotesSeeder completed.
✔ ReportsSeeder completed.
✅ Database successfully populated.

It stops at the first seeder that fails and exits 1.

---

Seeding one feature

splent db:seed notes

notes, splent_feature_notes and splent-io/splent_feature_notes@v1.2.0 all work. The match is exact, so notes never also seeds splent_feature_notes_tags. The product’s name seeds only the product’s own seeders.

---

Starting over with fresh data

splent db:seed --reset -y

--reset deletes every row and then seeds. Tables, migrations and schema stay, unlike db:reset, which drops the tables. -y skips the confirmation.

Without --reset, a seeder that inserts a row that is already there stops the run with duplicate data detected.

---

Writing a seeder

A feature’s seeders.py holds a class that extends BaseSeeder and implements run().

from splent_framework.seeders.BaseSeeder import BaseSeeder
from splent_io.splent_feature_notes.models import Notes

class NotesSeeder(BaseSeeder):

    def run(self):
        self.seed([
            Notes(title="Welcome", content="Your first note."),
        ])

self.seed(data) inserts a list of instances of one model and returns them with their ids. It raises SeederError on an integrity violation.

There is no priority to set. The order comes from feature:order, the UVL constraints with every refiner after its base, or the pyproject.toml order when there is no model. A feature without seeders.py is skipped.

---

Seeding a product’s own content

A feature seeds after the features it depends on. A product seeder that replaces a feature's seeder runs in its place, after every feature.

Features seed the content every product of the line shares. What one product decides for itself, such as the copy of its landing page, goes in src/<product>/seeders.py.

from splent_framework.seeders.BaseSeeder import BaseSeeder
from splent_io.splent_feature_landing.models import LandingSection

class LandingSeeder(BaseSeeder):
    replaces = ("splent_io.splent_feature_landing",)

    def run(self):
        self.seed([
            LandingSection(slug="who-we-are", title="Who we are", content="..."),
        ])

replaces names the feature seeder modules the product takes over, and those are skipped. Seeding the replaced feature alone runs the product’s seeder in its place.

  ↷ splent_feature_landing: seeder replaced by the product
✔ LandingSeeder completed.

---

Seeding on the first start

The product’s container seeds a fresh database by itself when RUN_DB_SEED=true, as the development .env sets. The start migrates with db:upgrade --fresh-marker, and when the database was empty it runs splent db:seed -y.

    applying pending migrations...
    fresh database, seeding...

A database that had tables is never seeded, so a restart does not duplicate data. Production is never seeded, whatever RUN_DB_SEED says. A failed seed stops the start, and the next start does not retry it, so fix the error and run splent db:seed by hand. See Migrating when the product starts.

---

Reference

Options

Option	Description
MODULE	Optional. Seed only this feature, or only the product’s seeders when it is the product’s name
--reset	Delete every row first. The schema stays
-y, --yes	Do not ask for confirmation

Errors

Message	What to do
❌ No seeders found for '<module>'. Nothing was cleared or seeded.	Name a declared feature with a seeders.py, or the product. Even with --reset, nothing was deleted
❌ N seeders module(s) could not be loaded. Nothing was cleared or seeded.	A seeders.py failed to import. The line above names the module it needs
❌ <Seeder>: duplicate data detected.	Run splent db:seed --reset
❌ Error in <Seeder>: <error>	Fix the seeder and run it again

---

Requirements

• A selected product (SPLENT_APP), and a reachable database.
• The features installed (product:resolve).
• The product is not deployed to production (SPLENT_ENV=prod), since the CLI would then reach the production database. Go back with splent product:down --prod and splent product:up --dev. See the CLI while production is deployed.