SQL databases (generic)

Plugin: go.d.plugin Module: sql

Overview

Metrics and charts for this collector are entirely defined by your SQL configuration. There is no fixed metric reference: each job can expose different metrics depending on its metrics and queries blocks.

To see what a specific job collects, open that job's dashboard in Netdata and inspect the charts and dimensions it created.

Jobs can also define functions that provide interactive table views in Netdata's Live tab. A job can have metrics only, functions only, or both.

:::tip

To change what is collected, edit the metrics (and optional queries) in the job configuration. After you save the changes, the updated set of charts and metrics is reflected in Netdata after the next data collection.

:::

The collector connects to your database using Go’s database/sql package and the selected driver:

mysql — MySQL / MariaDB
pgx — PostgreSQL
oracle — Oracle Database
sqlserver — Microsoft SQL Server / Azure SQL

For each metric block you define, it executes the SQL query (inline or via query_ref), reads the result set, and maps it to Netdata charts and dimensions.

Additionally, you can define functions that expose SQL query results as interactive table views in Netdata's Live tab. Functions support filtering, sorting, and searching without creating persistent metrics.

Result Processing Modes

Mode	How it works	Best used when
columns	Specific numeric columns from each row become dimensions on your charts.	The result set has stable, known column names.
kv	One column provides metric names (keys) and another provides their values.	The set of metrics is dynamic or key–value shaped.

This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

Default Behavior

Auto-Detection

This is a generic collector and does not perform automatic detection.

It does not create any jobs on its own — you must configure at least one job before it can collect data.

Limits

There are no built-in limits on the number of queries or rows processed. However, each metric block must define at least one chart, and each chart must define at least one dimension.

Keep your queries lightweight and scoped to the data you actually need to avoid adding load on the database server.

Performance Impact

Performance impact depends entirely on the queries you configure and the collection frequency (update_every).

Prefer indexed reads, avoid full table scans or heavy aggregations, and consider using database views tailored for monitoring.

Setup

You can configure the sql collector in two ways:

Method	Best for	How to
UI	Fast setup without editing files	Go to Nodes → Configure this node → Collectors → Jobs, search for sql, then click + to add a job.
File	If you prefer configuring via file, or need to automate deployments (e.g., with Ansible)	Edit `go.d/sql.conf` and add a job.

:::important

UI configuration requires paid Netdata Cloud plan.

:::

Prerequisites

Create a read-only database user

Create a dedicated user for Netdata with read-only privileges on the views/tables used in your monitoring queries.

For example, on a typical RDBMS you would:

Create a user.
Grant SELECT on system metrics views or monitoring views.

After creating the user and updating the configuration, restart the Netdata Agent with sudo systemctl restart netdata, or the appropriate method for your system.

Allow Netdata to connect to the database

Ensure the Netdata host can reach the database via the configured DSN, either using:

a local UNIX/TCP socket, or
a network connection (hostname/IP and port).

If the database is remote, make sure any firewalls or security groups allow connections from the Netdata node.

Configuration

Options

Full Configuration Structure

yaml

# ---------- CONNECTION ----------
driver: <mysql|pgx|oracle|sqlserver|azuresql> # REQUIRED. SQL driver.
dsn: "<connection string>"                   # REQUIRED. Driver-specific DSN/URL.

# Optional connection settings
timeout: <seconds>                           # OPTIONAL. Query timeout.
cloud_auth:                                  # OPTIONAL. Cloud auth for pgx/sqlserver/azuresql.
  provider: <none|azure_ad>                 # OPTIONAL. Default: none.
  azure_ad:
    mode: <service_principal|managed_identity|default>
    mode_service_principal:                  # REQUIRED for service_principal
      tenant_id: "<tenant-id>"
      client_id: "<client-id>"
      client_secret: "<client-secret>"
    mode_managed_identity:                   # OPTIONAL for managed_identity
      client_id: "<client-id>"               # Optional for user-assigned MI

# Optional static labels applied to all charts
static_labels:
  <label_key1>: <label_value>
  <label_key2>: <label_value>

