DBX

Web API Reference

This API powers the DBX Web UI and internal tooling such as the MCP Web backend. It is not a separate public integration contract. Endpoints and payloads may change between releases. For scripting and agent workflows, prefer @dbx-app/cli or @dbx-app/mcp-server when possible.

Base URL

By default, DBX Web listens on port 4224:

http://localhost:4224

When deployed behind a reverse-proxy subpath, set DBX_PUBLIC_BASE_PATH and prefix every route. For example, with /dbx:

https://example.com/dbx/api/auth/check

All API routes are under /api.

Authentication

Protected routes require a session cookie named dbx_session.

Check Auth State

GET /api/auth/check

Example response:

{
  "authenticated": false,
  "required": true,
  "setup_required": false
}
FieldMeaning
requiredPassword protection is enabled
setup_requiredFirst-run password setup is still needed
authenticatedCurrent request already has a valid session

First-Run Setup

POST /api/auth/setup
Content-Type: application/json

{
  "password": "your-password"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "password": "your-password"
}

On success, the response sets Set-Cookie: dbx_session=.... Reuse that cookie on later requests.

Five consecutive login failures trigger an approximately 60-second lockout. Sessions live in the current Web process and require login again after restart. The cookie is HttpOnly, uses SameSite=Lax, and follows DBX_PUBLIC_BASE_PATH for its path.

Logout

POST /api/auth/logout
Cookie: dbx_session=...

Environment Variables

VariablePurpose
DBX_PASSWORDSet an initial password at container startup
DBX_DISABLE_PASSWORD=1Disable password protection entirely
DBX_PORTChange the listen port (default 4224)
DBX_DATA_DIRData directory containing dbx.db
DBX_PUBLIC_BASE_PATHServe DBX under a subpath such as /dbx
DBX_MAX_UPLOAD_MBOverride the general request and uploaded-file limit; default 1024 MB. Multipart routes reserve fixed protocol overhead (set at least 4096 for a 4 GiB file)
DBX_AGENT_DIROverride the Web Agent/driver directory; defaults to agents under the data directory
DBX_STATIC_DIROverride the Web static asset directory
RUST_LOGConfigure Rust backend log filtering; the default is dbx_web=info,tower_http=info
RUST_BACKTRACE=1Include Rust backtraces when an error reports one

Logging and Troubleshooting

DBX Web reads the standard RUST_LOG filter when it starts. For a focused diagnostic run, increase the Web and HTTP middleware targets without enabling every dependency:

RUST_LOG=dbx_web=debug,tower_http=info ./dbx

Set RUST_BACKTRACE=1 as well when the error includes a Rust backtrace. If the problem is inside another DBX crate, add its target to the same filter, such as dbx_core, dbx_drivers, dbx_sql, dbx_plugin_runtime, dbx_ai_provider, or dbx_platform. RUST_LOG=debug enables a much broader and noisier filter. Logs are written to the process output; redirect that output when you need to save a diagnostic file.

Request Format

  • Field naming follows each Rust request type. Some bodies use camelCase, while connection configuration still contains snake_case; do not apply one naming convention to the whole API.
  • GET query parameters commonly use snake_case, such as connection_id, but the current route implementation remains authoritative.
  • Errors usually return JSON with an error field and an HTTP status code.
  • Long-running export, import, transfer, SQL-file, and AI operations commonly use a start request plus SSE progress and cancel/download routes rather than one synchronous response.

Only the data-grid extractor currently exposes a tested, scoped OpenAPI document at /api/query/data-grid-extractor-openapi.json. It does not cover the complete DBX Web API or version the other routes.

Connection APIs

List Connections

GET /api/connection/list
Cookie: dbx_session=...

Returns saved connection profiles. Secrets such as passwords are stored separately from the returned JSON.

Save Connections

Connections are upserted by id: connections the request does not mention are left untouched, so several clients can share one server without deleting each other's profiles. Deletions are explicit through the optional removedIds array.

POST /api/connection/save
Content-Type: application/json
Cookie: dbx_session=...

