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/migration.yaml

Configuration File

The configuration file defines your database connections, pool settings, migration table name, and logging preferences. All connection details live under a named entry inside the connections map; there are no top-level driver/host/port fields.

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

# Default connection name
default: postgres

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

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

    # Connection pool settings
    max_open_conns: 25
    max_idle_conns: 5
    conn_max_lifetime: 5m # duration string

    # Driver-specific options (e.g. PostgreSQL sslmode)
    options:
      sslmode: disable

# Migration settings (apply globally)
migration_table: migrations

# Logging
log_level: info

Supported Fields

Top-Level Keys

These are the only keys recognized at the top level of the config file:

Per-Connection Fields

Each entry under connections.<name> accepts these fields:

Environment Variable Fallback

go-migration can build an entire configuration from environment variables. This is a wholesale fallback: when the CLI fails to load the config file (for example, the file does not exist), it falls back to LoadFromEnv(), which constructs a single connection named after GOMIGRATE_DEFAULT_CONNECTION (default default). This is distinct from ${VAR} interpolation, which substitutes individual values inside a config file that does load.

Naming Convention

All recognized environment variables use the GOMIGRATE_ prefix. Connection fields use the GOMIGRATE_DB_ prefix:

Directory and Logging Settings

LoadFromEnv() also reads these top-level settings from GOMIGRATE_-prefixed variables:

Resolution Order

The CLI resolves configuration in this order:

1. Configuration file — config.Load() reads and parses the file (with ${VAR} interpolation applied first).
2. Environment fallback — if the file cannot be loaded, config.LoadFromEnv() builds the config entirely from GOMIGRATE_* variables.
3. Defaults — ApplyDefaults() fills in built-in defaults for any optional field still empty.

# Build the whole config from the environment (used when no config file loads)
export GOMIGRATE_DB_DRIVER=postgres
export GOMIGRATE_DB_HOST=prod-db.example.com
export GOMIGRATE_DB_PORT=5432
export GOMIGRATE_DB_DATABASE=myapp_production
export GOMIGRATE_DB_USERNAME=app_user
export GOMIGRATE_DB_PASSWORD=s3cret

Default Values

go-migration's ApplyDefaults() fills in these top-level defaults when they are not specified:

Pool Settings

go-migration sets no pool defaults of its own. It only calls SetMaxOpenConns, SetMaxIdleConns, and SetConnMaxLifetime when the corresponding config value is greater than zero; otherwise the underlying *sql.DB keeps Go's database/sql defaults.

Driver-Specific Examples

{
  "default": "postgres",
  "connections": {
    "postgres": {
      "driver": "postgres",
      "host": "localhost",
      "port": 5432,
      "database": "myapp",
      "username": "postgres",
      "password": "secret",
      "max_open_conns": 25,
      "max_idle_conns": 5,
      "conn_max_lifetime": "5m",
      "options": { "sslmode": "disable" }
    }
  },
  "migration_table": "migrations",
  "log_level": "info"
}

{
  "default": "mysql",
  "connections": {
    "mysql": {
      "driver": "mysql",
      "host": "localhost",
      "port": 3306,
      "database": "myapp",
      "username": "root",
      "password": "secret",
      "max_open_conns": 25,
      "max_idle_conns": 5,
      "conn_max_lifetime": "5m"
    }
  },
  "migration_table": "migrations",
  "log_level": "info"
}

{
  "default": "sqlite",
  "connections": {
    "sqlite": {
      "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. Every config file uses this structure — connection details always live under connections.<name>.

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}",
      "options": { "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}
    options:
      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 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 inside a config file that loads successfully.

default: postgres
connections:
  postgres:
    driver: postgres
    host: ${DB_HOST}
    port: 5432
    database: ${DB_NAME}
    username: ${DB_USER}
    password: ${DB_PASSWORD}
    options:
      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.

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

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

{
  "default": "postgres",
  "connections": {
    "postgres": {
      "driver": "postgres",
      "host": "localhost",
      "port": 5432,
      "database": "myapp",
      "options": { "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:

connections:
  postgres:
    # This resolves to the value of DB_HOST
    host: ${DB_HOST}
    # This produces the literal string "${NOT_REPLACED}"
    password: $${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 joined together:

configuration validation failed: connections.postgres.driver must be one of: postgres, mysql, sqlite, log_level must be one of: debug, info, warn, error

Programmatic Usage

The config package is publicly available at pkg/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/pkg/config"
)

func main() {
	// Load configuration from a JSON (or deprecated YAML) 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)
	}

	// Connection details live under the connections map.
	conn := cfg.Connections[cfg.DefaultConn]
	fmt.Printf("Connected to %s on %s:%d\n", conn.Database, conn.Host, conn.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