db-safety

name	db-safety
description	PreToolUse hooks that block direct production database access and raw SQL write operations. Prevents bypass scripts that skip Drizzle ORM migration tracking, and HARD BLOCKS raw psql writes with no bypass — all writes must go through Admin API.
user-invocable	false

Database Safety Hooks

Two PreToolUse hooks that enforce safe database access patterns.

Hook 1: Block Production Bypass Scripts

Script: scripts/preToolUse-block-prod-bypass.py Matcher: Write Triggers when: A .ts/.js file is being written that contains BOTH a production database hostname pattern (ep-flat-block, PROD_DATABASE_URL) AND a direct database client call (neon(, new Pool(, `sql``).

Purpose: Prevents creating scripts that run raw SQL against production, bypassing Drizzle ORM migration tracking. Legitimate files (migrate.ts, import scripts, db/index.ts) are allowlisted.

On block: Directs Claude to use npm run db:migrate or Vercel CI/CD instead.

Hook 2: Block Raw SQL Writes (Poka-Yoke — User Permission Required)

Script: scripts/preToolUse-block-raw-sql-writes.py Matcher: Bash Triggers when: A Bash command invokes a SQL CLI tool (psql, mysql, sqlite3, pgcli) with a write operation keyword (UPDATE, INSERT, DELETE, ALTER, DROP, TRUNCATE).

Purpose: Blocks all direct SQL write operations by default. All writes MUST go through Admin API endpoints.

System-level bypass: --user-approved-raw-sql-write flag exists as an emergency safety net.

🚨 SOP: NEVER use the bypass flag without explicit user permission in the current conversation. The bypass is for genuine emergencies where the user has been asked and approved. It is NOT for convenience or "no API exists yet" — in that case, create the API endpoint first.

If no API endpoint exists: Create the endpoint first, then use it. Ask user for permission to create the new endpoint.

Why: Direct SQL bypasses audit trails (updatedByUserId), validation, and access control. The Admin API ensures every write is attributed to a specific user.

Hook 3: Block Manual Migration Files (Poka-Yoke)

Script: scripts/preToolUse-block-manual-migration.py Matcher: Write Triggers when: A .sql file is being written inside a migrations/ directory.

Purpose: Migration files MUST be generated by drizzle-kit generate, never hand-written. Manual SQL files bypass drizzle's journal tracking (meta/_journal.json) and cause hash mismatches, phantom entries in drizzle.__drizzle_migrations, and future migration failures.

Bypass: --i-have-confirmed-drizzle-kit-generate-cannot-produce-this-migration-and-manual-sql-is-the-only-option flag as a SQL comment in the file. Requires explicit user permission.

Hook 4: Block Manual Production Migrations (Poka-Yoke)

Script: scripts/preToolUse-block-manual-prod-migrate.py Matcher: Bash Triggers when: A Bash command contains production migration indicators (migrate:prod, .env.production, migrate-prod.js, drizzle-kit migrate with prod context).

Purpose: CI/CD handles production migrations automatically on push to master. Running migrate:prod locally bypasses the pipeline.

Correct flow: Generate migration → commit → push to master → CI/CD applies to prod.

Bypass: --user-approved-manual-prod-migration-instead-of-the-normal-cicd-auto-migration flag. Only when CI/CD is genuinely broken/unavailable AND user has explicitly approved in the current conversation.