Connections
A connection is a configured device, broker or database the gateway talks to. Driver connections (OPC UA, MQTT) belong to their module and use the baseline routes described in Runtime and modules. This page covers the outside database connections and the storage routes that use them, all admin only because a connection carries a password. Dashboard side: Databases and storage.
Routes
| Method and path | Role | Purpose |
|---|---|---|
GET /api/v1/admin/databases/engines | admin | The supported engines with their default ports |
GET /api/v1/admin/databases | admin | Every database connection, by name, with status and usage |
POST /api/v1/admin/databases | admin | Create a connection |
PUT /api/v1/admin/databases/{id} | admin | Replace its settings |
DELETE /api/v1/admin/databases/{id} | admin | Delete it; refused while something is stored in it |
POST /api/v1/admin/databases/test | admin | Sign in with settings from the form, saved or not |
POST /api/v1/admin/databases/{id}/check | admin | Check a saved connection again now (202) |
GET /api/v1/admin/storage | admin | Where each kind of record is kept |
PUT /api/v1/admin/storage/{kind} | admin | Move a kind of record to a connection, or back to the gateway database |
Engines
GET /api/v1/admin/databases/engines returns [{ "id", "label", "defaultPort" }] for PostgreSQL, Microsoft SQL Server and MySQL/MariaDB. Only these have been built; none has been proven against a plant database beyond the test route.
Database connections
ConnectionBody, used by POST and PUT:
| Field | Type | Required | Meaning |
|---|---|---|---|
name | string | yes | Up to 60 characters; unique, case-insensitive (409) |
engine | string | yes | An engine id from the engines route (400 otherwise) |
host | string | yes | Server name or address, up to 255 characters, no whitespace or ; |
port | integer | no | 1 to 65535; defaults to the engine's port |
database | string | yes | Database name on the server, up to 128 characters |
username | string | yes | Up to 128 characters |
password | string | no | Stored encrypted. Blank on an edit keeps the saved one |
options | string | no | Extra connection-string settings, up to 1000 characters; must parse for the engine (400) |
enabled | boolean | no | Default true |
description | string | no | Up to 500 characters |
The response never includes the password, only hasPassword:
{
"id": "…", "name": "Plant historian", "engine": "postgres", "host": "db.plant.local", "port": 5432, "database": "scadex", "username": "scadex",
"hasPassword": true, "options": "", "enabled": true, "description": "", "createdAt": "…", "updatedAt": "…",
"usedFor": ["Audit log"],
"status": { "state": "connected", "error": null, "checkedAt": "…", "latencyMs": 3, "serverVersion": "16.2" },
"queries": { "perSecond": 0, "perMinute": 4 }
}
status comes from the connection monitor, which checks each enabled connection in turn; checkedAt is ISO-8601. Creating or changing a connection schedules a check soon. usedFor lists the storage kinds routed to it. Deleting a connection that is in use answers 409 naming what is stored there.
Testing
POST /api/v1/admin/databases/test body TestBody: the same fields as above without enabled and description, plus id (optional). With an id, a blank password means the saved one. Response: { "state", "error", "checkedAt", "latencyMs", "serverVersion" } with HTTP 200 whether or not the sign-in worked; state says.
Storage
GET /api/v1/admin/storage returns one row per kind of record the gateway can store elsewhere:
[ { "kind": "audit", "label": "Audit log", "connectionId": "…", "connectionName": "Plant historian", "updatedAt": "…",
"forwarding": { "waiting": 0, "lastCopiedAt": "…", "error": null, "errorAt": null } } ]
forwarding is present for the audit log when it is routed to an outside database: the gateway writes audit rows locally first and forwards them (store-and-forward), so waiting is the backlog. PUT /api/v1/admin/storage/{kind} body {"connectionId": "…"}; null or empty routes the kind back to the gateway database. An unknown kind is 404; an unknown connection 400. The response is the full list. Reading the audit log then follows the route; see the audit section of Administration.
The @gateway.connection tags
The gateway publishes the state of every connection it keeps as tags, gathered every two seconds from memory, so they can be trended and alarmed on like any tag (see Tags). The tree is:
| Path | Value |
|---|---|
@gateway.connection.{kind}.count | How many connections of this kind exist |
@gateway.connection.{kind}.connected | How many are up |
@gateway.connection.{kind}.{name}.name | The connection's name |
@gateway.connection.{kind}.{name}.state | Drivers: disabled, connected, connecting or faulted. Databases: the monitor's state |
@gateway.connection.{kind}.{name}.connected | Boolean |
@gateway.connection.{kind}.{name}.error | The last error, or "" |
@gateway.connection.database.{name}.latency | Milliseconds, databases only |
{kind} is database for outside databases, or the running driver module's technology (opcua, mqtt) for driver connections; {name} is the connection's name turned into a path segment. These tags are gateway-managed: they cannot be changed, moved or deleted (400), but alarms can be added to them.