{"id":13412070,"url":"https://github.com/rubenv/sql-migrate","last_synced_at":"2025-05-12T03:44:53.516Z","repository":{"id":20544304,"uuid":"23823837","full_name":"rubenv/sql-migrate","owner":"rubenv","description":"SQL schema migration tool for Go.","archived":false,"fork":false,"pushed_at":"2025-04-17T09:10:13.000Z","size":355,"stargazers_count":3319,"open_issues_count":90,"forks_count":285,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-05-01T13:51:55.080Z","etag":null,"topics":["bindata","go","sql","sql-schema-migration"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rubenv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-09-09T07:31:41.000Z","updated_at":"2025-05-01T10:41:52.000Z","dependencies_parsed_at":"2024-01-08T09:47:56.276Z","dependency_job_id":"f0339bde-f05d-4bc8-a687-32bece725304","html_url":"https://github.com/rubenv/sql-migrate","commit_stats":{"total_commits":284,"total_committers":72,"mean_commits":"3.9444444444444446","dds":0.5,"last_synced_commit":"5fd3db0fefadbeb8bcae4e330bcf67b8cb4a0eaa"},"previous_names":["rubenv/gorp-migrate"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenv%2Fsql-migrate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenv%2Fsql-migrate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenv%2Fsql-migrate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenv%2Fsql-migrate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rubenv","download_url":"https://codeload.github.com/rubenv/sql-migrate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253671629,"owners_count":21945462,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bindata","go","sql","sql-schema-migration"],"created_at":"2024-07-30T20:01:20.699Z","updated_at":"2025-05-12T03:44:53.471Z","avatar_url":"https://github.com/rubenv.png","language":"Go","readme":"# sql-migrate\n\n\u003e SQL Schema migration tool for [Go](https://golang.org/). Based on [gorp](https://github.com/go-gorp/gorp) and [goose](https://bitbucket.org/liamstask/goose).\n\n[![Test](https://github.com/rubenv/sql-migrate/actions/workflows/test.yml/badge.svg)](https://github.com/rubenv/sql-migrate/actions/workflows/test.yml) [![Go Reference](https://pkg.go.dev/badge/github.com/rubenv/sql-migrate.svg)](https://pkg.go.dev/github.com/rubenv/sql-migrate)\n\n## Features\n\n- Usable as a CLI tool or as a library\n- Supports SQLite, PostgreSQL, MySQL, MSSQL and Oracle databases (through [gorp](https://github.com/go-gorp/gorp))\n- Can embed migrations into your application\n- Migrations are defined with SQL for full flexibility\n- Atomic migrations\n- Up/down migrations to allow rollback\n- Supports multiple database types in one project\n- Works great with other libraries such as [sqlx](https://jmoiron.github.io/sqlx/)\n- Supported on go1.13+\n\n## Installation\n\nTo install the library and command line program, use the following:\n\n```bash\ngo get -v github.com/rubenv/sql-migrate/...\n```\n\nFor Go version from 1.18, use:\n\n```bash\ngo install github.com/rubenv/sql-migrate/...@latest\n```\n\n## Usage\n\n### As a standalone tool\n\n```\n$ sql-migrate --help\nusage: sql-migrate [--version] [--help] \u003ccommand\u003e [\u003cargs\u003e]\n\nAvailable commands are:\n    down      Undo a database migration\n    new       Create a new migration\n    redo      Reapply the last migration\n    status    Show migration status\n    up        Migrates the database to the most recent version available\n```\n\nEach command requires a configuration file (which defaults to `dbconfig.yml`, but can be specified with the `-config` flag). This config file should specify one or more environments:\n\n```yml\ndevelopment:\n  dialect: sqlite3\n  datasource: test.db\n  dir: migrations/sqlite3\n\nproduction:\n  dialect: postgres\n  datasource: dbname=myapp sslmode=disable\n  dir: migrations/postgres\n  table: migrations\n```\n\n(See more examples for different set ups [here](test-integration/dbconfig.yml))\n\nAlso one can obtain env variables in datasource field via `os.ExpandEnv` embedded call for the field.\nThis may be useful if one doesn't want to store credentials in file:\n\n```yml\nproduction:\n  dialect: postgres\n  datasource: host=prodhost dbname=proddb user=${DB_USER} password=${DB_PASSWORD} sslmode=require\n  dir: migrations\n  table: migrations\n```\n\nThe `table` setting is optional and will default to `gorp_migrations`.\n\nThe environment that will be used can be specified with the `-env` flag (defaults to `development`).\n\nUse the `--help` flag in combination with any of the commands to get an overview of its usage:\n\n```\n$ sql-migrate up --help\nUsage: sql-migrate up [options] ...\n\n  Migrates the database to the most recent version available.\n\nOptions:\n\n  -config=dbconfig.yml   Configuration file to use.\n  -env=\"development\"     Environment.\n  -limit=0               Limit the number of migrations (0 = unlimited).\n  -version               Run migrate up to a specific version, eg: the version number of migration 1_initial.sql is 1.\n  -dryrun                Don't apply migrations, just print them.\n```\n\nThe `new` command creates a new empty migration template using the following pattern `\u003ccurrent time\u003e-\u003cname\u003e.sql`.\n\nThe `up` command applies all available migrations. By contrast, `down` will only apply one migration by default. This behavior can be changed for both by using the `-limit` parameter, and the `-version` parameter. Note `-version` has higher priority than `-limit` if you try to use them both.\n\nThe `redo` command will unapply the last migration and reapply it. This is useful during development, when you're writing migrations.\n\nUse the `status` command to see the state of the applied migrations:\n\n```bash\n$ sql-migrate status\n+---------------+-----------------------------------------+\n|   MIGRATION   |                 APPLIED                 |\n+---------------+-----------------------------------------+\n| 1_initial.sql | 2014-09-13 08:19:06.788354925 +0000 UTC |\n| 2_record.sql  | no                                      |\n+---------------+-----------------------------------------+\n```\n\n#### Running Test Integrations\n\nYou can see how to run setups for different setups by executing the `.sh` files in [test-integration](test-integration/)\n\n```bash\n# Run mysql-env.sh example (you need to be in the project root directory)\n\n./test-integration/mysql-env.sh\n```\n\n### MySQL Caveat\n\nIf you are using MySQL, you must append `?parseTime=true` to the `datasource` configuration. For example:\n\n```yml\nproduction:\n  dialect: mysql\n  datasource: root@/dbname?parseTime=true\n  dir: migrations/mysql\n  table: migrations\n```\n\nSee [here](https://github.com/go-sql-driver/mysql#parsetime) for more information.\n\n### Oracle (oci8)\n\nOracle Driver is [oci8](https://github.com/mattn/go-oci8), it is not pure Go code and relies on Oracle Office Client ([Instant Client](https://www.oracle.com/database/technologies/instant-client/downloads.html)), more detailed information is in the [oci8 repo](https://github.com/mattn/go-oci8).\n\n#### Install with Oracle support\n\nTo install the library and command line program, use the following:\n\n```bash\ngo get -tags oracle -v github.com/rubenv/sql-migrate/...\n```\n\n```yml\ndevelopment:\n  dialect: oci8\n  datasource: user/password@localhost:1521/sid\n  dir: migrations/oracle\n  table: migrations\n```\n\n### Oracle (godror)\n\nOracle Driver is [godror](https://github.com/godror/godror), it is not pure Go code and relies on Oracle Office Client ([Instant Client](https://www.oracle.com/database/technologies/instant-client/downloads.html)), more detailed information is in the [godror repository](https://github.com/godror/godror).\n\n#### Install with Oracle support\n\nTo install the library and command line program, use the following:\n\n1. Install sql-migrate\n\n```bash\ngo get -tags godror -v github.com/rubenv/sql-migrate/...\n```\n\n2. Download Oracle Office Client(e.g. macos, click [Instant Client](https://www.oracle.com/database/technologies/instant-client/downloads.html) if you are other system)\n\n```bash\nwget https://download.oracle.com/otn_software/mac/instantclient/193000/instantclient-basic-macos.x64-19.3.0.0.0dbru.zip\n```\n\n3. Configure environment variables `LD_LIBRARY_PATH`\n\n```\nexport LD_LIBRARY_PATH=your_oracle_office_path/instantclient_19_3\n```\n\n```yml\ndevelopment:\n  dialect: godror\n  datasource: user/password@localhost:1521/sid\n  dir: migrations/oracle\n  table: migrations\n```\n\n### As a library\n\nImport sql-migrate into your application:\n\n```go\nimport \"github.com/rubenv/sql-migrate\"\n```\n\nSet up a source of migrations, this can be from memory, from a set of files, from bindata (more on that later), or from any library that implements [`http.FileSystem`](https://godoc.org/net/http#FileSystem):\n\n```go\n// Hardcoded strings in memory:\nmigrations := \u0026migrate.MemoryMigrationSource{\n    Migrations: []*migrate.Migration{\n        \u0026migrate.Migration{\n            Id:   \"123\",\n            Up:   []string{\"CREATE TABLE people (id int)\"},\n            Down: []string{\"DROP TABLE people\"},\n        },\n    },\n}\n\n// OR: Read migrations from a folder:\nmigrations := \u0026migrate.FileMigrationSource{\n    Dir: \"db/migrations\",\n}\n\n// OR: Use migrations from a packr box\n// Note: Packr is no longer supported, your best option these days is [embed](https://pkg.go.dev/embed)\nmigrations := \u0026migrate.PackrMigrationSource{\n    Box: packr.New(\"migrations\", \"./migrations\"),\n}\n\n// OR: Use pkger which implements `http.FileSystem`\nmigrationSource := \u0026migrate.HttpFileSystemMigrationSource{\n    FileSystem: pkger.Dir(\"/db/migrations\"),\n}\n\n// OR: Use migrations from bindata:\nmigrations := \u0026migrate.AssetMigrationSource{\n    Asset:    Asset,\n    AssetDir: AssetDir,\n    Dir:      \"migrations\",\n}\n\n// OR: Read migrations from a `http.FileSystem`\nmigrationSource := \u0026migrate.HttpFileSystemMigrationSource{\n    FileSystem: httpFS,\n}\n```\n\nThen use the `Exec` function to upgrade your database:\n\n```go\ndb, err := sql.Open(\"sqlite3\", filename)\nif err != nil {\n    // Handle errors!\n}\n\nn, err := migrate.Exec(db, \"sqlite3\", migrations, migrate.Up)\nif err != nil {\n    // Handle errors!\n}\nfmt.Printf(\"Applied %d migrations!\\n\", n)\n```\n\nNote that `n` can be greater than `0` even if there is an error: any migration that succeeded will remain applied even if a later one fails.\n\nCheck [the GoDoc reference](https://godoc.org/github.com/rubenv/sql-migrate) for the full documentation.\n\n## Writing migrations\n\nMigrations are defined in SQL files, which contain a set of SQL statements. Special comments are used to distinguish up and down migrations.\n\n```sql\n-- +migrate Up\n-- SQL in section 'Up' is executed when this migration is applied\nCREATE TABLE people (id int);\n\n\n-- +migrate Down\n-- SQL section 'Down' is executed when this migration is rolled back\nDROP TABLE people;\n```\n\nYou can put multiple statements in each block, as long as you end them with a semicolon (`;`).\n\nYou can alternatively set up a separator string that matches an entire line by setting `sqlparse.LineSeparator`. This\ncan be used to imitate, for example, MS SQL Query Analyzer functionality where commands can be separated by a line with\ncontents of `GO`. If `sqlparse.LineSeparator` is matched, it will not be included in the resulting migration scripts.\n\nIf you have complex statements which contain semicolons, use `StatementBegin` and `StatementEnd` to indicate boundaries:\n\n```sql\n-- +migrate Up\nCREATE TABLE people (id int);\n\n-- +migrate StatementBegin\nCREATE OR REPLACE FUNCTION do_something()\nreturns void AS $$\nDECLARE\n  create_query text;\nBEGIN\n  -- Do something here\nEND;\n$$\nlanguage plpgsql;\n-- +migrate StatementEnd\n\n-- +migrate Down\nDROP FUNCTION do_something();\nDROP TABLE people;\n```\n\nThe order in which migrations are applied is defined through the filename: sql-migrate will sort migrations based on their name. It's recommended to use an increasing version number or a timestamp as the first part of the filename.\n\nNormally each migration is run within a transaction in order to guarantee that it is fully atomic. However some SQL commands (for example creating an index concurrently in PostgreSQL) cannot be executed inside a transaction. In order to execute such a command in a migration, the migration can be run using the `notransaction` option:\n\n```sql\n-- +migrate Up notransaction\nCREATE UNIQUE INDEX CONCURRENTLY people_unique_id_idx ON people (id);\n\n-- +migrate Down\nDROP INDEX people_unique_id_idx;\n```\n\n## Embedding migrations with [embed](https://pkg.go.dev/embed)\n\nIf you like your Go applications self-contained (that is: a single binary): use [embed](https://pkg.go.dev/embed) to embed the migration files.\n\nJust write your migration files as usual, as a set of SQL files in a folder.\n\nImport the embed package into your application and point it to your migrations:\n\n```go\nimport \"embed\"\n\n//go:embed migrations/*\nvar dbMigrations embed.FS\n```\n\nUse the `EmbedFileSystemMigrationSource` in your application to find the migrations:\n\n```go\nmigrations := migrate.EmbedFileSystemMigrationSource{\n\tFileSystem: dbMigrations,\n\tRoot:       \"migrations\",\n}\n```\n\nOther options such as [packr](https://github.com/gobuffalo/packr) or [go-bindata](https://github.com/shuLhan/go-bindata) are no longer recommended.\n\n## Embedding migrations with libraries that implement `http.FileSystem`\n\nYou can also embed migrations with any library that implements `http.FileSystem`, like [`vfsgen`](https://github.com/shurcooL/vfsgen), [`parcello`](https://github.com/phogolabs/parcello), or [`go-resources`](https://github.com/omeid/go-resources).\n\n```go\nmigrationSource := \u0026migrate.HttpFileSystemMigrationSource{\n    FileSystem: httpFS,\n}\n```\n\n## Extending\n\nAdding a new migration source means implementing `MigrationSource`.\n\n```go\ntype MigrationSource interface {\n    FindMigrations() ([]*Migration, error)\n}\n```\n\nThe resulting slice of migrations will be executed in the given order, so it should usually be sorted by the `Id` field.\n\n## Usage with [sqlx](https://jmoiron.github.io/sqlx/)\n\nThis library is compatible with sqlx. When calling migrate just dereference the DB from your `*sqlx.DB`:\n\n```\nn, err := migrate.Exec(db.DB, \"sqlite3\", migrations, migrate.Up)\n                    //   ^^^ \u003c-- Here db is a *sqlx.DB, the db.DB field is the plain sql.DB\nif err != nil {\n    // Handle errors!\n}\n```\n\n## Questions or Feedback?\n\nYou can use Github Issues for feedback or questions.\n\n## License\n\nThis library is distributed under the [MIT](LICENSE) license.\n","funding_links":[],"categories":["数据库","Database","Go","Miscellaneous","Generators","\u003cspan id=\"数据库-database\"\u003e数据库 Database\u003c/span\u003e","sql","数据库  `go语言实现的数据库`","Repositories","Uncategorized","Data Integration Frameworks","數據庫"],"sub_categories":["高级控制台界面","Database Schema Migration","Advanced Console UIs","标准 CLI","数据库模式迁移","\u003cspan id=\"高级控制台用户界面-advanced-console-uis\"\u003e高级控制台用户界面 Advanced Console UIs\u003c/span\u003e","高級控制台界面"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubenv%2Fsql-migrate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubenv%2Fsql-migrate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubenv%2Fsql-migrate/lists"}