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).