{"id":35278162,"url":"https://github.com/krylosov-aa/pg-status","last_synced_at":"2026-01-19T13:00:37.560Z","repository":{"id":325845322,"uuid":"1102562115","full_name":"krylosov-aa/pg-status","owner":"krylosov-aa","description":"A microservice (sidecar) that helps instantly determine the status of your PostgreSQL hosts including whether they are alive, which one is the master, which ones are replicas, and how far each replica is lagging behind the master.","archived":false,"fork":false,"pushed_at":"2026-01-14T22:09:56.000Z","size":199,"stargazers_count":39,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-15T04:39:16.551Z","etag":null,"topics":["c","docker","high-availability","high-load","http-api","lightweight","master-replica","microservice","monitoring","observability","performance","pg","postgresql","replication","service-discovery","sidecar","sql"],"latest_commit_sha":null,"homepage":"","language":"C","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/krylosov-aa.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-23T17:22:40.000Z","updated_at":"2026-01-14T22:09:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/krylosov-aa/pg-status","commit_stats":null,"previous_names":["krylosov-aa/pg-status"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/krylosov-aa/pg-status","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krylosov-aa%2Fpg-status","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krylosov-aa%2Fpg-status/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krylosov-aa%2Fpg-status/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krylosov-aa%2Fpg-status/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krylosov-aa","download_url":"https://codeload.github.com/krylosov-aa/pg-status/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krylosov-aa%2Fpg-status/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28568833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T12:50:50.164Z","status":"ssl_error","status_checked_at":"2026-01-19T12:50:42.704Z","response_time":67,"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":["c","docker","high-availability","high-load","http-api","lightweight","master-replica","microservice","monitoring","observability","performance","pg","postgresql","replication","service-discovery","sidecar","sql"],"created_at":"2025-12-30T14:06:22.146Z","updated_at":"2026-01-19T13:00:37.551Z","avatar_url":"https://github.com/krylosov-aa.png","language":"C","funding_links":[],"categories":["High-Availability"],"sub_categories":[],"readme":"# pg-status\n\nA microservice (sidecar) that helps instantly determine the status of your PostgreSQL hosts including whether they are alive,\nwhich one is the master, which ones are replicas, and how far each replica is lagging behind the master.\n\nIt’s designed as a sidecar that runs alongside your main application. It’s\nlightweight, resource-efficient, and delivers high performance.\nYou can access it on every request without noticeable overhead.\n\npg-status polls database hosts in the background at a specified interval and exposes an HTTP\ninterface that can be used to retrieve a list of hosts meeting given conditions.\n\nIt always serves data directly from memory and responds extremely quickly, so it can be safely used on every request.\n\nTo learn more about why this project exists and\nwhat problem it solves, you can read the article on one of the\nplatforms that are convenient for you:\n\n- [dev.to](https://dev.to/krylosov-aa/pg-status-a-lightweight-microservice-for-checking-postgresql-host-status-32jd)\n- [medium](https://medium.com/@krylosov.andrew/pg-status-a-lightweight-microservice-for-checking-postgresql-host-status-a70f8944302a)\n\n\n# Usage\n\nRun the application on the same host next to the main service or actually anywhere you want.\nAfter it starts, the HTTP API will be available.\n\n## API\n\nThe service provides several HTTP endpoints for retrieving host information.\n\nAll APIs support two response formats: plain text and JSON.\n\nIf you include the header `Accept: application/json`, the response will be in JSON format, for example: `{\"host\": \"localhost\"}`\n\nIf you omit this header, the response will be plain text: `localhost`\n\nIf the API cannot find a matching host, it will return a 404 status code.\nIn this case, the response body will be empty for plain text mode, and `{\"host\": null}` for json mode.\n\n\n### `GET /master`\n\nReturns the host of the current master, if one exists. If no master is available, it returns null.\n\n### `GET /replica`\n\nReturns the host of a replica, selected using the round-robin algorithm.\nIf no replicas are available, the master’s host is returned instead.\n\n### `GET /sync_by_time`\n\nReturns the host of a replica (selected using the round-robin algorithm) considered time-synchronous — that is, its time lag is less than the value specified in `pg_status__sync_max_lag_ms`.\nIf no replica meets this condition, the master’s host is returned.\n\n### `GET /sync_by_bytes`\n\nReturns the host of a replica (selected using the round-robin algorithm) considered byte-synchronous — that is, according to the WAL LSN, its lag is less than the value specified in `pg_status__sync_max_lag_bytes`.\nIf no replica meets this condition, the master’s host is returned.\n\n### `GET /sync_by_time_or_bytes`\n\nReturns the host of a replica (selected using the round-robin algorithm) that is considered synchronous either by time or by bytes.\nIf no such replica exists, the master’s host is returned.\n\n### `GET /sync_by_time_and_bytes`\n\nReturns the host of a replica (selected using the round-robin algorithm) that is considered synchronous by both time and bytes.\nIf no such replica exists, the master’s host is returned.\n\n### `GET /hosts`\n\nReturns a list of all hosts with their status information in json format.\n\nFor example:\n```json\n[\n  {\n    \"host\": \"host-1\",\n    \"master\": true,\n    \"alive\": true\n  },\n  {\n    \"host\": \"host-2\",\n    \"master\": false,\n    \"alive\": true\n  },\n  {\n    \"host\": \"host-3\",\n    \"master\": false,\n    \"alive\": false\n  }\n]\n```\n\n### `GET /status`\n\nReturns status of a host that you specified in the get parameter.\n\nFor example: `http://127.0.0.1:8000/status?host=host-1`\n```json\n{\n  \"master\": false,\n  \"alive\": true,\n  \"sync_by_time\": true,\n  \"sync_by_bytes\": true\n}\n```\n\n### `GET /version`\n\nReturns the pg-status semver\n\n\n### Parameters\n\nYou can configure various parameters using environment variables:\n\n- `pg_status__pg_user` — The user under which SQL queries to PostgreSQL will be executed. Default: `postgres`\n- `pg_status__pg_password` — The password for the PostgreSQL user. Default: `postgres`\n- `pg_status__pg_database` — The name of the database to connect to. Default: `postgres`\n- `pg_status__hosts` — A list of PostgreSQL hosts, separated by the `,`.\n- `pg_status__pg_port` — The connection port. You can specify separate ports for individual hosts using the same delimiter. Default: `5432`\n- `pg_status__connect_timeout` — The time limit (in seconds) for establishing a connection to PostgreSQL. Default: `2`\n- `pg_status__max_fails` — The number of consecutive errors allowed when checking a host’s status before it is considered dead. Default: `3`\n- `pg_status__sleep` — The delay (in seconds) between consecutive host status checks. Default: `5`\n- `pg_status__sync_max_lag_ms` — The maximum acceptable replication lag (in milliseconds) for a replica to still be considered time-synchronous. Default: `1000`\n- `pg_status__sync_max_lag_bytes` — The maximum acceptable lag (in bytes) for a replica to still be considered byte-synchronous. Default: `1000000` (1 MB)\n- `pg_status__http_port` — the port on which the http server will listen. Default: `8000`\n\n\n# Installation\n\nIn short there is:\n- [deb package](https://github.com/krylosov-aa/pg-status/releases/download/1.5.1/pg-status_1.5.1_amd64.deb)\n- [published container to Docker Hub](https://hub.docker.com/r/krylosovaa/pg-status)\n- various [docker containers](docker)\n- [static binary](https://github.com/krylosov-aa/pg-status/releases/download/1.5.1/pg-status_1.5.1_linux_amd64_static.tar.gz)\n- [shared binary](https://github.com/krylosov-aa/pg-status/releases/download/1.5.1/pg-status_1.5.1_linux_amd64_shared.tar.gz)\n\n\nFor more information, go to the [docs/installation.md](docs/installation.md) section.\n\n# Performance\n\nMemory - 9Mib\n\nDepending on the API being called and the format selected\n(plain `/master` is the fastest, json `/hosts` is the slowest):\n\n- 0.1 CPU — Requests/sec: ~1600-2000\n- 1 CPU — Requests/sec: ~8600-9000\n\n[Detailed performance reports](docs/performance.md)\n\n# Implementation Details\n\nThere is one writer and many readers in the program. To ensure the fastest possible response for readers and to allow\nthe writer to record new host statuses without delay, a lock-free approach was chosen.\n\nThe writer goes through all the hosts listed in `pg_status__hosts` every `pg_status__sleep` seconds, attempting to\nconnect to each host and read its status. Upon successfully receiving a response from a host, its status is updated\nimmediately. This means if the writer has started traversing the hosts but hasn't finished yet, there will be\ninconsistency in the data: some hosts will have new data, while others will not. Thanks to the lock-free design,\nthe writer cannot be blocked for long, so the window of inconsistency is quite small; however, it can grow depending\non the value of `pg_status__connect_timeout`.\n\nFor this project, it was more important to achieve the fastest response times and the most up-to-date data possible,\nso consistency was intentionally sacrificed.\n\n\n# Logging\n\nThe service writes to stdout and stderr. All errors, such as connection errors to pg hosts,\nare written to stderr.\n\nInformational messages about service startup and shutdown are written to stdout.\n\nMore importantly, information about host status changes is written to stdout:\n\nIf a host is dead, the message will be: `\u003chost-name\u003e: dead`\n\nIf a host is revived or becomes a master after failover, the message will be: `\u003chost-name\u003e: master`\n\nIf a host is revived or becomes a replica after failover, the message will be: `\u003chost-name\u003e: replica`\n\nFor replicas, there are also messages about replica synchronicity:\n\n```\n\u003chost-name\u003e: synchronous in time\n\u003chost-name\u003e: out of sync in time\n\u003chost-name\u003e: synchronous in bytes\n\u003chost-name\u003e: out of sync in bytes\n```\n\n\n# Testing the service\n\nYou can start the containers and test the application however you like.\n\n### make build_up\n\nBuilds [the lightweight container]((docker/alpine/Dockerfile_shared)) using parameters defined in\n[docker-compose.yml](docker-compose.yml).\n\nYou can create and populate a `.env` file using [the provided example](.env_example), or specify the required\nparameters directly in [docker-compose.yml](docker-compose.yml).\nThis allows you to test the application with your own database setup.\n\n### make build_up_test\n\nBuilds [the lightweight container](docker/alpine/Dockerfile_shared)\nwith parameters defined in [test/docker-compose.yml](test/docker-compose.yml).\n\nIn addition to the main service, this setup launches two PostgreSQL instances: one acting as the master and the other as a replica.\nTo simulate host failover or disconnection, proxy services are used.\nThis approach allows you to test master-switch scenarios without actually stopping PostgreSQL — you can simply switch the proxy’s target instead.\n\nHelper shell scripts are provided for this purpose:\n- [test/pg-proxy-1_is_master.sh](test/pg-proxy-1_is_master.sh)\n- [test/pg-proxy-2_is_master.sh](test/pg-proxy-2_is_master.sh)\n\n\n# Third‑party components\n\nIt uses the following third‑party components:\n\n- libmicrohttpd — licensed under [the GNU Lesser General Public License v2.1 or later](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html)\n- cJSON — licensed under [the MIT License](https://github.com/DaveGamble/cJSON/blob/master/LICENSE)\n- libpq — licensed under [the PostgreSQL License](https://www.postgresql.org/about/licence/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrylosov-aa%2Fpg-status","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrylosov-aa%2Fpg-status","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrylosov-aa%2Fpg-status/lists"}