Skip to main content

SQL Migrations

Purpose​

  • This page documents how maintainers author, review, and apply ClickHouse schema migrations for Origo.

Required reading​

  • control-plane/migrations/README.md
  • control-plane/README.md
  • contracts/governance/storage-sql-discipline.json

Process​

  1. Add a new versioned migration under control-plane/migrations/sql.
  2. Keep the filename contiguous and descriptive.
  3. Author exactly one SQL statement per migration file.
  4. Apply and verify migrations using the control-plane migration CLI.

Checklist​

  • Filename follows NNNN__snake_case_name.sql.
  • Versions are contiguous.
  • Applied migrations are never edited in place.
  • Database names use {{DATABASE}} placeholders where required.
  • Commands are run from control-plane/.

Failure cases and review notes​

  • Do not modify an applied migration file.
  • Do not document a migration workflow that bypasses the maintained CLI surface.
  • docs/Developer/Release-And-Deployment.md
  • control-plane/migrations/README.md
  • control-plane/README.md