---

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:

1. Connect to a database and orient yourself in its schema.
2. Write and execute SQL in a native notebook.
3. Ask AI for schema-grounded help when the problem is ambiguous.
4. Inspect plans, activity, results, and performance signals.
5. 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

1. Add a connection and label its environment.
2. Expand a schema and open a table or function.
3. Open a .pgsql notebook and write a query.
4. Use Ctrl+Enter to execute the current cell.
5. Save the query with its connection and schema context.
6. 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:

1. Use the Save Query CodeLens action on a notebook cell.
2. Add a title, description, and tags.
3. Reopen it from the Saved Queries tree when the investigation returns.
4. 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

1. Ask — you describe the goal or trigger an analysis.
2. Ground — NexQL supplies selected live schema or result context.
3. Propose — AI produces SQL, an explanation, or an optimization path.
4. Review — you inspect the generated content in chat or a notebook.
5. 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

1. Open the Core project in VS Code.
2. Press F5 to launch an Extension Development Host.
3. 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

• 🐛 Report a bug
• 💡 Request a feature
• 🔧 Fork → branch → pull request
• 🧪 Run npm run test:all && npm run coverage before submitting

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

---