Skip to content

installation.md

Latest commit

 

History

History
265 lines (186 loc) · 6.68 KB

installation.md

File metadata and controls

265 lines (186 loc) · 6.68 KB
Raw

Installation Guide

This guide covers installing and setting up morphic for Go-based database migration management.

Prerequisites

  • Go 1.24 or later — Required to install/build the morphic CLI itself; not required at runtime when applying migrations (the Starlark interpreter executes them in-process — see How migrations run)
  • Git — For cloning the repository
  • CGO_ENABLED=1 — Required only when using SQLite; PostgreSQL, MySQL, and SQL Server do not need CGO
  • Database — One of the supported databases: PostgreSQL, MySQL, SQLite, or SQL Server

How migrations run

morphic migrate does not invoke go build. Each migration .star file in your project is loaded by the embedded Starlark-Go interpreter and executed in the morphic CLI process. Starlark is a deterministic, Python-like language designed for configuration and scripting — migrations generated by morphic generate use it transparently.

Installation Methods

Option 1: Go Install (Recommended)

go install github.com/ocomsoft/morphic@latest

This places the morphic binary in $(go env GOPATH)/bin. Ensure that directory is on your PATH.

Option 2: Build from Source

git clone https://github.com/ocomsoft/morphic.git
cd morphic
go build -o morphic .

# Optionally install globally
sudo cp morphic /usr/local/bin/

Option 3: Download Pre-Built Binary

Download pre-built binaries from the releases page:

# Linux/macOS
curl -L https://github.com/ocomsoft/morphic/releases/latest/download/morphic-linux-amd64 -o morphic
chmod +x morphic

# Windows
curl -L https://github.com/ocomsoft/morphic/releases/latest/download/morphic-windows-amd64.exe -o morphic.exe

Verification

Confirm the installation is working:

morphic --help
morphic init --help

Quickstart: Starlark Migration Workflow

This is the primary workflow. Migrations are generated as Starlark source files (.star) and applied in-process via the Starlark interpreter — no compile step required at runtime.

1. Install

go install github.com/ocomsoft/morphic@latest

2. Initialise Your Project

Run init from the root of your project. This creates a migrations/ subdirectory:

morphic init

3. Define Your Schema

Edit schema/schema.star to describe your database tables and fields:

database(
    name = "myapp",
    version = "1.0.0",
)

table(
    name = "users",
    fields = [
        field(name = "id", type = "uuid", primary_key = True, default = "new_uuid"),
        field(name = "email", type = "varchar", length = 255, nullable = False),
        field(name = "created_at", type = "timestamp", default = "now", auto_create = True),
    ],
)

4. Generate Your First Migration

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

5. Apply Migrations

morphic migrate up

This loads every .star file in migrations/ via the Starlark interpreter and runs them in-process. No compile step required.

6. Ongoing Workflow

After each change to schema.star, regenerate and apply:

morphic generate
morphic migrate up

Project Layout After Init

myapp/
├── go.mod
├── schema/
│   └── schema.star          # Starlark schema definitions
└── migrations/
    └── 0001_initial.star    # generated Starlark migration (after first morphic generate)

Database Configuration

The morphic CLI reads connection settings from environment variables.

PostgreSQL

export MORPHIC_DB_TYPE=postgresql
export MORPHIC_DB_HOST=localhost
export MORPHIC_DB_PORT=5432
export MORPHIC_DB_USER=postgres
export MORPHIC_DB_PASSWORD=yourpassword
export MORPHIC_DB_NAME=yourdb
export MORPHIC_DB_SSLMODE=disable

MySQL

export MORPHIC_DB_TYPE=mysql
export MORPHIC_DB_HOST=localhost
export MORPHIC_DB_PORT=3306
export MORPHIC_DB_USER=root
export MORPHIC_DB_PASSWORD=yourpassword
export MORPHIC_DB_NAME=yourdb

SQLite

SQLite requires CGO. Build with CGO_ENABLED=1:

export MORPHIC_DB_TYPE=sqlite
export MORPHIC_DATABASE_URL=./database.db

Development .env File

Create a .env file for local development:

MORPHIC_DB_TYPE=postgresql
MORPHIC_DB_HOST=localhost
MORPHIC_DB_PORT=5432
MORPHIC_DB_USER=dev_user
MORPHIC_DB_PASSWORD=dev_password
MORPHIC_DB_NAME=myapp_development

Production Environment

MORPHIC_DB_TYPE=postgresql
MORPHIC_DB_HOST=production-db-host
MORPHIC_DB_USER=app_user
MORPHIC_DB_PASSWORD=secure_password
MORPHIC_DB_NAME=myapp_production

Troubleshooting

"Command not found"

# Ensure GOPATH/bin is on your PATH
export PATH=$PATH:$(go env GOPATH)/bin

# Or use the full path
./morphic --help

"No schema files found"

# Check that schema.star exists in the expected location
find . -name "schema.star" -type f

# Verify directory structure
ls -la schema/

Database Connection Issues

# Check that environment variables are set
echo $MORPHIC_DB_HOST
echo $MORPHIC_DB_USER

# Test a direct connection
psql -h $MORPHIC_DB_HOST -U $MORPHIC_DB_USER -d $MORPHIC_DB_NAME

Schema Parsing Errors

# Validate your schema file syntax using morphic directly
morphic validate

SQLite: CGO Errors

SQLite requires CGO at the time the morphic CLI binary is built. If you installed morphic via go install and SQLite errors appear at runtime, rebuild with CGO enabled:

CGO_ENABLED=1 go install github.com/ocomsoft/morphic@latest

SQLite requires CGO at the time the morphic CLI binary is built. If you installed morphic via go install and SQLite errors appear at runtime, rebuild with CGO enabled as shown above.

Legacy SQL Workflow

For projects using the older YAML-to-SQL+Goose workflow, initialise with:

morphic init --sql

This generates raw .sql migration files managed by Goose instead of Starlark source files. See docs/commands/init.md for full details.

Next Steps

  1. Read the Configuration Guide to customise settings
  2. Review Schema Format Documentation for Starlark schema syntax
  3. Explore Command Documentation for detailed usage
  4. Set up CI/CD integration using --check and --silent flags

Support

  • Documentation: Browse the /docs directory for detailed guides
  • Examples: Check the /example directory for sample schemas
  • Issues: Report problems on GitHub Issues
  • Discussions: Join GitHub Discussions for questions

For detailed command usage, see the Commands Documentation.