{"id":19774534,"url":"https://github.com/sadeghhayeri/pgkit","last_synced_at":"2025-10-19T06:17:46.226Z","repository":{"id":39918018,"uuid":"325784165","full_name":"SadeghHayeri/pgkit","owner":"SadeghHayeri","description":"Pgkit - Backup, PITR and recovery management made easy","archived":false,"fork":false,"pushed_at":"2023-10-11T13:14:53.000Z","size":961,"stargazers_count":25,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2023-10-11T20:07:12.136Z","etag":null,"topics":["backup","backup-utility","pitr","postgres","postgresql","postgresql-backup"],"latest_commit_sha":null,"homepage":"","language":"Python","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/SadeghHayeri.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}},"created_at":"2020-12-31T11:18:34.000Z","updated_at":"2023-10-01T10:35:32.000Z","dependencies_parsed_at":"2023-02-01T09:17:06.734Z","dependency_job_id":"df45d771-7f27-4df8-8d2c-5a76d75b3679","html_url":"https://github.com/SadeghHayeri/pgkit","commit_stats":null,"previous_names":[],"tags_count":23,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SadeghHayeri%2Fpgkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SadeghHayeri%2Fpgkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SadeghHayeri%2Fpgkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SadeghHayeri%2Fpgkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SadeghHayeri","download_url":"https://codeload.github.com/SadeghHayeri/pgkit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224219442,"owners_count":17275477,"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":["backup","backup-utility","pitr","postgres","postgresql","postgresql-backup"],"created_at":"2024-11-12T05:13:14.206Z","updated_at":"2025-10-19T06:17:41.209Z","avatar_url":"https://github.com/SadeghHayeri.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PgKit\nPostgresql KIT - Backup, PITR and recovery management made easy\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/header-blue.png\" alt=\"pgkit logo\" width=\"100%\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/SadeghHayeri/pgkit.svg?color=green\u0026style=for-the-badge\"\u003e \u003cimg src=\"https://img.shields.io/github/repo-size/SadeghHayeri/pgkit.svg?color=green\u0026style=for-the-badge\"\u003e\n\u003c/p\u003e\n\nPgKit is an open-source administration tool for disaster recovery of PostgreSQL servers, It allows your organization to perform remote backups of multiple servers in business-critical environments to reduce risk and help DBAs during the recovery phase.\n\n### demo\n\u003ca href=\"https://asciinema.org/a/496249?speed=3\u0026theme=tango\u0026autoplay=1\" target=\"_blank\"\u003e\u003cimg src=\"https://asciinema.org/a/496249.svg\" /\u003e\u003c/a\u003e\n\n---\n## Installation\n[pgkit](https://pypi.org/project/pgkit/) can be installed through pip.\n\nAs the package works with postgresql, it should be installed as root to have enough privileges.\n```shell\n$ sudo pip3 install pgkit\n```\n\n---\n## Usage\n\npgkit provides a cli with these commands available:\n- config\n- list\n- pitr\n- dump\n- dumpall\n- shell\n- start\n- stop\n- restart\n\n### Config\nThe `config` command is used to add, get or remove database configs to the kit.\u003cbr\u003e\nThe following sub-commands are available:\n- add\n- get\n- remove\n\nNew database configs can be added both using flags or an interactive command prompt.\n\n#### Adding a database config using the flags:\n```shell\n$ sudo pgkit config add \\\n  --name \u003cname\u003e \\\n  --version \u003cversion\u003e \\\n  --host \u003chost-address\u003e \\\n  --port \u003chost-port\u003e \\\n  --dbname postgres \\\n  --slot \u003cslot-name\u003e \\\n  --username \u003chost-username\u003e \\\n  --password \u003chost-password\u003e \\\n  --replica-port \u003creplica-port\u003e \\\n  --use-separate-receivewal-service\n```\n\nThe `replica-port` and `use-separate-receivewal-service` flags are optional.\u003cbr\u003e\nThe `replica-port` specifies the port on which the replica listens.\u003cbr\u003e\nThe `use-separate-receivewal-service` flag specifies if pgkit should use a separate service to receive the WAL files\nfrom the host or to let the postgres cluster handle receiving the WAL files itself.\n\n\u003e **Important:** It's best to use a separate receivewal service (set the flag) if setting up a delayed replica (PITR). If setting\n\u003e up a real-time replica (zero delays) it is better to let PostgreSQL receive the WAL files itself.\n\n#### Adding a database config using the interactive prompt:\n```shell\n$ sudo pgkit config add\n\nName: main\nVersion (9.5, 10, 11, 12, 13): 12\nHost: master\nPort: 5432\nDbname: test\nSlot: test\nUsername: test\nPassword: test\n```\n\n#### Getting a config\nThe `get` command displays an existing config:\n```shell\n$ sudo pgkit config get \u003cname\u003e\n\ndbname: postgres\nhost: \u003chost\u003e\nmax_connections: 100\nmax_worker_processes: 8\nname: \u003cname\u003e\npassword: \u003cpassword\u003e\nport: \u003chost-port\u003e\nreplica_port: \u003creplica-port\u003e\nslot: \u003cslot\u003e\nuse_separate_receivewal_service: true|false\nusername: \u003chost-username\u003e\nversion: \u003chost-version\u003e\n\n```\n\n#### Removing a config\nThe `remove` command removes an existing config entry. Using this command requires providing the `--dangerous` flag.\n```shell\n$ sudo pgkit config remove \u003cname\u003e\n```\n\n### List\nThe list command lists all existing database config entries.\n```shell\n$ sudo pgkit list\n\n- sample\n- testdb\n- test2\n```\n\n### PITR\nThe `pitr` command is used to set up backup replicas and recover them.\u003cbr\u003e\nThe following subcommands are available:\n- backup\n- recover\n- promote\n\n#### Backup\nThis command is used to set up a replica with the desired amount of delay. The delay is in minutes.\n```shell\n$ sudo pgkit pitr backup \u003cname\u003e \u003cdelay\u003e\n```\n\n\u003e **Important:** This command may take a while to finish as it starts a base backup which copies the whole data directory\n\u003e of the host database. It is best to execute this command in a detachable environment such as `screen` or `tmux`.\n\n#### Recover\nThis command is used to recover a delayed replica to a specified point in time between now and the database's delay\namount. The time can be given in the `YYYY-mm-ddTHH:MM` format. The `latest` keyword can also be used to recover the\ndatabase up to the latest transaction available.\n```shell \n$ sudo pgkit pitr recover \u003cname\u003e \u003ctime\u003e\n$ sudo pgkit pitr recover \u003cname\u003e latest\n```\n\nThe database will then start replaying the WAL files. It's progress can be tracked through the log files at \n`/var/log/postgresql/`.\n\n#### Promote\nThis command promotes the replica, separating it from the master database and making it a master.\n```shell\n$ sudo pgkit pitr promote \u003cname\u003e\n```\n\n### Dump\nThis command is used to create a dump from a single database in a cluster.\n```shell\n$ sudo pgkit dump \u003ccluster-name\u003e \u003cdatabase-name\u003e \u003coutput-path\u003e\n```\nThe command does not compress the dump by default. If the `--compress` flag is given,\nthen the dump will be compressed. The `--compression-level` flag can also be given along with an argument that\nspecifies the compression level (1-9). If the compress flag is given without specifying the compression level, \nthe default gzip compression level (6) is used.\n```shell\n$ sudo pgkit dump \u003ccluster-name\u003e \u003cdatabase-name\u003e \u003coutput-path\u003e --compress --compression-level 9\n```\n\u003e The `\u003ccluster-name\u003e` specified in the command above is the name given when adding the database config.\n\n### Dumpall\nThis command is used to dump the whole cluster into an sql file.\n```shell\n$ sudo pgkit dumpall \u003ccluster-name\u003e \u003coutput-path\u003e\n```\nThe `--compress` and `--compression-level` flags are also available and work as explained above.\n\n### Shell\nThis command is used to enter the postgresql shell (psql).\n```shell\n$ sudo pgkit shell \u003cname\u003e\n```\nIf no flags are given, the shell will be connected to the source database. If a shell from the replica database is \nneeded, the `--replica` flag must be given.\n```shell\n$ sudo pgkit shell \u003cname\u003e --replica\n```\n\n### Start\nThis command starts the replica PostgreSQL cluster.\n```shell\n$ sudo pgkit start \u003cname\u003e\n```\n\n### Stop\nThis command stops the replica PostgreSQL cluster.\n```shell\n$ sudo pgkit stop \u003cname\u003e\n```\n\n### Restart\nThis command restarts the replica PostgreSQL cluster.\n```shell\n$ sudo pgkit restarts \u003cname\u003e\n```\n---\n## To-Do\n- [ ] Add `replica-port` and `use-separate-wal-receive-service` options to the interactive prompt.\n- [ ] Fix the tests.\n- [x] Add `edit` command to the `config` part.\n- [ ] Add `status` command to pgkit to show stats about the databases.\n\n## Test Environment\nWe have created a test environment using docker-compose consisting of one `master` and one `replica` postgresql servers.\nTo use this environment run:\n\n```bash\ncd deployment \u0026\u0026 sudo docker-compose build \u0026\u0026 sudo docker-compose up -d\n```\n\nNow exec into replica and run:\n\n```bash\npgkit --help\n```\n\n### Standby Replication\n\n#### Replication Setup\n\n* Add pgkit config:\n\n```bash\npgkit config add\n```\n\nIn the `Host` field enter `master`. A tested sample config is given below:\n\n```\nName: main\nVersion (9.5, 10, 11, 12, 13): 12\nHost: master\nPort: 5432\nDbname: test\nSlot: test\nUsername: test\nPassword: test\n```\n\n* Start replication process:\n\n```bash\npgkit pitr backup \u003cname\u003e 0\n```\n\n#### Restoration Process\n\n* Stop master:\n\n```bash\nsudo docker stop master\n```\n\n* Exec into replica and recover to latest:\n\n```bash\nsudo docker-compose exec replica bash\npgkit pitr recover \u003cname\u003e latest\n```\n\n* Promote the replica:\n\n```bash\npgkit pitr promote \u003cname\u003e\n```\n\nNow you can test the replica:\n* Connect to database `test` and select data:\n\n```bash\nsu postgres\npsql -d test -c \"select * from persons\"\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsadeghhayeri%2Fpgkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsadeghhayeri%2Fpgkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsadeghhayeri%2Fpgkit/lists"}