alembic-best-practices

Standardize SQLAlchemy database migrations with safe schema evolution patterns.

1|Updated May 21, 2026
One-click install
npx skills add https://github.com/hiddink-ai/hiddink-harness --skill alembic-best-practices-hiddink-ai
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: alembic-best-practices
Source: https://github.com/hiddink-ai/hiddink-harness/tree/main/templates/skills/alembic-best-practices
Command: npx skills add https://github.com/hiddink-ai/hiddink-harness --skill alembic-best-practices-hiddink-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pytest-alembic, alembic-utils, alembic-postgresql-enum, squawk-cli.

What problem does it solve?

This skill addresses the common pitfalls of database schema management, such as migration drift, data loss during column changes, and deployment locks, ensuring your database evolves safely alongside your application.

Core Features & Use Cases

  • Migration Safety: Provides patterns for zero-downtime schema changes using the expand-contract methodology.
  • Configuration Standards: Defines best practices for naming conventions, credential management, and async environment setup.
  • CI/CD Integration: Offers automated checks for pending migrations and static analysis for lock-risk DDL operations.

Quick Start

Use the alembic-best-practices skill to audit the current migration scripts for potential lock risks and verify that all models are correctly registered for autogeneration.

Frequently Asked Questions about alembic-best-practices

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

FAQPage Schema
How do I perform zero-downtime database migrations with SQLAlchemy?

Zero-downtime database migrations in SQLAlchemy require the expand-contract methodology, separating schema changes into backward-compatible phases. This pattern prevents deployment locks and data loss by expanding the schema first, migrating data, and then contracting old structures safely.

What's the best way to automate database migration checks in CI/CD?

Automating database migration checks in CI/CD involves running static analysis on DDL operations to detect lock risks and verifying pending migrations. Integrating testing frameworks ensures schema evolution workflows are validated against your existing database structures before deployment.

Why does Alembic migration drift happen and how do I prevent it?

Alembic migration drift happens when database schemas evolve outside of version control, causing inconsistencies between environments. Preventing drift requires standardizing migration workflows, maintaining strict naming conventions, and running automated validation checks to verify all models are correctly registered for autogeneration.

Does this database migration workflow support async SQLAlchemy environments?

Yes, this database migration workflow supports async SQLAlchemy environments through defined configuration standards. These standards establish best practices for credential management and async environment setup, ensuring your migration scripts run safely within asynchronous application contexts.

How do I detect lock-risk DDL operations in my Alembic migration scripts?

Detecting lock-risk DDL operations in Alembic migration scripts requires applying static analysis to audit your schema changes. This process identifies potentially blocking operations, ensuring your database schema evolution maintains zero-downtime deployment strategies without unexpected table locks.