morphic

README

morphic

A Go-first database migration tool with a Django-style workflow. Define your schema in YAML, generate type-safe Go migration files, and run them in-process — no Go toolchain required at runtime, no compiled binary to ship.

How migrations run. Generated migration files are real .go source — your IDE, gopls, and go vet treat them as ordinary Go. At runtime morphic migrate does not invoke go build. Instead it loads each .go file with yaegi, an embedded Go interpreter, and runs the migrations in the morphic process. The language inside migration files is "Go-like" — yaegi implements the Go spec but is not the official gc compiler, so a few features (cgo, deep reflection, some generics edge cases) work differently. For migrations generated by morphic generate this is invisible; for hand-edited migrations that import third-party packages, see Extending the yaegi Symbol Map.

✨ Why Go Migrations?

• 🔒 Type-safe at edit time: Migrations are real .go files interpreted by yaegi — your IDE, gopls, and go vet catch errors before they ever run
• ⚡ No build step at runtime: yaegi interprets the .go files directly; no go build, no temporary binary, no GOWORK juggling
• 🗄️ Database-agnostic schema: Write YAML once, deploy to PostgreSQL, MySQL, SQLite, or SQL Server — scripting migrations in Go (rather than raw SQL) means the same migration code works across all supported databases
• 🔀 DAG-based ordering: Migrations form a dependency graph so parallel branches merge cleanly
• 🔄 Auto change detection: Diff YAML schemas, generate only what changed
• ⚠️ Safe destructive ops: Field removals, table drops, and renames require explicit review
• 🛠 Optional standalone binary: The generated migrations/ directory is still a buildable Go module, so you can go build it for IDE type-checking or as an escape hatch

---

🚀 Quick Start

1. Install

go install github.com/ocomsoft/morphic@latest

2. Initialise your project

cd your-project
morphic init

This creates:

your-project/
└── migrations/
    ├── main.go     ← optional fallback entry point (`go build` still works)
    └── go.mod      ← dedicated migrations module (used by your IDE / gopls)

3. Define your schema

schema/schema.yaml:

defaults:
  postgresql:
    new_uuid: gen_random_uuid()
  mysql:
    new_uuid: uuid()
  sqlite:
    new_uuid: (lower(hex(randomblob(16))))

tables:
  - name: users
    fields:
      - name: id
        type: uuid
        primary_key: true
        default: new_uuid
      - name: email
        type: varchar
        length: 255
        nullable: false
      - name: created_at
        type: timestamp
        auto_create: true

  - name: posts
    fields:
      - name: id
        type: uuid
        primary_key: true
        default: new_uuid
      - name: title
        type: varchar
        length: 200
        nullable: false
      - name: user_id
        type: foreign_key
        foreign_key:
          table: users
          on_delete: CASCADE

The defaults section maps symbolic names (like new_uuid) to database-specific SQL expressions. Fields reference them by name — morphic resolves the correct expression for each target database at migration time.

4. Generate your first migration

morphic generate --name "initial"
# Creates: migrations/0001_initial.go

5. Apply to your database

export DATABASE_URL="postgresql://user:pass@localhost/mydb"
morphic migrate up

morphic migrate interprets the migration files in-process using yaegi and runs the embedded migration App. No go build, no temporary binary.

---

🔄 Day-to-Day Workflow

# 1. Edit your YAML schema
vim schema/schema.yaml

# 2. Preview what will be generated
morphic generate --dry-run

# 3. Generate the migration
morphic generate --name "add user preferences"
# Creates: migrations/0004_add_user_preferences.go

# 4. Review the SQL before applying
morphic migrate showsql

# 5. Apply
morphic migrate up

# 6. Verify
morphic migrate status

---

📋 migrate Subcommands

morphic migrate interprets the migration files in-process via yaegi and runs the embedded App. All arguments are forwarded:

morphic migrate up                       # apply all pending
morphic migrate up --to 0003_add_index   # apply up to a specific migration
morphic migrate down                     # roll back one
morphic migrate down --steps 3           # roll back multiple
morphic migrate status                   # show applied / pending
morphic migrate showsql                  # print SQL without running it
morphic migrate fake 0001_initial        # mark applied without running SQL
morphic migrate dag                      # show migration dependency graph

---

🏗️ Project Structure

your-project/
├── schema/
│   └── schema.yaml              ← your YAML schema definition
├── migrations/
│   ├── main.go                  ← binary entry point (generated by init)
│   ├── go.mod                   ← dedicated module (generated by init)
│   ├── 0001_initial.go          ← migration files (generated by morphic)
│   ├── 0002_add_posts.go
│   └── 0003_add_index.go
├── go.mod
└── main.go

---

🗄️ Database Support

