ruvnet--ruflo/plugins/ruflo-migrations/README.md

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

claude --plugin-dir plugins/ruflo-migrations

Agents

Agent	Model	Role
migration-engineer	sonnet	Generate sequential migrations, create up/down pairs, dry-run validation, rollback safety checks

Skills

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

Commands (6 subcommands)

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

Check	Severity	Description
Foreign key targets exist	Error	Referenced table/column must exist
Index coverage	Warning	WHERE/JOIN columns should be indexed
Data type compatibility	Error	ALTER COLUMN type must be compatible
NOT NULL without default	Error	Adding NOT NULL column requires DEFAULT
Down migration completeness	Warning	Every UP needs a corresponding DOWN
Destructive operations	Warning	DROP TABLE/COLUMN flagged for review
Naming conventions	Info	Tables plural, columns snake_case
Idempotency	Warning	Use 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 plugins/ruflo-migrations/scripts/smoke.sh
# Expected: "10 passed, 0 failed"

Architecture Decisions

• ADR-0001 — ruflo-migrations plugin contract (namespace-routing fix, smoke as contract)

Related Plugins

• 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