sql-migrate's container builds an older Go than its module needs
SQL schema migration tool for Go.
At a glance
- What is it?
- sql-migrate is a schema migration tool for Go, usable as a command or a library, supporting five databases through five drivers. Its Dockerfile pins a Go release older than the module declares and builds with cgo disabled, which quietly removes Oracle.
- Who is it for?
- sql-migrate fits a Go service that needs versioned schema changes with rollback, wants migrations written as plain SQL rather than generated code, and keeps its migration files somewhere the tool can read at build time or from memory.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 131 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- rubenv/sql-migrate3,413 ★ · -4
| Repository | 2026-09-24 | 2026-11-21 |
|---|---|---|
| rubenv/sql-migrate | 3.4k | 3.4k |
-4 Stars in the last 58 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two install commands for two Go eras
The installation section offers a command and then immediately offers a second one for a later version of the language:
go get -v github.com/rubenv/sql-migrate/...go install github.com/rubenv/sql-migrate/...@latestThe first is the pre-1.18 way of installing a program, the second is the version-aware replacement. Underneath them the README states that the tool is supported on Go 1.13 and later. The module file in the repository tells a much narrower story: it declares the language version the module itself needs, which is several releases past what the README claims to support. Nothing reconciles the two, so a reader pinning an old toolchain is left deciding which line of the file to believe, and the honest reading is that the language floor in the module file is the one that will stop the build.
The container builds an older Go than the module declares
The Dockerfile has three stages and two version arguments at the top: a Go release and an Alpine release, both pinned to old numbers. The first stage copies the tree and vendors the dependencies, the second builds the command with the target operating system, architecture, cgo disabled and module mode on, and the third copies the single resulting binary into the Alpine image and makes it the entry point. Two consequences follow. The pinned Go in that file is older than the language version the module file declares, so the build relies on the toolchain switching behaviour of recent Go releases to fetch something newer than the image asked for. More importantly, cgo is switched off for the build, and two of the five databases this tool supports need cgo to work at all.
Five databases, five drivers, one module
The feature list names five database families: SQLite, PostgreSQL, MySQL, SQL Server and Oracle, and says the support comes through a mapping library rather than through hand-written SQL per database. The module file matches that claim literally, with a direct requirement on a driver for each of the five plus two more for the two Oracle options. That means the Oracle drivers are in the module graph whether you use them or not, and both are native bindings that pull in a build dependency, which is why the file has three database sections rather than one. Two other direct requirements explain the shape of the command: a small command line framework, which is where the help output format comes from, and a table writer, which is what produces the status listing.
Two Oracle routes, two build tags, one native client
Oracle gets more space than any other database in the README, and for a consistent reason: neither driver is pure Go. Two are documented. The first is a driver that installs under a tag named for the database, and the second is a different driver that installs under a tag named for itself. Both are described as relying on an Oracle client library that has to be installed on the machine, and both take a connection string in the same user, password, host, port and service identifier shape. The second route is spelled out as three numbered steps: install with the tag, download the client archive for your platform, and point a library path environment variable at the extracted directory. The README calls that client an office client in both places, which is not what the linked downloads are.
The same file shows a disabled and a required TLS mode
The configuration file example appears twice with a difference that matters. The first production block connects to a PostgreSQL database with TLS explicitly disabled in the connection string. The second production block does the opposite: it requires TLS and takes the user and password from environment variables, with the note that this is useful if you do not want credentials stored in the file. The expansion is done by the tool's own environment substitution, so the variable names are written into the config and resolved at run time. Two defaults are worth knowing: the table name that records applied migrations is optional and falls back to a name carried over from the mapping library the tool is built on, and the environment selection defaults to the one named development.
down moves one step unless you say otherwise
The asymmetry between the two directions is deliberate and documented. Up applies every available migration. Down applies exactly one, by default, so a mistake is undone a step at a time. Both can be adjusted with a limit flag, which takes a number and where zero means unlimited, and both accept a version flag, which runs to a specific migration instead. Where the two are combined the README is explicit that the version flag wins. A third flag makes the whole thing safe to try: a dry run prints the migrations instead of applying them. The remaining two commands are development aids. One creates an empty migration file named after the current time and a name you give it, and one unapplies the last migration and reapplies it, which is the command you want while writing them.
The status example is dated 2014
The status output is shown as a bordered two-column table, one column for the migration file name and one for when it was applied, with a row reading no for anything outstanding. The example itself has a first migration applied in September 2014 and a second one pending, and the help text for the version flag uses that same first migration file as the worked example of a version number. Both are harmless, and both are the sort of detail that tells you the documentation was written once and extended since. The table's shape, on the other hand, is the contract: filenames on the left, timestamps on the right, and a plain word when a migration has not run.
The library lives in loose files at the root
The repository is laid out as a library with its source at the top rather than inside a versioned directory, with the core migration file and a package documentation file beside the module and licence files, the command itself in a subdirectory, and a small SQL parsing package of its own. Five test files sit at the root next to them, which is why the Makefile's test target is a plain run over everything. Two more directories carry the integration setups, one holding shell scripts you can execute to bring up a real server per database and one holding migration fixtures. That last point connects to the library API: a migration source can be memory, files, embedded data, or anything implementing the standard file system interface, which is how the same tool works from a binary and from inside an application.
Editorial conclusion
sql-migrate fits a Go service that needs versioned schema changes with rollback, wants migrations written as plain SQL rather than generated code, and keeps its migration files somewhere the tool can read at build time or from memory. Check four things before adopting it: which database you actually use, since Oracle needs a build tag and a native client library that the shipped container image cannot provide, whether you want credentials in the config file or expanded from the environment, since the README shows both, how you will pin the tool, since there are no published releases and the two documented install commands target different Go eras, and whether your migrations belong in the repository or embedded in the binary. The library API and the command share the same migration files, so either route works on the same set.
Frequently asked questions
What is sql-migrate?
A SQL schema migration tool for Go, usable as a command line program or as a library, based on a database mapping library and on an earlier migration tool. It supports SQLite, PostgreSQL, MySQL, SQL Server and Oracle, with atomic migrations and separate up and down halves for rollback.
How do I install sql-migrate?
Two routes are documented: the older go get form with the module path, and go install with the latest version suffix for Go 1.18 and later. The README states that the tool is supported on Go 1.13 and up.
Does sql-migrate need a configuration file?
Every command requires one. It defaults to dbconfig.yml and can be pointed elsewhere with the -config flag. It defines one or more environments, each with a dialect, a datasource, a migrations directory and an optional table name that defaults to gorp_migrations.
Can sql-migrate roll back a migration?
Each migration has an up and a down half. The down command applies a single migration by default, and both commands can be adjusted with a limit flag, while a version flag migrates to one specific file and takes priority over the limit. A dry run flag prints migrations instead of applying them.
Does sql-migrate support Oracle?
Through two drivers, neither of which is pure Go, and both of which need the Oracle client library installed on the machine. Each installs under its own build tag, and one documented route also asks you to download the client archive and set a library path environment variable.
Can I run sql-migrate from a container?
The repository ships a Dockerfile that vendors the dependencies, builds a single binary for Linux with cgo disabled and copies it into an Alpine image as the entry point. Because cgo is off in that build, the Oracle dialects are not usable from the image.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/rubenv-sql-migrate)Star history chart for your README
[](https://hysenlabs.com/projects/rubenv-sql-migrate)Was this useful?