Skip to main content

Database development

Source of truth​

Make schema changes in the owning db/sqlproj/Mastra.*Db/model/** project. The aggregate db/sqlproj/Mastra.AllDb/Mastra.AllDb.sqlproj must continue to reference every deployable project. Service-local ingestion SQL under apps/ingestion-server/db/** must be reconciled when it represents the same deployed contract.

Change workflow​

  1. Edit the owning table/view/procedure/type definition.
  2. Update Mastra.AllDb membership when a project is added or removed.
  3. Add an explicit migration or pre-deployment step only when existing data requires a transition that declarative publish cannot perform safely.
  4. Build the smallest project, then the aggregate project for cross-schema references.
  5. Review the publish script with BlockOnPossibleDataLoss=True; never weaken safety merely to make an unexplained diff pass.
  6. Update seeds, routes/contracts, and docs only when their behavior changes.
  7. Run targeted DB/infra tests and verify deployment ordering.

Build​

On a Windows/SSDT-capable host:

cd db/sqlproj
./Mastra.AllDb/build-dacpac.ps1 -Configuration Release

The aggregate script writes Mastra.AllDb.dacpac under Mastra.AllDb/bin/Output.

Connectivity check​

The registered admin tool can validate the deployed database inventory. Direct runtime/operator calls require the configured admin proxy guard; browser callers use the Admin UI BFF.

curl -X POST "$MASTRA_BASE_URL/admin/tools/db-health-check" \
  -H "Content-Type: application/json" \
  -H "X-Mastra-Admin-Proxy-Secret: $MASTRA_ADMIN_PROXY_SECRET" \
  -d '{"schema":"K12SAFETY"}'

The route accepts flat JSON and the compatibility { "data": { ... } } wrapper. See Admin database health check.

Safety notes​

  • Prefer additive nullable/defaulted changes before backfills and constraints.
  • Evaluate indexes, foreign keys, and dependent views for type changes.
  • GO splits SQL batches and is not a transaction boundary you can ignore.
  • Do not add runtime CREATE TABLE logic to compensate for an incomplete DACPAC.
  • Do not copy production data into tests or documentation.