BitzOrcas.Modern uses a CSV-based seed framework to populate platform system tables. Seeding runs as part of the --init-schema / --seed-demo command — the API host creates all tables, audit sharding tables, runs seed data, then exits without entering the web pipeline.
How seeding works
The seed runner
The ISeedRunner iterates registered ISeedStep implementations in order. Each step reads from a CSV asset file and upserts records via the configured ORM adapter (SqlSugar by default). The framework provides CsvSeedReader and CsvSeedStepBase<T> for standard CSV → entity mapping.
Seed data CSV files live under:
src/BuildingBlocks/BitzOrcas.Infrastructure.SqlSugar/Seeders/Assets/Each file follows the naming convention {order}-{table_name}.csv — the numeric prefix controls seeding order.
Schema initialisation modes
| Flag | Tables | Audit tables | Seed data |
|---|---|---|---|
--init-schema | ✅ Create | ✅ Create | ✅ Run |
--seed-demo | ✅ Create | ✅ Create | ✅ Run (alias) |
--seed-only | ❌ Skip | ❌ Skip | ✅ Run |
--no-seed | ✅ Create | ✅ Create | ❌ Skip |
The 14 platform seed tables
These are the system tables populated from CSV assets on --seed-demo:
| Order | Table | Description |
|---|---|---|
| 100 | sys_platform_tenant | Platform tenants (the root tenant and any system tenants) |
| 110 | sys_language | Supported languages (e.g. zh-CN, en-US) |
| 120 | sys_country | Countries and regions |
| 130 | sys_industry_setting | Industry classification codes |
| 140 | sys_general_code_group | General code groups (lookup categories) |
| 141 | sys_general_code | General codes (lookup values) |
| 142 | sys_general_code_text | General code display texts (i18n) |
| 150 | sys_exchange_rate | Currency exchange rates |
| 160 | sys_public_holiday | Public holidays by region |
| 200 | sys_role_type | Role type definitions |
| 210 | sys_role | System roles (Admin, Basic, etc.) |
| 220 | sys_module | Module definitions and permissions |
| 230 | sys_permission | Granular permission entries |
| 240 | sys_role_module_permission | Role-module-permission mappings |
Seeding order matters
Tables are seeded in numeric prefix order. Foreign key dependencies are respected — parent tables (like sys_general_code_group) are seeded before child tables (like sys_general_code).
Sandbox module data
In addition to the platform tables, the Sandbox module (Notes, Greetings, Ping) provides built-in endpoints for testing. These are not database-backed by default — the Notes feature uses ISandboxDataPort which resolves to NullSandboxDataPort in the API shell (returns empty). When a persistence adapter is configured (SqlSugar or EF Core), the sandbox port is automatically wired to the real implementation.
Sandbox endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/ping | GET | Health check / liveness probe |
/api/v1/greetings | POST | Create a greeting (demonstrates command pattern) |
/api/v1/notes/{id} | GET | Get a note by ID (demonstrates query pattern) |
/api/v1/notes | POST | Create a note (demonstrates write-through port) |
Adding custom seed data
To add your own seed data:
- Create a CSV file in the
Seeders/Assets/directory with the appropriate order prefix. - Create a
CsvSeedStepBase<T>subclass that maps CSV columns to your entity. - Register the step with
ISeedRunner— the framework executes it in order.
The seed runner is idempotent — each step checks before writing, so re-running against an already-seeded database is safe.
Related
- Quick Start — bring the stack up and run
--seed-demo. - Architecture — how the seed runner integrates into the DI pipeline.