# ---------- REUSABLE QUERIES ----------
# Optional. Define reusable SQL queries referenced later via query_ref.
queries:
  - id: <query_id>
    query: |
      SELECT ...

# ---------- METRICS ----------
# Each metric block runs one query and generates one or more charts.
metrics:
  - id: <metric_block_id>                    # REQUIRED. Unique within this job.

    # Choose ONE of these:
    query_ref: <query_id>                    # Use a reusable query
    # OR
    # query: |                               # Inline SQL
    #   SELECT ...

    mode: <columns|kv>                       # REQUIRED. How to interpret result rows.

    # KV mode settings (only when mode: kv)
    kv_mode:
      name_col: <column_name>                # Column containing keys
      value_col: <column_name>               # Column containing numeric values

    # Optional: derive labels from row columns (creates per-label charts)
    labels_from_row:
      - source: <column_name>                # Column name from result set
        name: <label_key>                    # Label key exposed to Netdata
      - source: <column_name>
        name: <label_key>

    # Charts produced by this metric block
    charts:
      - title: "<Chart Title>"               # REQUIRED. Shown in dashboards.
        context: "<context.name>"            # REQUIRED. Netdata context.
        family: "<family>"                   # REQUIRED. Netdata chart family.
        units: "<units>"                     # REQUIRED. Unit string for the chart.
        type: <line|stacked|area>            # OPTIONAL. Default: line.
        algorithm: <absolute|incremental>    # OPTIONAL. Default: absolute.

        dims:
          # ---- COLUMNS MODE DIM ----
          # In mode: columns, `source` MUST be a numeric COLUMN name from the result set.
          - name: <dim_id>                   # REQUIRED. Dimension id (unique within this chart).
            source: <column_name>            # REQUIRED. Numeric column to chart.

          # ---- KV MODE DIM ----
          # In mode: kv, `source` MUST be a KEY name (NOT a column).
          # The collector finds the row where (row[kv_mode.name_col] == `source`)
          # and uses row[kv_mode.value_col].
          - name: <dim_id>
            source: <key_name>               # REQUIRED. Key name resolved via kv_mode.name_col.

          # ---- STATUS DIM (one-hot 1/0) ----
          # Works in BOTH modes. Evaluates `status_when` against the resolved value:
          #   * columns mode: the value in the specified column for the row
          #   * kv mode:      the value for the resolved key (row[kv_mode.value_col])
          - name: <dim_id>
            source: <column_name_or_key_name>  # Same interpretation as above, per mode.
            status_when: # Exactly ONE of the following:
              equals: <string|number|bool>    # Active (1) if value == this literal.
              # in: [ <v1>, <v2>, ... ]       # Active if value is in the list.
              # match: '^regex$'              # Active if value matches this regex.

# ---------- FUNCTIONS ----------
# Set function_only: true if this job only provides functions (no metrics).
function_only: <true|false>                    # OPTIONAL. Default: false.

# Expose SQL queries as interactive table views in Netdata's Live tab.
functions:
  - id: <function_id>                          # REQUIRED. Unique identifier.
    name: <display_name>                       # OPTIONAL. Derived from id if not set.
    description: <help_text>                   # OPTIONAL. Shown in the UI.
    query: |                                   # REQUIRED. SQL to execute.
      SELECT ...
    timeout: <seconds>                         # OPTIONAL. Query timeout.
    limit: <max_rows>                          # OPTIONAL. Default: 100.
    default_sort: <column_name>                # OPTIONAL. Initial sort column.
    default_sort_desc: <true|false>            # OPTIONAL. Default: true.
    columns:                                   # OPTIONAL. Override column metadata.
      <column_name>:
        type: <string|integer|float|boolean|duration|timestamp>
        units: <unit_string>
        tooltip: <hover_text>
        visible: <true|false>
        sortable: <true|false>

<details open><summary>Config options</summary>

Group	Option	Description	Default	Required
Collection	update_every	Data collection interval (seconds).	1	no
	autodetection_retry	Autodetection retry interval (seconds). Not used for this collector. Set 0 to disable.	0	no
