SwissQL Database Access

SwissQL is Mopheus's core database access layer component. It does not handle tickets or schedule agents directly; it solves a more fundamental problem: letting AI agents and engineers safely access and operate heterogeneous 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 CapabilitiesCopy Anchor Link

Unified Database AccessCopy Anchor Link

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 ManagementCopy Anchor Link

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 EngineCopy Anchor Link

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 LoggingCopy Anchor Link

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.

ArchitectureCopy Anchor Link

             Mopheus Agent / CLI User
                        │
                        ▼
             ┌─────────────────────┐
             │     SwissQL CLI     │  ← Unified command-line entry
             │   swissql exec ...  │
             └──────────┬──────────┘
                        │
                        ▼
             ┌─────────────────────┐
             │  SwissQL Core API   │  ← REST service (Java / Spring Boot)
             │   /v1/sql/execute   │
             └──────────┬──────────┘
                        │
           ┌────────────┴────────────┐
           ▼                         ▼
┌─────────────────────┐   ┌─────────────────────┐
│Connection Management│   │   SQL Rule Engine   │
│   (HikariCP Pools)  │   │ (Inspect & Enforce) │
└──────────┬──────────┘   └──────────┬──────────┘
           │                         │
           ▼                         ▼
┌─────────────────────┐   ┌─────────────────────┐
│    JDBC Drivers     │   │      Audit Log      │
│(PostgreSQL/Oracle/…)│   │ (Record & Ticket ID)│
└─────────────────────┘   └──────────┬──────────┘
                                     │
                                     ▼
                                  Database

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 & DeploymentCopy Anchor Link

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 MopheusCopy Anchor Link

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
5. IT Asset Linkage — In Mopheus's IT Asset CMDB, a Database asset represents the logical cluster, while each concrete physical or containerized instance is modeled as a DatabaseInstance (dbi) asset. You can bind a SwissQL profile directly to a DatabaseInstance by writing its profile identifier into attributes.credential_ref using the swissql://<profile-id>[?server=<server-spec>] URI scheme (for example, credential_ref: "swissql://pg-prod-1?server=svc:mopheus-swissql-prod").
   • Asset Reference Mode (server=svc:<service-id>): Enforces decoupled CMDB topology. When the agent detects the svc: prefix, it automatically inspects the service asset to get its port (labels.port, defaulting to 18080) and follows runs_on to the hosting host asset to resolve the network address, dynamically constructing the backend URL.
   • Direct Endpoint Mode (server=http[s]://<host>:<port>): Ideal for lightweight scenarios pointing directly to an external or fixed network endpoint.
   • Default Fallback Mode (omitted server): Automatically falls back to the workspace or local default SwissQL backend. Because a single logical database may contain multiple instances (primary, standbys, read replicas), storing the profile URI on DatabaseInstance ensures an exact 1:1 mapping between physical instances and SwissQL connection profiles. When agents perform diagnostics or queries on an instance, they can directly resolve the instance's SwissQL profile and backend endpoint from its asset attributes without manual parameter assembly.