Grafana and InfluxDB integration with InfluxQL, Flux and SQL

Connecting self-hosted Grafana to InfluxDB means choosing the query language that matches your InfluxDB version, then securing the token and the plugin version. This page plans that work end to end.

On this page

Grafana and InfluxDB integration: what it covers and how it connects

A team with time-series data in InfluxDB that wants it charted and alerted on in a self-hosted Grafana can use the built-in InfluxDB data source, which connects to InfluxDB over its API and lets you write queries in SQL, InfluxQL or Flux. Grafana does not copy the data into its own store. Each panel and alert rule sends a query to InfluxDB and renders the result, so the InfluxDB instance, its retention settings and its network access rules remain the controlling pieces of the design. Choosing the query language is the first decision, and it shapes everything after it, including which editor you get and which InfluxDB version you can target. The supported targets are InfluxDB OSS 1.x, 2.x and 3.x, InfluxDB Enterprise 1.x and 3.x, and InfluxDB Cloud Serverless, Dedicated and TSM-based Cloud, as listed in the Grafana InfluxDB data source docs. Confirm which edition and version your organization runs before you pick a language, because the InfluxDB version determines which query languages are practical. Your InfluxDB version also governs how you create the authentication token and organization or bucket scope that Grafana will use. Ask your InfluxDB administrator for a read-only token limited to the buckets that the dashboards need, and record which edition, version and hosting model (self-managed or InfluxDB Cloud) the data source will target. This integration covers the data source configuration, query design and alerting against InfluxDB data. It also covers the plugin version you run, because earlier InfluxDB plugin versions could write API tokens to Grafana server logs in plain text at default log levels. Grafana recommends plugin version 13.1.0 or later, and if you ran an older version against a live token, plan to rotate that token. Items such as Grafana server sizing, high availability and authentication belong to other sections of this guide.

Prerequisites for a Grafana and InfluxDB connection

Before any query is written, the team needs to know which InfluxDB edition and version it runs, which Grafana build and InfluxDB plugin version will connect to it, and how traffic reaches the database. The cards below cover the items to confirm in your own environment, in the order they usually block a connection.

InfluxDB edition and version

Identify whether the data lives in InfluxDB OSS, InfluxDB Enterprise, or InfluxDB Cloud (Serverless, Dedicated, or TSM-based), and which major line it runs: 1.x, 2.x or 3.x. This decides which query languages are available. Grafana's InfluxDB data source supports SQL, InfluxQL and Flux, but the version on the server determines which of them your database accepts. Confirm the exact version with the database administrator rather than assuming it from the product name.

Grafana instance and plugin version

Check the Grafana server version and the InfluxDB data source plugin version that will run on it. Earlier plugin versions could write API tokens to Grafana server logs in plain text at default log levels. Grafana recommends plugin version 13.1.0 or later, so confirm the installed version before connecting any production token. If the team has run an older plugin, plan token rotation as part of the upgrade.

Network path from Grafana to InfluxDB

Map the route from the Grafana server to the InfluxDB endpoint, including any load balancer, proxy, firewall rule or segmented network between them. The Grafana server, not the user's browser, opens the connection to the database, so the check must run from the Grafana host or container. Confirm the port, DNS name and outbound rules with the network team, and test from the same subnet the Grafana service uses.

TLS certificates and trust

Decide whether Grafana will reach InfluxDB over HTTPS and which certificate authority signs the endpoint certificate. Internal certificate authorities often need their root certificate added to the Grafana host's trust store, and certificate names must match the hostname Grafana uses. Confirm expiry dates and the renewal owner before go-live, because an expired certificate stops every dashboard that queries the database.

Scoped read token

Create a token that can only read the buckets or databases the dashboards need. Use a dedicated token for Grafana rather than an administrator or all-access token, and record which team owns it. Confirm how your InfluxDB edition scopes tokens, since permission models differ between 1.x, 2.x and 3.x. Store the token in Grafana's secret handling, keep it out of provisioning files committed to Git, and plan rotation.

