github.com/quanghm/crate-migrate/v4@v4.0.0-20240506141318-8f1d4a2ddb6c/README.md (about) 1 [](https://github.com/quanghm/crate-migrate/actions/workflows/ci.yaml?query=branch%3Amaster) 2 [](https://pkg.go.dev/github.com/quanghm/crate-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/quanghm/crate-migrate/releases) 8 [](https://goreportcard.com/report/github.com/quanghm/crate-migrate/v4) 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 20 Forked from [mattes/migrate](https://github.com/mattes/migrate) 21 22 ## Databases 23 24 Database drivers run migrations. [Add a new database?](database/driver.go) 25 26 * [PostgreSQL](database/postgres) 27 * [PGX v4](database/pgx) 28 * [PGX v5](database/pgx/v5) 29 * [Redshift](database/redshift) 30 * [Ql](database/ql) 31 * [Cassandra / ScyllaDB](database/cassandra) 32 * [SQLite](database/sqlite) 33 * [SQLite3](database/sqlite3) ([todo #165](https://github.com/mattes/migrate/issues/165)) 34 * [SQLCipher](database/sqlcipher) 35 * [MySQL / MariaDB](database/mysql) 36 * [Neo4j](database/neo4j) 37 * [MongoDB](database/mongodb) 38 * [CrateDB](database/crate) ([todo #170](https://github.com/mattes/migrate/issues/170)) 39 * [Shell](database/shell) ([todo #171](https://github.com/mattes/migrate/issues/171)) 40 * [Google Cloud Spanner](database/spanner) 41 * [CockroachDB](database/cockroachdb) 42 * [YugabyteDB](database/yugabytedb) 43 * [ClickHouse](database/clickhouse) 44 * [Firebird](database/firebird) 45 * [MS SQL Server](database/sqlserver) 46 * [rqlite](database/rqlite) 47 48 ### Database URLs 49 50 Database 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` 51 52 Any [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) 53 54 Explicitly, the following characters need to be escaped: 55 `!`, `#`, `$`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `:`, `;`, `=`, `?`, `@`, `[`, `]` 56 57 It'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: 58 59 ```bash 60 $ python3 -c 'import urllib.parse; print(urllib.parse.quote(input("String to encode: "), ""))' 61 String to encode: FAKEpassword!#$%&'()*+,/:;=?@[] 62 FAKEpassword%21%23%24%25%26%27%28%29%2A%2B%2C%2F%3A%3B%3D%3F%40%5B%5D 63 $ python2 -c 'import urllib; print urllib.quote(raw_input("String to encode: "), "")' 64 String to encode: FAKEpassword!#$%&'()*+,/:;=?@[] 65 FAKEpassword%21%23%24%25%26%27%28%29%2A%2B%2C%2F%3A%3B%3D%3F%40%5B%5D 66 $ 67 ``` 68 69 ## Migration Sources 70 71 Source drivers read migrations from local or remote sources. [Add a new source?](source/driver.go) 72 73 * [Filesystem](source/file) - read from filesystem 74 * [io/fs](source/iofs) - read from a Go [io/fs](https://pkg.go.dev/io/fs#FS) 75 * [Go-Bindata](source/go_bindata) - read from embedded binary data ([jteeuwen/go-bindata](https://github.com/jteeuwen/go-bindata)) 76 * [pkger](source/pkger) - read from embedded binary data ([markbates/pkger](https://github.com/markbates/pkger)) 77 * [GitHub](source/github) - read from remote GitHub repositories 78 * [GitHub Enterprise](source/github_ee) - read from remote GitHub Enterprise repositories 79 * [Bitbucket](source/bitbucket) - read from remote Bitbucket repositories 80 * [Gitlab](source/gitlab) - read from remote Gitlab repositories 81 * [AWS S3](source/aws_s3) - read from Amazon Web Services S3 82 * [Google Cloud Storage](source/google_cloud_storage) - read from Google Cloud Platform Storage 83 84 ## CLI usage 85 86 * Simple wrapper around this library. 87 * Handles ctrl+c (SIGINT) gracefully. 88 * No config search paths, no config files, no magic ENV var injections. 89 90 __[CLI Documentation](cmd/migrate)__ 91 92 ### Basic usage 93 94 ```bash 95 $ migrate -source file://path/to/migrations -database postgres://localhost:5432/database up 2 96 ``` 97 98 ### Docker usage 99 100 ```bash 101 $ docker run -v {{ migration dir }}:/migrations --network host migrate/migrate 102 -path=/migrations/ -database postgres://localhost:5432/database up 2 103 ``` 104 105 ## Use in your Go project 106 107 * API is stable and frozen for this release (v3 & v4). 108 * Uses [Go modules](https://golang.org/cmd/go/#hdr-Modules__module_versions__and_more) to manage dependencies. 109 * To help prevent database corruptions, it supports graceful stops via `GracefulStop chan bool`. 110 * Bring your own logger. 111 * Uses `io.Reader` streams internally for low memory overhead. 112 * Thread-safe and no goroutine leaks. 113 114 __[Go Documentation](https://pkg.go.dev/github.com/quanghm/crate-migrate/v4)__ 115 116 ```go 117 import ( 118 "github.com/quanghm/crate-migrate/v4" 119 _ "github.com/quanghm/crate-migrate/v4/database/postgres" 120 _ "github.com/quanghm/crate-migrate/v4/source/github" 121 ) 122 123 func main() { 124 m, err := migrate.New( 125 "github://mattes:personal-access-token@mattes/migrate_test", 126 "postgres://localhost:5432/database?sslmode=enable") 127 m.Steps(2) 128 } 129 ``` 130 131 Want to use an existing database client? 132 133 ```go 134 import ( 135 "database/sql" 136 _ "github.com/lib/pq" 137 "github.com/quanghm/crate-migrate/v4" 138 "github.com/quanghm/crate-migrate/v4/database/postgres" 139 _ "github.com/quanghm/crate-migrate/v4/source/file" 140 ) 141 142 func main() { 143 db, err := sql.Open("postgres", "postgres://localhost:5432/database?sslmode=enable") 144 driver, err := postgres.WithInstance(db, &postgres.Config{}) 145 m, err := migrate.NewWithDatabaseInstance( 146 "file:///migrations", 147 "postgres", driver) 148 m.Up() // or m.Step(2) if you want to explicitly set the number of migrations to run 149 } 150 ``` 151 152 ## Getting started 153 154 Go to [getting started](GETTING_STARTED.md) 155 156 ## Tutorials 157 158 * [CockroachDB](database/cockroachdb/TUTORIAL.md) 159 * [PostgreSQL](database/postgres/TUTORIAL.md) 160 161 (more tutorials to come) 162 163 ## Migration files 164 165 Each migration has an up and down migration. [Why?](FAQ.md#why-two-separate-files-up-and-down-for-a-migration) 166 167 ```bash 168 1481574547_create_users_table.up.sql 169 1481574547_create_users_table.down.sql 170 ``` 171 172 [Best practices: How to write migrations.](MIGRATIONS.md) 173 174 ## Coming from another db migration tool? 175 176 Check out [migradaptor](https://github.com/musinit/migradaptor/). 177 *Note: migradaptor is not affiliated or supported by this project* 178 179 ## Versions 180 181 Version | Supported? | Import | Notes 182 --------|------------|--------|------ 183 **master** | :white_check_mark: | `import "github.com/quanghm/crate-migrate/v4"` | New features and bug fixes arrive here first | 184 **v4** | :white_check_mark: | `import "github.com/quanghm/crate-migrate/v4"` | Used for stable releases | 185 **v3** | :x: | `import "github.com/quanghm/crate-migrate"` (with package manager) or `import "gopkg.in/golang-migrate/migrate.v3"` (not recommended) | **DO NOT USE** - No longer supported | 186 187 ## Development and Contributing 188 189 Yes, please! [`Makefile`](Makefile) is your friend, 190 read the [development guide](CONTRIBUTING.md). 191 192 Also have a look at the [FAQ](FAQ.md). 193 194 --- 195 196 Looking for alternatives? [https://awesome-go.com/#database](https://awesome-go.com/#database).