SwissQL

SwissQL is Mopheus's database access layer. It does not handle tickets or schedule agents directly; it solves a more fundamental problem: letting AI agents safely access and operate databases.

Without SwissQL, agents need to use various native database clients: psql for PostgreSQL, sqlplus for Oracle, mysql for MySQL, gsql for openGauss... Each database has its own tool, syntax, and permission setup. This is already painful for human DBAs; for AI agents it is a disaster:

• Permissions are uncontrollable — Native client permissions are tied to database users. Once an agent gets a connection string, it can theoretically execute any SQL.
• No audit trail — Who executed what SQL, and whether it was blocked, cannot be traced.
• Cross-database costs are prohibitive — Every new database type requires the agent to learn a new CLI and dialect.

SwissQL covers all database types with a single unified CLI and REST API, while providing connection profile management, a SQL rule engine, and audit logging. This makes AI database management controllable, auditable, and scalable.

Core Capabilities

Unified Database Access

SwissQL supports PostgreSQL, Oracle, MySQL, SQL Server, openGauss, and more via JDBC. Agents still need to know which database they are operating (because diagnostic methods, system catalogs, and SQL dialects differ significantly), but they do not need to learn different connection tools and parameter formats for each database — regardless of the underlying type, they connect through the same swissql exec --profile-id <id> interface, while the profile encapsulates driver, address, credentials, and other connection details.

SwissQL has built-in support for PostgreSQL, Oracle, and MySQL (including MariaDB). More importantly: as long as a database provides a JDBC driver and supports SQL operations, SwissQL can support it — including but not limited to SQL Server, SQLite, openGauss, Dameng, Kingbase, H2, and other databases.

Extending support for any JDBC database is simple: place the vendor's JDBC driver JAR and a descriptor file driver.json into the jdbc_drivers/<dbType>/ directory of the SwissQL backend — no service restart required.

Connection Profile Management

Connection information is not scattered as plaintext connection strings. It is managed centrally as profiles in the SwissQL backend. Each profile contains:

• Database type (postgres, oracle, mysql, etc.)
• Connection address (DSN or JDBC URL)
• Credentials (supports env variable references, local file storage, or inline)
• Labels (e.g. env:production, cluster:pg-prod, role:primary)

When executing SQL, agents only reference the profile ID (e.g. --profile-id prod-pg-primary) without ever touching real passwords or connection addresses. Profiles can be tested for connectivity, enabled/disabled, or bulk-imported (including from DBeaver projects).

SQL Rule Engine

SwissQL has a built-in YAML-driven SQL rule engine that intercepts and checks SQL before execution. It supports:

• Whitelist / blacklist — Allow or deny by statement type (SELECT/INSERT/UPDATE/DELETE/DROP, etc.)
• Regex matching — Match SQL text against regex patterns to block dangerous operations
• Label-based filtering — Different profiles can have different rule sets
• Write operation control — Read-only by default; agents must explicitly pass --allow-write to perform writes

The rule engine and write control are independent layers. Rules are enforced strictly with no bypass. For example, you can configure a rule: all profiles labeled env:production block DROP TABLE and DELETE without WHERE. Even if an agent requests write permission (--allow-write), SQL that violates the rule is still rejected.

This layered design gives you two knobs: write control decides whether an agent can modify data at all, while the rule engine decides which specific SQL is absolutely forbidden.

SQL Audit Logging

Every SQL executed through SwissQL is logged: execution time, profile, SQL content, result, and whether it was blocked by rules.

More importantly, audit logs support two correlation features:

• Executor identity — Track who executed each SQL via the X-Executor header (agent name, human engineer, CI script, etc.). Unmarked requests default to anonymous
• Ticket correlation — Link multiple SQL requests to the same ticket via the X-Ticket-Id header. Combined with Mopheus's ticket system, you can trace "which SQL was triggered by ticket MO-123"

Audit logs can be sent to:

• Standard output (with [AUDIT] prefix)
• A dedicated log directory (persistent files)
• Completely disabled (via environment variable)

Audit logs are the first place to look when investigating "what did the agent do?" and are essential for security compliance.

Architecture

Mopheus Agent / CLI User
        |
        v
+---------------------+
|   SwissQL CLI       |  <- Unified command-line entry
|   swissql exec ...  |
+---------------------+
        |
        v
+---------------------+
|  SwissQL Core API   |  <- REST service (Java / Spring Boot)
|  /v1/sql/execute    |
+---------------------+
        |
   +----+----+
   |         |
   v         v
Connection  SQL Rule
Management  Engine
   |         |
   v         |
HikariCP    v
Pools       Audit Log
   |         |
   v         v
+---------+
|  JDBC   |
+---------+

SwissQL uses a frontend-backend separation architecture:

• SwissQL Core (backend) — A standalone REST service handling connection management, SQL execution, rules, and auditing
• SwissQL CLI (frontend) — A command-line tool that sends requests to the backend, providing a human-friendly interface

This separation means SwissQL Core can be deployed independently inside the Mopheus network, while the CLI can run on any machine (including the machine hosting agents).

Installation

In the standard Docker Compose deployment, SwissQL Core is already bundled and started alongside Mopheus — no separate deployment needed. The installer (mopheus.sh) also installs the swissql CLI for you.

SwissQL Core listens on host port 18080 (mapped from the container's internal 8080). When pointing the CLI at it, use http://<host>:18080 — not http://<host>:8080, which is the Mopheus backend.

Integration with Mopheus

Inside Mopheus, agents access databases through SwissQL:

1. Skill layer — Database operation skills (SQL analysis, health checks) internally call swissql exec
2. Profile binding — Each workspace or project can bind one or more SwissQL profiles; agents reference these profiles when executing tasks
3. Rule inheritance — Workspace-level SQL rules automatically apply to all profiles under that workspace, forming a unified execution boundary
4. Audit correlation — SwissQL audit logs are correlated with Mopheus's ticket system, so you can view "which SQL was triggered by this ticket" from the ticket detail page