Query language and editor choice

Decide which query language each team will use before building dashboards, because the choice affects the editor available to users. SQL and InfluxQL offer a visual builder and a code editor, while Flux is code editor only. Confirm that the query language the team plans to standardize on is supported by the InfluxDB version you run, so dashboard authors do not learn a language the database cannot execute.

How to configure the InfluxDB data source in Grafana

This sequence takes a self-hosted Grafana instance from an unconfigured state to a working InfluxDB connection, with a read-scoped token, the right query language and a verified test query before any dashboard is built.

  1. Confirm the InfluxDB version and edition

    Start by identifying exactly which InfluxDB you run: OSS 1.x, 2.x or 3.x, Enterprise 1.x or 3.x, or one of the InfluxDB Cloud offerings (Serverless, Dedicated or TSM-based). The Grafana InfluxDB data source docs list these as supported, and the version determines which query languages are available in the next step. Ask your InfluxDB administrator to confirm the version from the server itself, not from memory or an old runbook. You are done when the version and edition are written into the change record and the Grafana plugin version you plan to run is 13.1.0 or later, which is the release Grafana recommends after the token logging issue.

  2. Choose the query language for the data source

    Decide between SQL, InfluxQL and Flux based on your InfluxDB version and the query skills on your team. Per the Grafana InfluxDB data source docs, SQL and InfluxQL offer both a visual builder and a code editor, while Flux is code editor only. Teams that want point-and-click panels for simple time series usually start with the visual builder, and teams already writing Flux pipelines will need the code editor from the start. Record the decision because it sets the data source configuration and the query style every dashboard author must follow. You are done when the language is agreed by the people who will write panels and alert queries.

  3. Create a read-scoped InfluxDB token

    In InfluxDB, create a token that can only read the buckets or databases Grafana needs, and nothing else. Your InfluxDB administrator creates it, because Grafana should never hold a token with write or admin rights. Name the token for the Grafana instance so it can be rotated later, and store it in your secrets manager rather than in a shared document. Confirm the scope by testing the token with a read request against the target bucket and a write attempt that should be refused. You are done when the read succeeds, the write is rejected and the token is recorded with its owner and rotation date.

  4. Add the InfluxDB data source in Grafana

    In Grafana, open Connections, add a new data source, select InfluxDB and set the URL of your InfluxDB endpoint as Grafana can reach it from the Grafana server. Then enter the settings that match your version: the organization and default bucket for Flux and InfluxDB 2.x, or the database and retention policy for InfluxQL on 1.x, or the database for SQL on 3.x. Paste the read-scoped token into the secure token field so it is stored encrypted rather than in plain configuration. Confirm the exact field names for your version in the data source docs. You are done when the form saves without errors and the settings reflect the choices from the earlier steps.

  5. Run the data source test

    Use the Save and test action on the data source page. A successful result confirms that Grafana reached the InfluxDB endpoint and that the token and organization or database settings are accepted. If the test fails, check network routes from the Grafana server, the URL scheme and port, and whether the token belongs to the organization you configured. Do not loosen the token scope to get past an error. You are done when the test reports success on the saved data source.

  6. Run a test query and compare the points

    Open Explore, choose the new InfluxDB data source and run a simple query against a measurement you know well, such as one host or device with a recent, predictable value. Use the visual builder first if you chose SQL or InfluxQL, then switch to the code editor to confirm the same query returns the same series. Compare the number of points and the latest value with the result from the InfluxDB interface or CLI for the same time range. Differences usually point to the wrong bucket, database or time zone handling. You are done when the points and latest value match the reference, and that query is saved as the baseline for dashboard work.

  7. Record the token exposure check

    If any earlier plugin version was used with this InfluxDB data source, review the Grafana server logs for API tokens, because earlier plugin versions could write tokens to logs in plain text at default log levels. Grafana recommends rotating any token that may have been exposed. Rotate it in InfluxDB, update the secure field in Grafana, repeat the data source test and record the rotation in the change log. You are done when the logs show no token values and the rotated token passes the test.

