schema-change-checklist

Guides adding database columns through Drizzle schema, OpenAPI, codegen, and API route updates.

Updated Jun 15, 2026
One-click install
npx skills add https://github.com/ravenslight2010/Production-run-calculator --skill schema-change-checklist-ravenslight2010
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: schema-change-checklist
Source: https://github.com/ravenslight2010/Production-run-calculator/tree/main/.agents/skills/schema-change-checklist
Command: npx skills add https://github.com/ravenslight2010/Production-run-calculator --skill schema-change-checklist-ravenslight2010

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Adding a column to an existing database table touches many layers — Drizzle schema, OpenAPI spec, generated types, route mappers, and upsert clauses — and missing any one causes silent failures where fields never round-trip between the API and the database. ## Core Features & Use Cases - Ordered 10-step checklist: Walks through the Drizzle schema file, push-force migration, openapi.yaml request and response schemas, codegen, toApiItem, toDbValues, onConflictDoUpdate, typecheck, frontend consumers, and tests. - Common-miss catalog: Documents the seven most frequent omissions (e.g. the onConflictDoUpdate SET clause) so upserts do not silently keep stale values. - Additive-push-force constraints: Provides safe patterns for populated tables, such as using uniqueIndex instead of .unique() and avoiding composite primary keys with new columns. - Use Case: When asked to add an isPrep boolean to the mixes table, follow the checklist to update the schema, regenerate Zod types and React Query hooks, and wire the field through every route mapper without silent data loss. ## Quick Start Use the schema-change-checklist skill to add a new column to an existing database table and update all related API layers.

Frequently Asked Questions about schema-change-checklist

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a column to an existing Drizzle table safely?

Add the column with a drizzle builder like boolean or text using .notNull().default(value) so the migration is a single non-interactive DDL statement. Then run pnpm --filter @workspace/db run push-force and verify the column landed via information_schema.columns.

Why does my new database field not save on update?

The most common cause is a missing field in the onConflictDoUpdate SET clause, which makes upserts silently keep the old value. Also check that toDbValues includes the field, since Drizzle drops omitted values on UPDATE.

Should I use drizzle-kit push or push-force for schema changes?

Always use push-force in this repository. Plain push prompts interactively on populated tables, which hangs non-interactive post-merge scripts and production migrations that run without a TTY.

Can I add a unique constraint on a populated PostgreSQL table?

Do not use .unique() on a populated table because it triggers a truncate prompt that hangs non-interactive pushes. Use uniqueIndex("name").on(col1, col2) instead, which also works as an onConflictDoUpdate target.

Why is my new API field accepted but never returned to the frontend?

The field was likely added to the request schema in openapi.yaml but not the response schema, or codegen was not re-run. Update both schemas, run pnpm --filter @workspace/api-spec run codegen, and map the field in toApiItem.