portal-db-migrations

Create reversible PostgreSQL migrations with dbmate for catalog, user, and pgvector schemas.

Updated Jul 27, 2026
One-click install
npx skills add https://github.com/ArthurZizumbo/karisma-data --skill portal-db-migrations-arthurzizumbo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: portal-db-migrations
Source: https://github.com/ArthurZizumbo/karisma-data/tree/main/.claude/skills/portal-db-migrations
Command: npx skills add https://github.com/ArthurZizumbo/karisma-data --skill portal-db-migrations-arthurzizumbo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Managing schema changes for a PostgreSQL 15 + pgvector database without a disciplined migration workflow leads to drift, irreversible changes, and inconsistent environments. This Skill enforces a strict dbmate-based process so every schema change for the Portal Centralizado de Datos Financieros is versioned, reversible, and reproducible. ## Core Features & Use Cases - Reversible migrations: Every change uses migrate:up and migrate:down sections, with db/schema.sql regenerated and committed after each make db-up. - Canonical schema templates: Ready-made SQL for catalog_source, catalog_field, catalog_tribal_note, app_user (with Argon2-hashed seed users), export_job, and the pgvector extension with an HNSW index for embeddings. - Non-negotiable rules: Never edit applied migrations, never use SQLModel.metadata.create_all() in production, always use TIMESTAMPTZ DEFAULT now(), explicit ON DELETE clauses, and pre-hashed Argon2 seed passwords. - Use Case: When adding a new embedding column to catalog_field for the RAG phase, run make db-new SLUG=enable_pgvector, paste the provided up/down SQL, and apply it with make db-up. ## Quick Start Ask the assistant to create a new reversible dbmate migration for the Portal database, for example to add the catalog tables or enable pgvector, and have it generate the SQL file and apply it with the make commands.

Frequently Asked Questions about portal-db-migrations

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

FAQPage Schema
How do I create a new database migration with dbmate?

Run `make db-new SLUG=your_slug`, which calls `dbmate new` and creates a timestamped SQL file under `db/migrations/`. Fill in the `-- migrate:up` and `-- migrate:down` sections, then apply it with `make db-up`.

How do I add pgvector and an embedding column in PostgreSQL?

Create a migration that runs `CREATE EXTENSION IF NOT EXISTS vector`, adds an `embedding VECTOR(768)` column to `catalog_field`, and builds an HNSW index with `vector_cosine_ops`. The down migration drops the index, column, and extension.

Can I edit a dbmate migration that was already applied?

No. Applied migrations must never be edited; instead create a new migration that corrects the previous change. This keeps the migration history consistent across all environments.

Should I use SQLModel create_all or migrations for schema changes?

Use dbmate migrations exclusively for schema changes in production. SQLModel models only reflect the schema; `SQLModel.metadata.create_all()` is prohibited as a schema change mechanism.

How do I seed users with hashed passwords in a SQL migration?

Generate Argon2 hashes beforehand with pwdlib, for example `python -c "from pwdlib import PasswordHash; print(PasswordHash.recommended().hash('...'))"`, then insert the pre-hashed values in the migration. Never store plaintext passwords in SQL seeds.

How do I roll back the last applied dbmate migration?

Run `make db-rollback`, which invokes `dbmate rollback` to revert the most recent migration using its `migrate:down` section. Use `dbmate status` to check which migrations are applied or pending.