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