Databases
The model is provider-agnostic — NetForge runs on SQLite, PostgreSQL, or SQL Server. You pick the provider at scaffold time (--database); after that it's a config switch: set Database:Provider and a matching ConnectionStrings:Default.
| Provider | Best for | Notes |
|---|---|---|
| SQLite (default) | Local dev; small / single-instance production | Zero setup, in-process. Single writer — heavy concurrent writes serialize. |
| PostgreSQL | Production (recommended) | Scaffold ships a docker-compose.yml, so docker compose up -d gives you a local Postgres in one command. |
| SQL Server | Production on the Microsoft stack | Scaffold ships a docker-compose.yml. |
Every provider ships EF migrations, applied on boot.
Migrations
Each scaffold ships the migrations for the provider it was created for, and only those, in Data/Migrations (SQLite) or Data/Migrations/SqlServer / Data/Migrations/Postgres. On boot the app applies them with Database.Migrate(). From then on every schema change is the normal flow:
dotnet ef migrations add AddInvoices --project YourApp.ServerThe next boot applies it (or run dotnet ef database update). Commit the migrations folder.
A forgotten migration stops the boot. If an entity changed and no migration covers it, startup fails with a message naming the change (e.g. add column Invoices.DueDate) instead of the app running against a schema that doesn't match. Editions that leave a feature out keep that feature's tables in the migrations, created but unused — the check allows exactly those, and nothing else.
Schemas on Postgres / SQL Server
Everything the app owns lives in an app schema (the migrations history included), and background jobs keep their own hangfire schema beside it — nothing lands in public/dbo. Granting a reporting login read access is one statement: GRANT SELECT ON SCHEMA::app TO reporting (SQL Server) or GRANT USAGE ON SCHEMA app … + GRANT SELECT ON ALL TABLES IN SCHEMA app … (Postgres). SQLite has no schemas.
Switching provider later
Changing Database:Provider to a provider the project has no migrations for still runs: the schema is built from the model on first boot, and a warning says so. That schema can't evolve, so add migrations for the new provider before you rely on it: delete the old provider's migrations, drop the database, and run dotnet ef migrations add InitialCreate.
Projects scaffolded before per-provider migrations
Older Postgres / SQL Server scaffolds shipped SQLite's migrations and built their schema with EnsureCreated, which can never add a column. To move one onto migrations — once, while it has no data you need:
- Stop the app, and drop the database (with the bundled docker DB:
docker compose down -v && docker compose up -d) — it has no migrations history to build on. - Delete the shipped
Data/Migrationsfolder (it holds SQLite-shaped migrations), thendotnet ef migrations add InitialCreate --project YourApp.Server. - In
Data/Seed/DatabaseSeeder.cs, replacedb.Database.EnsureCreated()withdb.Database.Migrate().
Testing on your engine
The integration tests run on a throwaway SQLite file by default, so dotnet test needs nothing installed. Point them at the engine you deploy on to catch what SQLite hides — collation, date and decimal storage, what LINQ translates:
TEST_DATABASE=sqlserver dotnet test # LocalDB by default; TEST_DATABASE_SERVER overrides
TEST_DATABASE=postgres TEST_DATABASE_SERVER="Host=localhost;Username=postgres;Password=…" dotnet testEach test fixture creates its own test_… database and drops it afterwards. On the provider the project ships migrations for, the run also proves they apply to an empty database and cover the model.
Dev/prod split
Scaffolding with --devSplit true (or the configurator's "Use SQLite for local dev" checkbox) puts SQLite in appsettings.Development.json while production uses the server DB. It lowers local friction, but carries a real parity risk: SQLite stores dates and money differently (NetForge applies SQLite-only value converters), and case-sensitivity, JSON querying, and concurrency all differ — so you develop and test against a different engine than you ship.
The project ships the server provider's migrations; the SQLite dev database is built from the model, so delete it when the model changes. Generate new migrations against the server provider:
dotnet ef migrations add AddInvoices --project YourApp.Server -- --Database:Provider sqlserverPrefer parity
Prefer the bundled docker-compose to develop against the real engine. Choose the split only if you accept testing against a different database than production.