{"id":28545313,"url":"https://github.com/ducks/node-postgres-exporter","last_synced_at":"2026-05-02T22:37:40.368Z","repository":{"id":298156202,"uuid":"999042233","full_name":"ducks/node-postgres-exporter","owner":"ducks","description":"A lightweight, configurable Prometheus exporter for PostgreSQL written in Node.js.","archived":false,"fork":false,"pushed_at":"2025-06-18T15:17:52.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-18T15:44:12.463Z","etag":null,"topics":["nodejs","postgres","prometheus"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ducks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-06-09T16:43:24.000Z","updated_at":"2025-06-18T15:17:56.000Z","dependencies_parsed_at":"2025-06-09T18:39:39.858Z","dependency_job_id":null,"html_url":"https://github.com/ducks/node-postgres-exporter","commit_stats":null,"previous_names":["ducks/node-postgres-exporter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ducks/node-postgres-exporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fnode-postgres-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fnode-postgres-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fnode-postgres-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fnode-postgres-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ducks","download_url":"https://codeload.github.com/ducks/node-postgres-exporter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ducks%2Fnode-postgres-exporter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262047899,"owners_count":23250444,"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":["nodejs","postgres","prometheus"],"created_at":"2025-06-09T23:07:12.423Z","updated_at":"2025-10-28T10:32:58.037Z","avatar_url":"https://github.com/ducks.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# node-postgres-exporter\n\nA lightweight, configurable Prometheus exporter for PostgreSQL written in Node.js.\n\n- Collects core PostgreSQL metrics (connections, database size)\n- Collects metrics about itself (scrape duration, error count)\n- Supports dynamic custom metrics via `queries.json`\n- Supports multiple database connections via `databases.json`\n- Secured with API key using Bearer auth\n- Fully Docker-compatible and cloud-ready\n- Fast to set up, easy to extend\n\n---\n\n## Quickstart\n\n### 1. Clone and configure\n\n```bash\ngit clone git@github.com/ducks/node-postgres-exporter.git\ncd node-postgres-exporter\ncp .env.example .env\ncp databases.json.example databases.json\n```\n\nEdit `.env` to match your environment:\n\n```\nEXPORTER_PORT=9187\nEXPORTER_API_KEY=Defacing-Tingle-Caucus8-Refueling\nQUERIES_FILE=/app/queries.json\nDBS_CONFIG_FILE=/app/databases.json\n```\n\nEdit `databases.json` to match your environment:\n```\n{\n  \"databases\": [\n    {\n      \"name\": \"db1\",\n      \"host\": \"postgres1\",\n      \"port\": 5432,\n      \"user\": \"postgres\",\n      \"pass\": \"postgres\",\n      \"database\": \"db1\"\n    },\n    {\n      \"name\": \"db2\",\n      \"host\": \"postgres2\",\n      \"port\": 5432,\n      \"user\": \"postgres\",\n      \"pass\": \"postgres\",\n      \"database\": \"db2\"\n    }\n  ]\n}\n```\n\n### 2. Define your metrics\n\nEdit or mount a custom `queries.json` file:\n\n```\n[\n  {\n    \"name\": \"active_users\",\n    \"help\": \"Number of active users in the system\",\n    \"type\": \"gauge\",\n    \"labels\": [\"status\"],\n    \"query\": \"SELECT status, COUNT(*)::int FROM users GROUP BY status\"\n  }\n]\n```\n\n### 3. Run it\n\n```\ndocker build -t pg-exporter .\ndocker run -p 9187:9187 \\\n  --env-file .env \\\n  -v $(pwd)/queries.json:/app/queries.json \\\n  -v $(pwd)/databases.json:/app/databases.json \\\n  pg-exporter\n```\n\nOr with Docker Compose:\n\n`docker compose up`\n\n### 4. Configure Prometheus\n\n```\nscrape_configs:\n  - job_name: 'postgres_exporter'\n    static_configs:\n      - targets: ['your-exporter-host:9187']\n    authorization:\n      type: Bearer\n      credentials: your_secret_key\n```\n\n## Metrics Exposed\n\n| Metric                                   | Type    | Description                                       |\n|------------------------------------------|---------|---------------------------------------------------|\n| `pg_active_connections{db=\"...\"}`        | Gauge   | Number of active PostgreSQL connections per DB    |\n| `pg_database_size_bytes{db=\"...\",database=\"...\"}` | Gauge | Size of each database in bytes per DB      |\n| `pg_scrape_success{db=\"...\"}`            | Gauge   | 1 if last scrape succeeded for DB, 0 if failed    |\n| `pg_scrape_duration_seconds{db=\"...\"}`   | Gauge   | Duration of scrape per DB in seconds              |\n| `exporter_up`                            | Gauge   | Always `1` if exporter process is running         |\n| `exporter_errors_total`                  | Counter | Total number of scrape errors encountered         |\n| `exporter_scrape_duration_seconds`       | Gauge   | Total scrape duration for entire exporter         |\n| `exporter_scrape_lockouts_total`         | Counter | Total number of scrape requests rejected due to concurrent scrape lock |\n| _Custom metrics_                         | Gauge/Counter | Defined via `queries.json`, dynamically loaded    |\n\n## Endpoints\n\n| Path         | Method | Auth Required | Description                          |\n|--------------|--------|----------------|--------------------------------------|\n| `/metrics`   | GET    | ✅ Bearer Token | Prometheus scrape endpoint            |\n| `/healthz`   | GET    | ❌ None         | Liveness probe for health checks      |\n| `/livez`     | GET    | ❌ None         | Liveness probe; returns `200 OK` if process is alive     |\n| `/readyz`    | GET    | ❌ None         | Readiness probe. Returns `200 OK` if the database connection is successful. |\n| `/configz`   | GET    | ✅ Bearer Token | Returns current loaded database and metrics config |\n\n### Authorization\n\nThe `/metrics` endpoint requires a Bearer token.\n\nYou must include the following HTTP header:\n```\nAuthorization: Bearer your_secret_key\n```\n\n## Configuration\n\n| Variable            | Description                            |\n|---------------------|----------------------------------------|\n| `EXPORTER_PORT`     | HTTP server port (default `9187`)      |\n| `EXPORTER_API_KEY`  | Bearer token for `/metrics` access     |\n| `QUERIES_FILE`      | Path to `queries.json` file            |\n| `DBS_CONFIG_FILE`   | Path to `databases.json` file          |\n\n## Testing\n\nUnit tests are written using Vitest.\n\nUnit tests run on `main` branch push/PR. Integration tests requiring live\ndatabases are automatically skipped in CI environments.\n\nTo run full tests locally:\n\n`npm test`\n\n## TODOs / Improvement Ideas\n\n- [x] Rate-limit `/metrics` to protect against abuse or scraping loops\n- [x] Add exporter self-health metrics (up, scrape duration, error count)\n- [x] Add unit tests for query loading and metric registration\n- [x] Gracefully shut down DB pools on SIGINT/SIGTERM\n- [x] Support multiple database connections\n- [x] Add basic GitHub Actions CI integration\n- [x] Add `/configz` endpoint to expose active config for debugging\n\nFuture enhancements:\n\n- [ ] Hot-reload `queries.json` without restart\n- [ ] Support token auth via query param (e.g., `?token=...`)\n- [ ] Publish prebuilt Docker image to GitHub Container Registry\n- [ ] Support large `.sql` file queries\n- [ ] Expand metric type support beyond Gauge/Counter\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fducks%2Fnode-postgres-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fducks%2Fnode-postgres-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fducks%2Fnode-postgres-exporter/lists"}