ContextQMD
Back to Ruflo

ruflo-migrations

plugins/ruflo-migrations/README.md

3.6.303.8 KB
Original Source

ruflo-migrations

Schema migration management -- generate, validate, dry-run, and rollback database migrations.

Overview

Generates sequentially numbered database migrations with up/down SQL pairs for rollback safety. Includes dry-run mode to preview SQL without executing, validation checks for foreign key consistency, index coverage, and naming conventions, plus full migration history tracking in AgentDB.

Installation

bash
claude --plugin-dir plugins/ruflo-migrations

Agents

AgentModelRole
migration-engineersonnetGenerate sequential migrations, create up/down pairs, dry-run validation, rollback safety checks

Skills

SkillUsageDescription
migrate-create/migrate-create <name>Create a new sequentially numbered migration with up/down SQL files
migrate-validate/migrate-validateValidate pending migrations for FK consistency, rollback safety, and best practices

Commands (6 subcommands)

bash
migrate create <name>        # Create NNN_name.up.sql and NNN_name.down.sql
migrate up [--dry-run]       # Apply pending migrations (or preview SQL)
migrate down [--steps N]     # Rollback last N migrations (default: 1)
migrate status               # Show applied/pending migration status
migrate validate             # Validate pending migrations for safety
migrate history              # Show full migration execution history

Validation Checks

CheckSeverityDescription
Foreign key targets existErrorReferenced table/column must exist
Index coverageWarningWHERE/JOIN columns should be indexed
Data type compatibilityErrorALTER COLUMN type must be compatible
NOT NULL without defaultErrorAdding NOT NULL column requires DEFAULT
Down migration completenessWarningEvery UP needs a corresponding DOWN
Destructive operationsWarningDROP TABLE/COLUMN flagged for review
Naming conventionsInfoTables plural, columns snake_case
IdempotencyWarningUse IF EXISTS / IF NOT EXISTS

Migration File Format

migrations/
  001_create_users.up.sql
  001_create_users.down.sql
  002_add_email_index.up.sql
  002_add_email_index.down.sql

Compatibility

  • CLI: pinned to @claude-flow/cli v3.6 major+minor.
  • Verification: bash plugins/ruflo-migrations/scripts/smoke.sh is the contract.

Namespace coordination

This plugin owns the migrations AgentDB namespace (kebab-case is implicit when the plugin name is the intent — same documented exception as federation). Follows the convention from ruflo-agentdb ADR-0001 §"Namespace convention". Reserved namespaces (pattern, claude-memories, default) MUST NOT be shadowed.

migrations is accessed via memory_* tools (namespace-routed). Tracks migration metadata, applied/pending status, and validation results.

Routing note: Earlier versions of these skills used agentdb_hierarchical-* and agentdb_pattern-store with namespace arguments — those tool families route by tier/ReasoningBank and ignore namespace strings. ADR-0001 fixed the skills to use memory_* for namespaced reads/writes.

Verification

bash
bash plugins/ruflo-migrations/scripts/smoke.sh
# Expected: "10 passed, 0 failed"

Architecture Decisions

  • ruflo-agentdb — namespace convention owner; defines the routing rules ADR-0001 fixes a violation of
  • ruflo-adr -- Document schema change decisions as ADRs
  • ruflo-ddd -- Align migration boundaries with aggregate roots
  • ruflo-observability -- Track migration execution duration and failure rates

License

MIT