public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DOCS: Updates to help with UI improvement work (#109359)

Browse Source 
* updates to help with UI improvements

* ran prettier
This commit is contained in:
Larissa Wandzura
2025-08-07 15:38:00 -05:00
committed by GitHub
parent 0069d112fc
commit e6c24e0709
2 changed files with 57 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/datasources/postgres/configure/_index.md
+56 -32
View File
@@ -9,7 +9,7 @@ labels:
- cloud
- enterprise
- oss
menuTitle: Configure the PostgreSQL data source
menuTitle: Configure
title: Configure the PostgreSQL data source
weight: 10
refs:
@@ -51,10 +51,14 @@ This document provides instructions for configuring the PostgreSQL data source a
## Before you begin
You must have the `Organization administrator` role to configure the Postgres data source.
Organization administrators can also [configure the data source via YAML](#provision-the-data-source) with the Grafana provisioning system.
- You must have the `Organization administrator` role to configure the Postgres data source.
Organization administrators can also [configure the data source via YAML](#provision-the-data-source) with the Grafana provisioning system.
Grafana comes with a built-in PostgreSQL data source plugin, eliminating the need to install a plugin.
- Grafana comes with a built-in PostgreSQL data source plugin, eliminating the need to install a plugin.
- Familiarize yourself with your PostgreSQL security configuration and gather any necessary security certificates, client certificates, and client keys.
- Know which version of PostgreSQL you are running. You will be prompted for this information during the configuration process.
{{< admonition type="note" >}}
When adding a data source, the database user you specify should have only `SELECT` permissions on the relevant database and tables. Grafana does not validate the safety of queries, which means they can include potentially harmful SQL statements, such as `USE otherdb;` or `DROP TABLE user;`, that could be executed. To mitigate this risk, Grafana strongly recommends creating a dedicated PostgreSQL user with restricted permissions.
@@ -84,56 +88,76 @@ You are taken to the **Settings** tab where you will configure the data source.
Following is a list of PostgreSQL configuration options:
- **Name** - Sets the name you use to refer to the data source in panels and queries. Examples: `PostgreSQL-DB-1`.
- **Default** - Toggle to set this specific PostgreSQL data source as the default pre-selected data source in panels and visualizations.
| Setting | Description |
| ------- | ------------------------------------------------------------------------------------------------------------------------ |
| Name | Sets the name you use to refer to the data source in panels and queries. Examples: `PostgreSQL-DB-1`. |
| Default | Toggle to set this specific PostgreSQL data source as the default pre-selected data source in panels and visualizations. |
**Connection section:**
- **Host URL** - The IP address/hostname and optional port of your PostgreSQL instance.
- **Database name** - The name of your PostgreSQL database.
| Setting | Description |
| ------------- | ---------------------------------------------------------------------- |
| Host URL | The IP address/hostname and optional port of your PostgreSQL instance. |
| Database name | The name of your PostgreSQL database. |
**Authentication section:**
- **Username** - Enter the username used to connect to your PostgreSQL database.
- **Password** - Enter the password used to connect to the PostgreSQL database.
- **TLS/SSL Mode** - Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server. When **TLS/SSL Mode** is disabled, **TLS/SSL Method** and **TLS/SSL Auth Details** aren't visible options.
- **TLS/SSL Method** - Determines how TLS/SSL certificates are configured.
- **File system path** - This option allows you to configure certificates by specifying paths to existing certificates on the local file system where Grafana is running. Ensure this file is readable by the user executing the Grafana process.
- **Certificate content** - This option allows you to configure certificate by specifying their content. The content is stored and encrypted in the Grafana database. When connecting to the database, the certificates are saved as files, on the local filesystem, in the Grafana data path.
| Setting | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Username | Enter the username used to connect to your PostgreSQL database. |
| Password | Enter the password used to connect to the PostgreSQL database. |
| TLS/SSL Mode | Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server. When TLS/SSL Mode is disabled, TLS/SSL Method and TLS/SSL Auth Details aren’t visible options. |
| TLS/SSL Method | Determines how TLS/SSL certificates are configured. |
| - File system path | This option allows you to configure certificates by specifying paths to existing certificates on the local file system where Grafana is running. Ensure this file is readable by the user executing the Grafana process. |
| - Certificate content | This option allows you to configure certificate by specifying their content. The content is stored and encrypted in the Grafana database. When connecting to the database, the certificates are saved as files, on the local filesystem, in the Grafana data path. |
**TLS/SSL Auth Details**
**TLS/SSL Auth Details:**
If you select the TLS/SSL Mode options **require**, **verify-ca** or **verify-full** and **file system path** the following are required:
- **TLS/SSL Root Certificate** - Specify the path to the root certificate file.
- **TLS/SSL Client Certificate** - Specify the path to the client certificate and ensure the file is accessible to the user running the Grafana process.
- **TLS/SSL Client Key** - Specify the path to the client key file and ensure the file is accessible to the user running the Grafana process.
| Setting | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| TLS/SSL Root Certificate | Specify the path to the root certificate file. |
| TLS/SSL Client Certificate | Specify the path to the client certificate and ensure the file is accessible to the user running the Grafana process. |
| TLS/SSL Client Key | Specify the path to the client key file and ensure the file is accessible to the user running the Grafana process. |
If you select the TLS/SSL Mode option **require** and TLS/SSL Method certificate content the following are required:
- **TLS/SSL Client Certificate** - Provide the client certificate.
- **TLS/SSL Client Key** - Provide the client key.
| Setting | Description |
| -------------------------- | ------------------------------- |
| TLS/SSL Client Certificate | Provide the client certificate. |
| TLS/SSL Client Key | Provide the client key. |
If you select the TLS/SSL Mode options **verify-ca** or **verify-full** with the TLS/SSL Method certificate content the following are required:
- **TLS/SSL Client Certificate** - Provide the client certificate.
- **TLS/SSL Root Certificate** - Provide the root certificate.
- **TLS/SSL Client Key** - Provide the client key.
| Setting | Description |
| -------------------------- | ------------------------------- |
| TLS/SSL Client Certificate | Provide the client certificate. |
| TLS/SSL Root Certificate | Provide the root certificate. |
| TLS/SSL Client Key | Provide the client key. |
**PostgreSQL Options:**
- **Version** - Determines which functions are available in the query builder. The default is the current version.
- **Min time interval** - Defines a lower limit for the auto group by by time interval. Grafana recommends aligning this setting with the data write frequency. For example, set it to `1m` if your data is written every minute. Refer to [Min time interval](#min-time-interval) for format examples.
- **TimescaleDB** - A time-series database built as a PostgreSQL extension. When enabled, Grafana uses `time_bucket` in the `$__timeGroup` macro to display TimescaleDB specific aggregate functions in the query builder. For more information, refer to [TimescaleDB documentation](https://docs.timescale.com/timescaledb/latest/tutorials/grafana/grafana-timescalecloud/#connect-timescaledb-and-grafana).
| Setting | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Version | Determines which functions are available in the query builder. The default is the current version. |
| Min time interval | Defines a lower limit for the auto group by time interval. Grafana recommends aligning this setting with the data write frequency. For example, set it to `1m` if your data is written every minute. Refer to [Min time interval](#min-time-interval) for format examples. |
| TimescaleDB | A time-series database built as a PostgreSQL extension. When enabled, Grafana uses `time_bucket` in the `$__timeGroup` macro to display TimescaleDB-specific aggregate functions in the query builder. For more information, refer to [TimescaleDB documentation](https://docs.timescale.com/timescaledb/latest/tutorials/grafana/grafana-timescalecloud/#connect-timescaledb-and-grafana). |
**Connection limits:**
- **Max open** - The maximum number of open connections to the database. The default `100`.
- **Auto max idle** - Toggle to set the maximum number of idle connections to the number of maximum open connections. This setting is toggled on by default.
- **Max idle** - The maximum number of connections in the idle connection pool. The default `100`.
- **Max lifetime** - The maximum amount of time in seconds a connection may be reused. The default is `14400`, or 4 hours.
| Setting | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Max open | The maximum number of open connections to the database. The default is `100`. |
| Auto max idle | Toggle to set the maximum number of idle connections to the number of maximum open connections. This setting is toggled on by default. |
| Max idle | The maximum number of connections in the idle connection pool. The default is `100`. |
| Max lifetime | The maximum amount of time in seconds a connection may be reused. The default is `14400`, or 4 hours. |
**Private data source connect** - _Only for Grafana Cloud users._ Private data source connect, or PDC, allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. Click the drop-down to locate the URL for PDC. For more information regarding Grafana PDC refer to [Private data source connect (PDC)](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/).
**Private data source connect:**
| Setting | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Private data source connect | _Only for Grafana Cloud users._ Private data source connect, or PDC, allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. Click the drop-down to locate the URL for PDC. For more information, refer to [Private data source connect (PDC)](https://grafana.com/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/). |
Click **Manage private data source connect** to be taken to your PDC connection page, where you’ll find your PDC configuration details.
@@ -191,4 +215,4 @@ datasources:
If you encounter metric request errors or other issues:
- Ensure that the parameters in your data source YAML file precisely match the example provided, including parameter names and the correct use of quotation marks.
- Verify that the database name _isn't_ included in the URL.
- Verify that the database name **IS NOT** included in the URL.
docs/sources/datasources/postgres/query-editor/_index.md
+1 -1
View File
@@ -9,7 +9,7 @@ labels:
- cloud
- enterprise
- oss
menuTitle: PostgreSQL query editor
menuTitle: Query editor
title: PostgreSQL query editor
weight: 20
refs: