{"id":19188317,"url":"https://github.com/zx80/pg-schema-version","last_synced_at":"2025-10-20T02:45:54.899Z","repository":{"id":257826250,"uuid":"871640503","full_name":"zx80/pg-schema-version","owner":"zx80","description":"Simple Postgres Schema Versioning","archived":false,"fork":false,"pushed_at":"2025-04-08T11:10:23.000Z","size":110,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-20T06:34:55.349Z","etag":null,"topics":["database","postgres","schema","sql","versioning"],"latest_commit_sha":null,"homepage":"https://zx80.github.io/pg-schema-version/","language":"Python","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/zx80.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-12T14:25:48.000Z","updated_at":"2025-04-08T11:10:26.000Z","dependencies_parsed_at":"2024-10-21T20:59:37.689Z","dependency_job_id":null,"html_url":"https://github.com/zx80/pg-schema-version","commit_stats":null,"previous_names":["zx80/pg-schema-version"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zx80%2Fpg-schema-version","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zx80%2Fpg-schema-version/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zx80%2Fpg-schema-version/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zx80%2Fpg-schema-version/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zx80","download_url":"https://codeload.github.com/zx80/pg-schema-version/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252989940,"owners_count":21836665,"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","postgres","schema","sql","versioning"],"created_at":"2024-11-09T11:24:21.176Z","updated_at":"2025-10-20T02:45:54.880Z","avatar_url":"https://github.com/zx80.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# _Simple_ Postgres Schema Versioning\n\nThere already exists _many_ tools to manage database schema versions, such as\n[sqitch](https://sqitch.org/), [alembic](https://alembic.sqlalchemy.org/)\nor [pgroll](https://github.com/xataio/pgroll).\nPlease consider them first to check whether they fit your needs before\nconsidering this one.\nIn contrast to these tools, `pg-schema-version` emphasizes a _simple_ approach\nbased on a single plain `psql` SQL scripts and no configuration, to provide\nlimited but useful features with safety in mind.\nThe application schema status is maintained in one table to detect reruns,\nincluding checking patch signatures.\nSeveral application can share the same setup.\n\n![Status](https://github.com/zx80/pg-schema-version/actions/workflows/test.yml/badge.svg?branch=main\u0026style=flat)\n![Tests](https://img.shields.io/badge/tests-11%20✓-success)\n![Coverage](https://img.shields.io/badge/coverage-100%25-success)\n![Python](https://img.shields.io/badge/python-3-informational)\n![Version](https://img.shields.io/pypi/v/pg-schema-version)\n![License](https://img.shields.io/pypi/l/pg-schema-version?style=flat)\n![Badges](https://img.shields.io/badge/badges-7-informational)\n\n## Example Usage\n\nHere is a typical use case for `pg-schema-version`:\n\n1. Install from PyPi, e.g. with `pip`:\n\n   ```shell\n   pip install pg-schema-version\n   ```\n\n2. Write a sequence of incremental postgres SQL data definition scripts.\n   The `-- psv:` comment header is mandatory to declare the application name,\n   version and optional description.\n\n   - initial schema creation `create_000.sql`\n\n     ```sql\n     -- psv: acme +1 Acme Schema v1.0\n     CREATE TABLE AcmeData(aid SERIAL PRIMARY KEY, data TEXT UNIQUE NOT NULL);\n     ```\n\n   - first schema upgrade `create_001.sql`\n\n     ```sql\n     -- psv: acme +2 Acme Schema v1.1\n     CREATE TABLE AcmeType(atid SERIAL PRIMARY KEY, atype TEXT UNIQUE NOT NULL);\n     INSERT INTO AcmeType(atype) VALUES ('great'), ('super');\n     ALTER TABLE AcmeData ADD COLUMN atid INT NOT NULL DEFAULT 1 REFERENCES AcmeType;\n     ```\n\n   - second schema upgrade `create_002.sql`\n\n     ```sql\n     -- psv: acme +3 Acme Schema v2.0\n     INSERT INTO AcmeType(atype) VALUES ('wow'), ('incredible');\n     ```\n\n3. Generate a `psql`-script from these for the target application:\n\n   ```shell\n   pg-schema-version create_*.sql \u003e acme.sql\n   ```\n\n4. Execute the script against a database to bring its schema up to date.\n   By default the script runs in _dry_ mode and reports the proposed changes to\n   be applied by setting it in _wet_ mode.\n\n   ```shell\n   # first time can use command create to init the setup and register the app.\n   psql -v psv=create acme \u003c acme.sql\n   # psv for application acme\n   # psv dry create for acme on acme, enable with -v psv=create:latest:wet\n   # psv will create infra, register acme and execute all steps\n\n   psql -v psv=create:wet acme \u003c acme.sql\n   # psv for application acme\n   # psv wet create for acme on acme\n   # psv creating infra\n   # psv registering acme\n   # psv considering applying steps\n   # psv acme version: 0\n   # psv applying acme 1\n   # psv applying acme 2\n   # psv applying acme 3\n   # psv acme version: 3\n   # psv wet create for acme done\n\n   # on rerun, do nothing\n   psql -v psv=wet acme \u003c acme.sql\n   # psv for application acme\n   # psv wet apply for acme on acme\n   # psv skipping acme registration\n   # psv considering applying steps\n   # psv acme version: 3\n   # psv skipping acme 1\n   # psv skipping acme 2\n   # psv skipping acme 3\n   # psv acme version: 3\n   # psv wet apply for acme done\n\n   # show current status\n   psql -v psv=status acme \u003c acme.sql\n   # …\n   ```\n\n   \u003e | app  | version | description      |\n   \u003e |---   |     ---:|---               |\n   \u003e | acme |       3 | Acme Schema v2.0 |\n   \u003e | psv  |       0 | •                |\n\n## Features\n\nSee `pg-schema-version --help` for a synopsis and explanations of all available\noptions.\n\nThe python command generates a reasonably safe re-entrant idempotent `psql`\nscript driven by variable `psv` with value _command_:_version_:_moist_\n\n- available commands are (default is `apply`):\n  - `init` just initialize an empty psv infrastructure.\n  - `register` add new application to psv versioning.\n  - `apply` execute required steps on an already registered application.\n  - `reverse` execute scripts to reverse steps.\n  - `create` do the 3 phases above: init, register and apply.\n  - `unregister` remove application from psv versioning.\n  - `remove` drop psv infrastructure.\n  - `help` show some help.\n  - `status` show version status of applications.\n  - `history` show history of application changes.\n  - `catchup` update application version status without actually executing steps\n    (imply init and register).\n- versions are integers designating the target step, default is `latest`.\n- available moistures are (default is `dry`):\n  - `dry` meaning that no changes are applied.\n  - `wet` to trigger actual changes.\n\nEach provided script **must** contain a special `-- psv: name +5432 description`\nheader with:\n\n- `name` the application name, which **must** be consistent accross all scripts.\n- `+5432` the version for apply (`+`) or reverse (`-`) a schema step, which\n  will be checked for inconsistencies such as repeated or missing versions.\n- `description` an optional description of the resulting application status,\n  eg the corresponding application version.\n\nBeware that reversing may help you lose precious data, and that it is your\nresponsability that the provided reverse scripts undo what was done by the\nforward scripts.\n\nOther options at the `psql` script level:\n\n- `-v psv_debug=1` to set debug mode.\n- `-v psv_app=foo` to change the application registration name.\n  Probably a bad idea.\n\n## Caveats\n\nAlways:\n\n- have a working (i.e. actually tested) backup of your data.\n- run _dry_  and read the output carefully before running _wet_.\n- test your scripts with care before applying it to production data.\n\nThere is no magic involved, you can still shot yourself in the foot, although\nwith an effort.\nFor safety, SQL schema creation scripts must **not**:\n\n- include backslash commands which may interfere with the script owns.\n- include SQL transaction commands.\n\nImperfect checks are performed to try to detect the above issues.\nThey can be circumvented with option `--trust-scripts` or `-T`.\n\n## Versions\n\n### TODO\n\n- default phase? status? run? help?\n- check? `foo =n …`? so what?\n- on partial, detect missing path before trying?\n  at least report of target is not reached!\n- add synopsis and document all options\n- write a tutorial\n- write recipes\n- test setting `psv_app`\n\n### 1.0 on 2025-04-08\n\n- split and count actual test scenarii\n- use SPDX licensing format\n- improve CI\n- switch to stable, as it is already used and working for an internal project\n\n### 0.6 on 2024-10-27\n\n- be stricter about backslash command detection\n- improve documentation\n\n### 0.5 on 2024-10-22\n\n- add `reverse` command to allow going backwards, and tests\n- add `history` command to show application history of changes\n- keep step execution history\n- differentiate exit status depending on the error\n- add `--version` option\n- check app and hash option values\n- keep executed commands and session users\n- add debug mode\n- fix `psv` command parsing\n- add reverse catchup tests\n\n### 0.4 on 2024-10-20\n\n- make psv comment header (`-- psv: foo +1 …`) mandatory,\n  including many sanity checks about names, versions…\n- rename `run` to `apply`\n- show status only when asked\n- add `--partial` option to allow partial scripts (i.e. missing versions)\n- use `--app` to check script consistency\n- check current status strictly before applying a step\n- improve documentation, esp. the example\n- improve tests about descriptions\n- refactor script sources\n\n### 0.3 on 2024-10-19\n\n- add unregister and catchup commands\n- add setting a version target for a run\n- add filename and description fields\n- add verbose option\n- show description on status\n- escape schema and table identifiers\n- refactor application registration\n- improve documentation\n\n### 0.2 on 2024-10-15\n\n- activate GitHub pages\n- working GitHub CI\n- add coverage check\n- add markdown check\n- use exit code 3 for output file\n\n### 0.1 on 2024-10-14\n\n- initial beta version for testing\n\n## License\n\nThis code is [Public Domain](https://creativecommons.org/publicdomain/zero/1.0/).\n\nSee [online documentation](https://zx80.github.io/pg-schema-version/).\nSources and issues are on [GitHub](https://github.com/zx80/pg-schema-version).\nPackages are distributed from [PyPi](https://pypi.org/project/pg-schema-version/).\n\nAll software has bug, this is software, hence…\nBeware that you may lose your hairs or your friends because of it.\nIf you like it, feel free to send a postcard to the author.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzx80%2Fpg-schema-version","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzx80%2Fpg-schema-version","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzx80%2Fpg-schema-version/lists"}