Merge pull request #46 from MaxLinCode/codex/db-rollout-hardening

Harden DB rollout workflow

Author: MaxLinCode

.github/workflows/apply-db-migrations.yml

@@ -0,0 +1,46 @@
+name: Apply DB Migrations
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: apply-db-migrations-main
+  cancel-in-progress: false
+
+jobs:
+  apply-db-migrations:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    env:
+      DATABASE_URL: ${{ secrets.DATABASE_URL_PRODUCTION }}
+    steps:
+      - name: Check required secret
+        run: test -n "$DATABASE_URL"
+
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check migrations
+        run: pnpm --filter @atlas/db db:check
+
+      - name: Apply migrations
+        run: pnpm --filter @atlas/db db:migrate

README.md

@@ -25,13 +25,19 @@ Atlas is a chat-first brain-dump scheduler MVP. A user sends freeform text, the
 - `pnpm typecheck`: run TypeScript checks across the repo
 - `pnpm test`: run the test suite
 - `pnpm telegram:webhook:set`: register the Telegram webhook and print Telegram's current webhook info
-- `pnpm db:generate`: generate a new Drizzle migration from schema changes
-- `pnpm db:migrate`: apply existing Drizzle migrations to the configured database
-- `pnpm db:studio`: open the Drizzle Studio workflow
 - `pnpm db:test:start`: start the local Homebrew Postgres test service and create `atlas_test`
 - `pnpm db:test:reset`: reset the local `atlas_test` database schema for integration reruns
 - `pnpm db:test:stop`: stop the local Homebrew Postgres test service
 
+Database schema commands are owned by `packages/db`:
+
+- `cd packages/db && DATABASE_URL=... pnpm db:generate`
+- `cd packages/db && DATABASE_URL=... pnpm db:check`
+- `cd packages/db && DATABASE_URL=... pnpm db:migrate`
+- `pnpm --filter @atlas/db db:generate` with `DATABASE_URL` already set
+- `pnpm --filter @atlas/db db:check` with `DATABASE_URL` already set
+- `pnpm --filter @atlas/db db:migrate` with `DATABASE_URL` already set
+
 ## Prompt Improvement Loop
 
 Atlas treats prompt changes as product behavior changes. Use the live eval harness to iterate on prompts deliberately instead of editing blind.
@@ -79,7 +85,7 @@ Notes:
 ## Environment
 
 Copy `.env.example` into `apps/web/.env.local` for local development and provide real values through your deployment environment for hosted runs.
-For local-only test credentials, prefer `apps/web/.env.test.local`, which is gitignored and loaded by the Next app, Drizzle config, and integration test runner.
+For local-only test credentials, prefer `apps/web/.env.test.local`, which is gitignored and loaded by the Next app and integration test runner.
 
 - `DATABASE_URL`: Postgres connection string
 - `APP_BASE_URL`: canonical deployed app origin used when generating Google Calendar connect links
@@ -98,6 +104,8 @@ To register the production Telegram webhook once those values are set, also expo
 
 For hosted rollout steps, use [`docs/workflows/production-deploy-checklist.md`](docs/workflows/production-deploy-checklist.md) as the main production deploy runbook and [`docs/workflows/vercel-telegram-webhook.md`](docs/workflows/vercel-telegram-webhook.md) for the narrower webhook-only setup flow.
 
+Production schema changes are not applied from local laptops. Merge to `main`, let the GitHub Actions migration workflow apply `packages/db/drizzle/` against the production database, and only release after that workflow succeeds.
+
 Atlas no longer exposes public planner/debug mutation routes. The intended externally reachable surfaces are:
 
 - `POST /api/telegram/webhook`

docs/current-work.md

@@ -5,6 +5,8 @@
 Atlas is a schedule-forward, Google-calendar-gated product with a working mutation pipeline.
 Current implementation focus: replace transcript-heavy conversation memory with an explicit conversation-state layer. Atlas now persists a user-scoped conversation snapshot with transcript, summary, entity registry, and discourse state so reference resolution can anchor on known objects instead of reconstructing intent from recent turns alone. Recent work still includes the prompt-asset cleanup, expanded live eval coverage around ambiguous routing and confirmed-mutation recovery, a consolidated `pnpm eval:all` loop plus suite-specific eval reports and prompt-improvement briefs for prompt iteration, chat-first prompt/docs framing, and consistent `referenceTime` threading through scheduling.
 
+DB rollout hardening is now part of the active release path: `packages/db` owns all Drizzle commands and config, root-level DB command aliases are removed, and production migrations are expected to run from GitHub Actions before Vercel production release.
+
 ## Near-term milestones
 
 - Finish the prompt-asset cleanup and eval loop:

docs/workflows/production-deploy-checklist.md

