{"id":41870877,"url":"https://github.com/vmkteam/pgmigrator","last_synced_at":"2026-01-25T12:08:17.027Z","repository":{"id":104901213,"uuid":"439357421","full_name":"vmkteam/pgmigrator","owner":"vmkteam","description":"Command-line tool for PostgreSQL migrations","archived":false,"fork":false,"pushed_at":"2024-12-27T08:45:27.000Z","size":59,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-12-27T09:29:18.119Z","etag":null,"topics":["migration-tool","migrations","pgmigrator","postgresql","postgresql-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/vmkteam.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":"2021-12-17T14:21:17.000Z","updated_at":"2024-12-27T08:44:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"13d8c78b-2e97-4537-84db-05a8fc40547e","html_url":"https://github.com/vmkteam/pgmigrator","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/vmkteam/pgmigrator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmkteam%2Fpgmigrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmkteam%2Fpgmigrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmkteam%2Fpgmigrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmkteam%2Fpgmigrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vmkteam","download_url":"https://codeload.github.com/vmkteam/pgmigrator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmkteam%2Fpgmigrator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28752681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T10:25:12.305Z","status":"ssl_error","status_checked_at":"2026-01-25T10:25:11.933Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["migration-tool","migrations","pgmigrator","postgresql","postgresql-migration"],"created_at":"2026-01-25T12:08:16.169Z","updated_at":"2026-01-25T12:08:17.003Z","avatar_url":"https://github.com/vmkteam.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pgmigrator: command-line tool for PostgreSQL migrations.\n\n[![Release](https://img.shields.io/github/release/vmkteam/pgmigrator.svg)](https://github.com/vmkteam/pgmigrator/releases/latest)\n[![Build Status](https://github.com/vmkteam/pgmigrator/actions/workflows/go.yml/badge.svg?branch=master)](https://github.com/vmkteam/pgmigrator/actions)\n[![Linter Status](https://github.com/vmkteam/pgmigrator/actions/workflows/golangci-lint.yml/badge.svg?branch=master)](https://github.com/vmkteam/pgmigrator/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/vmkteam/pgmigrator)](https://goreportcard.com/report/github.com/vmkteam/pgmigrator)\n[![codecov](https://codecov.io/gh/vmkteam/pgmigrator/branch/master/graph/badge.svg)](https://codecov.io/gh/vmkteam/pgmigrator)\n\npgmigrator is a very simple utility designed to roll up incremental (up only) migrations for PostgreSQL only.\n\nGoal: to make an understandable tool for local development and stage environments.\n\nLimitations\n--\n* Database: PostgreSQL\n* Migrations filename mask: `YYYYY-MM-DDD-\u003cdescription\u003e.sql` / `YYYYY-MM-DD-\u003cdescription\u003e-NONTR.sql`\n* Migration types: UP only\n* Algorithm: applies sorted migrations files that are in the folder and fit the file mask, except for what is already applied in the database\n* The program works only with the configuration file located in the folder with migrations.\n\n\nFAQ\n--\nQ: Why only up migrations?\u003cbr\u003e\nA: In development, we almost never write down migrations because it's useless in 99% of cases. If something goes wrong, we just don't roll up or decide manually what to do.\n\nQ: Why only PostgreSQL? \u003cbr\u003e\nA: There is a goal to create a highly specialized simple tool for migrations.\n\nQ: Why such a specific file mask rather than the generally recognized one `V\u003cVersion\u003e_\u003cdescription\u003e.sql`?\u003cbr\u003e\nA: This is historically the case. The date in the file gives more transparency than the version number. Less development conflicts in the branch.\u003cbr\u003e\n_It is possible to override this parameter through the configuration file._\n\nQ: Why not as a library? Why migrations specifically as files on disk?\nA: The goal is a simple utility that works with files. Alternatives in the form of libraries have already been written here https://awesome-go.com/#database-schema-migration\n\nMigrations\n--\nMigration files are located in a folder. Subfolders are not counted. Files are sorted by name.\nAll recorded migrations are written to a table in database (by default `public.pgMigrations`)\nDefault file mask: `YYYYY-MM-DDD-\u003cdescription\u003e.sql`.\n\nAll migrations are started in a separate transaction with a specific StatementTimeout in the configuration file. If not specified, it is not used.\nNon-transactional migrations have the following file mask: `YYYYY-MM-DD-\u003cdescription\u003e-NONTR.sql` (e.g. for create index concurrently).\n\nYou can override the file mask through the configuration file. If not specified, the default one is used.\nIf there is `MANUAL` at the end of the file name, this migration will be ignored.\n\n        2020 // folder, not counted\n        pgmigrator.toml // mandatory configuration file\n        2021-04-12-create-table-commentTranslations.sql // runs inside transaction\n        2021-06-02-make-person-alias-not-null-NONTR.sql  // runs outside transaction\n        2021-06-03-make-person-alias-not-null-MANUAL.sql // ignored\n\n\nConfiguration file\n--\n\t[App]\n\tTable = \"public.pgMigrations\"\n\tStatementTimeout = \"5s\" \n\tFilemask = \"\\d{4}-\\d{2}-\\d{2}-\\S+.sql\"\n\t\n\t[Database]\n\tAddr     = \"localhost:5432\"\n\tUser     = \"postgres\"\n\tPassword = \"tesdb\"\n\tDatabase = \"testdb\"\n\tPoolSize = 1\n\tApplicationName = \"pgmigrator\"\n\nRun\n--\n    Command-line tool for PostgreSQL migrations\n    \n    Usage:\n    pgmigrator [command]\n    \n    Available Commands:\n    completion  Generate the autocompletion script for the specified shell\n    dryrun      Tries to apply migrations. Runs migrations inside single transaction and always rollbacks it\n    help        Help about any command\n    init        Initialize default configuration file in current directory\n    last        Shows recent applied migrations from db\n    plan        Shows migration files which can be applied\n    redo        Rerun last applied migration from db\n    run         Applies all new migrations\n    skip        Marks migrations done without actually running them.\n    verify      Checks and shows invalid migrations\n    \n    Flags:\n    -c, --config string   configuration file (default \"pgmigrator.toml\")\n    -h, --help            help for pgmigrator\n    -v, --version         version for pgmigrator\n    \n    Use \"pgmigrator [command] --help\" for more information about a command.\n\nAny command supports an argument in the form of a number. For `last` it is the number of last migrations (default is 5). For all others - the number of the file from `plan` to which to apply migrations. If no argument is passed, there are no restrictions (or default ones are used).\n\nThe base directory for migrations is the one where the configuration file is located.\nThat is, you can call `pgmigrator --config docs/patches/pgmigrator.toml plan` and it will take all migrations from the `docs/patches` folder.\n\n## Commands\n\n### Plan\n\n**Algorithm**\n\n* get a list of files sorted by name\n* connect to the database\n    - check if there is a table\n    - get the list of migrations from the database\n* display the list of files to be applied  (TODO: highlight DROP?)\n\n**Output**\n\n\tPlanning to apply Х migrations:\n\t\t1 - 2022-07-18-movieComments.sql\n\t\t2 - 2022-07-28-jwlinks.sql\n\t\t3 - 2022-07-30-compilations-fix.sql \n\n\n### Run\n\n**Algorithm**\n\n* create a table, if necessary\n* make a plan\n  - for each file\n     - if the migration is regular\n        - begin\n          - perform migration\n          - add a record of the completed migration\n        - commit\n     - if migration is non-transactional\n        - add migration record\n        - perform migration\n        - update migration record\n     - if something goes wrong - rollback and exit (except for nontr, since it is not clear what exactly happened).\n\n**Output**\n\n\tPlanning to apply Х migrations:\n\t\t1 - 2022-07-18-movieComments.sql\n\t\t2 - 2022-07-28-jwlinks.sql\n\t\t3 - 2022-07-30-compilations-fix.sql \n\n\tApplying:\n\t\t1 - 2022-07-18-movieComments.sql ... done in 2s \n\t\t2 - 2022-07-28-jwlinks.sql ... done in 3m\n\t\t3 - 2022-07-30-compilations-fix.sql ... \t\t\n\tERROR: \u003cerror text\u003e\n\n### DryRun\n\n* Like `Run`, but open one big transaction and use ROLLBACK.\n* If there is a NONTR - do not let dryrun run (only up to a certain filename)\n* `StatementTimeout` setting is ignored\n\n### Skip\n\nLike `Run`, but without actually running sql migration, only adding migration success record\n\n### Last\n\nShows the latest database migrations from a table.\n\n**Output**\n\n    Showing last migrations in public.pgMigrations:\n    34 - 2022-08-30 22:25:03 (ERR) \t \u003e 2022-07-30-compilations-NONTR.sql\n    33 - 2022-08-30 22:25:03 (3s)  \t \u003e 2022-07-30-compilations-fix.sql\n    32 - 2022-08-30 22:25:34 (1s)    \u003e 2022-07-28-jwlinks.sql\n    31 - 2022-08-30 22:23:12 (5m 4s) \u003e 2022-07-18-movieComments.sql\n\n### Verify\n\nChecks patch integrity in the database and locally by md5 hash.\n\n### Init\n\nInitializes a new configuration file with default settings.\n\n### Redo\n\nPerform again the last migration that is recorded in the table.\n\nDatabase model\n-- \nDefault: table `pgMigrations`, scheme `public`.\nIt is recommended to have a different migrations table for each schema.\n\n    create table if not exists \"pgMigrations\"\n    (\n        id            serial                    not null,\n        filename      text                      not null,\n        \"startedAt\"   timestamptz default now() not null,\n        \"finishedAt\"  timestamptz,\n        transactional bool        default true  not null,\n        md5sum        varchar(32)               not null,\n        primary key (\"id\"),\n        unique (\"filename\")\n    );\n\n* id (pk) – serial\n* filename - unique migration file name\n* startedAt - timestamp of starting migration\n* finishedAt - timestamp of finishing migration\n* transactional - transactional flag (false для NONTR migrations)\n* md5sum - md5 hash of migration file \n\n### Docker images\n- [Docker Hub](https://hub.docker.com/vmkteam/pgmigrator)\n- Packages Tab in this repo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmkteam%2Fpgmigrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvmkteam%2Fpgmigrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmkteam%2Fpgmigrator/lists"}