SOC2-05: Establishing an Auditable Database Migration History

Compliance context: This post documents a change management finding raised during SOC 2 audit preparation (Control SOC2-05) and the recommended remediation steps.

Background

SOC 2's Change Management control (CC8) requires that changes to system components — including the database schema — are authorised, tracked, and auditable. Without a versioned record of schema changes, an auditor cannot confirm what changed, when it changed, or who approved it.

The Problem

The project's drizzle.config.ts nominates ./src/db/migrations as the migrations output directory, but that directory was never present in the repository. Schema changes were applied using the db:push script, which runs drizzle-kit push — a convenience command that introspects the current Drizzle schema and alters the live database in place.

While drizzle-kit push is useful for rapid local development, it has a critical compliance gap: it generates no migration files. There is therefore no committed, reviewable record of schema evolution.

The Remediation

Replace the push-based workflow with Drizzle's generate-and-migrate workflow:

1. Generate migration files

npm run db:generate

This runs drizzle-kit generate and writes one or more timestamped SQL migration files into ./src/db/migrations. Each file represents a discrete, incremental schema change.

2. Commit the migrations directory

git add ./src/db/migrations
git commit -m "chore: add versioned migration files (SOC2-05)"

Once committed, the migrations directory becomes part of the repository's permanent history. Every future schema change must go through a pull request, giving you code review, approval records, and a full audit trail.

3. Update CI/CD to run migrations on deploy

Replace any invocation of drizzle-kit push in your deployment pipeline with:

npm run db:migrate

This runs drizzle-kit migrate, which applies only the pending migration files — it will never alter the database in an untracked way.

Why This Matters for SOC 2

Requirement	Push workflow	Generate + Migrate workflow
Auditable change history	❌ No files committed	✅ Every change is a committed SQL file
Change review / approval	❌ Applied directly	✅ Changes go through pull request review
Rollback capability	❌ Manual reconstruction	✅ Previous migration files are versioned
Consistent environments	⚠️ Drift possible	✅ All environments run the same migrations

Summary

Switching from drizzle-kit push to the drizzle-kit generate + drizzle-kit migrate workflow is a small operational change with significant compliance benefits. It brings database schema changes into the same review and audit pipeline as application code, directly satisfying the SOC 2 Change Management control requirement.