{"id":13563831,"url":"https://github.com/justwatchcom/sql_exporter","last_synced_at":"2026-01-12T14:35:47.800Z","repository":{"id":18343746,"uuid":"84057401","full_name":"justwatchcom/sql_exporter","owner":"justwatchcom","description":"Flexible SQL Exporter for Prometheus.","archived":false,"fork":false,"pushed_at":"2025-09-22T16:27:42.000Z","size":20740,"stargazers_count":473,"open_issues_count":42,"forks_count":127,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-09-29T06:39:34.268Z","etag":null,"topics":["athena","clickhouse","kubernetes","mysql","postgresql","prometheus","prometheus-exporter","snowflake","sql"],"latest_commit_sha":null,"homepage":"","language":"Go","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/justwatchcom.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":"2017-03-06T09:58:18.000Z","updated_at":"2025-09-26T13:49:06.000Z","dependencies_parsed_at":"2024-01-30T12:45:25.320Z","dependency_job_id":"f5a7d4dd-fa15-46f3-bdae-3967301121b4","html_url":"https://github.com/justwatchcom/sql_exporter","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/justwatchcom/sql_exporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justwatchcom%2Fsql_exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justwatchcom%2Fsql_exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justwatchcom%2Fsql_exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justwatchcom%2Fsql_exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justwatchcom","download_url":"https://codeload.github.com/justwatchcom/sql_exporter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justwatchcom%2Fsql_exporter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28340402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"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":["athena","clickhouse","kubernetes","mysql","postgresql","prometheus","prometheus-exporter","snowflake","sql"],"created_at":"2024-08-01T13:01:23.729Z","updated_at":"2026-01-12T14:35:47.758Z","avatar_url":"https://github.com/justwatchcom.png","language":"Go","readme":"# Prometheus SQL Exporter [![Build Status](https://travis-ci.org/justwatchcom/sql_exporter.svg?branch=master)](https://travis-ci.org/justwatchcom/sql_exporter)\n\n[![Docker Pulls](https://img.shields.io/docker/pulls/justwatch/sql_exporter.svg?maxAge=604800)](https://hub.docker.com/r/justwatch/sql_exporter)\n[![Go Report Card](https://goreportcard.com/badge/github.com/justwatchcom/sql_exporter)](https://goreportcard.com/report/github.com/justwatchcom/sql_exporter)\n\nThis repository contains a service that runs user-defined SQL queries at flexible intervals and exports the resulting metrics via HTTP for Prometheus consumption.\n\nStatus\n======\n\nActively used with PostgreSQL in production. We'd like to eventually support all databases for which stable Go database [drivers](https://github.com/golang/go/wiki/SQLDrivers) are available. Contributions welcome.\n\nCurrently supported:\n\n- Postgres\n- ClickHouse\n- AWS Athena\n- MS-SQL\n- MySQL\n- Snowflake\n- Vertica\n- Materialize\n- CloudSQL\n\n\nWhat does it look like?\n=======================\n\n![Grafana DB Dashboard](/examples/grafana/screenshot.jpg?raw=true)\n\nGetting Started\n===============\n\nCreate a _config.yml_ and run the service:\n\n```\ngo get github.com/justwatchcom/sql_exporter\ncp config.yml.dist config.yml\n./prom-sql-exporter\n```\n\nRunning in Docker:\n\n```bash\ndocker run \\\n  -v `pwd`/config.yml:/config/config.yml \\\n  -e CONFIG=/config/config.yml \\\n  -d \\\n  -p 9237:9237 \\\n  --name sql_exporter \\\n  ghcr.io/justwatchcom/sql_exporter\n```\n\nManual `scrape_configs` snippet:\n\n```yaml\nscrape_configs:\n- job_name: sql_exporter\n  static_configs:\n  - targets: ['localhost:9237']\n```\n\nFlags\n-----\n\nName    | Description\n--------|------------\n`version` | Print version information\n`web.listen-address` | Address to listen on for web interface and telemetry\n`web.telemetry-path` | Path under which to expose metrics\n`config.file` | SQL Exporter configuration file name\n\nEnvironment Variables\n---------------------\n\nName    | Description\n--------|------------\n`CONFIG`  | Location of Configuration File (yaml)\n\nUsage\n=====\n\nWe recommend to deploy and run the SQL exporter in Kubernetes.\n\nKubernetes\n----------\n\nSee [examples/kubernetes](https://github.com/justwatchcom/sql_exporter/tree/master/examples/kubernetes).\n\nGrafana\n-------\n\nSee [examples/grafana](https://github.com/justwatchcom/sql_exporter/tree/master/examples/grafana).\n\nPrometheus\n----------\n\nExample recording and alerting rules are available in [examples/prometheus](https://github.com/justwatchcom/sql_exporter/tree/master/examples/prometheus).\n\nConfiguration\n-------------\n\nWhen writing queries for this exporter please keep in mind that Prometheus data\nmodel assigns exactly one `float` to a metric, possibly further identified by a\nset of zero or more labels. These labels need to be of type `string` or `text`.\n\nIf your SQL dialect supports explicit type casts, you should always cast your\nlabel columns to `text` and the metric columns to `float`. The SQL exporter will\ntry hard to support other types or drivers w/o support for explicit cast as well,\nbut the results may not be what you expect.\n\nBelow is a documented configuration example showing all available options.\nFor a more realistic example please have a look at [examples/kubernetes/configmap.yml](https://github.com/justwatchcom/sql_exporter/blob/master/examples/kubernetes/configmap.yml).\n\n```yaml\n---\n# jobs is a map of jobs, define any number but please keep the connection usage on the DBs in mind\njobs:\n  # each job needs a unique name, it's used for logging and as a default label\n- name: \"example\"\n  # interval defined the pause between the runs of this job\n  interval: '5m'\n  # cron_schedule when to execute the job in the standard CRON syntax\n  # if specified, the interval is ignored\n  cron_schedule: \"0 0 * * *\"\n  # connections is an array of connection URLs\n  # each query will be executed on each connection\n  connections:\n  - 'postgres://postgres@localhost/postgres?sslmode=disable'\n  # startup_sql is an array of SQL statements\n  # each statements is executed once after connecting\n  startup_sql:\n  - 'SET lock_timeout = 1000'\n  - 'SET idle_in_transaction_session_timeout = 100'\n  # iterator is an optional mechanism to iterate over a series of values, e.g. multiple databases\n  iterator:\n    # sql is the SQL to execute to retrieve the list of values to iterate over -\n    # query result must be a single column\n    sql: 'SELECT database_name FROM databases'\n    # placeholder should be present in the original query and not also used as an environment variable\n    # e.g. {{PLACEHOLDER}} - it will be replaced by the values retrieved by the query\n    placeholder: PLACEHOLDER\n    # label is the label name to which the iterator value gets assigned\n    label: database\n  # queries is a map of Metric/Query mappings\n  queries:\n    # name is prefixed with sql_ and used as the metric name\n  - name: \"running_queries\"\n    # help is a requirement of the Prometheus default registry, currently not\n    # used by the Prometheus server. Important: Must be the same for all metrics\n    # with the same name!\n    help: \"Number of running queries\"\n    # Optional: Column to use as a metric timestamp source.\n    # Leave unset if it's not needed\n    timestamp: \"created_at\"\n    # Labels is an array of columns which will be used as additional labels.\n    # Must be the same for all metrics with the same name!\n    # All labels columns should be of type text, varchar or string\n    labels:\n      - \"datname\"\n      - \"usename\"\n    # Values is an array of columns used as metric values. All values should be\n    # of type float\n    values:\n      - \"count\"\n    # Query is the SQL query that is run unalterted on each of the connections\n    # for this job\n    query:  |\n            SELECT now() as created_at, datname::text, usename::text, COUNT(*)::float AS count\n            FROM pg_stat_activity GROUP BY created_at, datname, usename;\n    # Consider the query failed if it returns zero rows\n    allow_zero_rows: false\n```\n\nRunning as non-superuser on PostgreSQL\n--------------------------------------\n\nSome queries require superuser privileges on PostgreSQL.\nIf you prefer not to run the exporter with superuser privileges, you can use some views/functions to get around this limitation.\n\n```sql\nCREATE USER postgres_exporter PASSWORD 'pw';\nALTER USER postgres_exporter SET SEARCH_PATH TO postgres_exporter,pg_catalog;\n\nCREATE SCHEMA postgres_exporter AUTHORIZATION postgres_exporter;\n\nCREATE FUNCTION postgres_exporter.f_select_pg_stat_activity()\nRETURNS setof pg_catalog.pg_stat_activity\nLANGUAGE sql\nSECURITY DEFINER\nAS $$\n  SELECT * from pg_catalog.pg_stat_activity;\n$$;\n\nCREATE FUNCTION postgres_exporter.f_select_pg_stat_replication()\nRETURNS setof pg_catalog.pg_stat_replication\nLANGUAGE sql\nSECURITY DEFINER\nAS $$\n  SELECT * from pg_catalog.pg_stat_replication;\n$$;\n\nCREATE VIEW postgres_exporter.pg_stat_replication\nAS\n  SELECT * FROM postgres_exporter.f_select_pg_stat_replication();\n\nCREATE VIEW postgres_exporter.pg_stat_activity\nAS\n  SELECT * FROM postgres_exporter.f_select_pg_stat_activity();\n\nGRANT SELECT ON postgres_exporter.pg_stat_replication TO postgres_exporter;\nGRANT SELECT ON postgres_exporter.pg_stat_activity TO postgres_exporter;\n```\n\nLogging\n-------\n\nYou can change the loglevel by setting the `LOGLEVEL` variable in the exporters\nenvironment.\n\n```\nLOGLEVEL=info ./sql_exporter\n```\n\nDatabase specific configurations\n--------------------------------\n\nFor some database backends some special functionality is available:\n\n* cloudsql-postgres: A special `*` character can be used to query all databases accessible by the account\n* cloudsql-mysql: Same as above\n* rds-postgres: This type of URL expects a working AWS configuration\n  which will use the equivalent of `rds generate-db-auth-token`\n  for the password. For this driver, the `AWS_REGION` environment variable\n  must be set.\n* rds-mysql: This type of URL expects a working AWS configuration\n  which will use the equivalent of `rds generate-db-auth-token`\n  for the password. For this driver, the `AWS_REGION` environment variable\n  must be set.\n\n\nWhy this exporter exists\n========================\n\nThe other projects with similar goals did not meet our requirements on either\nmaturity or flexibility. This exporter does not rely on any other service and\nruns in production for some time already.\n\nLicense\n=======\n\nMIT License\n","funding_links":[],"categories":["Go","Integrations"],"sub_categories":["Metrics and Monitoring"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustwatchcom%2Fsql_exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustwatchcom%2Fsql_exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustwatchcom%2Fsql_exporter/lists"}