# Database Migrations

> Use when adding or changing a DB migration or schema, running migrations, or debugging null/missing response fields after a migration — the migration rules (additive, reversible, immutable, seed-vs-migration, push filters into SQL) and the "null fields = unapplied migration" gotcha.

- **Type:** Skill
- **Install:** `agentstack add skill-kennguyen887-agent-foundation-database-migrations`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kennguyen887](https://agentstack.voostack.com/s/kennguyen887)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kennguyen887](https://github.com/kennguyen887)
- **Source:** https://github.com/kennguyen887/agent-foundation/tree/main/skills/database-migrations

## Install

```sh
agentstack add skill-kennguyen887-agent-foundation-database-migrations
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Database & migrations

## Migration rules
- NEVER alter database schema manually — always generate a migration file.
- Migration files are IMMUTABLE once merged to main; create a new one to fix, never edit an existing migration.
- Every migration MUST be reversible — implement both `up` and `down`.
- After generating a migration, verify it runs clean on a fresh DB before committing.
- NEVER seed production-specific data inside migration files; use dedicated seed scripts. (Migrations =
  schema/DDL or transforming existing data; seeds = initial/reference or test data/DML — keep them apart.)
- Push row filters into the SQL `WHERE` — never fetch broadly and post-filter in application code
  (`rows.filter(...)` on a status/type/date condition the DB could evaluate). If the repository helper
  can't express the condition, extend the helper with an optional query/selector param; don't work
  around it in the service layer.

## Null fields after migration (debugging gotcha)
When API response fields appear as `null` for a specific record type, **check whether the migration
that adds those columns has actually been applied** before assuming the data was never saved.

Root cause: a new nullable column is added via migration, but the migration hasn't run on the
environment being tested. JavaScript's `undefined != null` evaluates to `false` (loose equality), so
an absent column (`undefined`) looks identical to a null column in guards like
`ctx.doc.field != null ? ... : null` — both silently return `null`. Invisible until you inspect the schema.

**Rule:** before testing/debugging any feature that reads new DB columns, run `pnpm migration:run`
(or equivalent) on the local DB first. If response fields are unexpectedly null, check
`SHOW COLUMNS FROM ` before investigating code or data.

**Before concluding there's a deployment/CI bug**, verify whether the migration file itself was
actually merged to a deployed branch. Run `git log origin/rc..HEAD --oneline` (or equivalent base) —
if the migration commit appears there, the columns are absent simply because the PR hasn't merged
yet, not because of a pipeline failure. Don't add CI/deployment changes to fix a missing migration
that's still on a feature branch.

## Migration-related release readiness
Before a schema-touching feature is "done": all DB changes have migration files that run on a clean
DB; pending migrations have been applied on the local DB before testing schema-dependent features.
(Full release checklist → `release-safety` skill.)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kennguyen887](https://github.com/kennguyen887)
- **Source:** [kennguyen887/agent-foundation](https://github.com/kennguyen887/agent-foundation)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kennguyen887-agent-foundation-database-migrations
- Seller: https://agentstack.voostack.com/s/kennguyen887
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.