How-to
How to publish InfluxDB v2 bucket data to MQTT
Short answer
Run a scheduled Flux task on the InfluxDB v2 server that queries the bucket and passes each row to mqtt.to() from the experimental mqtt package. Test TCP 1883 or 8883 from the server host first, keep credentials in secrets, and set range(start: -task.every) so every: 1m publishes each minute exactly once.
On this page
- How do I publish an InfluxDB v2 bucket to MQTT?
- Which component should open the connection to the broker?
- Can the InfluxDB server reach the broker port?
- What must the Flux query return before it is published?
- How do I call mqtt.to() without credentials in the script?
- How do I schedule the task without duplicating or losing points?
- How do I prove delivery from bucket to subscriber?
- Questions asked
Publish the bucket outbound with a scheduled Flux task that ends in mqtt.to(): the InfluxDB v2 server itself queries a time window and opens its own client session to the broker. The pipelines usually documented on this site run the other way — Telegraf landing broker messages in a bucket, as in how to store MQTT messages in InfluxDB with Telegraf — so this walkthrough builds the outbound hop in the order you meet it: reachability from the server host, a bounded query, credentials in secrets, a range that matches the interval, and a subscriber test that proves each point arrives once.
How do I publish an InfluxDB v2 bucket to MQTT? #
Run a scheduled Flux task on the InfluxDB v2 server that queries the bucket and passes the rows to mqtt.to() from the experimental mqtt package; with every: 1m and range(start: -task.every), each minute of data reaches the broker exactly once.
First confirm the instance: run influx version or read the version in the UI footer, because the experimental mqtt package belongs to the v2 Flux stack. The path then has three parts — the task schedule, the Flux query that shapes the rows, and the mqtt.to() call that publishes them — and you build it in this order:
- Verify the server host can reach the broker port.
- Shape the query in Data Explorer and confirm its row count.
- Store the broker credentials as InfluxDB secrets.
- Save the task with the range equal to the interval.
- Prove delivery with a subscriber before trusting the schedule.
Which component should open the connection to the broker? #
The InfluxDB v2 server itself: the Flux task executes there, so the server host is the MQTT client; keep that design for periodic publishes and reserve write-path forwarding for points that must leave as they arrive.
| Design | MQTT client runs on | Trigger | Use it when |
|---|---|---|---|
Flux task ending in mqtt.to() |
the InfluxDB v2 server | the task schedule (polling) | the data already sits in a bucket and a periodic publish is enough |
| Script using an MQTT client library | any host that reaches the broker | its own scheduler | the payload format or authentication Flux cannot express |
| Forwarder in the write path | the device or gateway that writes | every write | each point must reach the broker as it arrives |
Telegraf's documented role on this path is the inbound consumer; whether Telegraf can read a local InfluxDB bucket and feed a cloud target is the question to check before using it in the other direction. The broker on the far side routes messages but keeps no queryable history — whether an MQTT broker stores historic data you can query settles what a broker does hold — so the bucket stays the system of record. Because the mqtt package is experimental, its function signatures can change between releases: check the parameter list against the documentation for the version you run, and build on mqtt.to(), which outputs a stream of tables to a broker over MQTT — the package also lists mqtt.publish(), which the documentation says will not successfully publish to a broker.
Can the InfluxDB server reach the broker port? #
Test TCP 1883 (plain) or 8883 (TLS) from the InfluxDB host itself, not from your workstation; the task runs on the server, so a route that works from your laptop proves nothing about the run.
1883 and 8883 are the IANA-registered default ports for MQTT and MQTT over TLS; a broker can listen elsewhere, so confirm the configured listener before testing. Work the hops in order:
| Hop | Verify | Typical failure |
|---|---|---|
| Route | server and broker share a route with a return path | broker subnet has no route back |
| Name | the broker name in the task resolves on the server | the name resolves only on the engineering VLAN |
| Port | listener open on 1883 plain or 8883 TLS | listener bound to localhost, or a firewall drop |
| Session | credentials and topic ACL accept this client | CONNECT refused, or publish silently denied by the ACL |
From the InfluxDB host, test the port: on Windows, Test-NetConnection -ComputerName 192.0.2.10 -Port 1883; on Linux, nc -zv 192.0.2.10 1883 (that address is the example broker used throughout). Plain MQTT on 1883 sends the username, password and payload in clear text, so on a shared plant network use the TLS listener — 8883 with the tls:// scheme in the broker URL — and restrict this client to its topic in the broker ACL. Proceed only when the TCP test succeeds from the server host; everything you fix after that is Flux, not networking.
What must the Flux query return before it is published? #
A bounded stream of rows: mqtt.to() publishes one message per row, with a _time column, a _value column and the tag columns you want carried; at one point every 10 s, a 60 s window is 6 rows and 6 messages.
Open Data Explorer or the script editor and run the query without the mqtt.to() call. Constrain it with range(), filter() on measurement and field, and — when the subscriber cannot take the raw rate — aggregateWindow(). Confirm the output carries the columns you will map: the time column (_time by default), the value column (_value by default) and the tag columns.
Calculated example, one temperature tag logged every 10 s: a 60 s window holds 60 ÷ 10 = 6 rows, so a 1-minute task publishes 6 messages per run and 6 × 60 = 360 per hour. Wrapping the same query in aggregateWindow(every: 1m, fn: mean) collapses each window to 1 row: 1 message per minute, 60 per hour, a sixfold cut. Decide raw-versus-aggregate on the subscriber's message budget, not on the bucket's convenience.
How do I call mqtt.to() without credentials in the script? #
Store the broker username and password as InfluxDB secrets, read them with secrets.get() inside the task, and pass broker, topic, clientid, qos and timeout as parameters; nothing sensitive then appears in the task source.
| Parameter | What it sets |
|---|---|
broker |
scheme, host and port of the listener: tcp:// with 1883, tls:// with 8883 |
topic |
destination topic; the broker ACL must allow this client to publish there |
clientid |
the MQTT client identifier; unique per connected client |
qos, retain |
delivery guarantee and last-value retention on the broker |
timeout |
connection timeout; set it explicitly rather than relying on a default |
timeColumn, tagColumns, valueColumns |
which columns become the payload; _time and _value are the defaults |
Create the secret keys first with influx secret update, one key per value, then save the task:
import "experimental/mqtt"
option task = {name: "publish-temperature", every: 1m, offset: 30s}
from(bucket: "plant_data")
|> range(start: -task.every)
|> filter(fn: (r) => r._measurement == "temperature" and r._field == "value")
|> mqtt.to(
broker: "tcp://192.0.2.10:1883",
topic: "plant/temperature",
clientid: "influxdb-task-temperature",
username: secrets.get("mqtt-user"),
password: secrets.get("mqtt-pass"),
qos: 1,
timeout: 30s,
)
The bucket, measurement, field, broker address, topic, identifier and secret names above are example values for the 10 s temperature tag; the functions, task options and parameter names are the documented API. Before saving it as a task:
- Create the two secrets on the server.
- Paste the script into the editor and run it once manually.
- Keep a subscriber attached during that run; an error at this stage points at the broker URL, the credentials or the timeout — not at the schedule.
How do I schedule the task without duplicating or losing points? #
Set the range to the interval: range(start: -task.every) with every: 1m publishes each 60 s window exactly once; a range of -5m on a 1-minute task republishes every point five times.
The broker performs no deduplication, so the window discipline is yours. Wrong-size arithmetic on the same 10 s tag: a -5m range reads 5 × 6 = 30 rows per run and 30 × 60 = 1800 messages per hour — five copies of every point against the 360 the interval deserves. Create the task under Tasks in the UI and confirm every equals the range you queried.
Late writes are the other failure: a write that lands after its window's run has executed never publishes from the schedule. Add a task offset that covers your measured write latency — offset: 30s delays each run by 30 s while the window stays anchored to the schedule, so writes up to 30 s late are inside the window when it is read. Never chase late data by widening the range; that only buys duplicates. Fill gaps with a manual run instead.
How do I prove delivery from bucket to subscriber? #
Attach a subscriber to the topic before the first run, run the task manually, then let the schedule fire and count messages per interval against the query row count; the counts must match exactly.
- Subscribe first:
mosquitto_sub -h 192.0.2.10 -t "plant/temperature" -v, adding-uand-Pwhen the broker authenticates; a wildcard such asplant/#catches a topic typo. - Run the task manually from Tasks and open its run history.
- Treat a successful run with no subscriber output as an ACL denial or a topic mismatch, not as success.
- Read the payload and confirm its time, value and tags match the Data Explorer rows for the same window.
- Let the schedule fire for several intervals; messages per interval must equal the row count — 6 per minute in the example — with no repeated timestamps from earlier intervals.
- Stop the broker briefly, wait for one run, and confirm the run history reports a failure; restart and confirm the next run succeeds.
When the counts match and the failure test behaves, the outbound path is proven end to end: the bucket is the record, the task is the publisher, and the interval you chose is the latency you live with.
Questions asked
What happens if the broker is unreachable when the task runs?
The run is recorded as failed in the task run history, and that window is not republished automatically. The points are untouched in the bucket, so nothing is lost: re-run the task manually with a range widened to cover the gap, then return the task to its normal range.
How do I backfill three hours of missed publishes?
Run the same query manually with the range widened to the gap, for example range(start: -3h) with the mqtt.to() call attached. At the example rate of six points per minute, one run delivers 6 x 60 x 3 = 1080 messages. Size the range to the outage exactly so no point is sent twice.
Why does another MQTT client drop off when my task publishes?
The MQTT specification requires a broker to close the existing connection when a second client presents the same client identifier. If the task and another publisher share one identifier, each connect disconnects the other and the two loop. Give the task an identifier no other client uses.
How soon after a write does a point reach the broker?
A task is a poller, so the floor is one interval and the worst case is one interval plus the offset: every: 1m with offset: 30s delivers a write up to 90 seconds after it lands in the bucket. Writes that must leave immediately belong in the write path, not in a task.
When should the task publish with retain set?
Set retain when a new subscriber must see the last value the moment it connects, such as a dashboard that starts between runs. The broker keeps only the most recent value per topic, not history, so retained messages complement the bucket rather than replace it.