Choosing SQL, InfluxQL or Flux for each InfluxDB version

The Grafana InfluxDB data source covers three query languages, and the version of InfluxDB you run decides which of them you can use against it. InfluxDB OSS 1.x, 2.x and 3.x are supported, along with InfluxDB Enterprise 1.x and 3.x and the Cloud offerings. Language availability is not identical across these, so the first step is mapping each InfluxDB instance you plan to connect to the languages it accepts in your environment.

  • Version inventory: List every InfluxDB instance, including Enterprise and Cloud deployments, with its exact version.
  • Language mapping: Record which of SQL, InfluxQL and Flux each instance accepts for your intended queries.
  • Mixed estates: Expect different dashboards to use different languages when 1.x and 2.x or 3.x instances run side by side.
  • Upgrade effects: Treat a version upgrade as a possible change to the query language you must write.
  • Connection settings: Confirm the data source configuration matches the chosen version and language before building panels.

Confirm the supported language for each InfluxDB version and edition with the Grafana InfluxDB data source documentation and your own InfluxDB instances before you commit to a query standard.

How Grafana queries InfluxDB and where data is shaped

Every InfluxDB panel in Grafana follows the same path: the dashboard builds a query, the InfluxDB data source plugin translates it into the language selected for that data source (SQL, InfluxQL or Flux), and the plugin sends it to the InfluxDB HTTP API of your 1.x, 2.x or 3.x server. InfluxDB then does the filtering, grouping and aggregation and returns a result that Grafana renders. Grafana itself mainly controls the time range, template variables and any transformations applied after the data returns. Your team should trace this path for one representative panel before anything else, because the place where a filter or aggregation runs determines how much data crosses the network and how long the panel takes to load.

The time range is injected into the query by the plugin, so the stored data that InfluxDB scans depends on the range selected in the dashboard, the retention policy or bucket the query targets, and any GROUP BY time() interval the query builder chooses. Template variables are substituted into the query text before it is sent, which means a variable with many values can multiply the number of series scanned. Aggregations written in the query run inside InfluxDB, while transformations configured in the Grafana panel run in the browser or backend after the rows arrive. Moving an expensive reduction from a transformation into the query is often the first tuning step, but the result depends on the schema, not just the query text.

Query performance depends on InfluxDB schema and retention design: how measurements, tags and fields are modeled, how many distinct tag values exist, and how long each retention policy or bucket keeps data. A dashboard that is fast on a short range can become slow when a retention period or cardinality grows, so confirm those limits with your InfluxDB edition and the Grafana InfluxDB data source documentation before approving dashboards for wide use. Before rollout, review the queries each dashboard issues, including the interval, variables and default time range, with the InfluxDB team, and record which panels are allowed to scan long ranges.

Mapping InfluxDB buckets, databases and measurements to Grafana

This table maps InfluxDB concepts to the Grafana InfluxDB data source settings and query fields for each language. Read each row against the InfluxDB version you run, because names and required settings differ between 1.x, 2.x and 3.x. Confirm exact field names in the Grafana InfluxDB data source docs for your version before you build dashboards.

ConceptWhere it appears in GrafanaQuery language and version notesWhat to confirm
OrganizationData source setting for the organization in InfluxDB 2.x and laterUsed by Flux and API-based access in 2.x; not part of a 1.x InfluxQL queryOrganization name or ID exactly as shown in your InfluxDB instance
BucketDefault bucket setting in the data source, or the bucket chosen in a queryFlux queries name the bucket in the query; in 2.x and 3.x buckets are the storage unitBucket names and whether your version uses buckets or databases for the selected language
DatabaseDatabase setting in the data source for 1.x InfluxQL connectionsUsed by InfluxQL on 1.x; 2.x and 3.x SQL use database-style naming depending on the editionDatabase names and whether a database maps to a bucket in your release
Retention policyRetention policy field in InfluxQL queries on 1.xRelevant to 1.x InfluxQL; newer versions handle retention through bucket settingsDefault and custom retention policy names on your 1.x instance
MeasurementFROM clause in InfluxQL or table in SQL; measurement selector in the visual builderFlux addresses the measurement through a filter on the _measurement tagMeasurement names and whether your version exposes them as tables
TagGROUP BY and WHERE conditions in the visual builder or code editorTags are indexed; Flux filters on tags with a filter function, InfluxQL uses WHERETag keys and values used in your dashboard filters and variables
FieldSELECT expressions and value columns in query resultsFields carry the values; Flux uses the _field tag, InfluxQL uses SELECT, SQL uses named columnsField types, since numeric and string fields behave differently in aggregations
Time column and rangeTime range picker and macros in the query editorFlux uses a range function; InfluxQL and SQL use time filters on the time columnTime column name and macro support for the language you choose

