github.com/requaos/migrate@v3.4.0+incompatible/README.md (about) 1 [![Build Status](https://img.shields.io/travis/golang-migrate/migrate/master.svg)](https://travis-ci.org/golang-migrate/migrate) 2 [![GoDoc](https://godoc.org/github.com/golang-migrate/migrate?status.svg)](https://godoc.org/github.com/golang-migrate/migrate) 3 [![Coverage Status](https://img.shields.io/coveralls/github/golang-migrate/migrate/master.svg)](https://coveralls.io/github/golang-migrate/migrate?branch=master) 4 [![packagecloud.io](https://img.shields.io/badge/deb-packagecloud.io-844fec.svg)](https://packagecloud.io/golang-migrate/migrate?filter=debs) 5 [![Docker Pulls](https://img.shields.io/docker/pulls/migrate/migrate.svg)](https://hub.docker.com/r/migrate/migrate/) 6 ![Supported Go Versions](https://img.shields.io/badge/Go-1.9%2C%201.10-lightgrey.svg) 7 [![GitHub Release](https://img.shields.io/github/release/golang-migrate/migrate.svg)](https://github.com/golang-migrate/migrate/releases) 8 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 21 Looking for [v1](https://github.com/golang-migrate/migrate/tree/v1)? 22 23 24 ## Databases 25 26 Database drivers run migrations. [Add a new database?](database/driver.go) 27 28 * [PostgreSQL](database/postgres) 29 * [Redshift](database/redshift) 30 * [Ql](database/ql) 31 * [Cassandra](database/cassandra) 32 * [SQLite](database/sqlite3) ([todo #165](https://github.com/mattes/migrate/issues/165)) 33 * [MySQL/ MariaDB](database/mysql) 34 * [Neo4j](database/neo4j) ([todo #167](https://github.com/mattes/migrate/issues/167)) 35 * [MongoDB](database/mongodb) ([todo #169](https://github.com/mattes/migrate/issues/169)) 36 * [CrateDB](database/crate) ([todo #170](https://github.com/mattes/migrate/issues/170)) 37 * [Shell](database/shell) ([todo #171](https://github.com/mattes/migrate/issues/171)) 38 * [Google Cloud Spanner](database/spanner) 39 * [CockroachDB](database/cockroachdb) 40 * [ClickHouse](database/clickhouse) 41 42 ### Database URLs 43 44 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` 45 46 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) 47 48 Explicitly, the following characters need to be escaped: 49 `!`, `#`, `$`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `:`, `;`, `=`, `?`, `@`, `[`, `]` 50 51 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 helpers below: 52 ```bash 53 $ python3 -c 'import urllib.parse; print(urllib.parse.quote(input("String to encode: "), ""))' 54 String to encode: FAKEpassword!#$%&'()*+,/:;=?@[] 55 FAKEpassword%21%23%24%25%26%27%28%29%2A%2B%2C%2F%3A%3B%3D%3F%40%5B%5D 56 $ python2 -c 'import urllib; print urllib.quote(raw_input("String to encode: "), "")' 57 String to encode: FAKEpassword!#$%&'()*+,/:;=?@[] 58 FAKEpassword%21%23%24%25%26%27%28%29%2A%2B%2C%2F%3A%3B%3D%3F%40%5B%5D 59 $ 60 ``` 61 62 ## Migration Sources 63 64 Source drivers read migrations from local or remote sources. [Add a new source?](source/driver.go) 65 66 * [Filesystem](source/file) - read from fileystem 67 * [Go-Bindata](source/go_bindata) - read from embedded binary data ([jteeuwen/go-bindata](https://github.com/jteeuwen/go-bindata)) 68 * [Github](source/github) - read from remote Github repositories 69 * [AWS S3](source/aws_s3) - read from Amazon Web Services S3 70 * [Google Cloud Storage](source/google_cloud_storage) - read from Google Cloud Platform Storage 71 72 73 74 ## CLI usage 75 76 * Simple wrapper around this library. 77 * Handles ctrl+c (SIGINT) gracefully. 78 * No config search paths, no config files, no magic ENV var injections. 79 80 __[CLI Documentation](cli)__ 81 82 ### Basic usage: 83 84 ``` 85 $ migrate -database postgres://localhost:5432/database up 2 86 ``` 87 88 ### Docker usage 89 90 ``` 91 $ docker run -v {{ migration dir }}:/migrations --network host migrate/migrate 92 -path=/migrations/ -database postgres://localhost:5432/database up 2 93 ``` 94 95 ## Use in your Go project 96 97 * API is stable and frozen for this release (v3.x). 98 * Uses [dep](https://github.com/golang/dep) to manage dependencies 99 * To help prevent database corruptions, it supports graceful stops via `GracefulStop chan bool`. 100 * Bring your own logger. 101 * Uses `io.Reader` streams internally for low memory overhead. 102 * Thread-safe and no goroutine leaks. 103 104 __[Go Documentation](https://godoc.org/github.com/golang-migrate/migrate)__ 105 106 ```go 107 import ( 108 "github.com/golang-migrate/migrate" 109 _ "github.com/golang-migrate/migrate/database/postgres" 110 _ "github.com/golang-migrate/migrate/source/github" 111 ) 112 113 func main() { 114 m, err := migrate.New( 115 "github://mattes:personal-access-token@mattes/migrate_test", 116 "postgres://localhost:5432/database?sslmode=enable") 117 m.Steps(2) 118 } 119 ``` 120 121 Want to use an existing database client? 122 123 ```go 124 import ( 125 "database/sql" 126 _ "github.com/lib/pq" 127 "github.com/golang-migrate/migrate" 128 "github.com/golang-migrate/migrate/database/postgres" 129 _ "github.com/golang-migrate/migrate/source/file" 130 ) 131 132 func main() { 133 db, err := sql.Open("postgres", "postgres://localhost:5432/database?sslmode=enable") 134 driver, err := postgres.WithInstance(db, &postgres.Config{}) 135 m, err := migrate.NewWithDatabaseInstance( 136 "file:///migrations", 137 "postgres", driver) 138 m.Steps(2) 139 } 140 ``` 141 142 ## Migration files 143 144 Each migration has an up and down migration. [Why?](FAQ.md#why-two-separate-files-up-and-down-for-a-migration) 145 146 ``` 147 1481574547_create_users_table.up.sql 148 1481574547_create_users_table.down.sql 149 ``` 150 151 [Best practices: How to write migrations.](MIGRATIONS.md) 152 153 154 155 ## Development and Contributing 156 157 Yes, please! [`Makefile`](Makefile) is your friend, 158 read the [development guide](CONTRIBUTING.md). 159 160 Also have a look at the [FAQ](FAQ.md). 161 162 163 164 --- 165 166 Looking for alternatives? [https://awesome-go.com/#database](https://awesome-go.com/#database).