migrate/README.md

139 lines
4.9 KiB
Markdown
Raw Normal View History

2017-02-08 06:40:45 +00:00
[![Build Status](https://travis-ci.org/mattes/migrate.svg?branch=v3.0-prev)](https://travis-ci.org/mattes/migrate)
2014-08-11 03:06:38 +00:00
[![GoDoc](https://godoc.org/github.com/mattes/migrate?status.svg)](https://godoc.org/github.com/mattes/migrate)
2017-02-09 00:17:04 +00:00
[![Coverage Status](https://coveralls.io/repos/github/mattes/migrate/badge.svg?branch=v3.0-prev)](https://coveralls.io/github/mattes/migrate?branch=v3.0-prev)
2017-02-10 04:09:11 +00:00
[![packagecloud.io](https://img.shields.io/badge/deb-packagecloud.io-844fec.svg)](https://packagecloud.io/mattes/migrate?filter=debs)
2014-08-11 03:06:38 +00:00
2017-02-11 19:13:27 +00:00
# migrate
__Database migrations written in Go. Use as [CLI](#cli-usage) or import as [library](#use-in-your-go-project).__
* Migrate reads migrations from [sources](#migration-sources)
and applies them in correct order to a [database](#databases).
* Drivers are "dumb", migrate glues everything together and makes sure the logic is bulletproof.
(Keeps the drivers lightweight, too.)
* Database drivers don't assume things or try to correct user input. When in doubt, fail.
2014-08-13 21:58:30 +00:00
2014-08-11 01:42:57 +00:00
2017-02-08 06:40:45 +00:00
## Databases
2014-08-11 01:42:57 +00:00
2017-02-11 19:13:27 +00:00
Database drivers run migrations. [Add a new database?](database/driver.go)
2014-08-11 01:42:57 +00:00
2017-02-08 06:40:45 +00:00
* [PostgreSQL](database/postgres)
2017-02-17 04:41:17 +00:00
* [Cassandra](database/cassandra) ([todo #164](https://github.com/mattes/migrate/issues/164))
* [SQLite](database/sqlite) ([todo #165](https://github.com/mattes/migrate/issues/165))
* [MySQL/ MariaDB](database/mysql) ([todo #166](https://github.com/mattes/migrate/issues/166))
* [Neo4j](database/neo4j) ([todo #167](https://github.com/mattes/migrate/issues/167))
* [Ql](database/ql) ([todo #168](https://github.com/mattes/migrate/issues/168))
* [MongoDB](database/mongodb) ([todo #169](https://github.com/mattes/migrate/issues/169))
* [CrateDB](database/crate) ([todo #170](https://github.com/mattes/migrate/issues/170))
* [Shell](database/shell) ([todo #171](https://github.com/mattes/migrate/issues/171))
2014-08-11 01:42:57 +00:00
2017-02-11 19:13:27 +00:00
2017-02-08 06:40:45 +00:00
## Migration Sources
2014-08-11 01:42:57 +00:00
2017-02-11 19:13:27 +00:00
Source drivers read migrations from local or remote sources. [Add a new source?](source/driver.go)
2014-08-11 01:42:57 +00:00
2017-02-08 06:40:45 +00:00
* [Filesystem](source/file) - read from fileystem (always included)
* [Go-Bindata](source/go-bindata) - read from embedded binary data ([jteeuwen/go-bindata](https://github.com/jteeuwen/go-bindata))
* [Github](source/github) - read from remote Github repositories
2017-02-17 04:41:17 +00:00
* [AWS S3](source/aws-s3) - read from Amazon Web Services S3 ([todo #162](https://github.com/mattes/migrate/issues/162))
* [Google Cloud Storage](source/google-cloud-storage) - read from Google Cloud Platform Storage ([todo #163](https://github.com/mattes/migrate/issues/163))
2014-08-11 01:42:57 +00:00
2014-08-13 00:38:29 +00:00
2017-02-11 19:13:27 +00:00
## CLI usage
2017-02-10 04:00:38 +00:00
2017-02-11 19:13:27 +00:00
* Simple wrapper around this library.
* Handles ctrl+c (SIGINT) gracefully.
* No config search paths, no config files, no magic ENV var injections.
2017-02-10 04:00:38 +00:00
2017-02-11 19:13:27 +00:00
__[CLI Documentation](cli)__
2017-02-10 04:00:38 +00:00
2017-02-17 05:13:12 +00:00
([brew todo #156](https://github.com/mattes/migrate/issues/156))
```
2017-02-11 19:13:27 +00:00
$ brew install migrate --with-postgres
$ migrate -database postgres://localhost:5432/database up 2
2014-08-11 01:42:57 +00:00
```
2017-02-08 06:40:45 +00:00
## Use in your Go project
2014-08-11 01:42:57 +00:00
2017-02-11 19:13:27 +00:00
* API is stable and frozen for this release (v3.x).
* Package migrate has no external dependencies.
* Only import the drivers you need.
(check [dependency_tree.txt](https://github.com/mattes/migrate/releases) for each driver)
* To help prevent database corruptions, it supports graceful stops via `GracefulStop chan bool`.
* Bring your own logger.
* Uses `io.Reader` streams internally for low memory overhead.
* Thread-safe and no goroutine leaks.
2017-02-11 19:13:27 +00:00
__[Go Documentation](https://godoc.org/github.com/mattes/migrate)__
2014-08-13 00:38:29 +00:00
```go
2017-02-08 06:40:45 +00:00
import (
2017-02-11 19:13:27 +00:00
"github.com/mattes/migrate/migrate"
_ "github.com/mattes/migrate/database/postgres"
_ "github.com/mattes/migrate/source/github"
2017-02-08 06:40:45 +00:00
)
func main() {
2017-02-11 19:13:27 +00:00
m, err := migrate.New(
"github://mattes:personal-access-token@mattes/migrate_test",
"postgres://localhost:5432/database?sslmode=enable")
m.Steps(2)
2014-08-13 00:38:29 +00:00
}
2014-08-11 01:42:57 +00:00
```
2017-02-15 07:25:19 +00:00
Want to use an existing database client?
```go
import (
"database/sql"
_ "github.com/lib/pq"
"github.com/mattes/migrate/migrate"
"github.com/mattes/migrate/database/postgres"
)
func main() {
db, err := sql.Open("postgres", "postgres://localhost:5432/database?sslmode=enable")
driver, err := postgres.WithInstance(db, &postgres.Config{})
m, err := migrate.NewWithDatabaseInstance(
"file:///migrations",
"postgres", driver)
m.Steps(2)
}
```
2014-08-13 02:04:58 +00:00
## Migration files
2014-08-13 00:38:29 +00:00
2017-02-11 19:13:27 +00:00
Each migration has an up and down migration. [Why?](FAQ.md#why-two-separate-files-up-and-down-for-a-migration)
2014-08-11 01:42:57 +00:00
```
2017-02-08 06:40:45 +00:00
1481574547_create_users_table.up.sql
1481574547_create_users_table.down.sql
2014-08-11 01:42:57 +00:00
```
2017-02-11 19:13:27 +00:00
[Best practices: How to write migrations.](MIGRATIONS.md)
## Development and Contributing
Yes, please! [`Makefile`](Makefile) is your friend,
read the [development guide](CONTRIBUTING.md).
2017-02-11 19:13:27 +00:00
Also have a look at the [FAQ](FAQ.md).
2017-02-10 04:03:56 +00:00
2014-08-11 01:42:57 +00:00
2017-02-11 19:13:27 +00:00
---
2014-08-13 00:38:29 +00:00
2017-02-11 19:13:27 +00:00
__Alternatives__
2014-08-13 00:38:29 +00:00
2017-02-11 19:13:27 +00:00
https://bitbucket.org/liamstask/goose, https://github.com/tanel/dbmigrate,
https://github.com/BurntSushi/migration, https://github.com/DavidHuie/gomigrate,
https://github.com/rubenv/sql-migrate