@@ -43,6 +43,16 @@ Set these in the Vercel project for the target environment before deploying:
 - `GOOGLE_LINK_TOKEN_SECRET`, `GOOGLE_CALENDAR_TOKEN_ENCRYPTION_KEY`, and `CRON_SECRET` should be unique per environment.
 - `GOOGLE_CALENDAR_TOKEN_ENCRYPTION_KEY` must be a base64-encoded 32-byte key.
 - `TELEGRAM_ALLOWED_USER_IDS` is required in all environments. The app should not boot without it.
+- Vercel Preview and Vercel Production must use different `DATABASE_URL` values. Preview must not point at the production database.
+
+## GitHub Actions migration secret
+
+Set the production database connection string in GitHub Actions secrets as `DATABASE_URL_PRODUCTION`.
+
+- This secret is for the hosted migration workflow, not for Vercel runtime configuration.
+- The migration workflow maps `DATABASE_URL_PRODUCTION` to `DATABASE_URL` only inside the job that runs `pnpm --filter @atlas/db db:check` and `pnpm --filter @atlas/db db:migrate`.
+- Keep the production secret scoped to the repo or environment that owns production releases.
+- In GitHub branch protection or rulesets, mark `Apply DB Migrations / apply-db-migrations` as a required status check for the production release path.
 
 ## Pre-deploy checks
 
@@ -55,18 +65,25 @@ Set these in the Vercel project for the target environment before deploying:
 
 1. Review the pending migration files under `packages/db/drizzle/`.
 2. Confirm the migration set matches the code being deployed.
-3. Apply migrations to the target database before or alongside the app deploy, but do not leave the database halfway between expected schema versions.
-4. If the environment has known partial-state risk, verify the release migration is safe to rerun or has an explicit recovery plan.
-
-Atlas does not yet have a fully documented hosted migration runner. For now, production releases must include an explicit operator-applied migration step.
+3. Confirm the database commands are run only through `packages/db`:
+   - `cd packages/db && DATABASE_URL=... pnpm db:generate`
+   - `cd packages/db && DATABASE_URL=... pnpm db:check`
+   - `cd packages/db && DATABASE_URL=... pnpm db:migrate`
+   - or the equivalent `pnpm --filter @atlas/db ...` form with `DATABASE_URL` already set
+4. Merge the release to `main` and let [`.github/workflows/apply-db-migrations.yml`](/Users/maxlin/Code/Atlas/.github/workflows/apply-db-migrations.yml) run against `DATABASE_URL_PRODUCTION`.
+5. Do not apply production migrations from a local shell. The GitHub Actions migration workflow is the only supported production migration runner.
+6. Confirm the migration workflow succeeds before starting or approving the production Vercel release.
+7. If the environment has known partial-state risk, verify the release migration is safe to rerun or has an explicit recovery plan.
 
 ## Deploy
 
 1. Push the release branch and confirm the intended commit SHA.
-2. Verify the Vercel project uses `apps/web` as the Root Directory and can access workspace files outside that directory.
-3. Confirm the target Vercel environment has all required env vars.
-4. Deploy the intended commit to Vercel.
-5. Confirm the deployment is healthy before switching any production traffic assumptions to it.
+2. Merge the intended commit to `main`.
+3. Verify [`.github/workflows/apply-db-migrations.yml`](/Users/maxlin/Code/Atlas/.github/workflows/apply-db-migrations.yml) passed on that `main` commit before promoting any production deploy.
+4. Verify the Vercel project uses `apps/web` as the Root Directory and can access workspace files outside that directory.
+5. Confirm the target Vercel environment has all required env vars, including separate Preview and Production `DATABASE_URL` values.
+6. Deploy the intended `main` commit to Vercel Production.
+7. Confirm the deployment is healthy before switching any production traffic assumptions to it.
 
 ## Register or verify the Telegram webhook
 
@@ -122,11 +139,13 @@ curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo"
 1. Confirm removed public planner/debug routes are still unavailable.
 2. Confirm linked-account reads do not expose raw Google access or refresh tokens.
 3. Confirm Vercel logs do not expose webhook secrets, cron secrets, link tokens, or decrypted Google credentials.
+4. Confirm the production deploy commit has a successful `apply-db-migrations` GitHub Actions run attached to it.
 
 ## Rollback notes
 
 - If the app deploy is bad but the schema is still compatible, roll traffic back to the last known good deployment.
 - If a migration is not backward-compatible, do not assume app rollback alone is sufficient.
+- If the migration workflow fails, do not continue with production deploy until the workflow is fixed or the migration issue is explicitly recovered.
 - If Google OAuth is failing after deploy, first verify `APP_BASE_URL`, `GOOGLE_OAUTH_REDIRECT_URI`, and the Google Cloud OAuth client configuration all match exactly.
 - If Telegram delivery fails after deploy, verify webhook registration, secret-token alignment, and Vercel route health before changing app code.
 

docs/workflows/vercel-telegram-webhook.md

@@ -27,6 +27,8 @@ Set these in the Vercel project for the target environment before deploying:
 - `GOOGLE_CALENDAR_TOKEN_ENCRYPTION_KEY`
 - `CRON_SECRET`
 
