--- title: Integrate HiveMQ with Tiger Cloud | Tiger Data Docs description: Connect HiveMQ to Tiger Cloud and stream MQTT messages into a hypertable --- [HiveMQ](https://www.hivemq.com/) is an enterprise MQTT broker used to move data between IoT devices, applications, and backend systems in real time. This page shows you how to connect HiveMQ to your Tiger Cloud service using the [HiveMQ Enterprise Extension for PostgreSQL](https://docs.hivemq.com/hivemq-postgresql-extension/latest/) to stream MQTT messages into Tiger Cloud. ## Prerequisites for this integration guide To follow these steps, you'll need: - A [Tiger Cloud service](/docs/get-started/quickstart/create-service/index.md). These steps use Tiger Cloud, but the same approach applies to a [self-hosted TimescaleDB](/docs/get-started/choose-your-path/install-timescaledb/index.md) instance. * Your [connection details](/docs/integrate/find-connection-details/index.md). - A [HiveMQ Enterprise](https://www.hivemq.com/downloads/) broker with file system access on the host - The [HiveMQ Enterprise Extension for PostgreSQL](https://docs.hivemq.com/hivemq-postgresql-extension/latest/) downloaded ## Create a target table in Tiger Cloud 1. **Connect to your service** Use the [Tiger Console](/docs/build/data-management/run-queries-from-tiger-console/index.md), `psql`, or any other SQL editor to connect to your Tiger Cloud service. 2. **Create a hypertable for MQTT messages** Create a `hypertable` for time-series readings. The table stores the event time, a `tag_id`, the numeric `value`, and payload metadata fields: ``` CREATE TABLE mqtt_messages ( ts TIMESTAMPTZ NOT NULL, tag_id TEXT NOT NULL, value DOUBLE PRECISION, quality TEXT, units TEXT ) WITH ( tsdb.hypertable = true, tsdb.chunk_interval = '1 day' ); ``` This layout (`ts`, `tag_id`, `value`, `quality`, `units`) is recommended for time-series sensor readings when the payload includes metadata. If you want auditability or debugging, add a `payload JSONB` column so you preserve the raw message alongside parsed fields, then adjust the template below accordingly. Aim for 1–20 million rows per chunk. That's roughly 1 day for 10,000 messages/min, or 1 hour for 300,000 messages/min. Adjust `tsdb.chunk_interval` to match your broker's throughput. ## Install and configure the HiveMQ Enterprise Extension for PostgreSQL 1. **Install the extension** Unpack the extension into the `extensions` directory of your HiveMQ installation: Terminal window ``` unzip hivemq-postgresql-extension-.zip -d /extensions/ ``` The extension folder is disabled by default. Remove the `DISABLED` marker file once you have finished configuring it in the next steps: Terminal window ``` rm /extensions/hivemq-postgresql-extension/DISABLED ``` 2. **Configure the database connection** Edit `/extensions/hivemq-postgresql-extension/conf/config.xml` and add a PostgreSQL connection that points to your Tiger Cloud service. Use the **username**, **password**, **host**, and **port** from your service connection details: ``` tiger-cloud YOUR_SERVICE_HOST.tsdb.cloud.timescale.com 5432 tsdb tsdbadmin YOUR_PASSWORD true ``` Tiger Cloud requires TLS. Make sure the `true` block is present, otherwise the extension will not be able to connect. 3. **Define a route from MQTT topics to your table** Still in `config.xml`, add an MQTT-to-PostgreSQL route that uses a statement template to parse JSON payload fields and insert them into separate columns on `mqtt_messages`: ``` mqtt-to-tiger-cloud tiger-cloud uns/tiger-data/# conf/examples/hivemq-mqtt-message-template.sql ``` Narrow the `` to the topics you want to persist. Use `#` only if you want to capture every message on the broker. 4. **Create the statement template file** Create the statement template file at `HIVEMQ_HOME/extensions/hivemq-postgresql-extension/conf/examples/hivemq-mqtt-message-template.sql`. This will need to be customized based on the message format. #### Sample MQTT topic and JSON Given an mqtt topic and JSON as follows: ``` uns/tiger-data/plant-7/sensor-123/reading ``` ``` { "timestamp": "2026-06-12T14:26:00Z", "value": 74.5, "quality": "GOOD", "units": "°F" } ``` Then the template file might look like this: ``` INSERT INTO mqtt_messages (ts, tag_id, value, quality, units) VALUES ( ((${mqtt-payload-utf8})::jsonb ->> 'timestamp')::timestamptz, ${mqtt-topic}, ((${mqtt-payload-utf8})::jsonb ->> 'value')::double precision, ((${mqtt-payload-utf8})::jsonb ->> 'quality'), ((${mqtt-payload-utf8})::jsonb ->> 'units') ); ``` The `timestamp` field must be valid ISO 8601 so the cast to `timestamptz` succeeds. `${mqtt-topic}` inserts the full MQTT topic string as `tag_id`. If you only want a sensor identifier, extract the relevant segment from the topic path instead of storing the full topic. See the [HiveMQ extension reference](https://docs.hivemq.com/hivemq-postgresql-extension/latest/) for the full list of placeholders and supported statement templates. In this example, the topic was used as the tag\_id. 5. **Start HiveMQ and verify the extension is loaded** Start (or restart) HiveMQ and check the broker log for a line confirming the extension is started and the route is active: Terminal window ``` tail -f /log/hivemq.log ``` Publish a test message to a topic that matches your filter, then query the table to confirm rows are arriving: ``` SELECT * FROM mqtt_messages ORDER BY ts DESC LIMIT 10; ``` With messages flowing into `mqtt_messages`, add a retention policy to cap how long historical data is kept. The step below can be performed in the [Tiger Console](/docs/build/data-management/run-queries-from-tiger-console/index.md) or any other SQL editor. ## Optimize for HiveMQ workloads 1. **Optional: add a retention policy** ``` SELECT add_retention_policy('mqtt_messages', INTERVAL '1 year'); ``` You have successfully integrated HiveMQ with Tiger Cloud.