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