{"id":20441484,"url":"https://github.com/moritetu/pgenv2","last_synced_at":"2026-04-19T10:32:09.639Z","repository":{"id":85122539,"uuid":"138166814","full_name":"moritetu/pgenv2","owner":"moritetu","description":"pgenv2 is a tool to help you to manage multiple PostgreSQL versions.","archived":false,"fork":false,"pushed_at":"2020-12-16T13:55:56.000Z","size":103,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-02T08:43:57.702Z","etag":null,"topics":["pgenv","postgresql"],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/moritetu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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-06-21T12:23:12.000Z","updated_at":"2021-04-08T05:01:51.000Z","dependencies_parsed_at":"2023-07-21T19:51:29.766Z","dependency_job_id":null,"html_url":"https://github.com/moritetu/pgenv2","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/moritetu/pgenv2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritetu%2Fpgenv2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritetu%2Fpgenv2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritetu%2Fpgenv2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritetu%2Fpgenv2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moritetu","download_url":"https://codeload.github.com/moritetu/pgenv2/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritetu%2Fpgenv2/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267370650,"owners_count":24076462,"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","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["pgenv","postgresql"],"created_at":"2024-11-15T09:33:09.092Z","updated_at":"2026-04-19T10:32:04.589Z","avatar_url":"https://github.com/moritetu.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"pgenv2\n======\n\npgenv2 is a tool to help you to manage multiple PostgreSQL versions. This is useful for **testing** or **developing**\non your local machine. You can pick a PostgreSQL version and run it. And also pgenv2 helps you to setup your\ntesting replication cluster.\n\nSynopsis\n--------\n\n```bash\n# Install PostgreSQL\npgenv install 10.4\n\n# Install PostgreSQL with '--enable-debug' option.\npgenv install -d 10.4\n\n# Set current version\npgenv global 10.4\n\n# Show current version\npgenv current\n\n# Create a link to the the specified path where you installed postgresql\npgenv link /my/postgres my_postgres\n\n# Show the installed path.\npgenv prefix\n\n# Change current working directory and execute any commands\npgenv prefix --source \"cd contrib/auto_explain \u0026\u0026 make install\"\n\n# Show installed versions\npgenv list\n\n# Remove the installed version\npgenv remove 10.4\n\n# Show available versions\npgenv versions\npgenv versions -p  # pretty print\npgenv versions 9.6 # print only specified versions\n\n# Export PostgreSQL with tarball archive\npgenv export\n\n# Edit configure options\npgenv configure -e --default\n\n# Excecute any commands\npgenv exec initdb pgdata\npgenv exec -v 9.6 initdb pgdata96\n\n# Setup cluster\npgenv cluster -D clusterdir setup -s sync_standby -a async_standby primary\n\n# Usage\npgenv --help\npgenv cluster setup --help\n```\n\n\nGetting Started\n---------------\n\n### Required\n\nBash 4.2 or later ( But recommend Bash 4.4 or later )\n\n### Installing pgenv2\n\n**Clone the Github project:**\n\n```bash\n$ git clone https://github.com/moritetu/pgenv2\n$ cd pgenv2\n$ source install.sh\n```\n\n**Use source archive:**\n\n```bash\n$ unzip pgenv2-master.zip\n$ cd pgenv2\n$ source install.sh\n```\n\n### Installing PostgreSQL\n\nBefore installing a PostgreSQL, you should check available PostgreSQL versions.\nTo do it, you can use `versions` command.\n\n```bash\n$ pgenv versions\n```\n\npgenv2 gets available versions from the public PostgreSQL website, so please confirm whether the version you are going to install exists in the list.\n\nAnd also, you can print only specified versions with the pretty format.\n\n```bash\n$ pgenv versions -p 10\nPostgreSQL Available Versions 10\n=======================================================================\n10.0         10.1         10.2         10.3         10.4         10.5\n10.6         10.7         10.8         10.9         10.10\n```\n\nNext, you can build a PostgreSQL with `install` command.\n\n```bash\n$ pgenv install 10.4\n```\n\npgenv2 gets source archive from the public PostgreSQL repository, expands it and builds. If all is well, you will see the installed version with `list` command.\n\n```bash\n$ pgenv list\n  10.4\n```\n\n### Customizing configure options\n\nYou can customize configure options with `configure` command.\n\n```bash\n# With EDITOR\n$ pgenv configure -e\n# From STDIN\n$ pgenv configure -e \u003c\u003cEOF\n--with-libxml\nEOF\n```\n\nConfigure options file is read with the following priority:\n\n1.`$PGENV_ROOT/configure_options-\u003cversion\u003e`\n\n```\npgenv configure -e [--global]\n```\n\n2.`$PGENV_ROOT/configure_options`\n\n```\npgenv configure -e --default\n```\n\n3.`$PWD/pgenv_configure_opts`\n\n```\npgenv configure -e --local\n```\n\n### Setting default PostgreSQL\n\nYou can set the version to be used by default with `global` command.\n\n```bash\n$ pgenv global 10.4\nCurrent version -\u003e versions/10.4\n\n[Next step]\n\n  Create an instance and start postmaster:\n    $ initdb pgdata\n    $ pg_ctl -D pgdata -l postgresql.log start\n\n  Connect to the postgres database:\n    $ psql postgres\n```\n\nRun `list` command again. `*` mark means that current active version is 10.4.\n\n```bash\n$ pgenv list\n* 10.4\n```\n\nOr you can do it with `current` command.\n\n```bash\n$ pgenv current\n10.4\n```\n\nExecute the `psql` command and confirm current active version in the same way.\n\n```bash\n$ psql -V\npsql (PostgreSQL) 10.4\n```\n\nOK, `psql` says current active version is 10.4.\n\n### Showing path\n\nWhen you need to know where resources of the version that you installed are stored, you can use `prefix` command.\n\n```bash\n$ pgenv prefix\n/Users/guest/pgenv2/versions/10.4\n```\n\nIf with `--bin`, `--share`, `--lib` or `--source` option, path will be shown more deeply.\n\n```bash\n$ pgenv prefix --bin\n/Users/guest/pgenv2/versions/10.4/bin\n$ pgenv prefix --share\n/Users/guest/pgenv2/versions/10.4/share\n$ pgenv prefix --lib\n/Users/guest/pgenv2/versions/10.4/lib\n$ pgenv prefix --source\n/Users/guest/pgenv2/sources/10.4\n```\n\nIn addition to it, you can pass arbitrary commands as arguments.\n\n```bash\n$ pgenv prefix --bin \u003c\u003cCOM\ninitdb pgdata\nCOM\n$ pgenv prefix --source 'find src/backend -type f -name \"*.c\" | xargs grep \"too many clients\"'\nsrc/backend/postmaster/postmaster.c:\t\t\t\t\t errmsg(\"sorry, too many clients already\")));\nsrc/backend/storage/ipc/procarray.c:\t\t\t\t errmsg(\"sorry, too many clients already\")));\nsrc/backend/storage/ipc/sinvaladt.c:\t\t\t\t\t errmsg(\"sorry, too many clients already\")));\nsrc/backend/storage/lmgr/proc.c:\t\t\t\t errmsg(\"sorry, too many clients already\")));\n```\n\n### Link to the existed one\n\nIf built version already exists, you can make a link to it with arbitrary name.\n\n```bash\n$ pgenv link /path/to/existed/postgresql mypg\n$ pgenv list\n* 10.4\n  mypg\n```\n\n### Executing command\n\nYou can execute commands with any version you specify.\n\n```bash\n$ pgenv exec -v 9.6.9 \u003c\u003cEOF\ninitdb pgdata\npg_ctl -D pgdata -l postgresql.log start\nEOF\n```\n\n`pgenv exec` command tries to read environment variables from `pgenv_myenv` file in the current directory. You can create its file with `pgenv env` command.\n\n```bash\n$ pgenv env -w -v 9.6.9\nfile created: /Users/guests/pgenv_myenv-9.6.9\n$ pgenv exec -v 9.6.9 \u003c\u003c'EOF'\necho \\$PGHOST\nEOF\nlocalhost\n```\n\nConstructing Replication\n------------------------\n\npgenv2 helps you to construct replication environment for testing or development and so on.\n\n### Setting up a cluster\n\nFor setting up your cluster, you can use `cluster setup` command. In the following example, a set of a primary server and a synchronous standby server is created.\n\n```bash\npgenv cluster -D mycluster setup --sync-standby standby primary\n```\n\nIf setting up has done successfully, you will be able to see the following cluster status with `cluster status` command.\n\n```bash\n$ pgenv cluster -D mycluster status\n[Cluster Servers]\n# Primary server\nprimary:24312       pg_ctl: server is running (PID: 1118)\n\n# Synchronous standby servers\nstandby:24313       pg_ctl: server is running (PID: 1217)\n\n# Asynchronous standby servers\n\n[Replication Graph]\nprimary -\u003e standby\n  standby -\u003e\n```\n\n### Starting/Stopping cluster\n\nYou can start your cluster with `cluster start` command. `start` command with `-a` option starts all instances in your cluster.\n\n```bash\n$ pgenv cluster -D mycluster start -a\n```\n\nAnd also stop it with `cluster stop` command. `stop` command with `-a` option stops all instances in your cluster.\n\n```bash\n$ pgenv cluster -D mycluster stop -a\n```\n\n### Attaching/Detaching nodes\n\nAfter setting up your cluster, you can attach nodes to your cluster or detach nodes from it.\n\n**Attaching nodes:**\n\n```bash\n$ pgenv cluster -D mycluster ctrl --attach --fork-off primary standby2\n```\n\nYou can create a new standby node with `pg_basebackup` command , and start it.\n\n```bash\n$ pgenv cluster -D mycluster start standby2\n```\n\nThen check your cluster status.\n\n```bash\npgenv cluster -D mycluster status\n[Cluster Servers]\n# Primary server\nprimary:24312       pg_ctl: server is running (PID: 1517)\n\n# Synchronous standby servers\nstandby:24313       pg_ctl: server is running (PID: 1537)\n\n# Asynchronous standby servers\nstandby2:24314      pg_ctl: server is running (PID: 1713)\n\n[Replication Graph]\nstandby2 -\u003e\nprimary -\u003e standby standby2\n  standby -\u003e\n```\n\n**Detaching nodes:**\n\nHere is a example to detach standby2 node.\n\n```bash\n$ pgenv cluster -D mycluster ctrl --detach standby2\n```\n\nThen check your cluster status.\n\n```bash\n$ pgenv cluster -D mycluster status\n[Cluster Servers]\n# Primary server\nprimary:24312       pg_ctl: server is running (PID: 1517)\n\n# Synchronous standby servers\nstandby:24313       pg_ctl: server is running (PID: 1537)\n\n# Asynchronous standby servers\nstandby2:24314      pg_ctl: no server running\n\n[Replication Graph]\nstandby2 -\u003e\nprimary -\u003e standby\n  standby -\u003e\n```\n\n### Tailing logs\n\nYou can watch logs of all instances with `tail` command. This is useful for watching state of instances in your cluster.\n\n```bash\n$ pgenv cluster -D mycluster tail -f -a\n```\n\n### Cluster information\n\nThe setting about your cluster is saved under the cluster directory you specified with `-D` option.\n\n```\n# Cluster settings\nexport PGENV_CLUSTER_ROOT=\"/Users/guest/mycluster\"\n\n# Primary server\nprimary_server=\"primary\"\nprimary_port=\"24312\"\n\n# Synchronous standby servers\nsynchronous_standby_servers=(standby)\nsynchronous_standby_ports=(24313)\n\n# Asynchronous standby servers\nasynchronous_standby_servers=(standby2)\nasynchronous_standby_ports=(24314)\n\n# Sync + Async standby servers\nall_standby_servers=(standby standby2)\nall_standby_ports=(24313 24314)\n\n# Context when setup cluster\npg_setup_version=\"10.4\"\n\n# Version of pgenv\npgenv_version=\"pgenv2 0.1.2-beta\"\n\n# Other information\npg_start_port=24315   # Starting port number used when port number was not passed.\nworking_directory=\"/Users/guest/mycluster\"    # This is the directory where you were when creating a cluster.\n\n# Replication graph\n# This information is extracted from pg_stat_replication view.\n# So to analyze current exact replication state, all instances need to be started.\nreplication_tree[\"primary\"]=\"standby\"\nreplication_tree[\"standby\"]=\"\"\nreplication_tree[\"standby2\"]=\"\"\n```\n\nThese settings are normally updated and stored into `cluster_config.sh` file by pgenv, so you do not need to edit them directly.\n\n### Using hook at cluster setup\n\nYou can customize database configuration at cluster setup. By default, pgenv reads `libexec/pgenv--cluster-callback`, but you can overwrite by loading the your script which defines behaviors.\n\nIf `pgenv-cluster-callback.sh` exists on `PGENV_LOAD_PATH`, pgenv will load it after default script loaded at cluster setup.\n\n```bash\non_primary_setup() {\n  log_trace \"on_primary_setup\"\n  cat \u003c\u003cEOF \u003e \"$include_file\"\nport = $port\nEOF\n}\n\non_primary_started() {\n  log_trace \"on_primary_started\"\n  : Do something\n}\n\non_standby_setup() {\n  log_trace \"on_standby_setup\"\n  cat \u003c\u003cEOF \u003e \"$include_file\"\nport = $port\nEOF\n}\n\non_standby_recovery_setup() {\n  log_trace \"on_standby_recovery_setup\"\n  cat \u003c\u003cEOF \u003e\u003e \"$recovery_conf\"\nrecovery_target_timeline = 'latest'\nEOF\n}\n\non_standby_started() {\n  log_trace \"on_standby_started\"\n  : Do something\n}\n```\n\nDeveloping PostgreSQL Extension\n-------------------------------\n\npgenv will just help you to develop your extension.\n\n### Setting up a extension project\n\n```bash\n$ pgenv extension init myext\n```\n\nYou can choice another templates.\n\n```bash\n$ pgenv extension init -t command -Dextname=myext myext\n```\n\n\n### Building your extension\n\nYou can build your extension for all installed version.\n\n```bash\n$ cd myext\n$ pgenv extension install -v @all\n```\n\n### Testing your extension\n\n```bash\n$ pgenv extension run -v @all 'initdb  ${ver}data'\n$ pgenv extension run -v @all 'pg_ctl start -l $ver.log -D ${ver}data -o \"-p $((9000+i))\"'\n$ pgenv extension run -v @all 'psql -p $((9000+i)) postgres -c \"create extension myext\"'\n$ pgenv extension run -v @all 'psql -p $((9000+i)) postgres -c \"select myext()\"'\n$ pgenv extension run -v @all 'pg_ctl stop -D ${ver}data'\n$ pgenv extension run -v @all 'rm -rf ${ver}data $ver.log'\n```\n\nPlugin\n------\n\nYou can add your own features into pgenv2. A plugin can be installed under `$PGENV_ROOT/plugins`.\n\n```\n$PGENV_ROOT/plugins/my-plugin\n  |- bin\n    |- pgenv-exec-\u003ccommand name\u003e\n```\n\nThe description of your plugin can be shown with `pgenv help` command by writing `COMMAND` and `HELP` comment block into executable scripts.\n\n```\n#!/usr/bin/env bash\n\necho \"Hello my plugin\"\n\n#=begin COMMAND\n#\n# my          This is my plugin.\n#\n#=end COMMAND\n\n#=begin HELP\n#\n# Usage: pgenv my [-v|--version]\n#\n# OPTIONS\n#   -v, --version\n#     Show version.\n#\n#\n#=end HELP\n```\n\nYou will see the usage of the plugin with the following:\n\n```\n$ pgenv my -h\nUsage: pgenv my [-v]\n\nOPTIONS\n  -v, --version\n    Show version.\n\n```\n\nHooks\n-----\npgenv2 invokes hook scripts in running command optionally. The hook scripts can be installed into the followings.\n\n```\n$PGENV_ROOT/hooks/\u003chook_name\u003e/yourhook.bash\n$PGENV_ROOT/plugins/\u003cplugin_name\u003e/hooks/\u003chook_name\u003e/yourhook.bash\n~/.pgenv/hooks/\u003chook_name\u003e/yourhook.bash\n```\n\nThe name of hook sciprt file must end with `.bash`.\n\nSee more detail: [pgenv2 plugin sample]\n\nFAQ\n----\n\n\n**Q. Failed to `install` or `versions` command with reason for 'curl: (35) Peer reports incompatible or unsupported protocol version.'**\n\nTry to change `PGENV_CURL` environment variable.\n```bash\n$ PGENV_CURL=\"curl --tlsv1.2\" pgenv ...\n```\n\nBug Reporting\n-------------\n\nPlease use [GitHub issues].\n\n\nLicense\n-------\n\nDistributed under [The MIT License]; see [`LICENSE.md`] for terms.\n\n[pgenv2 plugin sample]: https://github.com/moritetu/pgenv-plugin-sample\n[GitHub issues]: https://github.com/moritetu/pgenv2/issues\n[The MIT License]: https://opensource.org/licenses/MIT\n[`LICENSE.md`]: https://github.com/moritetu/pgenv2/blob/master/LICENSE.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoritetu%2Fpgenv2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoritetu%2Fpgenv2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoritetu%2Fpgenv2/lists"}