leistungsbilanz-ts/docs/local-db-circuit-first-migration.md

Local DB Migration: Circuit-First Schema

This project uses SQLite at data/leistungsbilanz.db and Drizzle migrations in src/db/migrations.

Safe command order

1. Backup local DB (required before schema/data migration)

npm run db:backup

The command uses SQLite's online backup API, so committed WAL changes are included even while the application is running. It opens the resulting standalone database and requires both PRAGMA integrity_check and PRAGMA foreign_key_check to pass. Database backups are operational recovery files and remain separate from the future user-visible project version history.

2. Apply pending schema migrations (includes 0008_circuit_first_model, the additive 0009_project_device_circuit_fields transition and the post-cutover 0011_project_device_canonical_fields cleanup)

npm run db:migrate

3. Verify circuit-first tables exist

npm run db:verify:circuit-schema

4. Backfill default sections for existing circuit_lists

npm run db:backfill:sections

5. Run legacy consumer -> circuit/device-row migration explicitly

npm run db:migrate:legacy-consumers

Verification SQL

Run these against data/leistungsbilanz.db:

SELECT name
FROM sqlite_master
WHERE type = 'table'
  AND name IN (
    'circuit_sections',
    'circuits',
    'circuit_device_rows',
    'legacy_consumer_circuit_migrations',
    'legacy_consumer_migration_reports'
  )
ORDER BY name;

The verification command also checks the circuit-first project-device columns added by migration 0009.

SELECT circuit_list_id, key, prefix, sort_order
FROM circuit_sections
ORDER BY circuit_list_id, sort_order;

SELECT circuit_list_id, COUNT(*) AS circuits
FROM circuits
GROUP BY circuit_list_id;

SELECT c.circuit_list_id, COUNT(r.id) AS device_rows
FROM circuits c
LEFT JOIN circuit_device_rows r ON r.circuit_id = c.id
GROUP BY c.circuit_list_id;

API verification

After the steps above:

GET /api/projects/:projectId/circuit-lists/:circuitListId/tree

Expected response shape:

{
  "circuitListId": "string",
  "sections": [
    {
      "id": "string",
      "key": "lighting|single_phase|three_phase|unassigned|...",
      "displayName": "string",
      "prefix": "-1F|-2F|-3F|-UF|...",
      "sortOrder": 10,
      "circuits": [
        {
          "id": "string",
          "equipmentIdentifier": "-2F1",
          "displayName": "string",
          "sortOrder": 10,
          "isReserve": false,
          "circuitTotalPower": 1.23,
          "deviceRows": [
            {
              "id": "string",
              "displayName": "string",
              "quantity": 1,
              "powerPerUnit": 0.3,
              "simultaneityFactor": 1,
              "rowTotalPower": 0.3
            }
          ]
        }
      ]
    }
  ]
}

If migrations were not applied, endpoint may return an empty fallback with a warning.

Dev-only visual test helper (multi-device circuit)

Add one extra manual device row to an existing circuit:

npm run dev:add-manual-circuit-row -- <circuitId>

Default inserted values:

• name: Test sub device
• displayName: Beleuchtung WC
• phaseType: single_phase
• quantity: 1
• powerPerUnit: 0.05
• simultaneityFactor: 1
• cosPhi: 1

The script prints the created row id.

Delete the test row again:

npm run dev:delete-circuit-row -- <rowId>