Configuration

go-migration supports configuration through YAML files, JSON files, and environment variables. When using migrator.Run(), the config file defaults to migration.json in the current directory. You can also specify a path with the --config flag.

# Uses migration.json in the current directory (default)
go-migration migrate

# Specify a custom config file
go-migration migrate --config=./config/production.json
go-migration migrate --config=./config/go-migration.yaml

Configuration File

The configuration file defines your database connection, pool settings, migration table name, and logging preferences.

{
  "driver": "postgres",
  "host": "localhost",
  "port": 5432,
  "database": "myapp",
  "username": "dbuser",
  "password": "dbpass",
  "sslmode": "disable",
  "max_open_conns": 25,
  "max_idle_conns": 5,
  "conn_max_lifetime": 300,
  "migration_table": "migrations",
  "log_level": "info"
}

# Database driver: postgres, mysql, or sqlite
driver: postgres

# Connection details
host: localhost
port: 5432
database: myapp
username: dbuser
password: dbpass

# SSL mode (PostgreSQL only)
sslmode: disable

# Connection pool settings
max_open_conns: 25
max_idle_conns: 5
conn_max_lifetime: 300 # seconds

# Migration settings
migration_table: migrations

# Logging
log_level: info

Supported Fields

Environment Variable Fallback

go-migration checks for environment variables when a field is not set in the configuration file. This lets you keep secrets out of config files and override settings per environment.

Naming Convention

Environment variables use uppercase names with a DB_ prefix for connection fields:

Directory Settings

go-migration also supports environment variables for directory configuration with the GOMIGRATE_ prefix:

Resolution Order

For each field, go-migration resolves the value in this order:

1. Configuration file — value from YAML or JSON
2. Environment variable — fallback if the config field is empty or missing
3. Default value — built-in default if neither is set (for optional fields)

# Set environment variables for production
export DB_HOST=prod-db.example.com
export DB_PORT=5432
export DB_NAME=myapp_production
export DB_USER=app_user
export DB_PASSWORD=s3cret

Minimal Config with Environment Variables

You can use a minimal configuration file and let environment variables handle the sensitive values:

{
  "driver": "postgres",
  "sslmode": "require",
  "migration_table": "schema_migrations",
  "log_level": "info"
}

driver: postgres
sslmode: require
migration_table: schema_migrations
log_level: info
# host, port, database, username, password
# resolved from DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD

Default Values

Optional settings use these defaults when not specified in the config file or environment:

Driver-Specific Examples

driver: postgres
host: localhost
port: 5432
database: myapp
username: postgres
password: secret
sslmode: disable
max_open_conns: 25
max_idle_conns: 5
conn_max_lifetime: 300
migration_table: migrations
log_level: info

driver: mysql
host: localhost
port: 3306
database: myapp
username: root
password: secret
max_open_conns: 25
max_idle_conns: 5
conn_max_lifetime: 300
migration_table: migrations
log_level: info

driver: sqlite
database: ./data/myapp.db
migration_table: migrations
log_level: info

Multi-Connection Configuration

The default field specifies which connection is used when no specific connection is requested. The connections field is a map of named database connections, where each key is a connection name and the value contains the connection settings.

Directory and table settings (migration_dir, seeder_dir, factory_dir, migration_table, log_level) are defined at the top level and apply globally across all connections.

{
  "default": "postgres",
  "connections": {
    "postgres": {
      "driver": "postgres",
      "host": "${DB_HOST}",
      "port": 5432,
      "database": "${DB_DATABASE}",
      "username": "${DB_USERNAME}",
      "password": "${DB_PASSWORD}",
      "sslmode": "disable"
    },
    "mysql": {
      "driver": "mysql",
      "host": "${MYSQL_HOST}",
      "port": 3306,
      "database": "${MYSQL_DATABASE}",
      "username": "${MYSQL_USERNAME}",
      "password": "${MYSQL_PASSWORD}"
    }
  },
  "migration_dir": "database/migrations",
  "seeder_dir": "database/seeders",
  "factory_dir": "database/factories",
  "migration_table": "migrations",
  "log_level": "info"
}

