Backend Seed Data¶
This page is the orientation guide for the seed scripts that bootstrap
a local backend with realistic data. It covers what each make target
produces, when to use which, and how the seeded scopes line up with
login-test so a developer can reach a perimeter and see real numbers.
For broader backend context see:
- Overview - High-level architecture
- Permission System - Role/scope model
- Integration Testing - Test-time fixtures
The seed targets¶
Four make targets seed different things. Verified against
backend/Makefile on 2026-09-11.
| Target | Volume | Runs | Use when |
|---|---|---|---|
make seed-data |
Small, deterministic | seed_locations, seed_generic_factors, seed_reference_data |
You need predictable reference data. Default for local dev and CI fixtures. Does not create data entries. Factors seed before the building rooms reference, which is validated against them (#2716). |
make seed-generic-data |
Small, deterministic | seed_generic_data_entries — CSVs in backend/seed_data/ |
You need data entries to go with the reference data above. Run it after seed-data. |
make seed-units |
Institutional units | seed_units_from_accred |
You need the real EPFL unit tree rather than generated units. |
make seed-data-random |
~800k data_entry rows |
random_generator.seed_all |
You need scale: perf testing, pagination work, query-plan checks, populated charts. Issue #222. |
The ~800k figure is 500 units × 3 years × 8 modules × 60–74 entries
(NUM_UNITS in populate_units_and_users.py, ENTRIES_PER_MODULE_MIN/MAX
in seed_data_entries.py). Tune those constants to change the volume.
seed-data-random chains the random unit/user/year/project/report generators
with the canonical CSV-driven factor seeder, so factor classes stay aligned
with the generated equipment (class, sub_class) payloads.
What seed-data-random produces¶
Run order (see backend/scripts/random_generator/seed_all.py):
- 500 units + 4000 users + 2 admins — units have
institutional_codeU00000-U00499andinstitutional_idCF00000-CF00499. - 3 year_configuration rows — 2023/2024/2025, provider DEFAULT,
is_started=TRUE,configuration_completed=now(). Without these the UI gates the year picker. - 500 carbon_projects + 1500 carbon_reports + carbon_report_modules — one Calculator project per unit, one report per (project, year), all 8 module types per report.
- Factors from
backend/seed_data/*_factors.csv— canonical reference set; equipment classes are then used to seeddata_entrypayloads. - ~800k data_entries + matching emissions — sized via
NUM_UNITS × YEARS × ALL_MODULE_TYPE_IDS × ENTRIES_PER_MODULE.
Login-test perimeter map¶
Seeded users carry roles whose scope binds to a unit's institutional_id
(the cf-style key, CF00000+):
| User pattern | Role | Scope |
|---|---|---|
USR000000-USR003999 |
CO2_USER_STD or CO2_USER_PRINCIPAL | Single unit (institutional_id=CF…) |
ADMIN004000 |
CO2_BACKOFFICE_METIER | An affiliation (SB, STI, IC, SV) |
ADMIN004001 |
CO2_SUPERADMIN | Global |
In login-test, picking any USR… user lands you on that user's unit
perimeter. Picking the SUPERADMIN puts you in global scope; picking the
METIER admin scopes you to the affiliation row visible in the role.
When the seed fails¶
The seed assumes a clean DB. If a step mid-pipeline fails and you retry,
previously-committed rows collide on unique constraints (e.g.
ix_units_institutional_code). Recover with:
make db-drop && make db-create && make db-migrate && make seed-data-random
Tuning the volume¶
seed-data-random volume is driven by four constants:
NUM_UNITS,NUM_USERSinbackend/scripts/random_generator/populate_units_and_users.pyENTRIES_PER_MODULE_MIN,ENTRIES_PER_MODULE_MAXinbackend/scripts/random_generator/seed_data_entries.py
Expected total rows = NUM_UNITS × YEARS (3) × ALL_MODULE_TYPE_IDS (8) ×
avg(ENTRIES_PER_MODULE). The smoke test
tests/unit/seed/test_random_generator_builders.py::test_entries_per_module_window_targets_800k_rows
fails CI if a change moves the math outside the 700k-900k band — bump it
in the same PR if you really mean to retarget.
See also¶
- Implementation plan: 222-seed-data-faker.md
- Factor CSV formats:
backend/05-seed-datasubsection - ADR-018: Factor CSV delete-before-insert