{
  "configs": [
    {
      "name": "local-mysql",
      "db_type": "mysql",
      "host": "127.0.0.1",
      "port": 3306,
      "username": "root",
      "database": "app"
    }
  ],
  "removedIds": ["connection-to-delete"]
}

Test Connection

POST /api/connection/test
Content-Type: application/json

{
  "config": {
    "name": "temp",
    "db_type": "mysql",
    "host": "127.0.0.1",
    "port": 3306,
    "username": "root",
    "database": "app"
  }
}

Connect

Most data APIs expect the target connection to be active first.

POST /api/connection/connect
Content-Type: application/json

{
  "config": {
    "id": "connection-id",
    "name": "local-mysql",
    "db_type": "mysql",
    "host": "127.0.0.1",
    "port": 3306,
    "username": "root",
    "database": "app"
  }
}

Check Health

POST /api/connection/check-health
Content-Type: application/json

{
  "connectionId": "connection-id"
}

Schema APIs

List Tables

GET /api/schema/tables?connection_id=CONNECTION_ID&database=app&schema=
Cookie: dbx_session=...

List Columns

GET /api/schema/columns?connection_id=CONNECTION_ID&database=app&schema=&table=users
Cookie: dbx_session=...

Read Oracle-Family Triggers

To find triggers without knowing their owning table, use the object list with a trigger type filter. Search and type filters are applied before paging in the exact metadata adapters.

GET /api/schema/objects?connection_id=CONNECTION_ID&database=demo&schema=APP&object_types=TRIGGER&filter=audit&limit=100&offset=0&identity_mode=exact
Cookie: dbx_session=...

Use the owning object's schema and name to list its triggers. The returned trigger owner can differ from that schema.

GET /api/schema/triggers?connection_id=CONNECTION_ID&database=demo&schema=DATA&table=ORDERS&identity_mode=exact
Cookie: dbx_session=...

Fetch the full definition using the trigger's owner and name. On this route, table is the source object name, not its parent table.

GET /api/schema/object-source?connection_id=CONNECTION_ID&database=demo&schema=APP&table=AUDIT_ORDERS&object_type=TRIGGER&identity_mode=exact
Cookie: dbx_session=...

These three routes accept optional identity_mode=exact and catalog query parameters. Omitting identity_mode retains the existing metadata behavior. Exact reads preserve raw owner/name values; URL-encode spaces, quotes, and other reserved characters rather than trimming or changing their case. catalog is forwarded to the selected metadata provider; it does not replace schema.

Trigger summaries and source responses may contain trigger.oracle_metadata (oracle_metadata directly on entries returned by /schema/triggers). Version 1 includes the verified engine, exact owner/name, scope, independent parent, string-valued object ID, and per-field reads states. enabled is the trigger state; valid is the independently read object validity. Schema/database scopes do not have an invented table parent.

An exact source lookup that succeeds with no visible matching trigger returns reads.identity.state="empty" with the verified engine and raw target. It means empty within current visibility, not global absence. Query failures and legacy providers cannot supply that proof; creation still uses CREATE without REPLACE.

Source metadata additionally reports definition origin/format/completeness and compilation errors with line/position. A null or absent error list is unknown, not an empty successful read. Failed or incomplete reads cannot supply a write baseline; keep the draft, restore dictionary access or update the provider, and read again. Old Agents/plugins that omit the metadata contract remain usable in their original mode but do not prove exact identity. The source text can include a same-target state appendix from DBMS_METADATA; it is export text, not an arbitrary multi-statement save payload.

Other schema routes include:

  • /api/schema/databases
  • /api/schema/schemas
  • /api/schema/indexes
  • /api/schema/foreign-keys
  • /api/schema/ddl

SQL Query APIs

Execute One Statement

POST /api/query/execute
Content-Type: application/json

{
  "connectionId": "connection-id",
  "database": "app",
  "sql": "select id, name from users limit 10"
}

Example response shape:

{
  "columns": ["id", "name"],
  "rows": [[1, "Ada"], [2, "Lin"]]
}

Related routes:

