Managing Data Sources

1. Adding Data Source via UI

Example: Add Prometheus Data Source

1. Navigate to Configuration > Data Sources
2. Click "Add data source"
3. Select "Prometheus"
4. Enter URL: http://localhost:9090
5. Click "Save & Test"

Field	Description	Example Value
Name	Unique name for the data source	`Prometheus-Prod`
Type	Selected data source type	`Prometheus`
URL	Endpoint of the data source	`http://localhost:9090`
Access Mode	How Grafana accesses the data source	`Server`
Timeout	Request timeout in seconds	`30`

Note: Ensure the data source URL is accessible from the Grafana server.

Warning: Using Direct access mode in browser environments may require CORS configuration.

2. Adding Data Source via Provisioning

Example: Grafana Data Source Provisioning

datasources:
  - name: "Prometheus"
    type: prometheus
    uid: "prometheus-ds"
    access: proxy
    url: "http://localhost:9090"
    isDefault: true
    jsonData:
      timeInterval: "15s"
    secureJsonData:
      basicAuthPassword: "secret"

Field	Description	Values	Notes
name	Data source name	`string`	Must be unique within Grafana
type	Data source type	`string`	Valid options: `prometheus`, `loki`, `influxdb`, etc.
uid	Unique identifier	`string`	Used to reference this data source in dashboards
access	Access mode	`proxy`, `direct`	`proxy` is recommended for security
url	Endpoint URL	`string`	Must be accessible from Grafana server
isDefault	Set as default data source	`true`, `false`	Only one data source can be default
jsonData	Additional configuration	`object`	Contains type-specific settings like `timeInterval`
secureJsonData	Secure configuration	`object`	For sensitive values like passwords or tokens

Note: Provisioned data sources are managed via YAML files in /etc/grafana/provisioning/datasources/ directory.

Warning: Ensure that the url is accessible from the Grafana server and that any authentication credentials are properly secured.

3. Configuring Prometheus Data Source

Field	Description	Example Value
url	URL of the Prometheus server	`http://localhost:9090`
access	Access mode for the data source	`proxy` or `direct`
timeout	Timeout in seconds for queries	`30`
basicAuth	Enable basic authentication	`true`
basicAuthUser	Username for basic auth	`admin`
httpHeaderName1	Name of custom HTTP header	`X-API-Key`
httpHeaderValue1	Value of custom HTTP header	`secret-key`

Example: Adding Prometheus Data Source via API

{
  "name": "Prometheus-Prod",
  "type": "prometheus",
  "url": "http://prometheus-server:9090",
  "access": "proxy",
  "jsonData": {
    "httpMethod": "POST"
  },
  "secureJsonData": {
    "basicAuthPassword": "secret"
  }
}

Note: Ensure the Prometheus server is accessible from Grafana's network and that appropriate permissions are set for querying metrics.

4. Configuring InfluxDB Data Source

Field	Description	Example Value
Name	Unique name for the data source	`InfluxDB-Prod`
Type	Must be `InfluxDB`	`InfluxDB`
URL	Endpoint of the InfluxDB server	`http://localhost:8086`
Access Mode	How Grafana accesses the data source	`proxy` or `direct`
Database	InfluxDB database name to query	`telegraf`
Username	Authentication username (optional)	`grafana_user`
Password	Authentication password (optional)	`secret123`
HTTP Method	HTTP method used for queries	`POST`
TLS Skip Verify	Disable TLS certificate verification (if needed)	`false`

Example: InfluxDB Data Source Configuration

{
  "name": "InfluxDB-Prod",
  "type": "influxdb",
  "url": "http://localhost:8086",
  "database": "telegraf",
  "user": "grafana_user",
  "password": "secret123",
  "access": "proxy"
}

Note: Ensure the InfluxDB server allows connections from Grafana's IP address. If using direct access mode, the InfluxDB server must be accessible from the Grafana instance.

Warning: Avoid storing passwords in plain text. Use secure methods like environment variables or Grafana's secure variable feature.

5. Configuring MySQL Data Source

