seb/dashback
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

u

Browse Source
This commit is contained in:
seb
2026-10-09 18:25:56 +02:00
parent daf2d0525f
commit cd6879f3b7
1 changed files with 42 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
.agents/skills/database-schema-updates/SKILL.md Normal file
View File

@@ -0,0 +1,42 @@
---
name: database-schema-updates
description: "Use when changing or diagnosing the Dash database schema, applying a local schema patch, or rerunning the off-repository development migration script."
---
# Database Schema Updates
Use this workflow for schema changes and local database updates in the Dashback + `dashdbschema` setup.
## Project map
- The schema/store repository is the sibling [`dashdbschema`](../../../../dashdbschema) (`libdashstore`).
- MSSQL schema DDL: [`schema.js`](../../../../dashdbschema/src/providers/mssql/schema.js).
- SQLite schema DDL: [`schema.js`](../../../../dashdbschema/src/providers/sqlite3/schema.js).
- Provider behavior: `../../../../dashdbschema/src/providers/{mssql,sqlite3}/`.
- Store implementation: `../../../../dashdbschema/src/store/`; SQL queries: `../../../../dashdbschema/src/providers/mssql/queries/`.
- Schema/store overview and conventions: [`README.md`](../../../../dashdbschema/README.md) and [`AGENTS.md`](../../../../dashdbschema/AGENTS.md).
- Store API documentation index: [`API.md`](../../../../dashdbschema/API.md), with per-domain details in `../../../../dashdbschema/API.<module>.md`.
- Dashback database configuration: `src/config/env.js` and the local, untracked `.env`. SQLite defaults to `data/dash.db` unless `SQLITE_PATH` or `SQLITE_FILENAME` overrides it; `DB_PROVIDER` determines the active provider.
## Rules
- Do not add migration/upgrade code, migration scripts, or migration-only DDL to a Git repository. The checked-in schema must describe the desired state for a fresh database.
- Existing local-development databases may need separate schema-patch scripts maintained in the Git-ignored `data/` folder. Name them `NNN-description.mjs`, using a three-digit sequence that increments from the highest existing number (for example, `001-schema-patch.mjs`, then `002-add-index.mjs`). Never reuse a number or renumber existing scripts; retain older scripts so patches can be tracked and rerun in order. Do not put these scripts in Git-tracked folders.
- In this dashback workspace, sibling repositories are read-only. Read their schema and conventions, but do not edit, install dependencies, or run their scripts unless the user explicitly authorizes work in that sibling repository.
- Never use `purge-db` or `reset-db` on a database that contains data: those commands purge tables. Do not assume that `initialize()` upgrades existing tables.
- Do not print credentials or expose `.env` values in tool output.
## Workflow
1. Confirm which schema/provider and environment the change concerns. Read the applicable schema, provider, and domain query/store code, plus the relevant repository instructions. For SQL changes, check both MSSQL and SQLite behavior where applicable.
2. Make the checked-in schema represent the desired fresh-database shape. Respect the sibling-repository read-only boundary; ask the user to coordinate or authorize a `dashdbschema` change rather than editing across that boundary.
3. For an existing local dev database, identify the numbered patch script in `data/` and verify its exact path and contents before running it. Create new local-only patch scripts with the next consecutive three-digit number; never overwrite or renumber existing patches. Confirm the target is the local development database by checking the active provider and configured database path/name without displaying secrets. If the script, target, or safety of rerunning it is unclear, ask the user rather than guessing.
4. Preserve local data. For a file-backed SQLite database, make a backup before applying a script that changes it. Do not run against production, a shared database, or an unconfirmed target. Do not stop or start the API as part of this workflow.
5. Run or rerun the requested numbered script against the confirmed local dev database from its established location and documented invocation; do not embed credentials in command arguments or logs. Report the result and any errors explicitly.
6. Verify the intended schema change against the local dev database using a targeted, read-only schema check. Do not claim success if the script failed or verification was not possible.
## Important notes
- The schema source is DDL for new databases, not an upgrade mechanism. Keep fresh database initialization aligned with any manual/local schema changes.
- [`no-schema-migrations.mdc`](../../../../dashdbschema/.cursor/rules/no-schema-migrations.mdc) documents the no-migration-code convention. Its reset-db workflow is destructive; it is not a substitute for the separate local dev migration script.
- Local patches belong in the Git-ignored `data/` directory and use continuous three-digit numbering. If the correct database target or script operation cannot be verified, ask the user rather than guessing.