# Migration

How to change the database schema in this repo.

- Repository: https://github.com/kortix-ai/suna (20345 stars)
- Category: Data and ML
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add kortix-ai/suna --skill migration -g -a claude-code -y`
Codex: `npx skills add kortix-ai/suna --skill migration -g -a codex -y`
Cursor: `npx skills add kortix-ai/suna --skill migration -g -a cursor -y`
Gemini CLI: `npx skills add kortix-ai/suna --skill migration -g -a gemini-cli -y`

## Description

How to change the database schema in this repo. Current engine: node-pg-migrate, with SQL generated from Drizzle schema changes when possible. Load whenever you add/alter/drop a table, column, enum, index, constraint, RLS/function/grant, or any file under packages/db/migrations.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Database migrations

The canonical, detailed runbook is `packages/db/MIGRATIONS.md`. This skill is a
short safety wrapper; if anything here seems incomplete, trust that file and the
current `package.json` scripts.

> **Also load the `learnings` skill.** It carries the incident rules that apply
> while WRITING a migration, above all: never backfill data inside a
> single-transaction `.sql` migration (2026-08-10 v0.12.7 prod outage; enforced
> by the `backfill-safe` lint guard, but the rule explains what to build
> instead: a batched `.concurrent.ts` pass or an out-of-band runbook).

## Current model

- **Engine:** node-pg-migrate, invoked by `packages/db/scripts/migrate.ts`.
- **Schema source:** `packages/db/src/schema/kortix.ts` for the Drizzle-modeled
  `kortix` schema.
- **Migration files:** immutable SQL files in `packages/db/migrations/`, named
  with a 17-digit UTC timestamp (`YYYYMMDDHHMMSSmmm_slug.sql`).
- **Applied-state table:** `kortix_migrations.pgmigrations` (node-pg-migrate
  tracks migration names; it does not checksum file contents).
- **Deploy:** `deploy-dev.yml` and `deploy-prod.yml` run `pnpm --filter
  @kortix/db migrate` before the ECS Fargate rollout (`infra/scripts/ecs-deploy.sh`).
  Migrations always land before new code.

## Rules

The rest: https://github.com/kortix-ai/suna/blob/HEAD/.agents/skills/migration/SKILL.md