Field	Description	Example Value
Name	Unique name for the data source	`MySQL-Prod`
Type	Must be `MySQL`	`MySQL`
Host	MySQL server address and port (e.g., `localhost:3306`)	`db.example.com:3306`
Database	Name of the database to connect to	`analytics_db`
User	Username for authentication	`grafana_user`
Password	Password for the user	`secure_password`
TLS Skip Verify	Set to `true` to skip TLS certificate verification (not recommended in production)	`false`

Example: MySQL Data Source Configuration

{
  "name": "MySQL-Prod",
  "type": "mysql",
  "url": "db.example.com:3306",
  "database": "analytics_db",
  "user": "grafana_user",
  "password": "secure_password",
  "jsonData": {
    "tlsSkipVerify": false
  }
}

Note: Ensure the MySQL user has appropriate permissions to read the required tables and views.

Warning: Avoid storing passwords in plain text. Use secure credential management or environment variables.

6. Configuring PostgreSQL Data Source

Field	Description	Example Value
Name	Unique name for the data source	`PostgreSQL-Prod`
Type	Selected data source type	`PostgreSQL`
Host	Database host address and port	`db.example.com:5432`
Database	Name of the PostgreSQL database to connect to	`grafana_db`
User	Database user with read access	`grafana_user`
Password	Password for the database user	`secure_password`
SSL Mode	Connection security mode (disable, require, verify-full)	`require`

Example: PostgreSQL Data Source Configuration

{
  "name": "PostgreSQL-Prod",
  "type": "postgres",
  "url": "db.example.com:5432",
  "database": "grafana_db",
  "user": "grafana_user",
  "password": "secure_password",
  "sslmode": "require"
}

Note: Ensure the Grafana server can reach the PostgreSQL host on the specified port and that the database user has appropriate permissions to read data.

7. Testing Data Source Connection (Save & Test)

Field	Description	Example
Name	The name of the data source	`My Prometheus`
Type	The type of data source (e.g., Prometheus, MySQL)	`Prometheus`
URL	The URL of the data source endpoint	`http://localhost:9090`
Access Mode	How Grafana accesses the data source (Direct or Proxy)	`Proxy`
Database	Database name (for SQL-based data sources)	`mydb`

Example: Save & Test Connection

curl -X POST "http://localhost:3000/api/datasources" \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d &#x27;{
    "name": "My Prometheus",
    "type": "prometheus",
    "url": "http://localhost:9090",
    "access": "proxy"
  }&#x27;

Note: After saving, click the Save & Test button in the Grafana UI to verify connectivity.

Warning: Ensure the data source URL is accessible from the Grafana server.

8. Setting Default Data Source

Property	Value	Description
defaultDataSourceId	`1`	ID of the data source to set as default

Example: Setting Default Data Source via API

curl -X PUT "http://localhost:3000/api/org/preferences" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"defaultDataSourceId": 1}'

Note: The default data source is applied per organization and affects all dashboards within that org.

9. Using Data Source Variables ($datasource)

Variable	Description	Usage
$datasource	Reference to the current data source	`SELECT * FROM "$datasource".table_name`

Example: Using $datasource in a Query

SELECT * FROM "$datasource".metrics WHERE time > now() - 1h

Note: The $datasource variable is particularly useful in templates and dashboards where the same query needs to be reused across different data sources.

10. Configuring Data Source Proxy

Property	Value	Description
datasource.proxy	`true`	Enables proxying requests to the data source
datasource.proxyTimeout	`30s`	Timeout for proxy requests in seconds
datasource.proxyHeaders	`{}`	Custom headers to send with proxy requests

Example: Proxy Configuration

{
  "datasource": {
    "proxy": true,
    "proxyTimeout": 30,
    "proxyHeaders": {
      "Authorization": "Bearer <token>"
    }
  }
}

Note: Proxying is required when data sources are not accessible from the Grafana server directly.

11. Managing Data Source Permissions

Permission	Resource	Description	Scope
datasource:read	`datasource:id`	Read access to a data source	Specific data source
datasource:write	`datasource:id`	Write access to a data source (edit, delete)	Specific data source
datasource:query	`datasource:id`	Query access to a data source (run queries)	Specific data source

Example: Assigning Permissions via API

curl -X POST "http://grafana.example.com/api/access-control/datasource/1/permissions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "datasource:read",
    "user": "user@example.com"
  }'

Note: Permissions can also be managed via the Grafana UI under Configuration > Users > Permissions.