Repository navigation
Releases
v1.7.0
v1.7.0
Run the same migration directory across multiple databases with bounded
concurrency. Generate commented YAML configurations for numbered shards,
shared SSH settings and proxies directly from the CLI.
Added
- Named
data_sourcesusing one shared migration directory, dialect and history
table name. Each database keeps its own migration history and pending plan. - Multi-source
create,baseline,status,upanddown, with--parallel
controlling concurrency (default 8; use 1 for sequential execution). A source
failure does not stop healthy sources; all results are collected and any
failure or cancellation produces a nonzero exit code. - Sorted per-source results, grouped dry-run plans, source-labelled stderr logs
and a JSON result array for multi-sourcestatus. Single-source status JSON
retains its existing shape. - Shared SSH/proxy configuration defaults with optional whole-object overrides
per source. Each task owns and closes its database connection and SSH transport. new config --multi --shards Nforshard_0throughshard_(N-1), referencing
the correspondingSHARD_0_DSN,SHARD_1_DSN, etc. environment variables.
--multialone generates two shards.- Initialization flags for SSH agent, private-key and password authentication,
SOCKS5/HTTP proxies, and explicit YAML/JSON output. Generated YAML includes
configuration comments; initialization does not resolve credentials or connect
to databases.
Changed
new confignow defaults tomigration_config.ymlwith native YAML comments.
Use--format jsonto generate strict JSON.- Configuration discovery tries
migration_config.yml,migration_config.yaml,
thenmigration_config.json. An explicit--configselects only that file.
Fixed
- Report the installed Go module version in
versionandcapabilitiesfor
go install ...@version, while retaining injected release build versions and
thedevfallback for local builds. - Display a documentation website favicon with the correct Pages base path on
every language page.
Upgrade notes
- Existing single-source JSON configurations remain supported. When several
default configuration files exist, the highest-priority YAML file wins;
parsing or validation errors do not fall back to another file. Remove unused
configurations or select the intended file with--config. - Multi-source configurations use
data_sourcesinstead of the top-level
data_source_name. Top-levelssh_tunnelremains a shared configuration
default; a source's non-null SSH object replaces that whole default object. - Each source must identify an independent database. There is no distributed
transaction or automatic rollback of successful databases when another fails.
After inspecting failed database state, rerun to apply its missing migrations;
already-applied migrations are skipped using each database's own history. - Parent cancellation stops dispatching new tasks, cancels active work and waits
for local cleanup. Cancellation is not a cross-database rollback guarantee;
inspect database state after interrupted or nontransactional operations. new versiongenerates one file using shared settings, without opening database
connections or requiring source credentials. The public Go migration API and
existing dialect transaction limits remain unchanged.
Install
go install github.com/exc-works/migrate/cmd/migrate@v1.7.0
migrate version
migrate capabilities --output jsonTo initialize four shards sharing SSH and proxy settings:
migrate new config shards.yml --multi --shards 4 --ssh-tunnel --proxy socks5
# Edit the configuration and set its referenced environment variables first.
migrate --config shards.yml up --parallel 4Prebuilt binaries cover Linux arm64/x64/x86, macOS arm64/amd64, and Windows
arm64/x64/x86. Verify downloads against checksums.txt; migration-api.d.ts
provides editor declarations. Script execution requires no Node.js runtime.
中文文档 ·
English documentation ·
Changelog ·
Changes since v1.6.0
v1.6.0
v1.6.0
Connect through SSH bastions and proxies, and run SQL, JavaScript, TypeScript and
MJS migrations with one CLI. This release also adds a documentation website and
fixes first-use SSH host trust timing out while saving known_hosts.
Added
- Native SSH tunnels for PostgreSQL, MySQL, MariaDB, MSSQL, Oracle, ClickHouse,
TiDB and Redshift, optionally reached through a SOCKS5 or HTTP CONNECT proxy.
Connections retain the database's original TLS identity and remote DNS routing. - Password, private-key and SSH-agent authentication, environment-based secrets,
hidden terminal prompts, and--non-interactivefor unattended execution. - Interactive first-use host trust showing the SSH address, key algorithm and
SHA256 fingerprint. Trust is saved only after explicit approval; changed,
revoked or invalid host keys fail without offering approval. - The Go
OpenConnectionAPI for a migration-owned connection pool and optional
SSH transport. Caller-provided database pools retain their existing ownership. - A topic-based English and Chinese documentation website covering installation,
migration workflows, scripts, the Go API, SSH configuration and troubleshooting.
Changed
- Retire the separate
fullbuild mode. SQL, JS, TS and MJS migrations use the
same executable and installation command. - Publish one binary per platform, using the existing platform filenames without
_fullassets. SQL and script tests run in one CI build configuration. - Remove the
builddiscriminator fromcapabilitiestext and JSON output.
Supported formats and script dialect metadata remain available.
Fixed
- Keep the SSH handshake timeout paused while an approved host key is saved and
rechecked. File-lock waits and filesystem synchronization no longer consume
the network handshake budget. Caller cancellation still interrupts lock waits,
and the network timeout resumes before SSH authentication.
Upgrade notes
- Update download automation that selects
_fullassets to use the corresponding
platform filename, for examplemigrate_v1.6.0_linux_x64or
migrate_v1.6.0_windows_x64.exe. - Consumers of
capabilitiesmust stop reading the removedbuildfield. Use
formats,script_dialectsandscript_dialect_capabilitiesto inspect support. - Existing SQL hashes, script entry-source hashes and migration history remain
unchanged. Imported helpers and installed packages remain outside script hashes;
retain historical dependency behavior and pin package versions. - SSH uses explicit configuration, without OpenSSH configuration, an external
sshprocess or automatic reconnection. Library secret and host-key prompts
require opt-in callbacks; nil callbacks never prompt or approve unknown keys. - Script support for TiDB, Redshift, Oracle, ClickHouse and MSSQL remains
experimental. Optional external Oracle, Redshift and MSSQL checks require
dedicated DSNs; skipped checks do not establish real-instance verification. - Existing database transaction limits remain: some DDL implicitly commits,
ClickHouse has no automatic transaction rollback, and explicitly
nontransactional scripts can leave partial changes after failure.
Install
go install github.com/exc-works/migrate/cmd/migrate@v1.6.0
migrate version
migrate capabilities --output jsonPrebuilt binaries cover Linux arm64/x64/x86, macOS arm64/amd64, and Windows
arm64/x64/x86. Verify downloads against checksums.txt; migration-api.d.ts
provides editor declarations. Script execution uses an embedded engine and does
not require Node.js or download an interpreter.
中文文档 ·
English documentation ·
Runnable examples ·
Changelog ·
Changes since v1.5.0
v1.5.0
v1.5.0
Share code between script migrations with static local and installed npm imports.
This release also adds experimental script support for more databases, explicit
transaction control, SQL error recovery, and restored 32-bit release builds.
Added
- Static imports and re-exports in JS, TS and MJS migrations, including shared
helpers outside the migration directory and installed npm packages compatible
with Goja. Package exports, subpaths and static CommonJS dependencies are bundled. - Embedded and in-memory module sources through the public Go API, with explicit
disk dependency directories when virtual sources need installed packages. - Per-script
export const config = { transaction: false }for native/manual
transaction workflows on a dedicated connection. - Experimental JS/TS/MJS execution for TiDB, Redshift, Oracle, ClickHouse and MSSQL.
Inspect verification status, aliases and transaction modes withmigrate capabilities. - Case-insensitive database aliases, including PostgreSQL
pg/pgsql/postgresql/pgx
and MSSQLsqlserver/azuresql. - Runnable SQLite examples for shared helpers, package.json/npm imports and Go embedding.
Fixed
- Restore Linux and Windows x86 SQL/full builds with the upstream Oracle driver fix
for 32-bit INTERVAL arithmetic overflow. - Ignore ordinary synchronous return values from migration entrypoints.
- Allow scripts to catch sanitized driver errors and perform subsequent SQL recovery.
Actual execution cancellation, overall timeout, validation and resource limits remain
fatal; commit and history-write errors still fail the migration. - Forward script SQL unchanged to drivers, including native batches and procedure
definitions. Remove keyword and single-statement restrictions and the handwritten
MSSQL validator. SQL files retain their existing parser. - Return healthy nontransactional connections to the pool; discard failed/panicked
invocations to clean up unfinished manual transactions. - Upgrade Oracle to go-ora v3 for modern authentication and correct history DDL,
native binding and missing result metadata handling.
Compatibility
- Default builds remain SQL-only. Full assets add
_fullbefore the optional.exe
suffix; existing SQL asset filenames, SQL hashes and migration history stay compatible. - Script checksums cover entry source only. Helpers, packages and lockfiles are excluded;
dependency changes do not replay applied migrations. Retain historical dependency
behavior and pin package versions when migrations must remain reproducible. - Install npm dependencies before migration execution. The tool does not install
packages or provide Node.js APIs, native addons, dynamic loading or async entrypoints. - Nontransactional scripts can leave partial changes without successful history on
failure. Authors finish manual transactions and restore session state. Oracle DDL
can implicitly commit; ClickHouse has no automatic transaction rollback. - New script dialects remain experimental. TiDB container coverage uses Unistore;
distributed TiKV and Azure SQL deployments remain unverified. External Oracle,
Redshift and MSSQL integration checks require dedicated DSNs; skipped checks do
not establish real-instance verification.
Install
Default SQL build:
go install github.com/exc-works/migrate/cmd/migrate@v1.5.0Full SQL/JS/TS/MJS build:
go install -tags=full github.com/exc-works/migrate/cmd/migrate@v1.5.0
migrate capabilities --output jsonPrebuilt SQL and full binaries cover Linux arm64/x64/x86, macOS arm64/amd64, and
Windows arm64/x64/x86. Verify downloads against checksums.txt; migration-api.d.ts
provides editor declarations. No Node.js installation is required to execute migrations.
中文指南 ·
English guide ·
Runnable examples ·
Full changelog ·
Changes since v1.4.0
v1.4.0
SQL and standalone JavaScript/TypeScript migrations in one tool.
Added
- Accept
.mjsas a JavaScript migration alias in full builds; SQL-only builds
detect and reject it before migration writes. Supportnew version --format mjs. - Optional
fullbuilds support standalone synchronous JS/TS migrations alongside SQL,
with framework-owned transactions, exact value conversion, source checksums,
execution deadlines and query result limits. capabilitiesreports compiled formats without configuration or a connection.new version --format sql|js|ts|mjscreates migration templates; script timeout and
result limits can be configured through JSON or the Go facade.- Generated JS/MJS templates include JSDoc database types; TS templates provide
equivalent method, parameter and result declarations for editor assistance. - SQL/full CI matrices and real-driver script integration for PostgreSQL, MySQL,
MariaDB and SQLite; full release binaries and editor API declarations.
Fixed
- Migration callbacks that panic now roll back instead of entering deferred commit.
- Execution validates complete selected plans before changing data, including
irreversible rollback ranges and unsupported script capabilities.
Compatibility
- Default binaries and existing release filenames remain SQL-only. Existing SQL
hashes, migration history and version command output remain unchanged. - Known JS/TS/MJS migration files are discovered by both builds; SQL-only execution
refuses them instead of silently skipping required versions.
Install
Default SQL build:
go install github.com/exc-works/migrate/cmd/migrate@v1.4.0Full SQL/JS/TS/MJS build:
go install -tags=full github.com/exc-works/migrate/cmd/migrate@v1.4.0Release binaries with _full before the optional .exe suffix support scripts; existing filenames remain SQL-only. No Node.js installation or runtime download is required. Script support covers PostgreSQL, MySQL, MariaDB and SQLite. Verify downloads against checksums.txt.
v1.3.1
v1.3.0
v1.2.1
Behavior fixes: - Improve CLI usability for users and AI agents - Add machine-readable status output (--output json) - Enforce safe rollback arg validation for down
v1.2.0
feat(cli): add top-level version command
v1.1.1
fix: track cmd/migrate sources and narrow gitignore
v1.0.0
docs: add bilingual user guides and link from README