1[](https://github.com/golang-migrate/migrate/actions/workflows/ci.yaml?query=branch%3Amaster)
2[](https://pkg.go.dev/github.com/golang-migrate/migrate/v4)
3[](https://coveralls.io/github/golang-migrate/migrate?branch=master)
4[](https://packagecloud.io/golang-migrate/migrate?filter=debs)
5[](https://hub.docker.com/r/migrate/migrate/)
6
7[](https://github.com/golang-migrate/migrate/releases)
8[](https://goreportcard.com/report/github.com/golang-migrate/migrate)
9
10# migrate
11
12__Database migrations written in Go. Use as [CLI](#cli-usage) or import as [library](#use-in-your-go-project).__
13
14* Migrate reads migrations from [sources](#migration-sources)
15 and applies them in correct order to a [database](#databases).
16* Drivers are "dumb", migrate glues everything together and makes sure the logic is bulletproof.
17 (Keeps the drivers lightweight, too.)
18* Database drivers don't assume things or try to correct user input. When in doubt, fail.
19
20Forked from [mattes/migrate](https://github.com/mattes/migrate)
21
22## Databases
23
24Database drivers run migrations. [Add a new database?](database/driver.go)
25
26* [PostgreSQL](database/postgres)
27* [PGX](database/pgx)
28* [Redshift](database/redshift)
29* [Ql](database/ql)
30* [Cassandra](database/cassandra)
31* [SQLite](database/sqlite)
32* [SQLite3](database/sqlite3) ([todo #165](https://github.com/mattes/migrate/issues/165))
33* [SQLCipher](database/sqlcipher)
34* [MySQL/ MariaDB](database/mysql)
35* [Neo4j](database/neo4j)
36* [MongoDB](database/mongodb)
37* [CrateDB](database/crate) ([todo #170](https://github.com/mattes/migrate/issues/170))
38* [Shell](database/shell) ([todo #171](https://github.com/mattes/migrate/issues/171))
39* [Google Cloud Spanner](database/spanner)
40* [CockroachDB](database/cockroachdb)
41* [ClickHouse](database/clickhouse)
42* [Firebird](database/firebird)
43* [MS SQL Server](database/sqlserver)
44
45### Database URLs
46
47Database connection strings are specified via URLs. The URL format is driver dependent but generally has the form: `dbdriver://username:password@host:port/dbname?param1=true¶m2=false`
48
49Any [reserved URL characters](https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters) need to be escaped. Note, the `%` character also [needs to be escaped](https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_the_percent_character)
50
51Explicitly, the following characters need to be escaped:
52`!`, `#`, `$`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `:`, `;`, `=`, `?`, `@`, `[`, `]`
53
54It's easiest to always run the URL parts of your DB connection URL (e.g. username, password, etc) through an URL encoder. See the example Python snippets below:
55
56```bash
57$ python3 -c 'import urllib.parse; print(urllib.parse.quote(input("String to encode: "), ""))'
58String to encode: FAKEpassword!#$%&'()*+,/:;=?@[]
59FAKEpassword%21%23%24%25%26%27%28%29%2A%2B%2C%2F%3A%3B%3D%3F%40%5B%5D
60$ python2 -c 'import urllib; print urllib.quote(raw_input("String to encode: "), "")'
61String to encode: FAKEpassword!#$%&'()*+,/:;=?@[]
62FAKEpassword%21%23%24%25%26%27%28%29%2A%2B%2C%2F%3A%3B%3D%3F%40%5B%5D
63$
64```
65
66## Migration Sources
67
68Source drivers read migrations from local or remote sources. [Add a new source?](source/driver.go)
69
70* [Filesystem](source/file) - read from filesystem
71* [Go-Bindata](source/go_bindata) - read from embedded binary data ([jteeuwen/go-bindata](https://github.com/jteeuwen/go-bindata))
72* [GitHub](source/github) - read from remote GitHub repositories
73* [GitHub Enterprise](source/github_ee) - read from remote GitHub Enterprise repositories
74* [Bitbucket](source/bitbucket) - read from remote Bitbucket repositories
75* [Gitlab](source/gitlab) - read from remote Gitlab repositories
76* [AWS S3](source/aws_s3) - read from Amazon Web Services S3
77* [Google Cloud Storage](source/google_cloud_storage) - read from Google Cloud Platform Storage
78
79## CLI usage
80
81* Simple wrapper around this library.
82* Handles ctrl+c (SIGINT) gracefully.
83* No config search paths, no config files, no magic ENV var injections.
84
85__[CLI Documentation](cmd/migrate)__
86
87### Basic usage
88
89```bash
90$ migrate -source file://path/to/migrations -database postgres://localhost:5432/database up 2
91```
92
93### Docker usage
94
95```bash
96$ docker run -v {{ migration dir }}:/migrations --network host migrate/migrate
97 -path=/migrations/ -database postgres://localhost:5432/database up 2
98```
99
100## Use in your Go project
101
102* API is stable and frozen for this release (v3 & v4).
103* Uses [Go modules](https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more) to manage dependencies.
104* To help prevent database corruptions, it supports graceful stops via `GracefulStop chan bool`.
105* Bring your own logger.
106* Uses `io.Reader` streams internally for low memory overhead.
107* Thread-safe and no goroutine leaks.
108
109__[Go Documentation](https://godoc.org/github.com/golang-migrate/migrate)__
110
111```go
112import (
113 "github.com/golang-migrate/migrate/v4"
114 _ "github.com/golang-migrate/migrate/v4/database/postgres"
115 _ "github.com/golang-migrate/migrate/v4/source/github"
116)
117
118func main() {
119 m, err := migrate.New(
120 "github://mattes:personal-access-token@mattes/migrate_test",
121 "postgres://localhost:5432/database?sslmode=enable")
122 m.Steps(2)
123}
124```
125
126Want to use an existing database client?
127
128```go
129import (
130 "database/sql"
131 _ "github.com/lib/pq"
132 "github.com/golang-migrate/migrate/v4"
133 "github.com/golang-migrate/migrate/v4/database/postgres"
134 _ "github.com/golang-migrate/migrate/v4/source/file"
135)
136
137func main() {
138 db, err := sql.Open("postgres", "postgres://localhost:5432/database?sslmode=enable")
139 driver, err := postgres.WithInstance(db, &postgres.Config{})
140 m, err := migrate.NewWithDatabaseInstance(
141 "file:///migrations",
142 "postgres", driver)
143 m.Steps(2)
144}
145```
146
147## Getting started
148
149Go to [getting started](GETTING_STARTED.md)
150
151## Tutorials
152
153* [CockroachDB](database/cockroachdb/TUTORIAL.md)
154* [PostgreSQL](database/postgres/TUTORIAL.md)
155
156(more tutorials to come)
157
158## Migration files
159
160Each migration has an up and down migration. [Why?](FAQ.md#why-two-separate-files-up-and-down-for-a-migration)
161
162```bash
1631481574547_create_users_table.up.sql
1641481574547_create_users_table.down.sql
165```
166
167[Best practices: How to write migrations.](MIGRATIONS.md)
168
169## Versions
170
171Version | Supported? | Import | Notes
172--------|------------|--------|------
173**master** | :white_check_mark: | `import "github.com/golang-migrate/migrate/v4"` | New features and bug fixes arrive here first |
174**v4** | :white_check_mark: | `import "github.com/golang-migrate/migrate/v4"` | Used for stable releases |
175**v3** | :x: | `import "github.com/golang-migrate/migrate"` (with package manager) or `import "gopkg.in/golang-migrate/migrate.v3"` (not recommended) | **DO NOT USE** - No longer supported |
176
177## Development and Contributing
178
179Yes, please! [`Makefile`](Makefile) is your friend,
180read the [development guide](CONTRIBUTING.md).
181
182Also have a look at the [FAQ](FAQ.md).
183
184---
185
186Looking for alternatives? [https://awesome-go.com/#database](https://awesome-go.com/#database).
View as plain text