What Data Operations Can Be Performed with DBX: Complete API Reference

DBX supports four core data operations—listing tables/collections, describing schema metadata, executing queries or MongoDB commands, and running Redis commands—through a unified API that works across PostgreSQL, MySQL, MongoDB, Redis, and SQLite.

DBX (the Database Explorer) provides a programmatic interface for interacting with heterogeneous data stores through a single abstraction layer. Whether connecting to relational databases via direct drivers or tunneling through SSH proxies, the packages/node-core library exposes consistent data operations that function identically across all supported backends.

Core DBX Data Operations

The public API surface in packages/node-core/src/web-backend.ts exposes four primary functions that handle data access across SQL, MongoDB, and Redis systems.

Listing Tables and Collections

The listTables function retrieves schema metadata regardless of the underlying engine. For SQL databases, it queries the /api/schema/tables endpoint to return table names and schemas. For MongoDB deployments, it calls /api/mongo/list-collections to enumerate available collections.

In packages/node-core/src/web-backend.ts (lines 90-106), the implementation branches based on connection type:

• SQL: Constructs a metadata query compatible with PostgreSQL, MySQL, SQLite, and other relational engines
• MongoDB: Returns collection names from the target database

Describing Table and Collection Structure

The describeTable function infers or retrieves column-level metadata. Relational connections fetch column types, constraints, and defaults through /api/schema/columns, while MongoDB connections sample documents and run inferMongoColumns to determine field types dynamically.

This operation is implemented in packages/node-core/src/web-backend.ts (lines 109-127), providing uniform schema introspection across structured and document-based stores.

Executing Queries and Commands

The executeQuery function handles arbitrary data manipulation and retrieval. For SQL databases, it passes statements to the query helper in packages/node-core/src/database.ts, supporting SELECT, INSERT, UPDATE, DELETE, and DDL operations. For MongoDB, it parses shell-style syntax (e.g., db.users.find({})) and validates safety through sqlSafetyFromEnv before executing against the appropriate API endpoints.

Implementation details reside in packages/node-core/src/web-backend.ts (lines 129-158), with safety evaluation occurring in packages/node-core/src/sql-safety.ts.

Redis Command Execution

The executeRedisCommand function sends arbitrary Redis instructions with mandatory safety classification. Commands are parsed and categorized as allowed, confirm, or blocked via classifyRedisCommand in packages/node-core/src/redis-command.ts (lines 73-82).

When a direct connection is available, the function calls executeRedisCommandDirect in packages/node-core/src/database.ts (lines 554-562). For proxied connections, it routes through the DBX bridge while preserving safety checks.

Supported Database Backends

DBX normalizes operations across the following data stores:

• SQL Engines: PostgreSQL, MySQL, MariaDB, SQLite, RQLite, StarRocks, Amazon Redshift, and Apache Doris
• MongoDB: Any version supporting the standard wire protocol, accepting shell-style commands including find, aggregate, countDocuments, createIndex, and dropIndex
• Redis: Standalone instances with command classification and safety enforcement
• Embedded SQLite: Local file access via better-sqlite3 for offline inspection

Transport Architecture: Direct vs. Bridge

DBX automatically selects the appropriate transport mechanism based on connection configuration:

Direct Driver: Used when connections lack SSH or proxy layers and utilize native drivers (Postgres, MySQL, SQLite, MongoDB, Redis). This path offers lower latency and bypasses the bridge process.

Bridge Transport: Activated for SSH tunnels or HTTP proxy configurations. Requests are forwarded to the DBX bridge process via bridgeDataRequest, allowing secure access to firewalled databases without exposing ports.

This dual-path architecture ensures that listTables, describeTable, and executeQuery calls function identically regardless of network topology.

Safety and Resource Management

All data operations incorporate safety mechanisms to prevent accidental data loss. MongoDB commands pass through evaluateMongoWriteSafety, while Redis commands are classified by risk level. Destructive operations require explicit user confirmation unless safety checks are bypassed via environment configuration.

Resource cleanup is handled by closeDatabaseResources in packages/node-core/src/database.ts (lines 92-110), which gracefully terminates connection pools and tears down proxy tunnels created for SSH or HTTP proxy layers.

Practical Code Examples

import {
  listTables,
  describeTable,
  executeQuery,
  executeRedisCommand,
} from "dbx/packages/node-core/src/web-backend.js";
import type { ConnectionConfig } from "dbx/packages/node-core/src/connections.js";

// 1. Load a PostgreSQL connection from the store
const pgConn = await findConnection("my-postgres");

// 2. List tables in the default schema
const tables = await listTables(pgConn);
console.log("Tables:", tables.map(t => t.name));

// 3. Get column details for a specific table
const columns = await describeTable(pgConn, "users");
console.table(columns);

// 4. Run a SELECT query with row limit
const result = await executeQuery(
  pgConn, 
  "SELECT id, email FROM users ORDER BY id DESC", 
  { maxRows: 20 }
);
console.log("Rows:", result.rows);

// 5. MongoDB example – count documents
const mongoConn = await findConnection("my-mongo");
const mongoResult = await executeQuery(
  mongoConn,
  "db.orders.countDocuments({status:\"pending\"})"
);
console.log("Pending orders:", mongoResult.rows[0].count);

// 6. Redis example – get a key
const redisConn = await findConnection("my-redis");
const redisRes = await executeRedisCommand(redisConn, 0, "GET my:key");
console.log("Value:", redisRes.value);

All calls automatically route through the bridge when the connection configuration includes SSH or proxy layers, ensuring consistent behavior across local and remote databases.

Summary

• DBX provides four core data operations: listTables, describeTable, executeQuery, and executeRedisCommand, implemented in packages/node-core/src/web-backend.ts
• Multi-backend support includes PostgreSQL, MySQL, MongoDB, Redis, and SQLite through a unified TypeScript API
• Automatic transport selection chooses between direct drivers and SSH bridge proxies without code changes
• Safety enforcement via sql-safety.ts and redis-command.ts prevents destructive operations unless explicitly authorized
• Resource management through closeDatabaseResources ensures proper cleanup of connection pools and tunnels

Frequently Asked Questions

What databases does DBX support?

DBX supports relational databases including PostgreSQL, MySQL, MariaDB, SQLite, RQLite, StarRocks, Redshift, and Doris; document stores via MongoDB; and key-value operations through Redis. The same executeQuery interface works across SQL and MongoDB, while Redis uses the dedicated executeRedisCommand function.

How does DBX handle connections through SSH tunnels?

DBX automatically detects SSH or HTTP proxy configurations and routes requests through the DBX bridge process rather than using direct drivers. This happens transparently in packages/node-core/src/web-backend.ts, ensuring that code written for local databases works identically when tunneling through bastion hosts.

What safety features prevent accidental data deletion?

All MongoDB and Redis commands pass through safety evaluators (evaluateMongoWriteSafety and classifyRedisCommand) that categorize operations as allowed, confirm, or blocked. Destructive commands like FLUSHALL or dropDatabase require explicit user confirmation unless the environment variable DBX_SKIP_SAFETY_CHECKS is set, preventing accidental data loss in production environments.

Can DBX execute raw MongoDB shell commands?

Yes, the executeQuery function accepts MongoDB shell-style syntax such as db.collection.find(), db.collection.aggregate(), and db.collection.countDocuments(). The parser in packages/node-core/src/web-backend.ts validates the command structure and safety level before translating it to the appropriate MongoDB driver API calls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}