Target	driver	SQL driver to use. Supported values: `mysql`, `pgx`, `oracle`, `sqlserver`, `azuresql`.	mysql	yes
	dsn	Database connection string (DSN). The format depends on the selected driver ( MySQL, PostgreSQL, MS SQL Server).		yes
Cloud Auth	cloud_auth.provider	Cloud auth provider (`none` or `azure_ad`). Supported for `pgx`, `sqlserver`, and `azuresql`.	none	no
Cloud Auth/Azure	cloud_auth.azure_ad.mode	Azure AD credential mode (`service_principal`, `managed_identity`, or `default`). Required when `cloud_auth.provider` is `azure_ad`.		yes
	cloud_auth.azure_ad.mode_service_principal.tenant_id	Azure tenant ID. Required for `service_principal` mode.		no
	cloud_auth.azure_ad.mode_service_principal.client_id	Azure client ID. Required for `service_principal` mode.		no
	cloud_auth.azure_ad.mode_service_principal.client_secret	Azure client secret for `service_principal` mode.		no
	cloud_auth.azure_ad.mode_managed_identity.client_id	Optional client ID of a user-assigned managed identity (`managed_identity` mode).		no
Connection	timeout	Query and connection check timeout (seconds).	5	no
Labels	static_labels	A map of static labels added to every chart created by this job. Useful for tagging charts with environment, region, or role.	{}	no
Queries & Metrics	queries	A list of reusable queries. Metric blocks can reference these via `query_ref` to avoid repeating SQL. See Configuration Structure for details.	[]	no
	metrics	A list of metric blocks. Each block defines how a query is executed and how its result is transformed into one or more charts. See Configuration Structure for details.	[]	no
Functions	functions	A list of SQL functions exposed as interactive table views in Netdata's Live tab. Each function runs a SQL query and displays results in a filterable, sortable table. See Functions for details.	[]	no
	functions[].id	Unique identifier for this function.		yes
	functions[].name	Display name shown in the UI. Auto-derived from ID if not set.		no
	functions[].description	Help text shown in the UI.		no
	functions[].query	SQL query to execute when this function is called.		yes
	functions[].timeout	Query timeout (seconds). Uses collector timeout if not set.		no
	functions[].limit	Maximum rows to return.	100	no
	functions[].default_sort	Column name for initial sort order.		no
	functions[].default_sort_desc	Sort in descending order by default.	yes	no
	functions[].columns	Override auto-detected column metadata. Map of column name to settings (type, units, tooltip, visible, sortable).	{}	no
	function_only	Set to true if this job only provides functions (no metrics). When enabled, metrics configuration is not required and no charts are created.	no	no
Virtual Node	vnode	Associates this data collection job with a Virtual Node.		no

</details>

via UI

Configure the sql collector from the Netdata web interface:

Go to Nodes.
Select the node where you want the sql data-collection job to run and click the :gear: (Configure this node). That node will run the data collection.
The Collectors → Jobs view opens by default.
In the Search box, type sql (or scroll the list) to locate the sql collector.
Click the + next to the sql collector to add a new job.
Fill in the job fields, then click Test to verify the configuration and Submit to save.
- Test runs the job with the provided settings and shows whether data can be collected.
- If it fails, an error message appears with details (for example, connection refused, timeout, or command execution errors), so you can adjust and retest.

via File

The configuration file name for this integration is go.d/sql.conf.

The file format is YAML. Generally, the structure is:

yaml

update_every: 1
autodetection_retry: 0
jobs:
  - name: some_name1
  - name: some_name2

You can edit the configuration file using the edit-config script from the Netdata config directory.

bash

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config go.d/sql.conf

Examples

Azure SQL with service principal (azuresql)

SQL Server query example against Azure SQL using Microsoft Entra service principal authentication.

<details open><summary>Config</summary>

yaml

