{"id":13412021,"url":"https://github.com/robinjoseph08/go-pg-migrations","last_synced_at":"2025-04-04T11:13:39.022Z","repository":{"id":47498186,"uuid":"144363215","full_name":"robinjoseph08/go-pg-migrations","owner":"robinjoseph08","description":"A Go package to help write migrations with go-pg/pg.","archived":false,"fork":false,"pushed_at":"2024-10-17T18:11:32.000Z","size":77,"stargazers_count":85,"open_issues_count":3,"forks_count":22,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T10:07:52.815Z","etag":null,"topics":["go","go-pg","golang","migrations","postgresql"],"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/robinjoseph08.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2018-08-11T07:00:13.000Z","updated_at":"2025-02-26T02:36:20.000Z","dependencies_parsed_at":"2024-01-30T04:07:21.790Z","dependency_job_id":"0aff0680-8171-453d-a130-d118ec90070f","html_url":"https://github.com/robinjoseph08/go-pg-migrations","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinjoseph08%2Fgo-pg-migrations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinjoseph08%2Fgo-pg-migrations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinjoseph08%2Fgo-pg-migrations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robinjoseph08%2Fgo-pg-migrations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robinjoseph08","download_url":"https://codeload.github.com/robinjoseph08/go-pg-migrations/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247166168,"owners_count":20894654,"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":["go","go-pg","golang","migrations","postgresql"],"created_at":"2024-07-30T20:01:20.207Z","updated_at":"2025-04-04T11:13:39.000Z","avatar_url":"https://github.com/robinjoseph08.png","language":"Go","funding_links":[],"categories":["Database","Data Integration Frameworks","Generators","数据库","数据库  `go语言实现的数据库`","Uncategorized"],"sub_categories":["Database Schema Migration","Advanced Console UIs","数据库模式迁移","标准 CLI"],"readme":"# go-pg-migrations\n\n[![Version](https://img.shields.io/badge/version-v3.1.0-green.svg)](https://github.com/robinjoseph08/go-pg-migrations/releases)\n[![GoDoc](https://godoc.org/github.com/robinjoseph08/go-pg-migrations?status.svg)](http://godoc.org/github.com/robinjoseph08/go-pg-migrations)\n[![Build Status](https://github.com/robinjoseph08/go-pg-migrations/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/robinjoseph08/go-pg-migrations/actions)\n[![Coverage Status](https://coveralls.io/repos/github/robinjoseph08/go-pg-migrations/badge.svg?branch=master)](https://coveralls.io/github/robinjoseph08/go-pg-migrations?branch=master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/robinjoseph08/go-pg-migrations)](https://goreportcard.com/report/github.com/robinjoseph08/go-pg-migrations)\n\nA Go package to help write migrations with [`go-pg/pg`](https://github.com/go-pg/pg).\n\n## Usage\n\n### Installation\n\nBecause `go-pg` [now has Go modules\nsupport](https://github.com/go-pg/pg#get-started), `go-pg-migrations` also has\nmodules support; it currently depends on v10 of `go-pg`. To install it, use the\nfollowing command in a project with a `go.mod`:\n\n```sh\n$ go get github.com/robinjoseph08/go-pg-migrations/v3\n```\n\nIf you are not yet using Go modules, you can still use v1 of this package.\n\n### Running\n\nTo see how this package is intended to be used, you can look at the [example\ndirectory](/example). All you need to do is have a `main` package (e.g.\n`example`); call `migrations.Run` with the directory you want the migration\nfiles to be saved in (which will be the same directory of the main package, e.g.\n`example`), an instance of `*pg.DB`, and `os.Args`; and log any potential errors\nthat could be returned.\n\nYou can also call `migrations.RunWithOptions` to configure the way that the\nmigrations run (e.g. customize the name of the migration tables).\n\nOnce this has been set up, then you can use the `create`, `migrate`, `status`,\n`rollback`, `help` commands like so:\n\n```\n$ go run example/*.go create create_users_table\nCreating example/20180812001528_create_users_table.go...\n\n$ go run example/*.go migrate\nRunning batch 1 with 1 migration(s)...\nFinished running \"20180812001528_create_users_table\"\n\n$ go run example/*.go status\n+---------+-----------------------------------+-------+\n| Applied | Migration                         | Batch |\n+---------+-----------------------------------+-------+\n|    √    | 20180812001528_create_users_table |     1 |\n+---------+-----------------------------------+-------+\n\n$ go run example/*.go rollback\nRolling back batch 1 with 1 migration(s)...\nFinished rolling back \"20180812001528_create_users_table\"\n\n$ go run example/*.go help\nUsage:\n  go run example/*.go [command]\n\nCommands:\n  create   - create a new migration in example with the provided name\n  migrate  - run any migrations that haven't been run yet\n  rollback - roll back the previous run batch of migrations\n  status   - show the status of each migration\n  help     - print this help text\n\nExamples:\n  go run example/*.go create create_users_table\n  go run example/*.go migrate\n  go run example/*.go rollback\n  go run example/*.go status\n  go run example/*.go help\n```\n\nWhile this works when you have the Go toolchain installed, there might be a\nscenario where you have to run migrations and you don't have the toolchain\navailable (e.g. in a `scratch` or `alpine` Docker image deployed to production).\nIn that case, you should compile another binary (in addition to your actual\napplication) and copy it into the final image. This will include all of your\nmigrations and allow you to run it by overriding the command when running the\nDocker container.\n\nThis would look something like this:\n\n```dockerfile\n# Dockerfile\nFROM golang:1.13.3 as build\n\nWORKDIR /app\n\nCOPY go.mod go.mod\nCOPY go.sum go.sum\nRUN go mod download\n\nCOPY . .\n\nRUN CGO_ENABLED=0 GOOS=linux go build -installsuffix cgo -ldflags '-w -s' -o ./bin/serve ./cmd/serve\nRUN CGO_ENABLED=0 GOOS=linux go build -installsuffix cgo -ldflags '-w -s' -o ./bin/migrations ./cmd/migrations\n\nFROM alpine:3.8\n\nRUN apk --no-cache add ca-certificates\nCOPY --from=build /app/bin /bin\n\nCMD [\"serve\"]\n```\n\n```sh\n$ docker build -t service:latest .\n$ docker run --rm service:latest migrations migrate\n```\n\n## Why?\n\nWhile go-pg has [its own `migrations`\npackage](https://github.com/go-pg/migrations), it leaves a bit to be desired.\nSome additional features that this package supports:\n\n- Complete migration diffing to determine which migrations still need to be run.\n  Since `go-pg/migrations` checks the current version of migrations and runs any\n  migrations after that, some migrations can be missed, especially when several\n  people are working on the same project.\n- Timestamp-based prefixes to prevent two people creating a migration with the\n  same version on two separate branches. If the current version is 3, and more\n  than one person branches off and creates a new migration, all of them will be\n  version 4.\n- The ability to run migrations in a transaction on a case-by-case basis. Most\n  of the time, running migrations within a transaction is desirable, so that if\n  it errs out within the \"up\" function, the whole migration is reverted. But\n  since some long-running migrations might have a statement with a relatively\n  exclusive lock, you might opt out of running that specific migration within a\n  transaction.\n- A migration locking mechanism. This is to avoid two people (or an automated\n  deployment system) attempting to run migrations at the same time against the\n  same database, which could lead to undesired behavior.\n- An expected workflow of how this package should be used within a project.\n  While `go-pg/migrations` has some recommendations and examples, this package\n  takes a more opinionated approach which makes it so you don't have to think\n  about it as much, and there's less code for you to write and maintain.\n- Batch-level rollbacks. When there are multiple migration files run during the\n  same migration invocation, they are all grouped together into a \"batch\".\n  During rollbacks, each batch gets rolled back together. This tends to be more\n  desireable since this usually means the application is reverting back to a\n  previous release, so the database should be in the state expected for that\n  release.\n\nMany of these features and expected behaviors come from using [Knex.js\nmigrations](https://knexjs.org/#Migrations) in production for many years. This\nproject is heavily inspired by Knex to provide a robust and safe migration\nexperience.\n\n`go-pg` is a great and performant project, and hopefully, this makes it a little\nbetter.\n\n## Development\n\nTo develop on this project, you'll need to have Postgres running because the\ntests depend on it.\n\nIf you have it running on your machine because it was installed through your\npackage manager (like `brew` or `apt-get`), you just need to run the following\nto get it set up correctly:\n\n```sh\nmake setup\n```\n\nIf you don't have it on your laptop, you can run the following to start it\nwithin Docker:\n\n```sh\nmake postgres\n```\n\nThat should start the container and keep it running while you develop. Once\nyou're done, you can `^C` out of it and it will stop the container.\n\nTo run the tests, you should run:\n\n```sh\nmake test\n```\n\nTo run the linter, you should run:\n\n```sh\nmake lint\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobinjoseph08%2Fgo-pg-migrations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobinjoseph08%2Fgo-pg-migrations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobinjoseph08%2Fgo-pg-migrations/lists"}