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

> Explore DBX API for four key data operations: list tables, describe schema, execute queries, and run commands. Unified API works across PostgreSQL MySQL MongoDB Redis SQLite.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: api-reference
- Published: 2026-07-06

---

**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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/web-backend.ts) (lines 129-158), with safety evaluation occurring in [`packages/node-core/src/sql-safety.ts`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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

```typescript
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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/sql-safety.ts) and [`redis-command.ts`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/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`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/web-backend.ts) validates the command structure and safety level before translating it to the appropriate MongoDB driver API calls.