Database Workspace

A lightweight, project-scoped database explorer and query runner for VS Code.

Supported databases:

PostgreSQL
MongoDB
ClickHouse
Redis
SQLite

The extension is designed for quick developer inspection. It keeps queries beside source code, stores connection metadata in Git, and stores passwords through VS Code SecretStorage.

Features

Explore PostgreSQL, MongoDB, ClickHouse, Redis, and SQLite from one workspace view.
Run associated query files with connection-aware IntelliSense and bounded results.
Build native .dbworkbook notebooks with a safe target for every cell.
Keep connection metadata project-local while passwords stay in VS Code SecretStorage.
Enforce workspace trust, read-only connections, query classification, timeouts, and row limits.

Install

VS Code Marketplace

Open Extensions in VS Code, search for Database Workspace, verify the publisher is npv2k1, and select Install. The listing URL is npv2k1.db-workspace.

VSIX

Install the packaged VSIX:

code --install-extension db-workspace-0.2.3.vsix

Reload VS Code and open the database icon in the Activity Bar.

Quick start

Open Databases in the Activity Bar.
Run Database: Manage Connections and add a disposable development database.
Store its password with Database: Set Password.
Connect, expand the database tree, and use Database: New Query or Database: New Workbook.
Keep production environments read-only until their permissions and query safeguards have been reviewed.

Workspace configuration

Create .db-workspace/connections.json:

{
  "version": 1,
  "connections": [
    {
      "id": "app-postgres",
      "name": "App PostgreSQL",
      "driver": "postgresql",
      "environments": {
        "development": {
          "host": "${env:POSTGRES_HOST}",
          "port": 5432,
          "database": "app",
          "username": "app_reader",
          "environment": "development",
          "readOnly": false,
          "allowUnclassifiedQueries": false
        }
      }
    },
    {
      "id": "app-mongodb",
      "name": "App MongoDB",
      "driver": "mongodb",
      "environments": {
        "development": {
          "host": "localhost",
          "port": 27017,
          "database": "app",
          "username": "reader",
          "options": { "authSource": "admin" }
        }
      }
    },
    {
      "id": "warehouse-clickhouse",
      "name": "Warehouse ClickHouse",
      "driver": "clickhouse",
      "environments": {
        "development": {
          "host": "localhost",
          "port": 8123,
          "database": "warehouse",
          "username": "default"
        }
      }
    },
    {
      "id": "app-redis",
      "name": "App Redis",
      "driver": "redis",
      "environments": {
        "local": {
          "host": "localhost",
          "port": 6379,
          "database": 0,
          "environment": "local"
        }
      }
    }
  ],
  "queryAssociations": [
    {
      "glob": "database/postgres/**/*.sql",
      "connection": "app-postgres",
      "environment": "development"
    },
    {
      "glob": "database/mongodb/**/*.mongodb.js",
      "connection": "app-mongodb",
      "environment": "development"
    }
  ]
}

Use ${env:VARIABLE_NAME} in committed values that differ by machine. Set envFile to a workspace-relative dotenv file (for example .env) to resolve placeholders from that file before falling back to the extension host process environment. Set passwordEnv to the name of a password variable; a password saved with Database: Set Password takes precedence. Do not put password values in the manifest.

SQLite profiles use database (or connectionString) as a workspace-relative database file, or :memory: for a temporary database:

{
  "id": "local-sqlite",
  "name": "Local SQLite",
  "driver": "sqlite",
  "environments": { "local": { "database": "data/app.sqlite" } }
}

Local override

For local ports, VPN endpoints, or SSH tunnels, create .db-workspace/connections.local.json:

{
  "overrides": {
    "app-postgres.development": {
      "host": "127.0.0.1",
      "port": 15432
    }
  }
}

Add it to .gitignore:

.db-workspace/connections.local.json

Query files

Database	File
PostgreSQL	`.sql`
ClickHouse	`.sql`
MongoDB	`.mongodb.js`
Redis	`.redis`
SQLite	`.sql`

Select text and press Cmd+Enter on macOS or Ctrl+Enter elsewhere. With no selection, the entire file executes.

Connected database IntelliSense

