pg_prometheus is a PostgreSQL extension developed by Timescale that enables PostgreSQL to store and query Prometheus metrics data. The extension defines a custom Prometheus metric samples data type and provides multiple storage formats for persisting Prometheus monitoring data within PostgreSQL databases. The project is written in C and integrates PostgreSQL's capabilities with Prometheus, the popular open-source monitoring and alerting system.
The extension supports integration with Prometheus through the Prometheus PostgreSQL adapter, which acts as a remote storage backend. This allows Prometheus to write metrics directly to PostgreSQL instead of relying solely on its local time-series database. The project also works optionally with TimescaleDB, Timescale's specialized PostgreSQL extension for time-series workloads, which provides improved performance and scalability when handling large volumes of metric data. A pre-built Docker image is available on Docker Hub that includes both pg_prometheus and TimescaleDB already installed, simplifying deployment for users who want to quickly set up the stack.
The extension provides two distinct storage formats for Prometheus metrics. The raw format stores all Prometheus samples in a single column using the custom prom_sample data type, with appropriate indexes created automatically. The normalized format, which is the default, separates metric labels into a companion table while storing values in a separate table, offering significant disk space savings when labels are long or repetitive. Both formats are abstracted behind a metrics view that allows users to query and insert data consistently regardless of the underlying storage approach.
Installation requires PostgreSQL libraries, headers, and development packages for C language backend development. After compilation from source, users must edit the postgresql.conf configuration file to load the extension and then install it as a superuser. The extension creates a metrics table for inserting data in Prometheus exposition format and a metrics_view for querying. Data insertion follows the Prometheus exposition format standard, and the extension provides specialized copy tables with a _copy suffix to handle bulk data loading since PostgreSQL does not permit COPY operations directly on views.
According to GitGenius activity data, pg_prometheus shares contributors with other Timescale projects including timescaledb, as well as with unrelated projects like kcp-dev/kcp and marimo-team/marimo. The repository is classified across multiple domains including timeseries, observability, exporter, instrumentation, database, integration, database performance, system health, and monitoring.
Notably, the project has entered maintenance mode and is being sunset in favor of a newer implementation called Promscale, which offers additional functionality and better support for newer TimescaleDB features such as compression. The README explicitly directs users to the Promscale project at github.com/timescale/promscale for ongoing development and new features. The extension is released under the Apache 2 Open Source License, and contributions are welcome from developers willing to sign the project's Contributor License Agreement.
