1# migrate CLI 2 3## Installation 4 5### Download pre-built binary (Windows, MacOS, or Linux) 6 7[Release Downloads](https://github.com/golang-migrate/migrate/releases) 8 9```bash 10$ curl -L https://github.com/golang-migrate/migrate/releases/download/$version/migrate.$platform-amd64.tar.gz | tar xvz 11``` 12 13### MacOS 14 15```bash 16$ brew install golang-migrate 17``` 18 19### Windows 20 21Using [scoop](https://scoop.sh/) 22 23```bash 24$ scoop install migrate 25``` 26 27### Linux (*.deb package) 28 29```bash 30$ curl -L https://packagecloud.io/golang-migrate/migrate/gpgkey | apt-key add - 31$ echo "deb https://packagecloud.io/golang-migrate/migrate/ubuntu/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/migrate.list 32$ apt-get update 33$ apt-get install -y migrate 34``` 35 36### With Go toolchain 37 38#### Versioned 39 40```bash 41$ go get -u -d github.com/golang-migrate/migrate/cmd/migrate 42$ cd $GOPATH/src/github.com/golang-migrate/migrate/cmd/migrate 43$ git checkout $TAG # e.g. v4.1.0 44$ # Go 1.15 and below 45$ go build -tags 'postgres' -ldflags="-X main.Version=$(git describe --tags)" -o $GOPATH/bin/migrate $GOPATH/src/github.com/golang-migrate/migrate/cmd/migrate 46$ # Go 1.16+ 47$ go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@$TAG 48``` 49 50#### Unversioned 51 52```bash 53$ # Go 1.15 and below 54$ go get -tags 'postgres' -u github.com/golang-migrate/migrate/cmd/migrate 55$ # Go 1.16+ 56$ go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest 57``` 58 59#### Notes 60 611. Requires a version of Go that [supports modules](https://golang.org/cmd/go/#hdr-Preliminary_module_support). e.g. Go 1.11+ 621. These examples build the cli which will only work with postgres. In order 63to build the cli for use with other databases, replace the `postgres` build tag 64with the appropriate database tag(s) for the databases desired. The tags 65correspond to the names of the sub-packages underneath the 66[`database`](../database) package. 671. Similarly to the database build tags, if you need to support other sources, use the appropriate build tag(s). 681. Support for build constraints will be removed in the future: https://github.com/golang-migrate/migrate/issues/60 691. For versions of Go 1.15 and lower, [make sure](https://github.com/golang-migrate/migrate/pull/257#issuecomment-705249902) you're not installing the `migrate` CLI from a module. e.g. there should not be any `go.mod` files in your current directory or any directory from your current directory to the root 70 71## Usage 72 73```bash 74$ migrate -help 75Usage: migrate OPTIONS COMMAND [arg...] 76 migrate [ -version | -help ] 77 78Options: 79 -source Location of the migrations (driver://url) 80 -path Shorthand for -source=file://path 81 -database Run migrations against this database (driver://url) 82 -prefetch N Number of migrations to load in advance before executing (default 10) 83 -lock-timeout N Allow N seconds to acquire database lock (default 15) 84 -verbose Print verbose logging 85 -version Print version 86 -help Print usage 87 88Commands: 89 create [-ext E] [-dir D] [-seq] [-digits N] [-format] NAME 90 Create a set of timestamped up/down migrations titled NAME, in directory D with extension E. 91 Use -seq option to generate sequential up/down migrations with N digits. 92 Use -format option to specify a Go time format string. 93 goto V Migrate to version V 94 up [N] Apply all or N up migrations 95 down [N] Apply all or N down migrations 96 drop Drop everything inside database 97 force V Set version V but don't run migration (ignores dirty state) 98 version Print current migration version 99``` 100 101So let's say you want to run the first two migrations 102 103```bash 104$ migrate -source file://path/to/migrations -database postgres://localhost:5432/database up 2 105``` 106 107If your migrations are hosted on github 108 109```bash 110$ migrate -source github://mattes:personal-access-token@mattes/migrate_test \ 111 -database postgres://localhost:5432/database down 2 112``` 113 114The CLI will gracefully stop at a safe point when SIGINT (ctrl+c) is received. 115Send SIGKILL for immediate halt. 116 117## Reading CLI arguments from somewhere else 118 119### ENV variables 120 121```bash 122$ migrate -database "$MY_MIGRATE_DATABASE" 123``` 124 125### JSON files 126 127Check out https://stedolan.github.io/jq/ 128 129```bash 130$ migrate -database "$(cat config.json | jq '.database')" 131``` 132 133### YAML files 134 135```bash 136$ migrate -database "$(cat config/database.yml | ruby -ryaml -e "print YAML.load(STDIN.read)['database']")" 137$ migrate -database "$(cat config/database.yml | python -c 'import yaml,sys;print yaml.safe_load(sys.stdin)["database"]')" 138``` 139