138 lines
3.4 KiB
Markdown
138 lines
3.4 KiB
Markdown
# Local DB Migration: Circuit-First Schema
|
|
|
|
This project uses SQLite at `data/leistungsbilanz.db` and Drizzle migrations in `src/db/migrations`.
|
|
|
|
This document is an upgrade runbook for databases created before the Circuit-First
|
|
cutover. A clean installation only needs the normal `db:migrate` and schema
|
|
verification steps documented in the main README.
|
|
|
|
## Safe command order
|
|
|
|
1. Backup local DB (required before schema/data migration)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
npm run db:migrate
|
|
```
|
|
|
|
3. Verify circuit-first tables exist
|
|
|
|
```bash
|
|
npm run db:verify:circuit-schema
|
|
```
|
|
|
|
4. Backfill default sections for existing `circuit_lists`
|
|
|
|
```bash
|
|
npm run db:backfill:sections
|
|
```
|
|
|
|
5. Run legacy consumer -> circuit/device-row migration explicitly
|
|
|
|
```bash
|
|
npm run db:migrate:legacy-consumers
|
|
```
|
|
|
|
## Verification SQL
|
|
|
|
Run these against `data/leistungsbilanz.db`:
|
|
|
|
```sql
|
|
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`.
|
|
|
|
```sql
|
|
SELECT circuit_list_id, key, prefix, sort_order
|
|
FROM circuit_sections
|
|
ORDER BY circuit_list_id, sort_order;
|
|
```
|
|
|
|
```sql
|
|
SELECT circuit_list_id, COUNT(*) AS circuits
|
|
FROM circuits
|
|
GROUP BY circuit_list_id;
|
|
```
|
|
|
|
```sql
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
## Visual verification
|
|
|
|
Manual device rows and multi-device circuits can be created directly in the
|
|
circuit-list editor. The former development scripts for direct database writes
|
|
were removed because they bypassed project revisions and persistent undo/redo.
|