OntoBricks deployment checklist

Use this list before your first deploy (or when moving to a new workspace / instance). Automate most checks with:

make deploy-check
# or, equivalently:
scripts/_internal/check-deploy-prerequisites.sh
scripts/deploy.sh --dry-run

1. Local workstation

Local-only check:

scripts/_internal/check-deploy-prerequisites.sh --local

2. Databricks CLI authentication

databricks auth login --host https://<workspace> --profile <profile>

3. Workspace resources (must exist before deploy)

Configure in scripts/deploy.config.sh (single source of truth).

Verify resources:

databricks warehouses get <WAREHOUSE_ID>
databricks volumes read <catalog>.<schema>.<volume>
databricks postgres list-databases "projects/<project>/branches/<branch>" -o json

4. Lakebase bootstrap (bootstrap-lakebase-perms.sh)

Run automatically on every dev-lakebase deploy (make deploy), or manually:

make bootstrap-lakebase

Preflight (read-only):

scripts/_internal/check-deploy-prerequisites.sh --lakebase

5. In-place app upgrade (0.6.x → 0.7.0)

v0.7.0 derives app name + DAB target from DEFAULT_INSTANCE_ID (ontobricks-<id>, dev-lakebase-<id>). Changing the app name under the same Terraform state is a destroy-then-create (Databricks app names are immutable). Deploy preflight blocks that unless you confirm.

In-place example:

DEFAULT_INSTANCE_ID=060 DAB_TARGET=dev-lakebase make deploy

Keep Lakebase / UC variables pointed at the same registry. Then apply registry DDL (§6) if you have not already via make bootstrap-lakebase.

Full narrative: releases/ReleaseNotes_V0.7.0.md → Upgrade Notes → Keep the existing Databricks app.

6. Registry DB upgrades (0.4 → 0.5 → 0.6 → 0.7 → 0.8)

For in-place upgrades of an existing Lakebase registry, schema DDL must be applied as the schema owner. OntoBricks applies the same objects in four ways (pick one):

1. make bootstrap-lakebase / scripts/bootstrap/lakebase-perms.sh (recommended — idempotent Step 2b; runs automatically from make deploy)
2. scripts/migrations/upgrade_0.4_to_0.5.sql — adds domain_versions.status + backfill from mcp_enabled
3. scripts/migrations/upgrade_0.5_to_0.6.sql — collaborative tables, graph analytics, edit locks, change events
4. scripts/migrations/upgrade_0.6_to_0.7.sql — generic scheduled-task columns on schedules / schedule_runs + unique-constraint swap
5. scripts/migrations/upgrade_0.7_to_0.8.sql — domains.mcp_policy (per-domain MCP tool + context policy). No backfill: the {} default reproduces pre-0.8 behaviour

Preflight reports pending or stale migration objects before deploy:

python3 scripts/_internal/_lakebase_preflight.py \
  --project "$LAKEBASE_PROJECT" \
  --branch "$LAKEBASE_BRANCH" \
  --database "$LAKEBASE_DATABASE" \
  --schema "$LAKEBASE_SCHEMA"

Manual upgrade example (0.7 → 0.8):

psql "host=<endpoint> dbname=<datname> sslmode=require user=<you>" \
  -v reg_schema=<schema> \
  -f scripts/migrations/upgrade_0.7_to_0.8.sql

7. App permission bootstrap (bootstrap-app-permissions.sh)

Run automatically after deploy, or manually:

make bootstrap-perms

8. Deploy workflow (happy path)

[ ] Edit scripts/deploy.config.sh (DEFAULT_INSTANCE_ID, Lakebase coords, warehouse, UC;
    for a pre-0.7 in-place upgrade also set DEFAULT_DAB_TARGET=dev-lakebase — see §5)
[ ] scripts/_internal/check-deploy-prerequisites.sh          # or make deploy-check
[ ] make deploy-dry-run                            # read-only full orchestrator check
[ ] make deploy                                    # deploy + bootstrap
[ ] Databricks Apps UI: bind sql-warehouse, volume, postgres (first time only)
[ ] App UI: Settings → Registry → Initialize
[ ] make bootstrap-lakebase                          # if schema was created after deploy
[ ] App UI: Settings → Graph DB → Create graph DB  # grants graph schema separately

9. Optional / mode-specific

Quick reference — scripts