🐘 NexQL
The PostgreSQL workbench for developers and AI agents
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.
📖 Documentation · 🛒 Marketplace · 🌐 NexQL OSS · 🤝 Contributing · 📝 Changelog
One workbench. Every database moment.
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.
A database explorer that stays close to your code
- Browse databases, schemas, tables, views, materialized views, functions, procedures, aggregates, types, roles, extensions, sequences, triggers, partitions, publications, event triggers, tablespaces, and FDWs.
- Open object definitions as readable SQL with copy, edit, and routine scaffolding workflows.
- Create and modify tables with a visual designer where available.
- Manage indexes and constraints without losing the underlying SQL.
- Drag tables, columns, functions, notebooks, and saved queries into the SQL Assistant as context.
Notebooks, results, and reusable knowledge
- Native .pgsql notebooks with persistent cells, rich output, completions, and execution history.
- Saved query library with tags, connection context restoration, in-place editing, and optional AI-generated metadata.
- Result grids with filtering, column statistics, transpose view, structured in-grid editing, and explicit commit confirmation.
- Sliding-window streaming for large SELECT results.
- Configurable bytea rendering for hex, PostgreSQL, and JSON-debug workflows.
- Export results to CSV, JSON, or Excel.
- One-click charts for bar, line, area, pie, doughnut, and scatter exploration.
Performance and operational intelligence
- EXPLAIN CodeLens directly from notebook cells.
- Historical query execution tracking with degradation signals.
- Table profiles covering size, statistics, activity, index usage, and bloat indicators.
- Live activity monitoring with lock/wait status and health-focused telemetry cards.
- Index and constraint management, plus schema search and migration-oriented workflows.
AI and agent connectivity
- Natural language to SQL with live schema context.
- Query explanation, optimization guidance, error translation, and result-set analysis.
- Multiple SQL Assistant tabs for parallel investigations.
- Provider flexibility: NexQL Free AI, GitHub Models, GitHub Copilot/VS Code LM, OpenAI, Anthropic, Gemini, Ollama, LM Studio, and custom OpenAI-compatible endpoints.
- 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:
| Object | Operations |
|---|
| Tables | View, edit, insert, update, delete, truncate, drop, VACUUM, ANALYZE, REINDEX |
| Views | View definition, edit, query data, drop |
| Materialized views | Refresh, view data, edit, drop |
| Functions and procedures | View, edit, call with parameters, drop |
| Types and domains | View properties, edit, drop |
| Foreign data wrappers | Create/drop servers, user mappings, import schema |
| Foreign tables | View, edit, drop |
| Extensions | Enable, disable, drop |
| Roles | Grant/revoke permissions, edit, drop |
The available operation set is capability-aware and may vary by PostgreSQL version, permissions, and compatible platform.
🤖 AI and MCP: capability without blind execution
NexQL treats AI as a database-aware collaborator, not an unattended production operator.
NexQL Free AI
The published product offers a zero-configuration managed provider:
- Smart — everyday query generation, explanations, and schema help.
- Engineer — deeper optimization and migration support.
- Architect — advanced database engineering workflows.
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.allowUsage: anonymous usage counters — default: true
- postgresExplorer.telemetry.allowPerformance: anonymized performance buckets — default: false
Optional PostHog sink
- postgresExplorer.telemetry.posthogHost: defaults to https://us.i.posthog.com
- 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
- MARKETPLACE.md — concise Marketplace-facing product description
- 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
For platform-specific helpers:
# Linux/macOS
./scripts/test.sh --unit
./scripts/test.sh --integration --pg 16
./scripts/test.sh --coverage
# Windows
scripts\test.bat --unit
scripts\test.bat --integration --pg 16
scripts\test.bat --coverage
🤝 Contributing
Use Conventional Commits:
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 |
| Safety signals | Environment tags, read-only mode, risk scoring, confirmation, Auto-LIMIT |
| Performance workflow | EXPLAIN, activity, table intelligence, index signals, and query history |
| AI workflow | Schema-aware assistance with explicit human approval before execution |
| Agent workflow | MCP tools grounded in the live database rather than copied schema snippets |
| Open core | A usable MIT Core with a clear extension seam for the Pro product |
Made with ❤️ for the PostgreSQL community
Also available on Open VSX