Securing the InfluxDB token and the Grafana data source

The InfluxDB data source is only as safe as the token behind it and the people allowed to change it. The cards below cover how to scope that token, what to do if an older plugin exposed it, and which Grafana controls keep the connection from drifting.

Scope the token to read-only queries

Create a token for Grafana that can only read the buckets or databases your dashboards and alerts use. Avoid reusing an admin or write-capable token from a collector or script. In InfluxDB 2.x and 3.x, confirm the token's permissions in the InfluxDB UI or CLI before saving it in Grafana, and note which buckets it can see. Write access is rarely needed for visualization and should be treated as a separate decision.

Rotate tokens after plugin exposure

Earlier InfluxDB plugin versions could write API tokens to Grafana server logs in plain text at default log levels. Identify every Grafana server that ran an affected version, search its logs for token material if your retention allows, and rotate any token that may have been exposed. Rotate in InfluxDB first, then update the data source in Grafana, and confirm that dashboards and alerts still load. Treat old log archives and backups as copies of the secret.

Run plugin version 13.1.0 or later

Grafana recommends InfluxDB plugin version 13.1.0 or later, which stops API tokens from reaching server logs at default log levels. Check the installed version on the plugin page or in the plugin directory on each node, and include the plugin in your upgrade checks because it can lag behind the Grafana core release. Pin the version in your provisioning or container image so a rebuild does not reintroduce an older release.

Limit who can edit data sources

Anyone who can edit an InfluxDB data source can view or replace its stored credentials and point it at a different server. In the open-source edition, restrict data source administration to a small group of Grafana admins and keep editor roles for dashboard work. Confirm which roles your edition allows to manage data sources, and review that list whenever you add teams. Team sync and SAML group mapping depend on edition, so confirm what you can enforce before you rely on it.

Provision the data source from code

Defining the InfluxDB data source in provisioning files keeps its URL, database name and settings in version control and makes changes reviewable. Store the token in an environment variable or secret store rather than in the file itself, and confirm that your Grafana version reads the secret reference you use. Changes made through the UI can then be detected and reverted at the next restart, which lowers the chance of an untracked token being left in place.

Apply general Grafana hardening

Baseline hardening also protects the InfluxDB connection. Enable secure and SameSite cookies, a Content Security Policy, hide the Grafana version from unauthenticated users, require authentication for the metrics endpoint and set the domain verification against DNS rebinding. Review these settings after each upgrade, because defaults and option names can change between releases. Check the current hardening guide before you apply them to a production instance.

How to test the InfluxDB connection before dashboards go live

Test the connection in a fixed order before any team sees a dashboard, because each step rules out a different class of fault. Start with the data source health check on the InfluxDB data source configuration page, which confirms that Grafana can reach the InfluxDB endpoint and authenticate with the token or credentials you configured. Then run one sample query in each query language you have chosen. For SQL and InfluxQL, use the visual builder to build a simple query, switch to the code editor, and confirm both return the same series. For Flux, which supports the code editor only, run a short query against a known bucket and measurement. A health check that passes does not prove that every language can read the data you need, so test each one separately.

