Agent skill
database-migration
Create database migrations from templates in the Commons monorepo. Use when the user wants to create a migration, add database columns, create tables, or modify the database schema.
Install this agent skill to your Project
npx add-skill https://github.com/jakewaldrip/.dotfiles/tree/main/misc/commons/.opencode/skills/database-migration
SKILL.md
Create Database Migration
When to Use
Schema changes only: adding/removing/modifying columns, tables, indexes, or feature flags.
When NOT to Use
Patient data operations (backfilling, updating, transforming data) → Use commons-packages/backend/jobs/ instead.
Create a Migration
npm run migrate:make <name-of-migration>
Creates file in commons-packages/backend/models/migrations/YYYYMMDDHHMMSS_name-of-migration.ts
Common Patterns
Standard Table Columns
table.uuid('id').primary().defaultTo(knex.raw('uuid_generate_v4()'));
table.timestamp('createdAt').defaultTo(knex.raw('now()')).notNullable();
table.timestamp('updatedAt').defaultTo(knex.raw('now()')).notNullable();
Soft Delete Columns
table.timestamp('deletedAt');
table.uuid('deletedById').references('id').inTable('user').onDelete('SET NULL').nullable();
table.index(['deletedById'], `${TABLE_NAME}_deleted_by_id_idx`);
Audit Columns
table.uuid('createdById').references('id').inTable('user').onDelete('SET NULL').nullable();
table.uuid('updatedById').references('id').inTable('user').onDelete('SET NULL').nullable();
Foreign Key with Index
table.uuid('patientId').references('id').inTable('patient').onDelete('CASCADE').notNullable();
table.index(['patientId'], `${TABLE_NAME}_patient_id_idx`);
Partial Index (for soft-deleted tables)
table.index(['columnName'], `${TABLE_NAME}_column_name_idx`, {
predicate: knex.whereNull('deletedAt'),
});
Enum Column (type-safe)
// Import TYPE only, hardcode values to prevent future breakage
import type { MyStatus } from '@commons/shared/graphql/enums/my-status.enum';
const VALUES = ['open', 'closed'] as const satisfies readonly MyStatus[];
table.enum('status', VALUES).notNullable();
Validation
# Run pending migrations
npm run migrate
# Test rollback
npm run migrate:rollback
Best Practices
- Always implement both
upanddownfor rollback capability - Check table existence before operations:
await knex.schema.hasTable(TABLE_NAME) - Add indexes for foreign keys to improve query performance
- Use CASCADE DELETE carefully—consider orphaned records in rollback
- For column removal: Rename to
drop_*first, then drop in a later migration
Templates and Examples
- Templates:
commons-packages/backend/models/migrations/examples/ - See TEMPLATES.md for additional patterns and helper functions
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
jakewaldrip/.dotfiles
react-component-writing
React component patterns and style guide for the Commons monorepo. Use when creating React components, working with GraphQL in components, or implementing internationalization with MessageFormat.
jakewaldrip/.dotfiles
graphite-cli
Use Graphite CLI (gt) for stacked PRs and branch management. Use when creating branches, committing changes, submitting PRs, syncing with trunk, or managing stacked pull requests.
jakewaldrip/.dotfiles
test-running
Run Jest tests in the Commons monorepo. Use when testing code changes, validating implementations, debugging test failures, or when the user mentions running tests.
jakewaldrip/.dotfiles
document-type-adding
Add new document types to the DocuSign integration in the Commons monorepo. Use when the user wants to add a patient document, consent form, or agreement to the DocuSign workflow.
jakewaldrip/.dotfiles
dataloader-dual-mode-migration
Migrate dataloaders to dual-mode pattern supporting both patientId and enrollmentId for Member Model 2.0. Use when converting a patient-based dataloader to support the MemberModelV2Switch.
jakewaldrip/.dotfiles
feature-flag-create-or-remove
Create or remove feature flags in the Commons application. Use when the user wants to add a new feature flag, delete a feature flag, or asks about feature flag naming conventions.
Didn't find tool you were looking for?