dashback/.agents/skills/database-schema-updates/SKILL.md

name, description

name	description
database-schema-updates	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 (libdashstore).
• MSSQL schema DDL: schema.js.
• SQLite schema DDL: 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 and AGENTS.md.
• Store API documentation index: 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 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.