jobs:
  - name: azure_sql_connections
    driver: azuresql
    dsn: "sqlserver://my-server.database.windows.net:1433?database=master"
    timeout: 5
    cloud_auth:
      provider: azure_ad
      azure_ad:
        mode: service_principal
        mode_service_principal:
          tenant_id: "00000000-0000-0000-0000-000000000000"
          client_id: "11111111-1111-1111-1111-111111111111"
          client_secret: "super-secret-value"
    metrics:
      - id: user_connections
        mode: columns
        query: |
          SELECT COUNT(*) AS connections
          FROM sys.dm_exec_sessions
          WHERE is_user_process = 1;
        charts:
          - title: "Azure SQL user connections"
            context: sql.azure_sql_user_connections
            family: connections
            units: sessions
            dims:
              - name: users
                source: connections

</details>

Azure PostgreSQL with default credential (pgx)

PostgreSQL query example against Azure Database for PostgreSQL using the default Azure credential chain.

<details open><summary>Config</summary>

yaml

jobs:
  - name: azure_pg_uptime
    driver: pgx
    dsn: 'postgresql://[email protected]:5432/postgres?sslmode=require'
    timeout: 5
    cloud_auth:
      provider: azure_ad
      azure_ad:
        mode: default
    metrics:
      - id: uptime
        mode: columns
        query: |
          SELECT EXTRACT(EPOCH FROM (now() - pg_postmaster_start_time())) AS uptime_seconds;
        charts:
          - title: "Azure PostgreSQL uptime"
            context: sql.azure_pg_uptime
            family: uptime
            units: seconds
            dims:
              - name: uptime
                source: uptime_seconds

</details>

Columns mode – per-database conflicts (with labels)

PostgreSQL example that collects database-level conflict counters from pg_stat_database_conflicts and creates a separate chart instance per database using labels_from_row.

The query:

sql

SELECT
  datname,
  confl_tablespace,
  confl_lock,
  confl_snapshot,
  confl_bufferpin,
  confl_deadlock
FROM pg_stat_database_conflicts;

Example output:

datname	confl_tablespace	confl_lock	confl_snapshot	confl_bufferpin	confl_deadlock
postgres	0	0	0	0	0
production	0	0	0	0	0

This configuration turns each row into a chart instance (one for db=postgres, one for db=production) with five dimensions (confl_tablespace, confl_lock, confl_snapshot, confl_bufferpin, confl_deadlock).

<details open><summary>Config</summary>

yaml

jobs:
  - name: pg_conflicts_per_db
    driver: pgx
    dsn: 'postgresql://netdata:[email protected]:5432/postgres'
    timeout: 5

    metrics:
      - id: conflicts
        mode: columns
        query: |
          SELECT
            datname,
            confl_tablespace,
            confl_lock,
            confl_snapshot,
            confl_bufferpin,
            confl_deadlock
          FROM pg_stat_database_conflicts;
        labels_from_row:
          - source: datname
            name: db
        charts:
          - title: "PostgreSQL conflicts"
            context: sql.pg_conflicts
            family: conflicts
            units: conflicts
            type: line
            algorithm: absolute
            dims:
              - name: confl_tablespace
                source: confl_tablespace
              - name: confl_lock
                source: confl_lock
              - name: confl_snapshot
                source: confl_snapshot
              - name: confl_bufferpin
                source: confl_bufferpin
              - name: confl_deadlock
                source: confl_deadlock

</details>

Columns mode – single numeric value (uptime)

PostgreSQL example that exposes a single numeric metric (server uptime in seconds) as a one-dimension chart using columns mode.

The query:

sql

SELECT
  EXTRACT(
    EPOCH FROM (now() - pg_postmaster_start_time())
  ) AS uptime_seconds;

Example output:

uptime_seconds
50.867359

This configuration maps the uptime_seconds column to a single uptime dimension on the sql.pg_uptime chart.

<details open><summary>Config</summary>

yaml

