Tern is a standalone migration tool for PostgreSQL. It includes traditional migrations as well as a separate optional workflow for managing database code such as functions and views.
- Multi-platform
- Stand-alone binary
- SSH tunnel support built-in
- Data variable interpolation into migrations
Go versions up to and including 1.17:
go get -u github.com/jackc/tern
Go versions 1.17 and higher:
go install github.com/jackc/tern@latest
To create a new tern project in the current directory run:
tern init
Or to create the project somewhere else:
tern init path/to/project
Tern projects are composed of a directory of migrations and optionally a config file. See the sample directory for an example.
Database connection settings can be specified via the standard PostgreSQL environment variables, via program arguments, or in a config file. By default tern will look in the current directory for the config file tern.conf and the migrations.
The tern.conf
file is stored in the ini
format with two sections,
database
and data
. The database
section contains settings for connection
to the database server.
Values in the data
section will be available for interpolation into
migrations. This can help in scenarios where migrations are managing
permissions and the user to which permissions are granted should be
configurable.
If all database settings are supplied by PG* environment variables or program
arguments the config file is not required. In particular, using the PGSERVICE
can reduce or eliminate the need for a configuration file.
The entire tern.conf
file is processed through the Go standard
text/template
package. Sprig functions
are available.
Example tern.conf
:
[database]
# host supports TCP addresses and Unix domain sockets
# host = /private/tmp
host = 127.0.0.1
# port = 5432
database = tern_test
user = jack
password = {{env "MIGRATOR_PASSWORD"}}
# version_table = public.schema_version
#
# sslmode generally matches the behavior described in:
# http://www.postgresql.org/docs/9.4/static/libpq-ssl.html#LIBPQ-SSL-PROTECTION
#
# There are only two modes that most users should use:
# prefer - on trusted networks where security is not required
# verify-full - require SSL connection
# sslmode = prefer
#
# "conn_string" accepts two formats; URI or DSN as described in:
# https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
#
# This property is lenient i.e., it does not throw error
# if values for both "conn_string" and "host/port/.." are
# provided. In this case, the individual properties will
# override the correspoding part in the "conn_string".
#
# URI format:
# conn_string = postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
# DSN format:
# conn_string = host=localhost port=5432 dbname=mydb connect_timeout=10
# Proxy the above database connection via SSH
# [ssh-tunnel]
# host =
# port = 22
# user defaults to OS user
# user =
# password is not required if using SSH agent authentication
# password =
[data]
prefix = foo
app_user = joe
This flexibility configuration style allows handling multiple environments such as test, development, and production in several ways.
- Separate config file for each environment
- Environment variables for database settings and optionally one config file for shared settings
- Program arguments for database settings and optionally one config file for shared settings
To create a new migration:
tern new name_of_migration
This will create a migration file with the given name prefixed by the next available sequence number (e.g. 001, 002, 003).
The migrations themselves have an extremely simple file format. They are simply the up and down SQL statements divided by a magic comment.
---- create above / drop below ----
Example:
create table t1(
id serial primary key
);
---- create above / drop below ----
drop table t1;
If a migration is irreversible such as a drop table, simply delete the magic comment.
drop table widgets;
To interpolate a custom data value from the config file prefix the name with a dot and surround the whole with double curly braces.
create table {{.prefix}}config(
id serial primary key
);
Migrations are read from files in the migration directory in the order of the numerical prefix. Each migration is run in a transaction.
Any SQL files in subdirectories of the migration directory, will be available for inclusion with the template command. This can be especially useful for definitions of views and functions that may have to be dropped and recreated when the underlying table(s) change.
// Include the file shared/v1_001.sql. Note the trailing dot.
// It is necessary if the shared file needs access to custom data values.
{{ template "shared/v1_001.sql" . }}
);
Tern uses the standard Go text/template package so conditionals and other advanced templating features are available if needed. See the package docs for details. Sprig functions are also available.
To migrate up to the last version using migrations and config file located in the same directory simply run tern:
tern migrate
To migrate up or down to a specific version:
tern migrate --destination 42
To migrate up N versions:
tern migrate --destination +3
To migrate down N versions:
tern migrate --destination -3
To migrate down and rerun the previous N versions:
tern migrate --destination -+3
To use a different config file:
tern migrate --config path/to/tern.json
To use a different migrations directory:
tern migrate --migrations path/to/migrations
When migrations are created on multiple branches the migrations need to be renumbered when the branches are merged. The
tern renumber
command can automatically do this. On the branch with the only migrations to keep at the lower numbers
run tern renumber start
. Merge the branches. Then run tern renumber finish
.
$ git switch master
Switched to branch 'master'
$ ls
001_create_users.sql
002_add_last_login_to_users.sql
$ git switch feature
Switched to branch 'feature'
$ ls
001_create_users.sql
002_create_todos.sql
# Both branches have a migration number 2.
# Run tern renumber start on the branch with the migrations that should come first.
$ git switch master
Switched to branch 'master'
$ tern renumber start
# Then go to the branch with migrations that should come later and merge or rebase.
$ git switch feature
$ git rebase master
Successfully rebased and updated refs/heads/feature.
$ ls
001_create_users.sql
002_add_last_login_to_users.sql
002_create_todos.sql
# There are now two migrations with the same migration number.
$ tern renumber finish
$ ls
001_create_users.sql
002_add_last_login_to_users.sql
003_create_todos.sql
# The migrations are now renumbered in the correct order.
The migration paradigm works well for creating and altering tables, but it can be unwieldy when dealing with database
code such as server side functions and views. For example, consider a schema where view c
depends on view b
which
depends on view a
. A change to a
may require the following steps:
- Drop
c
- Drop
b
- Drop
a
- Create
a
- Create
b
- Create
c
In addition to the challenge of manually building such a migration it is difficult to use version control to see the changes in a particular database object over time when its definition is scattered through multiple migrations.
A solution to this is code packages. A code package is a directory with an install.sql
file that contains the
instructions to completely drop and recreate a set of database code. The command code install
can be used to directly
install a code package (especially useful during development) and the code snapshot
command can be used to make a
single migration that installs that code package.
For example given a directory code
containing the following files:
-- install.sql
drop schema if exists code cascade;
create schema code;
{{ template "a.sql" . }}
{{ template "b.sql" . }}
{{ template "c.sql" . }}
-- a.sql
create view code.a as select ...;
-- b.sql
create view code.b as select * from code.a where ...;
-- c.sql
create view code.c as select * from code.b where ...;
Then this command would install the package into the database.
tern code install path/to/code --config path/to/tern.conf
And this command would create a migration from the current state of the code package.
tern code snapshot path/to/code --migrations path/to/migrations
Code packages have access to data variables defined in your configuration file as well as functions provided by Sprig.
It is recommended but not required for each code package to be installed into its own PostgreSQL schema. This schema could be determined by environment variable as part of a blue / green deployment process.
The env
function can be used to read process environment variables.
drop schema if exists {{ env "CODE_SCHEMA" }} cascade;
create schema {{ env "CODE_SCHEMA" }};
The Sprig dictionary functions can be useful to call templates with extra parameters merged into the .
value.
{{ template "_view_partial.sql" (merge (dict "view_name" "some_name" "where_clause" "some_extra_condition=true") . ) }}
Tern includes SSH tunnel support. Simply supply the SSH host, and optionally
port, user, and password in the config file or as program arguments and Tern
will tunnel the database connection through that server. When using a SSH tunnel
the database host should be from the context of the SSH server. For example, if
your PostgreSQL server is pg.example.com
, but you only have SSH access, then
your SSH host would be pg.example.com and your database host would be
localhost
.
Tern will automatically use an SSH agent or ~/.ssh/id_rsa
if available.
All the actual functionality of tern is in the github.com/jackc/tern/migrate library. If you need to embed migrations into your own application this library can help.
To run the tests tern requires two test databases to run migrations against.
-
Create a new database for main tern program tests.
-
Open testdata/tern.conf.example
-
Enter the connection information.
-
Save as testdata/tern.conf.
-
Create another database for the migrate library tests.
-
Run tests with the connection string for the migrate library tests in the MIGRATE_TEST_CONN_STRING environment variable
MIGRATE_TEST_CONN_STRING="host=/private/tmp database=tern_migrate_test" go test ./...
The projects using the prior version of tern that was distributed as a Ruby Gem are incompatible with the version 1 release. However, that version of tern is still available through RubyGems and the source code is on the ruby branch.
- Add conn string connection config option (vivek-shrikhande)
- Add Filename to MigrationPgError (davidmdm)
- Look for SSH keys in
~/.ssh/id_rsa
(Miles Delahunty)
- Use user's known_hosts file when connecting via SSH
- Fix reported version number
- Fix setting port from config file
- Fix non-schema qualified version table not in public but in search path (Tynor Fujimoto)
- Update to latest version of pgx.
- Command code install no longer outputs compiled SQL.
- Add code compile command to print compiled SQL code package.
- Better error reporting for code install.
- Add Sprig functions to configuration file and migrations.
- Add SQL code management distinct from migrations.
- CLI now handles SIGINT (ctrl+c) and attempts to cancel in-progress migration before quitting
- Fix default CLI version-table argument overriding config value
- Better locking to protect against multiple concurrent migrators on first run
- Update pgx version to support PostgreSQL service files
- Look for version table in all schemas in search_path instead of just the top schema
- Default version table is explicitly in public schema
- Update to pgx v4 (Alex Gaynor)
- Show PostgreSQL error details
- Rename internal error type
- Issue
reset all
after every migration - Use go modules instead of Godep / vendoring
- Update to latest version of pgx (PostgreSQL driver)
- Support PGSSLROOTCERT
- Fix typos and internal cleanup
- Refactor internals for easier embedding (hsyed)
- Simplify SSH tunnel code so it does not listen on localhost
- Add SSH tunnel support
- Fix version output
- Evaluate config files through text/template with ENV
- Optionally read database connection settings from environment
- Accept database connection settings via program arguments
- Make config file optional
- Add status command
- Add relative migration destinations
- Add redo migration destinations
- Add TLS support
- Fix version output
- Better error messages
- Fix custom version table name
- Prefer host config whether connecting with unix domain socket or TCP
- Fix new migration short name
- Support socket directory as well as socket file
- Move to subcommand interface
- Require migrations to begin with ascending, gapless numbers
- Fix: migrations directory can contain other files
- Fix: gracefully handle invalid current version
- Fix: gracefully handle migrations with duplicate sequence number
- Do not require user -- default to OS user
- Add sub-template support
- Switch to ini for config files
- Add custom data merging
- Total rewrite in Go
- Print friendly error message when database error occurs instead of stack trace.
- Added ERB processing to SQL files
Copyright (c) 2011-2014 Jack Christensen, released under the MIT license