Next, check time handling and variables. Set the dashboard time range to a window where you know the expected values, then compare the plotted points with the same window queried directly in InfluxDB. Confirm the timezone that Grafana uses for the dashboard and for the query output, since a mismatch shifts daily totals and alert windows. Then test each dashboard variable with its default value and with a multi-value selection, and confirm that the generated queries change as expected. Record the InfluxDB version, the Grafana version, the InfluxDB plugin version and the query language for each check. Review the Grafana server logs at the log level you run in production, and search for any API token string. Any match means the plugin version is out of date, so update it and rotate the exposed token before go-live.

Keep the results in a dated test record and repeat the full set of checks after every Grafana upgrade and every InfluxDB upgrade, since either can change query behavior, plugin compatibility or log output. Confirm with your InfluxDB edition and Grafana release notes which checks need to change for your versions.

Common Grafana and InfluxDB connection failures and fixes

This table pairs each common failure with its likely cause and a general fix, so you can match a symptom in Grafana to the layer that produced it. Start with the query language and InfluxDB version, since most empty panels and errors trace back to that mismatch. Check the token and TLS rows next, and treat any token that may have appeared in logs as exposed.

SymptomLikely causeGeneral fix
Query errors or no data after connectingThe selected query language does not match the InfluxDB version, for example InfluxQL used against a 3.x or Flux-only setup.Confirm the InfluxDB version first, then choose SQL, InfluxQL or Flux to match it in the data source settings.
Flux queries fail to build in the visual editorFlux is supported in the code editor only, so the builder is not offered for that language.Write Flux in the code editor and keep the visual builder for SQL or InfluxQL queries.
Unauthorized or forbidden errorsThe API token lacks read permission on the target bucket or database, or it was revoked or rotated.Create a read-scoped token for the required bucket or database, update the data source, and test the connection again.
Connection refused or timeoutThe Grafana server cannot reach the InfluxDB URL or port because of network routing, DNS or a firewall rule.Test connectivity from the Grafana host itself, not from a workstation, and confirm the URL, port and firewall path.
TLS handshake or certificate errorsInfluxDB uses a certificate that Grafana does not trust, such as an internal certificate authority or a hostname mismatch.Install the issuing certificate authority on the Grafana host or configure the data source with the correct CA, and confirm the hostname matches the certificate.
Panels empty for a known time rangeThe dashboard time range or the data source time zone does not cover the period where points were written.Widen the dashboard time range, check the time zone setting, and run the same query in the InfluxDB interface to confirm points exist.
Panels empty for a measurement or fieldThe measurement, bucket, database or field name differs in case or spelling from what was written, or the retention policy hides older data.List measurements and fields from InfluxDB, copy the exact names into the query, and confirm the retention period covers the window.
API tokens visible in Grafana server logsPlugin versions before 13.1.0 could write tokens to server logs in plain text at default log levels.Upgrade the InfluxDB plugin to 13.1.0 or later, search existing logs for the token, and rotate any token that may have been exposed.

Questions buyers ask about Grafana and InfluxDB integration

Can our team connect Grafana to InfluxDB without outside help?

Yes, many teams with an operations or platform engineer who knows InfluxDB and Grafana can do the basic connection themselves. The Grafana InfluxDB data source supports SQL, InfluxQL and Flux, and the visual builder covers simple queries. The harder part is usually the surrounding work: deciding which InfluxDB version you run, setting up read-only tokens, reviewing who can see credentials in Grafana, and rebuilding dashboards that depend on existing queries. If nobody on your team has time for that review, or if the data is regulated, a fixed-scope engagement with written deliverables can cover the gap. Ask any partner to show how they will handle these points before work starts.

What drives the effort of an InfluxDB integration in Grafana?

Four factors matter most. The first is your InfluxDB version (1.x, 2.x or 3.x, including Enterprise and Cloud variants), because each uses different query languages and authentication. The second is the number of dashboards and panels you need to rebuild or port. The third is query complexity, such as Flux transformations, joins across measurements or alert queries that must run reliably. The fourth is the security review, which covers token scope, token storage, network paths and who may edit data sources. Each factor can raise or lower the work considerably, so a quote should state which of them it assumes.