# Default connection name
default: postgres

# Multiple database connections
connections:
  postgres:
    driver: postgres
    host: ${DB_HOST}
    port: 5432
    database: ${DB_DATABASE}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    sslmode: disable

  mysql:
    driver: mysql
    host: ${MYSQL_HOST}
    port: 3306
    database: ${MYSQL_DATABASE}
    username: ${MYSQL_USERNAME}
    password: ${MYSQL_PASSWORD}

# Directory and settings (apply globally)
migration_dir: database/migrations
seeder_dir: database/seeders
factory_dir: database/factories
migration_table: migrations
log_level: info

When using the --config flag, the multi-connection structure works the same way:

go-migration migrate --config=./config/migration.json

Environment Variable Interpolation

You can embed environment variable references directly in your YAML or JSON config values using ${VAR_NAME} placeholders. This is different from the environment variable fallback — interpolation lets you compose values from multiple environment variables.

driver: postgres
host: ${DB_HOST}
port: 5432
database: ${DB_NAME}
username: ${DB_USER}
password: ${DB_PASSWORD}
sslmode: ${DB_SSLMODE}
log_level: info

How It Works

Interpolation happens after reading the file and before YAML/JSON parsing:

1. go-migration reads the raw config file content
2. All ${VAR_NAME} placeholders are replaced with the corresponding environment variable values
3. The resulting string is then parsed as YAML or JSON

Auto-Unquote for JSON (v1.0.0)

When using JSON config files, InterpolateEnv automatically removes surrounding quotes for values that resolve to numeric, boolean (true/false), or null types. This means your JSON stays valid with correct types after interpolation.

{
  "driver": "postgres",
  "host": "${DB_HOST}",
  "port": "${DB_PORT}",
  "database": "${DB_NAME}",
  "sslmode": "disable"
}

With DB_HOST=localhost, DB_PORT=5432, and DB_NAME=myapp, the result after interpolation is:

{
  "driver": "postgres",
  "host": "localhost",
  "port": 5432,
  "database": "myapp",
  "sslmode": "disable"
}

Notice that "port": "${DB_PORT}" becomes "port": 5432 (a number, not the string "5432"). The same applies to boolean and null values:

Escaping

To produce a literal ${VAR_NAME} in your config (without interpolation), use the double-dollar escape sequence:

# This resolves to the value of DB_HOST
host: ${DB_HOST}

# This produces the literal string "${NOT_REPLACED}"
some_field: $${NOT_REPLACED}

Missing Variables

If any ${VAR_NAME} references an environment variable that is not set, go-migration returns an error listing all unresolved variables. This prevents silent misconfiguration.

Config Validation

go-migration validates your configuration at load time and reports all violations in a single error. This catches common mistakes before any database operations are attempted.

Validated Fields

Example Error

If multiple fields are invalid, you get a single error with all violations:

config validation failed:
  - driver must be one of: postgres, mysql, sqlite (got "mongo")
  - port must be positive (got -1)
  - log_level must be one of: debug, info, warn, error (got "verbose")

Programmatic Usage

The config package is publicly available at config/, so you can import it directly in your own Go projects — no need to reimplement config loading, validation, or environment variable interpolation.

package main

import (
	"fmt"
	"log"

	"github.com/gopackx/go-migration/config"
)

func main() {
	// Load configuration from a YAML or JSON file
	cfg, err := config.Load("migration.json")
	if err != nil {
		log.Fatalf("failed to load config: %v", err)
	}

	// Apply default values for optional fields
	cfg.ApplyDefaults()

	// Validate the resolved configuration
	if err := cfg.Validate(); err != nil {
		log.Fatalf("invalid config: %v", err)
	}

	fmt.Printf("Connected to %s on %s:%d\n", cfg.Database, cfg.Host, cfg.Port)
}

What's Next?

• Framework Integration — use go-migration with Gin, Echo, Fiber, or net/http
• CLI Reference — run migrations from the command line
• Error Handling — diagnose and handle migration errors