RoutePurpose
/api/query/execute-multiExecute multiple result sets in one request
/api/query/execute-batchExecute a list of statements
/api/query/cancelCancel a running query
/api/query/build-table-select-sqlBuild a table browse query

Prepare One Oracle-Family Trigger Definition

POST /api/query/prepare-oracle-trigger-sql accepts { "input": ... } with databaseType (oracle, oceanbase-oracle, or dameng), raw owner/name, source, and purpose (inspect, create, or replace). It returns a single normalized definition, the parsed header, and independent inline/export enabled states. This route only prepares SQL; execute through the normal query route after checking the current object, privileges, and concurrent changes.

comparisonSource is for readback comparison only. It canonicalizes the known declaration wrapper while preserving the remaining header, body, comments, and literal newlines. Execute definition, not this comparison form.

structuredEditable reports whether the complete definition's header can be represented without loss by the timing/event/body form. A false or absent value requires the complete-source editor for structural changes; a plain TRIGGER_BODY alone does not establish this capability.

For create/replace, supply binding with the verified scope (TABLE, VIEW, SCHEMA, DATABASE, or TIMER), parent owner/name where applicable, and pluggable for a verified Oracle container scope. Omitted ON qualifiers are filled only from that binding. Replace also requires the current desired enabled state. Create produces CREATE without OR REPLACE. Oracle and verified OceanBase preserve state in the definition; DM's requiresStateRestore indicates a separate native state step to preview and verify. allowExportAppendix is only for inspecting trusted metadata exports; write purposes reject it and any extra SQL.

Redis APIs

Redis browser and command execution use dedicated routes.

POST /api/redis/execute-command
Content-Type: application/json

{
  "connectionId": "redis-id",
  "db": 0,
  "command": "GET mykey"
}

Other common Redis routes:

  • /api/redis/scan-keys
  • /api/redis/get-value
  • /api/redis/set-string
  • /api/redis/delete-key

MongoDB APIs

MongoDB routes are POST endpoints with JSON bodies.

List Collections

POST /api/mongo/list-collections
Content-Type: application/json

{
  "connectionId": "mongo-id",
  "database": "app"
}

Find Documents

POST /api/mongo/find-documents
Content-Type: application/json

{
  "connectionId": "mongo-id",
  "database": "app",
  "collection": "users",
  "skip": 0,
  "limit": 20,
  "filter": "{}"
}

Other MongoDB routes include aggregate-documents, insert-documents, update-documents, and delete-documents.

MCP and CLI Integration

For automation, these packages are usually easier to maintain than calling the Web API directly:

When MCP runs against a deployed Web instance, set:

{
  "env": {
    "DBX_WEB_URL": "http://localhost:4224",
    "DBX_WEB_PASSWORD": "your-password"
  }
}

The MCP server handles login and session cookies for you.

CLI supports the same DBX_WEB_URL and DBX_WEB_PASSWORD variables. Both integrations reuse server-side connections, drivers, read-only protection, production protection, and database privileges, making them easier to maintain across DBX upgrades than copied internal route payloads.

Writes, Safety, and File Boundaries

  • API authentication proves only that the request belongs to a logged-in session; it does not replace database privileges
  • Query, import, and transfer paths continue to enforce connection read-only protection, while production and SQL-risk policy apply in their corresponding core paths
  • Browser-selected table-import and SQL files are uploaded into server temporary storage, not read from arbitrary client paths
  • Web exports create a temporary server file, return it through a download route, and then clean it up
  • Reverse proxies should preserve cookies and SSE streaming, allow appropriate long-running timeouts, and limit public exposure

Example Scripts

See the repository examples:

Route Groups

The Web backend exposes many more routes for the UI, including:

  • /api/export/* for exports and downloads
  • /api/import/* for table imports
  • /api/transfer/* for data transfer jobs
  • /api/ai/* for the built-in AI assistant
  • /api/agents/* and /api/jdbc/* for driver management
  • /api/history/* and /api/saved-sql/* for editor state

Browse crates/dbx-web/src/main.rs in the repository for the full route list.