A lightweight, configurable Prometheus exporter for PostgreSQL written in Node.js.

• Collects core PostgreSQL metrics (connections, database size)
• Collects metrics about itself (scrape duration, error count)
• Supports dynamic custom metrics via queries.json
• Supports multiple database connections via databases.json
• Secured with API key using Bearer auth
• Fully Docker-compatible and cloud-ready
• Fast to set up, easy to extend

git clone git@github.com/ducks/node-postgres-exporter.git
cd node-postgres-exporter
cp .env.example .env
cp databases.json.example databases.json

Edit .env to match your environment:

EXPORTER_PORT=9187
EXPORTER_API_KEY=Defacing-Tingle-Caucus8-Refueling
QUERIES_FILE=/app/queries.json
DBS_CONFIG_FILE=/app/databases.json

Edit databases.json to match your environment:

{
  "databases": [
    {
      "name": "db1",
      "host": "postgres1",
      "port": 5432,
      "user": "postgres",
      "pass": "postgres",
      "database": "db1"
    },
    {
      "name": "db2",
      "host": "postgres2",
      "port": 5432,
      "user": "postgres",
      "pass": "postgres",
      "database": "db2"
    }
  ]
}

Edit or mount a custom queries.json file:

[
  {
    "name": "active_users",
    "help": "Number of active users in the system",
    "type": "gauge",
    "labels": ["status"],
    "query": "SELECT status, COUNT(*)::int FROM users GROUP BY status"
  }
]

docker build -t pg-exporter .
docker run -p 9187:9187 \
  --env-file .env \
  -v $(pwd)/queries.json:/app/queries.json \
  -v $(pwd)/databases.json:/app/databases.json \
  pg-exporter

Or with Docker Compose:

docker compose up

scrape_configs:
  - job_name: 'postgres_exporter'
    static_configs:
      - targets: ['your-exporter-host:9187']
    authorization:
      type: Bearer
      credentials: your_secret_key

The /metrics endpoint requires a Bearer token.

You must include the following HTTP header:

Authorization: Bearer your_secret_key

Unit tests are written using Vitest.

Unit tests run on main branch push/PR. Integration tests requiring live databases are automatically skipped in CI environments.

To run full tests locally:

npm test

• Rate-limit /metrics to protect against abuse or scraping loops
• Add exporter self-health metrics (up, scrape duration, error count)
• Add unit tests for query loading and metric registration
• Gracefully shut down DB pools on SIGINT/SIGTERM
• Support multiple database connections
• Add basic GitHub Actions CI integration
• Add /configz endpoint to expose active config for debugging

Future enhancements:

• Hot-reload queries.json without restart
• Support token auth via query param (e.g., ?token=...)
• Publish prebuilt Docker image to GitHub Container Registry
• Support large .sql file queries
• Expand metric type support beyond Gauge/Counter

MIT