+Vercel Preview and Vercel Production must use different `DATABASE_URL` values. Preview must not target the production database.
+
 ## Route expectations
 
 - The Telegram webhook endpoint is `POST /api/telegram/webhook`.
@@ -39,7 +41,7 @@ Set these in the Vercel project for the target environment before deploying:
 2. Set the framework to Next.js.
 3. Set the Root Directory to `apps/web`.
 4. Enable the Vercel setting that allows the build to access workspace files outside the Root Directory if Vercel does not detect it automatically.
-5. Add the required environment variables in Vercel for Preview or Production.
+5. Add the required environment variables in Vercel for Preview or Production, including separate Preview and Production `DATABASE_URL` values.
 6. Deploy the latest `main` commit.
 
 ## Register the Telegram webhook
@@ -73,7 +75,7 @@ curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo"
 ## Notes
 
 - Vercel only hosts the protected cron endpoints. Scheduled follow-up dispatch and Google Calendar reconciliation now come from GitHub Actions via [`.github/workflows/send-followups.yml`](/Users/maxlin/Code/Atlas/.github/workflows/send-followups.yml) and [`.github/workflows/reconcile-google-calendar.yml`](/Users/maxlin/Code/Atlas/.github/workflows/reconcile-google-calendar.yml), not from Vercel Cron Jobs.
+- Production database migrations are owned by `packages/db` and are applied by [`.github/workflows/apply-db-migrations.yml`](/Users/maxlin/Code/Atlas/.github/workflows/apply-db-migrations.yml), not by ad hoc local commands or Vercel deploy hooks.
 - Do not log the webhook secret in Vercel function logs or error output.
 - Keep the route handler thin and continue moving persistence and planning behavior into workspace packages.
 - After the first Vercel smoke test, the next backend milestone is replacing the `processInboxItem` stub with planner-owned persistence that reads canonical `inbox_items`, creates validated `tasks`, and records `planner_runs` as operational audit state.
-- End-to-end deployability is not fully hardened yet. Follow-up work should add a hosted migration-apply workflow, rename or replace any misleading generate-only migration commands, and document a repeatable production deploy checklist that covers schema application, deployment, webhook registration, and post-deploy verification.

package.json

@@ -15,9 +15,6 @@
     "typecheck": "pnpm -r typecheck",
     "test": "pnpm -r test",
     "telegram:webhook:set": "bash scripts/set-telegram-webhook.sh",
-    "db:generate": "pnpm --filter @atlas/db db:generate",
-    "db:migrate": "pnpm --filter @atlas/db db:migrate",
-    "db:studio": "pnpm --filter @atlas/db db:studio",
     "db:test:start": "bash scripts/db-test-start.sh",
     "db:test:stop": "bash scripts/db-test-stop.sh",
     "db:test:reset": "bash scripts/db-test-reset.sh"

packages/db/drizzle.config.ts

@@ -1,28 +1,17 @@
-import { existsSync } from "node:fs";
-import path from "node:path";
-import { loadEnvFile } from "node:process";
-import { fileURLToPath } from "node:url";
-
 import { defineConfig } from "drizzle-kit";
+const databaseUrl = process.env.DATABASE_URL;
 
-const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-
-loadLocalEnv(path.join(rootDir, "apps/web/.env.local"));
-loadLocalEnv(path.join(rootDir, "apps/web/.env.test.local"));
-loadLocalEnv(path.join(rootDir, ".env.local"));
-loadLocalEnv(path.join(rootDir, ".env.test.local"));
+if (!databaseUrl) {
+  throw new Error(
+    "packages/db/drizzle.config.ts requires DATABASE_URL in the environment. Run Drizzle commands from packages/db or via `pnpm --filter @atlas/db ...` with DATABASE_URL already set."
+  );
+}
 
 export default defineConfig({
   schema: "./src/schema.ts",
   out: "./drizzle",
   dialect: "postgresql",
   dbCredentials: {
-    url: process.env.DATABASE_URL ?? "postgresql://postgres@localhost:5432/atlas_test"
+    url: databaseUrl
   }
 });
-
-function loadLocalEnv(filePath: string) {
-  if (existsSync(filePath)) {
-    loadEnvFile(filePath);
-  }
-}

packages/db/package.json

@@ -11,9 +11,10 @@
     "lint": "tsc --noEmit -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
-    "db:generate": "drizzle-kit generate",
-    "db:migrate": "drizzle-kit migrate",
-    "db:studio": "drizzle-kit studio"
+    "db:generate": "drizzle-kit generate --config=./drizzle.config.ts",
+    "db:check": "drizzle-kit check --config=./drizzle.config.ts",
+    "db:migrate": "drizzle-kit migrate --config=./drizzle.config.ts",
+    "db:studio": "drizzle-kit studio --config=./drizzle.config.ts"
   },
   "dependencies": {
     "@atlas/core": "workspace:*",