How long does a Grafana and InfluxDB integration take?

The duration depends on the same drivers as the cost: InfluxDB version, dashboard count, query complexity and the review your organization requires. A small set of dashboards on one InfluxDB instance with straightforward queries is far less work than a migrated estate with many alerts and several teams signing off. Rather than relying on a general figure, ask for a timeline tied to a written scope, with milestones for connection setup, query validation, dashboard rebuilding, alert testing and handover. Any timeline that does not name these phases is hard to verify.

What do we need to provide for the integration?

Plan to provide access and approvals before the build starts. You will need administrative access to the InfluxDB instance, or a named owner who can create tokens with the right read permissions. Each token needs an owner who is responsible for rotating it. You also need Grafana administrator access, a test environment where practical, and network approvals that allow Grafana servers to reach the InfluxDB endpoints on the required ports. Your security team should confirm where tokens will be stored and who can view data source settings. Missing approvals are one of the most common causes of delay, so list them in the scope document.

Should we choose SQL, InfluxQL or Flux for InfluxDB in Grafana?

Choose based on the InfluxDB version you run and the skills your team already has. The Grafana InfluxDB data source supports SQL, InfluxQL and Flux. SQL and InfluxQL both offer a visual builder and a code editor, while Flux is available only in the code editor. Teams with existing InfluxQL dashboards on InfluxDB 1.x usually keep InfluxQL, while teams writing new queries against newer InfluxDB versions often prefer SQL for familiarity. Flux suits teams that already write Flux and need its transformation features. Confirm the query language your specific InfluxDB version and edition supports before you commit to a design.

Why does the InfluxDB plugin version matter for security?

Earlier versions of the InfluxDB plugin could write API tokens to Grafana server logs in plain text at default log levels. Grafana recommends plugin version 13.1.0 or later. If you ran an earlier version with InfluxDB tokens configured, treat those tokens as potentially exposed, review who can read the server logs, and rotate the affected tokens. Your engagement scope should include a check of installed plugin versions, a token inventory and a log review, so that the fix is verified rather than assumed.

What should a quote for this integration include?

A useful quote lists the InfluxDB versions and editions in scope, the number of data sources, dashboards and alert rules, the query languages to be used, and the sources of data for each dashboard. It should name the security work, including token scope, storage, rotation, plugin version checks and review of Grafana access. It should state what is one-time work, such as setup and dashboard rebuilding, and what recurs, such as token rotation, plugin updates and support. It should also list your responsibilities, the acceptance tests and the deliverables you will receive, including configuration and documentation. Request that the quote be fixed in writing before work begins.

How DeployOpen scopes and delivers the Grafana and InfluxDB work

DeployOpen starts with a written scope, and that document is what the rest of the engagement is measured against. The scope names the InfluxDB edition and version in use (InfluxDB OSS 1.x, 2.x or 3.x, InfluxDB Enterprise, or InfluxDB Cloud Serverless, Dedicated or TSM-based Cloud), the query language for each data source (SQL, InfluxQL or Flux), and which panels and alerts must be built with the visual builder and which will be hand-written in the code editor. It also records the plugin version to be installed, which must be 13.1.0 or later, and the token handling approach: which tokens exist, who owns them, where they are stored, and whether any earlier plugin version has been running in your environment. Ask your partner to show these decisions line by line before any build starts.

Delivery happens inside your own infrastructure, on your Grafana servers, your InfluxDB instances and your network. Tests are part of the scope, not an add-on: they cover query results against known data, dashboard variables under load, a check that API tokens do not appear in Grafana server logs at default log levels, and a rotation procedure for any token that may have been exposed. Pricing follows the written scope. DeployOpen does not publish a price list, so a quote is produced from the scope document, and the quote should separate one-time build work from any recurring work. Once the integration is live, an optional retainer can cover plugin and Grafana upgrades, since the Grafana upgrade guidance describes minor releases every other month and patch releases at least monthly. Confirm with us how often each upgrade is tested against your dashboards before you sign.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.