Connections
A connection is a configured, named, credentialed endpoint. Everything else in QUBIQ refers to it by name: tag bindings, pipeline nodes, named queries, the historian, the audit journal.
Create it once. QUBIQ pools it, monitors it, encrypts its credentials, and gives every consumer the same shared, healthy client.
Supported connection types
| Type | Used for | Page |
|---|---|---|
| OPC-UA | PLCs, DCS, gateways speaking OPC Unified Architecture | OPC-UA |
| MQTT | Brokers, classic MQTT and Sparkplug B | MQTT & Sparkplug B |
| Modbus | Modbus TCP/RTU devices | Modbus |
| SNMP | Network gear, UPS, environmental monitors; v1/v2c/v3 | SNMP |
| TCP/UDP | Serial-over-Ethernet, scales, barcode readers, custom protocols | TCP/UDP |
| SQL database | Postgres, MySQL, SQL Server, SQLite | SQL databases |
| MongoDB | Document stores | MongoDB |
| QuestDB | Time-series storage; the historian's backing store | QuestDB |
| Media server | IP cameras and video streams | Media servers |
| SMTP · Telegram · WhatsApp | Outbound notification, referenced by the notification nodes and by alarms | Notification providers |
| Qdrant | The vector store behind the assistant's knowledge base | Vector store |
Creating a connection
Connections → New connection, pick a type, fill the form, save. The dialog validates the form as
you type and refuses to save until every required field is filled; there is no separate test step.
| Field | Every connection has it |
|---|---|
| Name | The identifier used everywhere else. Choose a stable, meaningful name — PLC-Filler-01, not conn1. |
| Enabled | A disabled connection is not opened, not polled and not monitored. Use it to take a device out of service without deleting its configuration. |
The rest of the form is protocol-specific.
Knowing whether it worked
Save an enabled connection and QUBIQ opens it. Its real state then shows in the Connections list and in the Status panel — which is the same signal that will tell you about it at 3am, rather than a one-off check that was true when you pressed it.
| Symptom | Usual cause |
|---|---|
| Never reaches connected; times out | Firewall, wrong port, device off |
| Authentication rejected | Wrong credentials, or the account lacks the right on the device |
| TLS/certificate error | Untrusted certificate, hostname mismatch, expired cert |
| Connects, then errors | Right host, wrong protocol or wrong security policy |
If you are not ready for the connection to be live, save it disabled and enable it when you are.
Credentials and secrets
- Secrets are encrypted at rest with key material derived from the installation's
ENCRYPTION_KEY, and are decrypted only in the process that needs them. - Secrets are never returned to the browser. Edit forms show presence flags (
has_credentials,has_auth_key, …) so you can see that a secret is set without it leaving the server. - Leaving a secret field blank on edit keeps the existing value. Clearing it requires the explicit "clear" action.
- Protocol workers do not read the database. They ask CoreServer to resolve a connection over the bus and receive the decrypted detail there.
Only a passphrase-encrypted backup carries connection secrets. An unencrypted backup restores the configuration with credentials blank — deliberately, so an unprotected archive cannot leak plant access. → Backup & restore
AI-scoped credentials
SQL, MongoDB and QuestDB connections can carry a second, read-only credential used by the AI assistant instead of the primary one. If your assistant may explore a production database, give it an account that cannot write.
It has its own Test AI credential action on the connection form (needs Edit connections), which signs in with the credentials currently typed in the form. It is the only way to check an AI credential, because nothing else in the product ever uses it.
Pooling
Every protocol goes through a pool. A pool means:
- One underlying client per connection, shared by every consumer — not one per tag, per pipeline node or per screen.
- Reconnection, backoff and session re-establishment handled once.
- Bounded resource use:
maxConnectionson database connections caps concurrency.
The practical rule: never bypass a connection. A pipeline node, a named query and a bound widget that all touch the same database share one pool.
Health monitoring
Connection health is primarily passive. QUBIQ uses each protocol library's own signals — broker connect/disconnect callbacks, driver errors, subscription notifications, database SDAM events — so healthy connections generate no probe traffic at all.
An active probe runs only for connections whose passive signal has gone stale, as a safety net.
Set LIVENESS_MODE to choose the behaviour:
| Mode | Probe cadence | When to use |
|---|---|---|
passive (default) | 5 min safety-net probe | Normal operation |
hybrid | 30 s | Diagnosing a flapping connection |
active | 10 s, probe everything | Legacy behaviour; highest load |
Status is visible in the Connections list and the Status panel, and available at the Status panel (needs View the status panel).
Health is not only an indicator — the store-and-forward forwarders use it to avoid retrying against a connection known to be down. → Store and forward
Browsing a connection
Where the protocol supports discovery, Browse walks the remote structure so you can pick addresses instead of typing them:
| Type | Browse shows |
|---|---|
| OPC-UA | The server's address space tree |
| SQL / QuestDB | Schemas, tables, columns |
| MongoDB | Databases and collections |
| MQTT (Sparkplug) | Discovered groups, edge nodes, devices and metrics |
| SNMP | A walk of the agent, with symbolic names resolved from loaded MIBs |
| Modbus | A one-shot register read for verification |
Browse requires View connections.
Permissions
| Action | Permission |
|---|---|
| List and browse connections, view health | View connections |
| Create | Create connections |
| Edit, clear quarantine, manage historian designation | Edit connections |
| Delete | Delete connections |
Deleting a connection
Deleting a connection does not delete the tags bound to it. Their bindings are left without a connection, which shows up as a broken binding rather than a silent data loss. That is intentional: re-pointing bindings at a replacement connection is a normal migration, and losing the tag model because a device was swapped would not be.
Check the namespace's binding statistics before deleting, to see what depends on it.
When a delete is refused
Four guards can refuse the delete, and the dialog says which:
| Refusal | What it means |
|---|---|
| In use | Pipelines and Designer projects reference it. Both are listed by name, so you can go and re-point them. |
| This is the system historian | The connection is the designated history store. Change the designation first. |
| This holds a project's operator accounts | It is the runtime user database for a LiveView project. Those operators would lose their sign-in. |
| Undelivered writes are buffered | Store-and-forward is still holding data for it, and deleting discards that data. |
The first shows a list; the other three are a sentence and a name, because there is nothing to enumerate. All four offer a force delete — take it only once you know what the refusal was protecting, particularly the buffered case, where the cost is data that has not been written yet.
Next
Pick your protocol from the list above, or start with OPC-UA.