{"id":15518445,"url":"https://github.com/c9s/goose","last_synced_at":"2025-04-23T04:10:03.204Z","repository":{"id":57507771,"uuid":"234481309","full_name":"c9s/goose","owner":"c9s","description":"Goose database migration tool - fork of https://github.com/pressly/goose","archived":false,"fork":false,"pushed_at":"2024-09-11T05:57:24.000Z","size":6490,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-29T10:00:36.679Z","etag":null,"topics":["database-migration","goose","sql-migration"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/c9s.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}},"created_at":"2020-01-17T05:58:48.000Z","updated_at":"2024-09-30T13:17:50.000Z","dependencies_parsed_at":"2024-11-07T01:26:11.111Z","dependency_job_id":"47cb7c68-8321-4ebf-99b0-b514f4224514","html_url":"https://github.com/c9s/goose","commit_stats":{"total_commits":350,"total_committers":61,"mean_commits":5.737704918032787,"dds":0.7228571428571429,"last_synced_commit":"2a3c63d062f8a47fd52ed63d5de7d5c719110ab4"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c9s%2Fgoose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c9s%2Fgoose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c9s%2Fgoose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c9s%2Fgoose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/c9s","download_url":"https://codeload.github.com/c9s/goose/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247750939,"owners_count":20989862,"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":["database-migration","goose","sql-migration"],"created_at":"2024-10-02T10:17:23.908Z","updated_at":"2025-04-17T06:30:56.651Z","avatar_url":"https://github.com/c9s.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# goose\n\nGoose is a database migration tool. Manage your database schema by creating incremental SQL changes or Go functions.\n\n[![GoDoc Widget]][GoDoc] [![Travis Widget]][Travis]\n\n### Goals of this fork\n\n`github.com/c9s/goose` is a fork of `github.com/pressly/goose` with the following changes:\n\n- Backward compatible with the original goose migration tool.\n- The goose migration table can be specified to the custom table name.\n- Added Go module support\n- Goose environment variable support for driver and DSN.\n\nDifference from `bitbucket.org/liamstask/goose`:\n\n- No config files\n- [Default goose binary](./cmd/goose/main.go) can migrate SQL files only\n- Go migrations:\n    - We don't `go build` Go migrations functions on-the-fly\n      from within the goose binary\n    - Instead, we let you\n      [create your own custom goose binary](examples/go-migrations),\n      register your Go migration functions explicitly and run complex\n      migrations with your own `*sql.DB` connection\n    - Go migration functions let you run your code within\n      an SQL transaction, if you use the `*sql.Tx` argument\n- The goose pkg is decoupled from the binary:\n    - goose pkg doesn't register any SQL drivers anymore,\n      thus no driver `panic()` conflict within your codebase!\n    - goose pkg doesn't have any vendor dependencies anymore\n- We use timestamped migrations by default but recommend a hybrid approach of using timestamps in the development process and sequential versions in production.\n\n# Install\n\n    $ go get -u github.com/c9s/goose/cmd/goose\n\nThis will install the `goose` binary to your `$GOPATH/bin` directory.\n\nFor a lite version of the binary without DB connection dependent commands, use the exclusive build tags:\n\n    $ go build -tags='no_postgres no_mysql no_sqlite3' -i -o goose ./cmd/goose\n\n\n# Usage\n\n```\nUsage: goose [OPTIONS] DRIVER DBSTRING COMMAND\n\nDrivers:\n    postgres\n    mysql\n    sqlite3\n    mssql\n    redshift\n\nExamples:\n    goose sqlite3 ./foo.db status\n    goose sqlite3 ./foo.db create init sql\n    goose sqlite3 ./foo.db create add_some_column sql\n    goose sqlite3 ./foo.db create fetch_user_data go\n    goose sqlite3 ./foo.db up\n\n    goose postgres \"user=postgres dbname=postgres sslmode=disable\" status\n    goose mysql \"user:password@/dbname?parseTime=true\" status\n    goose redshift \"postgres://user:password@qwerty.us-east-1.redshift.amazonaws.com:5439/db\" status\n    goose tidb \"user:password@/dbname?parseTime=true\" status\n    goose mssql \"sqlserver://user:password@dbname:1433?database=master\" status\n\nEnvironment Variable Support:\n\n    GOOSE_DRIVER=sqlite3 GOOSE_DBSTRING=./foo.db goose status\n    GOOSE_DRIVER=sqlite3 GOOSE_DBSTRING=./foo.db goose create init sql\n    GOOSE_DRIVER=postgres GOOSE_DBSTRING=\"user=postgres dbname=postgres sslmode=disable\" goose status\n    GOOSE_DRIVER=mysql GOOSE_DBSTRING=\"user:password@/dbname\" goose status\n    GOOSE_DRIVER=redshift GOOSE_DBSTRING=\"postgres://user:password@qwerty.us-east-1.redshift.amazonaws.com:5439/db\" goose status\n\nOptions:\n\n  -dir string\n    \tdirectory with migration files (default \".\")\n  -h\tprint help\n  -v\tenable verbose mode\n  -version\n    \tprint version\n\nCommands:\n    up                   Migrate the DB to the most recent version available\n    up-by-one            Migrate the DB up by 1\n    up-to VERSION        Migrate the DB to a specific VERSION\n    down                 Roll back the version by 1\n    down-to VERSION      Roll back to a specific VERSION\n    redo                 Re-run the latest migration\n    reset                Roll back all migrations\n    status               Dump the migration status for the current DB\n    version              Print the current version of the database\n    create NAME [sql|go] Creates new migration file with the current timestamp\n    fix                  Apply sequential ordering to migrations\n```\n\n## create\n\nCreate a new SQL migration.\n\n    $ goose create add_some_column sql\n    $ Created new file: 20170506082420_add_some_column.sql\n\nEdit the newly created file to define the behavior of your migration.\n\nYou can also create a Go migration, if you then invoke it with [your own goose binary](#go-migrations):\n\n    $ goose create fetch_user_data go\n    $ Created new file: 20170506082421_fetch_user_data.go\n\n## up\n\nApply all available migrations.\n\n    $ goose up\n    $ OK    001_basics.sql\n    $ OK    002_next.sql\n    $ OK    003_and_again.go\n\n## up-to\n\nMigrate up to a specific version.\n\n    $ goose up-to 20170506082420\n    $ OK    20170506082420_create_table.sql\n\n## up-by-one\n\nMigrate up a single migration from the current version\n\n    $ goose up-by-one\n    $ OK    20170614145246_change_type.sql\n\n## down\n\nRoll back a single migration from the current version.\n\n    $ goose down\n    $ OK    003_and_again.go\n\n## down-to\n\nRoll back migrations to a specific version.\n\n    $ goose down-to 20170506082527\n    $ OK    20170506082527_alter_column.sql\n\n## redo\n\nRoll back the most recently applied migration, then run it again.\n\n    $ goose redo\n    $ OK    003_and_again.go\n    $ OK    003_and_again.go\n\n## status\n\nPrint the status of all migrations:\n\n    $ goose status\n    $   Applied At                  Migration\n    $   =======================================\n    $   Sun Jan  6 11:25:03 2013 -- 001_basics.sql\n    $   Sun Jan  6 11:25:03 2013 -- 002_next.sql\n    $   Pending                  -- 003_and_again.go\n\nNote: for MySQL [parseTime flag](https://github.com/go-sql-driver/mysql#parsetime) must be enabled.\n\n## version\n\nPrint the current version of the database:\n\n    $ goose version\n    $ goose: version 002\n\n# Migrations\n\ngoose supports migrations written in SQL or in Go.\n\n## SQL Migrations\n\nA sample SQL migration looks like:\n\n```sql\n-- +goose Up\nCREATE TABLE post (\n    id int NOT NULL,\n    title text,\n    body text,\n    PRIMARY KEY(id)\n);\n\n-- +goose Down\nDROP TABLE post;\n```\n\nNotice the annotations in the comments. Any statements following `-- +goose Up` will be executed as part of a forward migration, and any statements following `-- +goose Down` will be executed as part of a rollback.\n\nBy default, all migrations are run within a transaction. Some statements like `CREATE DATABASE`, however, cannot be run within a transaction. You may optionally add `-- +goose NO TRANSACTION` to the top of your migration\nfile in order to skip transactions within that specific migration file. Both Up and Down migrations within this file will be run without transactions.\n\nBy default, SQL statements are delimited by semicolons - in fact, query statements must end with a semicolon to be properly recognized by goose.\n\nMore complex statements (PL/pgSQL) that have semicolons within them must be annotated with `-- +goose StatementBegin` and `-- +goose StatementEnd` to be properly recognized. For example:\n\n```sql\n-- +goose Up\n-- +goose StatementBegin\nCREATE OR REPLACE FUNCTION histories_partition_creation( DATE, DATE )\nreturns void AS $$\nDECLARE\n  create_query text;\nBEGIN\n  FOR create_query IN SELECT\n      'CREATE TABLE IF NOT EXISTS histories_'\n      || TO_CHAR( d, 'YYYY_MM' )\n      || ' ( CHECK( created_at \u003e= timestamp '''\n      || TO_CHAR( d, 'YYYY-MM-DD 00:00:00' )\n      || ''' AND created_at \u003c timestamp '''\n      || TO_CHAR( d + INTERVAL '1 month', 'YYYY-MM-DD 00:00:00' )\n      || ''' ) ) inherits ( histories );'\n    FROM generate_series( $1, $2, '1 month' ) AS d\n  LOOP\n    EXECUTE create_query;\n  END LOOP;  -- LOOP END\nEND;         -- FUNCTION END\n$$\nlanguage plpgsql;\n-- +goose StatementEnd\n```\n\n## Go Migrations\n\n1. Create your own goose binary, see [example](./examples/go-migrations)\n2. Import `github.com/c9s/goose`\n3. Register your migration functions\n4. Run goose command, ie. `goose.Up(db *sql.DB, dir string)`\n\nA [sample Go migration 00002_users_add_email.go file](./examples/go-migrations/00002_rename_root.go) looks like:\n\n```go\npackage migrations\n\nimport (\n\t\"database/sql\"\n\n\t\"github.com/c9s/goose\"\n)\n\nfunc init() {\n\tgoose.AddMigration(Up, Down)\n}\n\nfunc Up(tx *sql.Tx) error {\n\t_, err := tx.Exec(\"UPDATE users SET username='admin' WHERE username='root';\")\n\tif err != nil {\n\t\treturn err\n\t}\n\treturn nil\n}\n\nfunc Down(tx *sql.Tx) error {\n\t_, err := tx.Exec(\"UPDATE users SET username='root' WHERE username='admin';\")\n\tif err != nil {\n\t\treturn err\n\t}\n\treturn nil\n}\n```\n\n# Hybrid Versioning\nPlease, read the [versioning problem](https://github.com/pressly/goose/issues/63#issuecomment-428681694) first.\n\nWe strongly recommend adopting a hybrid versioning approach, using both timestamps and sequential numbers. Migrations created during the development process are timestamped and sequential versions are ran on production. We believe this method will prevent the problem of conflicting versions when writing software in a team environment.\n\nTo help you adopt this approach, `create` will use the current timestamp as the migration version. When you're ready to deploy your migrations in a production environment, we also provide a helpful `fix` command to convert your migrations into sequential order, while preserving the timestamp ordering. We recommend running `fix` in the CI pipeline, and only when the migrations are ready for production.\n\n## License\n\nLicensed under [MIT License](./LICENSE)\n\n[GoDoc]: https://godoc.org/github.com/c9s/goose\n[GoDoc Widget]: https://godoc.org/github.com/c9s/goose?status.svg\n[Travis]: https://travis-ci.org/c9s/goose\n[Travis Widget]: https://travis-ci.org/c9s/goose.svg?branch=master\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc9s%2Fgoose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fc9s%2Fgoose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc9s%2Fgoose/lists"}