Skip to main content

Database structure

Repository layout​

The declarative schema source is db/sqlproj/**:

db/
  sqlproj/
    Mastra.AllDb/                       aggregate DACPAC
    Mastra.CoreDb/                      Core, Memory, MastraNative
    Mastra.Platform.HandbookDb/         HANDBOOK
    Mastra.Platform.IngestionDb/        Ingestion
    Mastra.Platform.K12SafetyDb/        K12SAFETY
    Mastra.Platform.ReasoningEngineDb/  REASONING
    Mastra.Platform.RecoveredDb/        RECOVERED
    Mastra.Platform.SDACDb/             SDAC
    Mastra.Platform.TapDb/              TAP
    migrations/                         cross-project transitions
    seeds/                              explicit idempotent seed scripts
  migrations/                           additional explicit transitions
  seed-data/                            snapshots and shared seed inputs

apps/ingestion-server/db/** also contains service-local ingestion material. When an ingestion change spans runtime and deployment, reconcile it with Mastra.Platform.IngestionDb rather than allowing two schema contracts to diverge.

SQL project layout​

Projects normally keep tables, views, procedures, and types under model/**, with Script.PreDeployment.sql and Script.PostDeployment.sql where required. The project file is the exact authority for included artifacts; do not assume a folder is compiled merely because it exists.

Aggregate project​

Mastra.AllDb.sqlproj references all workload projects and is the normal full environment DACPAC. Adding or removing a SQL project requires updating the aggregate project and its validation coverage. Run the repo-local check-alldb skill for project-membership changes.

Seeds and migrations​

  • Schema shape belongs in SQL projects.
  • Data transitions that cannot be represented safely by a declarative publish need an explicit reviewed migration.
  • Seed scripts under db/sqlproj/seeds/** are opt-in and idempotent.
  • Core/aggregate post-deployment scripts explicitly avoid automatic profile seeding; runtime seedConfig, manual seeds, Admin UI, and manifest-backed model seeding have separate responsibilities.

See Database deployment and Database seeding.