The PostgreSQL workbench for developers and AI agents
Intelligent PostgreSQL tooling for VS Code | Build, explore, and query Postgres faster
ดาว
14
เครื่องมือ
—
อัปไทม์
—
NexQL brings connection management, schema exploration, SQL notebooks, query intelligence, safe database operations, and AI-native workflows into the editor where you already build software: VS Code.
NexQL is designed for the full PostgreSQL workflow—not just sending a query and staring at a result grid.
Moment
What NexQL gives you
Connect
Secure connection storage, SSL, SSH tunnels, environment signals, and compatibility across PostgreSQL-wire databases
Explore
A fast database tree for schemas, tables, views, functions, types, roles, extensions, and foreign data wrappers
Query
Native .pgsql notebooks, completion, saved queries, result streaming, export, and keyboard-first execution
Understand
EXPLAIN CodeLens, query history, table intelligence, index usage, activity monitoring, and visual result analysis
Operate
Guarded CRUD and DDL workflows, maintenance commands, transactions, object definition viewers, and migration-friendly SQL
Extend
AI assistance and MCP tools that ground compatible agents in the live database while keeping execution human-approved
Built for real database work
Schema and application development — inspect objects, write repeatable notebook workflows, and move from a failing query to a tested fix.
Production investigation — distinguish environments at a glance, inspect activity and locks, profile tables, and diagnose regressions without leaving VS Code.
Performance engineering — run EXPLAIN workflows, review plan shape, inspect index usage, and keep query history close to the code that caused it.
Data exploration — filter, transpose, inspect column statistics, stream large results, create charts, and export only what you need.
AI-assisted engineering — generate, explain, optimize, and analyze SQL with schema-aware context; connect MCP-capable agents to safe live database tools.
NexQL is built around a simple principle: make database work feel like software work—contextual, reviewable, repeatable, and close to the code.
📺 See the workflow
The NexQL website includes an interactive VS Code workbench demo covering the complete product loop:
Connect to a database and orient yourself in its schema.
Write and execute SQL in a native notebook.
Ask AI for schema-grounded help when the problem is ambiguous.
Inspect plans, activity, results, and performance signals.
Make a controlled change with the right environment context.
✨ Capability map
Connection and environment safety
Credentials stored with VS Code SecretStorage encryption.
Environment tagging for PROD, STAGING, and DEV.
Read-only mode, risk scoring, confirmation prompts, and configurable Auto-LIMIT protection.
SSL modes, CA certificates, SSH tunneling, and PostgreSQL-compatible cloud connection support.
Pooler-aware guidance for services such as Neon and Supabase.
Built-in MCP integration for schema discovery, safe SELECT, EXPLAIN, join-path inference, table statistics, and index usage.
The default AI workflow is notebook-first: AI proposes SQL, you review it, and you choose when to execute it.
Core, Pro, and the product you install
NexQL uses an open-core architecture:
NexQL Core is this MIT-licensed repository. It contains the open-source extension foundation, connection and explorer workflows, notebooks, database operations, safety primitives, testing infrastructure, and extension seams.
NexQL Pro is the published Marketplace/Open VSX build. It layers premium product capabilities—including AI chat, MCP, dashboard, Plan Studio, backup and restore, visual schema design, and database indexing—on top of Core.
Both distributions are built from the same product direction. Core is intentionally usable on its own and intentionally extensible.
This distinction matters when building locally: a Core checkout produces the free/OSS build unless a sibling packages/pro checkout is present.
📋 Capability and availability matrix
Area
Core / OSS
Marketplace / Pro
Secure connections, SSL, SSH, and environment signals
✅
✅
Database explorer and PostgreSQL object operations
✅
✅
SQL notebooks, completions, saved queries, and exports
✅
✅
Query safety, read-only mode, Auto-LIMIT, and confirmation flows
✅
✅
EXPLAIN workflows, result tooling, and core performance services
✅
✅
AI chat and provider integrations
Extension seam
✅
Live monitoring dashboard
Extension seam
✅
MCP server and agent tools
Extension seam / bundled integration points
✅
Backup and restore
—
✅
Database indexing and semantic grounding
—
✅
Plan Studio and visual schema designer
—
✅
The exact premium surface evolves with the published build. See CHANGELOG.md and the NexQL website for the current product surface.
🌐 PostgreSQL, wherever it runs
NexQL speaks the PostgreSQL wire protocol, so it works with self-hosted databases, local containers, managed services, and compatible distributed systems.
Platform
Status
Connection note
PostgreSQL 12–17
✅ Supported
Integration-tested across the supported release range
Neon
✅ Works
Prefer the direct, non-pooler endpoint with SSL require
Supabase
✅ Works
Use direct or session pooler connections; avoid transaction pooler for interactive sessions
TimescaleDB / Timescale Cloud
✅ Compatible
PostgreSQL extension compatibility
YugabyteDB (YSQL)
✅ Mostly compatible
Use port 5433; capability-gated features fall back when needed
AWS RDS / Aurora
✅ Works
Use the provider’s SSL requirements
Google Cloud SQL / AlloyDB
✅ Works
Use the provider’s SSL requirements
Azure Database for PostgreSQL Flexible Server
✅ Works
Set SSL mode to require or stronger
See docs/COMPATIBILITY.md for the detailed matrix, provider-specific settings, and caveats.
🚀 Quick start
Install the published extension
# From VS Code
ext install ric-v.postgres-explorer
# Or from a terminal
code --install-extension ric-v.postgres-explorer
Then open the PostgreSQL activity-bar view, choose Add Connection, enter your details, and connect.
Your first useful loop
Add a connection and label its environment.
Expand a schema and open a table or function.
Open a .pgsql notebook and write a query.
Use Ctrl+Enter to execute the current cell.
Save the query with its connection and schema context.
Use EXPLAIN, table intelligence, or result analysis when the question becomes a performance question.
Keyboard shortcuts
Shortcut
Action
Ctrl+Enter
Execute the current cell
Shift+Enter
Execute and move to the next cell
F5
Refresh the current item
Ctrl+Shift+P
Open the Command Palette
💾 Saved queries: turn investigations into reusable knowledge
Saved Queries preserves the context that usually gets lost after a database investigation:
Tag-based organization — group queries by topic such as analytics, maintenance, or daily reports.
Connection context — remember the original connection, database, and schema.
One-click reopening — restore the query in a notebook with its original context.
In-place editing — update title, description, tags, and SQL without creating duplicates.
Optional AI metadata — generate titles, descriptions, and tags when the published AI surface is enabled.
Typical workflow:
Use the Save Query CodeLens action on a notebook cell.
Add a title, description, and tags.
Reopen it from the Saved Queries tree when the investigation returns.
Edit it in place as the schema or operational question evolves.
🛠️ Database operations at a glance
NexQL keeps common administration actions discoverable while preserving the SQL underneath:
Availability, quotas, and pricing can change; use AI Settings and the current Marketplace listing for the latest details.
Bring your own provider
Configure NexQL to use GitHub Models, GitHub Copilot/VS Code LM, OpenAI, Anthropic, Gemini, Ollama, LM Studio, or a custom OpenAI-compatible endpoint. Provider configuration is exposed through postgresExplorer.ai.chat.provider and NexQL: Open AI Settings.
MCP for compatible agents
The published product can expose live, read-focused database tools to GitHub Copilot, Cursor, Claude Desktop, Codex, and other MCP-compatible clients:
Discover schemas and objects.
Describe objects and search schema metadata.
Run safe SELECT statements.
Explain queries.
Infer join paths.
Inspect table statistics and index usage.
By default, VS Code can spawn the bundled nexql-mcp binary through stdio. For external clients, NexQL also supports an optional fixed port and SecretStorage-backed bearer token. SSH-tunneled connections are intentionally excluded from ephemeral MCP profiles; managed TLS profiles carry the relevant certificate settings.
Configure MCP from NexQL Settings → Preferences. Use postgresExplorer.mcp.binaryPath to override binary resolution when debugging or packaging.
Safe execution model
Ask — you describe the goal or trigger an analysis.
Ground — NexQL supplies selected live schema or result context.
Propose — AI produces SQL, an explanation, or an optimization path.
Review — you inspect the generated content in chat or a notebook.
Execute — you explicitly run the cell when you are ready.
No query is executed automatically by the notebook-first AI workflow.
🔒 Privacy and telemetry
NexQL ships a privacy-first telemetry client for anonymous product analytics:
SQL text, schema and object names, hostnames, database names, usernames, and credentials are not collected.
VS Code’s global telemetry setting is a hard gate; when disabled globally, NexQL telemetry is disabled.
Event payloads are allowlisted and bucketed, including durations and result sizes, to avoid raw sensitive values.
Configure telemetry
Set these in VS Code settings:
postgresExplorer.telemetry.mode: off | basic | detailed — default: basic
postgresExplorer.telemetry.posthogApiKey: your PostHog project key
If posthogApiKey is empty, telemetry remains local through the debug sink.
Tracked event families include lifecycle, feature usage, connection outcomes, query success/failure with coarse buckets, and provider-level AI outcomes.
📚 Documentation map
README.md — product overview, architecture, installation, development, and troubleshooting
docs/COMPATIBILITY.md — platform compatibility matrix and provider caveats
docs/ARCHITECTURE.md — system architecture and component/data-flow details
docs/STYLING_GUIDE.md — centralized styling and UI refactoring patterns
docs/TESTING.md — test strategy and execution notes
SECURITY.md — vulnerability reporting and security policy
CHANGELOG.md — release history and migration-relevant changes
walkthroughs/ — guided onboarding steps for connections, explorer, notebooks, and sync
Stable: v2.4.0 · Nightly: v2.5.0
See CHANGELOG.md for the current release notes and the website for product-level updates.
🏗️ Project structure
NexQL-Core/
├── src/
│ ├── extension.ts # Extension entry point
│ ├── commands/ # Database and notebook commands
│ │ ├── sql/ # Reusable SQL template modules
│ │ └── ...
│ ├── providers/ # Tree, notebook, completion, and chat seams
│ ├── services/ # Connections, secrets, query history, telemetry
│ ├── renderer/ # Notebook result rendering and interactions
│ ├── ui/ # Shared UI and renderer components
│ ├── pro/ # Core ↔ Pro integration seam and stubs
│ └── test/ # Unit, integration, and renderer tests
├── resources/ # Icons, styles, and bundled assets
├── docs/ # Technical documentation
├── walkthroughs/ # Guided in-product onboarding content
├── scripts/ # Build, package, test, and release helpers
├── package.json # Extension manifest and scripts
└── tsconfig*.json # TypeScript configurations
🛠️ Local development
Prerequisites
Node.js ≥ 18.0.0
VS Code ≥ 1.105.0
PostgreSQL for local and integration testing
Docker for the compatibility test matrix
Setup
git clone https://github.com/NexQL-OSS/NexQL-Core.git
cd NexQL-Core
npm ci
# Compile the Core build
npm run compile
To work on the Pro build, clone the private Pro repository as packages/pro inside the Core checkout. The Core build scripts alias @nexql/pro to that path when present; see NexQL Pro or the project maintainers for access and packaging instructions.
Development commands
Command
Description
npm run watch
Watch TypeScript and recompile
npm run compile
One-time TypeScript compilation
npm run esbuild
Build the free/OSS bundle with source maps
npm run esbuild:pro
Build the Pro bundle when packages/pro is available
npm run esbuild-watch
Watch extension and renderer bundles
npm run lint
Run ESLint
npm run format
Check Prettier formatting
npm run test
Compile and run unit tests
npm run test:all
Run the complete test suite
npm run coverage
Run unit tests with coverage
npm run vscode:prepublish
Produce the free release build
Run the extension
Open the Core project in VS Code.
Press F5 to launch an Extension Development Host.
Or use Run and Debug → Run Extension.
Useful debugging surfaces:
Output panel: Ctrl+Shift+U → select NexQL.
Extension-host DevTools: Ctrl+Shift+I.
Webview DevTools: right-click inside a webview → Inspect.
🧪 Testing
Standard commands
npm ci
npm run test:all
npm run coverage
# Focused suites
npm run test:unit
npm run test:integration
npm run test:renderer
Docker-based PostgreSQL matrix
make docker-up
npm run test:integration
make docker-down
The test infrastructure covers:
Unit behavior with Mocha, Chai, and Sinon.
Connection lifecycle, SSL, pool exhaustion, SSH, and version compatibility.
Renderer components, tree views, forms, notebooks, and dashboards.
PostgreSQL 12, 14, 15, 16, and 17 containers.
CI matrix coverage across Node.js 18–22 and PostgreSQL 12–17.
The repository also provides focused Make targets:
make test-unit
make test-integration
make test-renderer
make test-all
make coverage
make test-full
feat: add a feature
fix: resolve a defect
docs: improve documentation
refactor: restructure code
test: add or update tests
chore: maintain tooling
📦 Building and publishing
# Build a VSIX
npx vsce package
# Publish to VS Code Marketplace
npx vsce publish
# Publish to Open VSX
npx ovsx publish
Stable and nightly channels
Stable releases use version tags (v*) in the Pro publishing repository.
Nightly releases are published as pre-releases from the nightly workflow.
Stable extension ID: ric-v.postgres-explorer.
Open VSX nightly companion ID: ric-v.postgres-explorer-nightly.
In VS Code, switch through Switch to Pre-Release Version or Switch to Release Version.
On Open VSX-based editors, uninstall the nightly companion to return to stable.
The Core repository itself does not contain Marketplace secrets or the Pro publishing workflows. Publishing responsibilities live with the Pro distribution.
📝 License and open-core notice
This repository is available under the MIT License.
The Core checkout builds a fully working free/OSS extension with make package-free. Anyone may fork, rebrand, and publish that build under their own extension ID. The ric-v.postgres-explorer Marketplace/Open VSX product is the Pro build: Core plus proprietary premium features maintained in the private Pro repository.
Repository history before the open-core split may contain formerly bundled premium sources under MIT. New premium development belongs in the Pro repository and should connect through the documented Core ↔ Pro seam.
🔧 Troubleshooting
SSL connection failures
Symptoms: SSL connection failed or certificate verify failed.
Use disable only for local development.
Try prefer when the server supports both modes.
For verified connections, use verify-ca and provide the CA certificate path.
Check the provider’s required SSL mode and certificate chain.
Connection timeouts
Symptoms: Connection timeout or ETIMEDOUT.
Increase the connection timeout in settings.
Check firewall and security-group rules.
Verify pg_hba.conf allows the client.
Confirm PostgreSQL is listening on the expected interface and port.
SSH tunnel failures
Verify the SSH host, user, key, and port.
Test manually with ssh user@host -p port.
Check private-key permissions with chmod 600 ~/.ssh/id_rsa.
Confirm the SSH server allows port forwarding.
Large result sets
NexQL bounds result rendering and supports configurable limits plus sliding-window streaming. Use an explicit LIMIT for targeted investigations and increase result settings only when you understand the memory and network cost.
Slow tree view
Filter the tree to narrow the object set.
Collapse unused schemas.
Disable object-count badges when working with very large catalogs.
Prefer a targeted schema search for high-cardinality databases.
Common errors
Error
Likely cause
First check
password authentication failed
Wrong credentials
Verify the username, password, and auth method
database does not exist
Incorrect database name
Confirm the target database
permission denied
Insufficient privileges
Grant the required object or schema permissions
too many connections
Pool exhaustion
Close unused sessions and review pool settings
no pg_hba.conf entry
Access-control mismatch
Add a matching pg_hba.conf rule
How NexQL is different
NexQL is intentionally opinionated about the developer workflow:
Capability
NexQL
Native VS Code integration
Database work lives beside application code
SQL notebooks
Queries, context, outputs, and reasoning stay together