Database	Status	Notes
PostgreSQL	✅ Full	UUID, JSONB, arrays, advanced types
MySQL	✅ Supported	JSON, AUTO_INCREMENT, InnoDB
SQLite	✅ Supported	Simplified types, basic constraints
SQL Server	✅ Supported	UNIQUEIDENTIFIER, NVARCHAR, BIT
Amazon Redshift	✅ Provider ready	SUPER JSON, IDENTITY sequences
ClickHouse	✅ Provider ready	MergeTree engine, Nullable types
TiDB	✅ Provider ready	MySQL-compatible, distributed
Vertica	✅ Provider ready	Columnar analytics
YDB (Yandex)	✅ Provider ready	Optional, native JSON
Turso	✅ Provider ready	Edge SQLite
StarRocks	✅ Provider ready	MPP analytics, OLAP
Aurora DSQL	✅ Provider ready	AWS serverless, PostgreSQL-compatible

PostgreSQL has been tested against real database instances. All other providers have comprehensive unit tests but may need additional validation for production.

---

⚠️ Destructive Operations

When a field removal, table drop, or rename is detected, morphic shows an interactive prompt before generating:

⚠  Destructive: field_removed on "users" (field: "legacy_col")
SQL: ALTER TABLE "users" DROP COLUMN "legacy_col"

> Generate       — include operation in migration
  Review         — include with // REVIEW comment
  Omit           — skip SQL; schema state still advances (SchemaOnly)
  IgnoreErrors   — include with IgnoreErrors: true
  Exit           — cancel migration generation

  Scope: [This only]  All remaining   All of this type

↑/↓ select • tab scope • enter confirm • esc cancel

Use Tab to cycle the scope — This only, All remaining (apply your choice to every subsequent destructive op), or All of this type (e.g. apply to all field_removed ops but still prompt for table_removed).

---

🔀 Branch & Merge

When two developers generate migrations concurrently the DAG develops branches:

0001_initial
├── 0002_add_messaging   (developer A)
└── 0003_add_payments    (developer B)

Resolve with a merge migration:

morphic generate --merge
# Creates: migrations/0004_merge_0002_add_messaging_and_0003_add_payments.go

---

⚙️ Configuration

Database connection

morphic migrate reads connection details from DATABASE_URL and DB_TYPE:

export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export DB_TYPE=postgresql   # optional, defaults to postgresql

If you prefer the optional fallback path of compiling migrations/ into a standalone binary, edit migrations/main.go to read additional vars (DB_HOST, DB_PORT, DB_USER, …) — see the Manual Build Guide.

Configuration file

migrations/morphic.config.yaml:

database:
  type: postgresql

migration:
  directory: migrations
  include_down_sql: true

output:
  verbose: false

See the Configuration Guide for complete options.

---

📖 Documentation

Guides

• Installation Guide
• Schema Format Guide — complete YAML schema reference
• Configuration Guide
• Manual Build Guide — GOWORK/GOTOOLCHAIN details for CI/CD
• Extending the yaegi Symbol Map — let interpreted migrations import third-party packages
• Claude Code Skill — auto-triggered AI assistant skill for schema-first migrations

Command Reference

Schema & Generation

Command	Description
init	Initialize migrations directory and config
generate	Generate migration files from YAML schema changes
generate empty	Create a blank migration for custom operations
generate dump-data	Generate a data-seeding migration from live DB

Migration Runtime

Command	Description
migrate	Run migrations in-process via yaegi

Inspection & Debugging

Command	Description
schema-diff	Show drift between YAML schema and migration state
db-diff	Compare live DB schema against migration state
current-state	Show reconstructed schema state as YAML
schema-to-sql	Convert merged YAML schema to SQL
schema-to-diagram	Generate Markdown docs with diagrams

Conversion Tools

Command	Description
db-to-schema	Reverse-engineer YAML schema from existing DB
struct-to-schema	Convert Go structs to YAML schema
find-includes	Discover schema includes from Go modules

🤖 Claude Code Skill

morphic includes a Claude Code skill that auto-triggers whenever Claude detects database schema work in your Go project. It enforces the correct workflow: edit schema/schema.yaml → generate migrations → avoid raw SQL.

Installing the Skill

Option 1: Personal skill (recommended — available in all Go projects):

cp -r skills/ ~/.claude/skills/go-morphic

Option 2: Plugin (if the repo is registered as a Claude Code plugin):

The .claude-plugin/ directory is detected automatically when installed.

What the Skill Does

• Auto-triggers when you ask Claude to add tables, fields, indexes, foreign keys, or modify columns
• Guides Claude through init → schema edit → migration generation → SQL preview → verification
• Provides quick reference for field types, properties, indexes, defaults, and type mappings
• Enforces schema-first workflow — RunSQL only as a last resort
• Covers both new project bootstrapping and ongoing schema changes

See skills/SKILL.md for the full skill content and docs/claude-code-skill.md for detailed usage.

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Add tests for new functionality
4. Ensure all tests pass: go test ./...
5. Submit a pull request

📄 License

MIT License — see LICENSE file for details.

---

Ready to get started? Run morphic init in your project directory.

Documentation

Overview

MIT License

Copyright (c) 2025 OcomSoft

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.