After a profile is connected, SQL, MongoDB Query, and Redis editors offer database-aware completions with Ctrl+Space (or the platform equivalent). Suggestions include safe starter snippets plus the connected profile's schemas, tables/collections, columns, and scanned Redis keys where the adapter exposes them. Typing table. narrows SQL suggestions to that table's columns.

The provider uses the query file association or workbook cell target first, then the active connection. It never auto-connects an offline profile. Metadata is cached briefly and refreshed after connection changes.

Database workbooks

Run Database: New Workbook from the Command Palette to open a native VS Code notebook. Save it with the .dbworkbook extension.

Each code cell has its own database target. Use the database button in the cell toolbar or the target label below the cell to select it:

PostgreSQL: connection, environment, and its configured database
ClickHouse: connection, environment, and database
MongoDB: connection, environment, and database
Redis: connection, environment, and logical database number
SQLite: connection, environment, and its configured database file

Workbook target selection stops at the database; it does not require a schema, table, or collection. The selected driver automatically sets the cell language to SQL, MongoDB Query, or Redis Commands. Empty cells receive a database-neutral starter query, and existing query text is preserved when changing targets.

Use the standard notebook actions to run one cell, run all cells, cancel execution, reorder cells, and clear outputs. Results and errors render directly below each cell. Connection credentials are never written to the workbook; cells store only connection IDs and target metadata.

Workbook execution uses the same read-only enforcement, row limit, timeout, and query history as regular query files. MongoDB and ClickHouse cells execute against their selected database. Redis cells targeting a non-default logical database use an isolated client so they do not alter the shared connection state.

MongoDB supported syntax

db.collection("ticketDetails")
  .find({ requestCode: "N20072026360" })
  .project({ requestCode: 1, itemId: 1, unitPrice: 1 })
  .sort({ updatedAt: -1 })
  .limit(100);

Supported operations are find, findOne, aggregate, countDocuments, estimatedDocumentCount, and distinct. Supported cursor modifiers are project, sort, skip, and limit. Values support plain literals, objects, arrays, regular expressions, ObjectId, ISODate, and Decimal128.

The parser does not execute arbitrary JavaScript.

Redis commands

GET session:123
HGETALL ticket:price:N20072026360:203533
SCAN 0 MATCH "ticket:price:*" COUNT 100

Commands run sequentially. The explorer always uses SCAN; it never uses KEYS *. Destructive administrative and blocking commands are rejected by the MVP safety policy.

Safety

VS Code workspace trust is required before connecting.
Production profiles never auto-connect.
Production defaults to read-only.
Recognized write queries run immediately on profiles with readOnly: false; they do not show a confirmation prompt.
Recognized write queries are rejected on profiles with readOnly: true.
Legacy confirmWrites values in manifests or VS Code settings are accepted for compatibility but ignored; readOnly is the write-permission switch.
Queries the adapter cannot classify remain blocked by default. allowUnclassifiedQueries: true enables a guarded override for that environment; every override requires confirmation, and production requires typing the connection name.
allowUnclassifiedQueries never bypasses readOnly: true. Prefer adding classifier support for recurring statements instead of leaving the override enabled.
A server-side read-only database user is still strongly recommended.
Result rows are bounded by dbWorkspace.maxRows.
Query execution is bounded by dbWorkspace.queryTimeoutMs when supported by the server.

Development

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. By participating, you agree to follow CODE_OF_CONDUCT.md. Please report vulnerabilities through the private process in SECURITY.md, not a public issue.

npm install
npm run check
npm test
npm run compile

Press F5 from VS Code to launch an Extension Development Host. Package with:

npm run package

The checked-in .vscode/launch.json compiles the extension before launch. Set breakpoints in src/**, choose Run Database Workspace Extension, and press F5; source maps map the bundled extension back to TypeScript.

Maintainers can use the release checklist. See the changelog, contribution guide, support guide, and security policy for project details. Database Workspace is maintained by Phạm Văn Nguyên.

MVP limitations

The result grid is read-only.
MongoDB runs a safe subset of playground syntax, not a full mongosh runtime.
Redis key grouping and server/cluster administration are not included.
SQL executes the selection or the entire file; statement-under-cursor parsing is not included.
Backup, restore, migrations, schema editing, ERD, and DBA monitoring are outside this MVP.