{"id":24793059,"url":"https://github.com/zhenglinlei/pgcloud","last_synced_at":"2026-05-08T18:33:09.190Z","repository":{"id":247209552,"uuid":"824762050","full_name":"ZhengLinLei/pgcloud","owner":"ZhengLinLei","description":"PostgreSQL 16 + Pgpool II + PgBouncer + Docker","archived":false,"fork":false,"pushed_at":"2025-02-28T21:30:36.000Z","size":2194,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T17:05:03.264Z","etag":null,"topics":["docker","pgbouncer","pgpool","postgresql"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZhengLinLei.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":"2024-07-05T22:12:39.000Z","updated_at":"2025-02-28T21:30:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"252a76af-a5e5-4ad8-9dc7-404c0a92cae1","html_url":"https://github.com/ZhengLinLei/pgcloud","commit_stats":null,"previous_names":["zhenglinlei/pgcloud"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ZhengLinLei/pgcloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZhengLinLei%2Fpgcloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZhengLinLei%2Fpgcloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZhengLinLei%2Fpgcloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZhengLinLei%2Fpgcloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZhengLinLei","download_url":"https://codeload.github.com/ZhengLinLei/pgcloud/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZhengLinLei%2Fpgcloud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32792136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["docker","pgbouncer","pgpool","postgresql"],"created_at":"2025-01-29T21:55:46.965Z","updated_at":"2026-05-08T18:33:09.159Z","avatar_url":"https://github.com/ZhengLinLei.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cbr\u003e\u003cbr\u003e\r\n\u003ch5 align=\"center\" style=\"font-family: monospace;\"\u003ePgCloud\u003c/h5\u003e\r\n\u003cbr\u003e\r\n\u003cp align=\"center\"\u003e\r\n    \u003cimg src=\"doc/img/pgcloud_small_logo_bgWhite_rounded.png\" width=\"80px\"\u003e\r\n\u003c/p\u003e\r\n\u003cbr\u003e\u003cbr\u003e\r\n\r\n\u003c!-- End Header --\u003e\r\n\r\n\u003cp align=\"center\"\u003e\r\n    \u003cq\u003e\u003cb\u003e\u003ci\u003e\u0026nbsp;Such as k8s but more beautiful.\u0026nbsp;\u003c/i\u003e\u003c/b\u003e\u003c/q\u003e\r\n\u003c/p\u003e\r\n\u003cbr\u003e\u003cbr\u003e\r\n\u003cp align=\"center\"\u003e\r\n    \u003ca href=\"./CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e\r\n    ·\r\n    \u003ca href=\"https://github.com/ZhengLinLei/pgcloud/issues\"\u003eIssues\u003c/a\u003e\r\n    ·\r\n    \u003ca href=\"https://github.com/ZhengLinLei/pgcloud/wiki\"\u003eWiki\u003c/a\u003e\r\n    ·\r\n    \u003ca href=\"./doc/wiki\"\u003eBook\u003c/a\u003e\r\n\u003c/p\u003e\r\n\u003cbr\u003e\r\n\u003cp align=\"center\"\u003e\r\n    \u003ca href=\"https://www.gnu.org/licenses/gpl-3.0.html\"\u003e\r\n        \u003cimg src=\"https://img.shields.io/badge/License-GPL%203.o-blue.svg\" alt=\"License\" /\u003e\r\n    \u003c/a\u003e\r\n    \u0026emsp;    \r\n    \u003ca\u003e\r\n        \u003cimg src=\"https://img.shields.io/badge/version-0.1.0-brightgreen\" alt=\"Version\" /\u003e\r\n    \u003c/a\u003e\r\n\u003c/p\u003e\r\n\u003cbr\u003e\r\n\u003chr\u003e\r\n\u003cbr\u003e\r\n\r\n## 🧐  What is PgCloud?\r\n\r\n\u003cp align=\"justify\" style=\"font-family: monospace;\"\u003e\r\n    PgCloud is an \u003ccode\u003eautomatic system\u003c/code\u003e for generating distributed nodes of PostgreSQL, PgPool and PgBouncer without the need to remain on a physical machine, since it uses docker technology. The system is capable of generating Postgres nodes with database replication on the same or different machines, load balancing with PgPool and connection caching with PgBouncer.\r\n\u003c/p\u003e \r\n\r\n\u003cbr\u003e\u003cbr\u003e\r\n## 📁  What does PgCloud have?\r\n\u003cp align=\"justify\" style=\"font-family: monospace;\"\u003e\r\n    There are several architectures offered by PgCloud tested perfectly by our team. There is even the possibility of customising the architecture with some extra configuration. The architecture is separated by layers, specifically three: \u003ccode\u003eReplication Layer\u003c/code\u003e, \u003ccode\u003eLoad Balancing Layer\u003c/code\u003e and \u003ccode\u003eConnection Pool Layer\u003c/code\u003e.\r\n\u003c/p\u003e\r\n\u003cbr\u003e\r\n\r\n### Three-tier architecture\r\n\u003cbr\u003e\r\n\u003cp align=\"justify\" style=\"font-family: monospace;\"\u003e\r\n    \u003cp align=\"center\"\u003e\r\n        \u003cimg align=\"center\" src=\"doc/readme/1_three_layer_diagram.png\" width=\"400px\"\u003e\r\n    \u003c/p\u003e\r\n    \u003cbr\u003e\u003cbr\u003e\r\n    \u003cp align=\"justify\"\u003e\r\n        The \u003ccode\u003ethree-tier architecture\u003c/code\u003e is the most used in environments where it requires much more data load and data consistency is prioritised, but its disadvantage is the time cost per request.\r\n        \u003cbr\u003e\r\n        \u003cblockquote\u003e\r\n            \u003cb\u003e\u003ci\u003eNOTE:\u003c/i\u003e\u003c/b\u003e Please note that there may be a bottleneck in PgBouncer if you do not place the nodes on machines with sufficient resources.\r\n        \u003c/blockquote\u003e\r\n    \u003c/p\u003e\r\n\u003c/p\u003e\r\n\u003cbr\u003e\r\n\r\n### Two-tier architecture\r\n\u003cbr\u003e\r\n\u003cp align=\"justify\" style=\"font-family: monospace;\"\u003e\r\n    \u003cp align=\"center\"\u003e\r\n        \u003cimg align=\"center\" src=\"doc/readme/2_two_layer_diagram.png\" width=\"400px\"\u003e\r\n    \u003c/p\u003e\r\n    \u003cbr\u003e\u003cbr\u003e\r\n    \u003cp align=\"justify\"\u003e\r\n        The other \u003ccode\u003etwo-tier architecture\u003c/code\u003e is preferred for systems where time is prioritised, but the amount of load is low. It is also the fastest in preparing the cluster in case of a node failover. Since there is less communication and it is easier to reach a node agreement.\r\n    \u003c/p\u003e\r\n\u003c/p\u003e\r\n\r\n\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\r\nBy default the system is enabled to launch this architecture.\r\n\r\n\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\r\n## 🔌  Diagram\r\n\r\n\u003cp align=\"justify\"\u003e\r\n    Each layer architecture has different conditions of nodes to occupy, below is an example of a complete architecture with connections. Each figure represents a node and not a physical machine, the decision of putting one or two different nodes in the same machine depends on the load and stability that is desired to give to the system.\r\n\u003c/p\u003e\r\n\u003cbr\u003e\r\n\r\n### Two-tier diagram\r\n\u003cbr\u003e\r\n\u003cp align=\"center\"\u003e\r\n    \u003cimg src=\"doc/readme/3_three_layer_diagram.png\" width=\"45%\"\u003e\r\n    \u003cimg src=\"doc/readme/4_three_layer_diagram.png\" width=\"45%\"\u003e\r\n\u003c/p\u003e\r\n\u003cp align=\"justify\"\u003e\r\n    \u003cul\u003e\r\n        \u003cli\u003e\r\n            This is the most basic configuration that we can configure to offer load balancing. Its weakness is that it does not have a PgPool backup when a node goes down, the entire system stops receiving requests. Although it is undoubtedly the least expensive, optimal and simple for simple systems where it does not require much availability and load.\r\n        \u003c/li\u003e\r\n        \u003cbr\u003e\r\n        \u003cli\u003e\r\n            Creating a PgPool cluster alongside the PostgreSQL cluster helps to solve both the failover of a postgres node and a PgPool node. Throughout this documentation we will use primary and replica to map the postgres and master and slave roles for the PgPool cluster.\r\n        \u003c/li\u003e\r\n    \u003c/ul\u003e\r\n\u003c/p\u003e\r\n\u003cbr\u003e\r\n\r\n### Three-tier diagram\r\n\u003cbr\u003e\r\n\u003cp align=\"center\"\u003e\r\n    \u003cimg src=\"doc/readme/5_two_layer_diagram.png\" width=\"500px\"\u003e\r\n\u003c/p\u003e\r\n\u003cp align=\"justify\"\u003e\r\n    With a three-tier architecture we have better consistency between nodes, this way if PgBouncer were to fail we could replace it with a PgPool gate, losing the capacity offered by PgBouncer but obtaining more availability. With this we are able to create a distributed system that offers load balancing and connection caching for fast management.\r\n\u003c/p\u003e\r\n\u003cbr\u003e\r\n\r\n### Other architectures\r\n\u003cbr\u003e\r\n\u003cp align=\"justify\"\u003e\r\n    You can also use the system where you omit the load balancing layer, that is, use PgBouncer with Postgres. This architecture is not the most common but it does offer quite a few advantages if you only require these two modules.\r\n\u003c/p\u003e\r\n\u003cp align=\"center\"\u003e\r\n    \u003cimg src=\"doc/readme/6_two_layer_diagram_other.png\" width=\"400px\"\u003e\r\n\u003c/p\u003e\r\n\u003cp align=\"justify\"\u003e\r\n    PgBouncer is an optimal choice for efficiently pooling database connections, especially when your system needs connection caching rather than load balancing. Unlike PgPool, which offers additional features like load balancing, PgBouncer focuses solely on connection pooling. This makes it lightweight, with lower memory consumption and minimal configuration, ideal for handling high connection rates while maintaining a stable database environment.\r\n    \u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\r\n    An example using this layer is:\r\n\u003c/p\u003e\r\n\u003cp align=\"center\"\u003e\r\n    \u003cimg src=\"doc/readme/7_two_layer_diagram_other.png\" width=\"400px\"\u003e\r\n\u003c/p\u003e\r\n\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\r\n\u003cp align=\"center\" style=\"font-family: monospace;\"\u003e...\u003c/p\u003e\r\n\u003cbr\u003e\u003cbr\u003e\r\n\u003ch5 align=\"center\" style=\"font-family: monospace;\"\u003eRead more in our official Wiki or Book\u003c/h5\u003e\r\n\u003cbr\u003e\r\n\u003cp align=\"center\"\u003e\r\n    \u003ca href=\"https://github.com/ZhengLinLei/pgcloud/wiki\"\u003eWiki\u003c/a\u003e\r\n    ·\r\n    \u003ca href=\"./doc/wiki\"\u003eBook\u003c/a\u003e\r\n\u003c/p\u003e\r\n\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\u003cbr\u003e\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhenglinlei%2Fpgcloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhenglinlei%2Fpgcloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhenglinlei%2Fpgcloud/lists"}