jobs:
  - name: pg_uptime
    driver: pgx
    dsn: 'postgresql://netdata:[email protected]:5432/postgres'
    timeout: 5

    metrics:
      - id: uptime
        mode: columns
        query: |
          SELECT
            EXTRACT(
              EPOCH FROM (now() - pg_postmaster_start_time())
            ) AS uptime_seconds;
        charts:
          - title: "PostgreSQL uptime"
            context: sql.pg_uptime
            family: uptime
            units: seconds
            type: line
            algorithm: absolute
            dims:
              - name: uptime
                source: uptime_seconds

</details>

KV mode – connection states as key/value pairs

PostgreSQL example that aggregates connection states from pg_stat_activity and uses kv mode to map each state to a dimension.

The query:

sql

SELECT
  state,
  count(*) AS cnt
FROM pg_stat_activity
GROUP BY state;

Example output:

state	cnt
active	1
idle	14
idle in transaction	7
idle in transaction (aborted)	1
fastpath function call	1
disabled	1

With mode: kv, state becomes the key and cnt the value. Each distinct state value is mapped to a chart dimension via dims[*].source.

<details open><summary>Config</summary>

yaml

jobs:
  - name: pg_activity_states
    driver: pgx
    dsn: 'postgresql://netdata:[email protected]:5432/postgres'
    timeout: 5

    metrics:
      - id: activity_states
        mode: kv
        query: |
          SELECT
            state,
            count(*) AS cnt
          FROM pg_stat_activity
          GROUP BY state;
        kv_mode:
          name_col: state
          value_col: cnt
        charts:
          - title: "PostgreSQL connection states"
            context: sql.pg_activity_states
            family: connections
            units: connections
            type: stacked
            algorithm: absolute
            dims:
              - name: active
                source: active
              - name: idle
                source: idle
              - name: idle_in_transaction
                source: "idle in transaction"
              - name: idle_in_transaction_aborted
                source: "idle in transaction (aborted)"
              - name: fastpath_function_call
                source: "fastpath function call"
              - name: disabled
                source: disabled

</details>

Columns mode – map state values to a status metric

Simple PostgreSQL example that turns a boolean-like state into a 0/1 status metric using status_when.

The query:

sql

SELECT pg_is_in_recovery();

Example output:

pg_is_in_recovery
f

This configuration creates a single chart with two status dimensions:

in_recovery becomes 1 when the value is "t" and 0 otherwise.
not_in_recovery becomes 1 when the value is "f" and 0 otherwise.

<details open><summary>Config</summary>

yaml

jobs:
  - name: pg_recovery_status
    driver: pgx
    dsn: 'postgresql://netdata:[email protected]:5432/postgres'
    timeout: 5

    metrics:
      - id: recovery_status
        mode: columns
        query: |
          SELECT pg_is_in_recovery();
        charts:
          - title: "PostgreSQL recovery status"
            context: sql.pg_recovery_status
            family: state
            units: status
            type: line
            algorithm: absolute
            dims:
              - name: in_recovery
                source: pg_is_in_recovery
                status_when:
                  equals: "t"
              - name: not_in_recovery
                source: pg_is_in_recovery
                status_when:
                  equals: "f"

</details>

Function-only mode – slow query analysis

PostgreSQL example that provides an interactive slow query analysis view without collecting any time-series metrics.

This is useful for ad-hoc troubleshooting via the Netdata Live tab. The function queries pg_stat_statements to show the slowest queries sorted by total execution time.

<details open><summary>Config</summary>

yaml

jobs:
  - name: pg_slow_queries
    driver: pgx
    dsn: 'postgresql://netdata:[email protected]:5432/postgres'
    timeout: 10
    function_only: true

    functions:
      - id: slow-queries
        name: Slow Queries
        description: Top queries by total execution time from pg_stat_statements
        query: |
          SELECT
            queryid,
            LEFT(query, 100) AS query,
            calls,
            total_exec_time,
            mean_exec_time,
            rows
          FROM pg_stat_statements
          ORDER BY total_exec_time DESC
        limit: 100
        default_sort: total_exec_time
        default_sort_desc: true
        columns:
          total_exec_time:
            type: duration
            units: milliseconds
            tooltip: Total time spent executing this query
          mean_exec_time:
            type: duration
            units: milliseconds
            tooltip: Average execution time per call

