db-alembic-ops

insoln's avatarfrom insoln

Database + Alembic workflow for Slack-MM2 Sync (migrations, collapsed history, NEVER CANCEL guidance, and troubleshooting queries). Use when changing schema, debugging DB state, or dealing with migration failures.

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026
[SQL and Databases]

When & Why to Use This Skill

The db-alembic-ops skill is a specialized workflow designed for managing Postgres database migrations and schema integrity within the Slack-MM2 Sync environment. It leverages Alembic for version control and provides robust troubleshooting protocols for Docker-based deployments, ensuring seamless data synchronization and system stability during complex schema updates.

Use Cases

  • Executing and debugging Alembic migrations to synchronize database schemas with backend updates using standardized CLI commands.
  • Inspecting real-time database states, including entities and import job statuses, to verify data consistency during synchronization tasks.
  • Troubleshooting backend startup failures and migration bottlenecks by analyzing Docker container logs and executing direct psql queries.
  • Managing schema versioning and index updates while adhering to critical safety guidelines, such as the 'NEVER CANCEL' protocol for active migrations.
namedb-alembic-ops
descriptionDatabase + Alembic workflow for Slack-MM2 Sync (migrations, collapsed history, NEVER CANCEL guidance, and troubleshooting queries). Use when changing schema, debugging DB state, or dealing with migration failures.
licenseComplete terms in LICENSE.txt
compatibilityRequires Postgres access; Docker Compose recommended for dev.

Database & Alembic Operations

When to use

  • Running or debugging Alembic migrations
  • Inspecting entities, entity_relations, import_jobs state
  • Updating schema or indexes
  • Investigating migration/startup failures

Migrations

Canonical command (repo root):

  • alembic -c alembic.ini upgrade head

Important:

  • Migrations are also applied automatically when backend starts (lifespan hook). If backend appears “stuck”, it may be running migrations.
  • NEVER CANCEL a migration command once started.

Collapsed migration history

This repo uses a collapsed history model. For clean DBs, upgrade head is the expected flow. If you’re dealing with a historical DB/schema mismatch, follow the guidance in backend/README.md / docs/dev.md rather than guessing.

Common troubleshooting

  • View backend logs (migration errors surface there):

    • docker compose -f infra/docker-compose.dev.yml logs -f backend

  • Inspect DB quickly:

    • docker compose -f infra/docker-compose.dev.yml exec db \ psql -U slack-mm -d slack-mm -P pager=off -c "select * from import_jobs order by id desc limit 5;"

  • Inspect entities:

    • docker compose -f infra/docker-compose.dev.yml exec db \ psql -U slack-mm -d slack-mm -P pager=off -c "select id, entity_type, status from entities order by id desc limit 20;"