</details>

Combined metrics and functions

PostgreSQL example that collects time-series metrics AND provides interactive function views in the same job.

The metrics block creates charts for connection states.
The functions block provides an interactive activity view.

<details open><summary>Config</summary>

yaml

jobs:
  - name: pg_combined
    driver: pgx
    dsn: 'postgresql://netdata:[email protected]:5432/postgres'
    timeout: 5

    # Time-series metrics
    metrics:
      - id: connections
        mode: kv
        query: |
          SELECT state, count(*) AS cnt
          FROM pg_stat_activity
          GROUP BY state
        kv_mode:
          name_col: state
          value_col: cnt
        charts:
          - title: "Connection states"
            context: sql.pg_connections
            family: connections
            units: connections
            type: stacked
            dims:
              - name: active
                source: active
              - name: idle
                source: idle

    # Interactive functions
    functions:
      - id: active-sessions
        name: Active Sessions
        description: Currently running queries
        query: |
          SELECT
            pid,
            usename,
            datname,
            state,
            query_start,
            LEFT(query, 200) AS query
          FROM pg_stat_activity
          WHERE state = 'active'
        limit: 50
        columns:
          query_start:
            type: timestamp

</details>

Alerts

There are no alerts configured by default for this integration.

Metrics

Metrics and charts are defined by your SQL queries and metric blocks at runtime. They differ by database engine, schema, and configuration, and may include, for example, connection counts, cache hit ratios, row throughput, lock statistics, or custom business KPIs. Use the Metrics tab on the job’s dashboard to see exactly what is collected for that job.

:::tip

To change what is collected, edit the metrics (and optionally queries) sections in go.d/sql.conf for the corresponding job. Each change is reflected in Netdata charts after the next data collection.

:::

Live Data

This collector supports user-defined SQL functions that expose query results as interactive table views in Netdata's Live tab. Functions are configured per job in the functions section of the job configuration. Since functions are entirely user-defined, no predefined functions are listed here.

In the Live tab, functions appear in a hierarchical menu:

Databases
└── SQL
    └── <job_name>
        ├── <function_name_1>
        └── <function_name_2>

Each job creates its own group containing all functions defined for that job.

Troubleshooting

Debug Mode

Important: Debug mode is not supported for data collection jobs created via the UI using the Dyncfg feature.

To troubleshoot issues with the sql collector, run the go.d.plugin with the debug option enabled. The output should give you clues as to why the collector isn't working.

Navigate to the plugins.d directory, usually at /usr/libexec/netdata/plugins.d/. If that's not the case on your system, open netdata.conf and look for the plugins setting under [directories].
bash
```
cd /usr/libexec/netdata/plugins.d/
```
Switch to the netdata user.
bash
```
sudo -u netdata -s
```
Run the go.d.plugin to debug the collector:
bash
```
./go.d.plugin -d -m sql
```
To debug a specific job:
bash
```
./go.d.plugin -d -m sql -j jobName
```

Getting Logs

If you're encountering problems with the sql collector, follow these steps to retrieve logs and identify potential issues:

Run the command specific to your system (systemd, non-systemd, or Docker container).
Examine the output for any warnings or error messages that might indicate issues. These messages should provide clues about the root cause of the problem.

System with systemd

Use the following command to view logs generated since the last Netdata service restart:

bash

journalctl _SYSTEMD_INVOCATION_ID="$(systemctl show --value --property=InvocationID netdata)" --namespace=netdata --grep sql

System without systemd

Locate the collector log file, typically at /var/log/netdata/collector.log, and use grep to filter for collector's name:

bash

grep sql /var/log/netdata/collector.log

Note: This method shows logs from all restarts. Focus on the latest entries for troubleshooting current issues.

Docker Container

If your Netdata runs in a Docker container named "netdata" (replace if different), use this command:

bash

docker logs netdata 2>&1 | grep sql