NexQL

🐘 NexQL

Professional Database Management for VS Code

[](https://marketplace.visualstudio.com/items?itemName=ric-v.postgres-explorer) [](https://marketplace.visualstudio.com/items?itemName=ric-v.postgres-explorer) [](https://marketplace.visualstudio.com/items?itemName=ric-v.postgres-explorer) [](https://github.com/dev-asterix/NexQL/releases)

NexQL (formerly YAPE) is a comprehensive PostgreSQL database management extension featuring interactive SQL notebooks, real-time monitoring dashboard, AI-powered assistance, and advanced database operations—all within VS Code.

📖 Documentation • 🛒 Marketplace • [🤝 Contributing](#-contributing) • [📝 v2.2.1 Release Notes](CHANGELOG.md) • [📋 Full Changelog](CHANGELOG.md)

---

📺 Video Guides

1. Setup

2. More Settings

3. AI Assistant

4. AI Copilot

5. Dashboard

6. DB Operations

7. Power Editor

8. More Features

---

✨ Key Features

• 🔌 Secure Connections — VS Code SecretStorage encryption
• 🛡️ Connection Safety — Environment tagging (🔴 PROD, 🟡 STAGING, 🟢 DEV), read-only mode, query safety analyzer
• ⏱️ Performance Tracking — Historical query execution monitoring with degradation alerts
• 📊 Live Dashboard — Real-time metrics & query monitoring
• 🚦 Dashboard Health Signals — Status badges, lock/wait indicators, and performance-focused telemetry cards
• 📓 SQL Notebooks — Interactive notebooks with AI assistance
• 🗂️ Notebook Manager — Open/create notebooks with searchable picker and improved metadata context
• 💾 Saved Queries — Tag-based organization, connection context restoration, AI metadata generation, edit & reuse
• 🌳 Database Explorer — Browse tables, views, functions, types, FDWs
• 🛠️ Object Operations — CRUD, scripts, VACUUM, ANALYZE, REINDEX, plus triggers/sequences/domains/rules/partitions/publications/event triggers/tablespaces/aggregates
• 🏗️ Visual Table Designer — Create/Edit tables with a robust GUI
• 🧭 Definition Viewer (SQL Preview) — Open object DDL with toggleable SQL preview, copy/edit workflows, and routine scaffolding
• 🔑 Index & Constraint Manager — Visual management of DB constraints
• 🧠 Schema Intelligence — Schema search, index advisor, and migration generator workflows
• 📋 Smart Paste — Context-aware clipboard actions (SQL/CSV/JSON)
• 📊 Table Intelligence — Profile, activity monitor, index usage, definition viewer
• 🔍 EXPLAIN CodeLens — One-click query analysis directly in notebooks
• 🎛️ Advanced Result UX — Column stats, transpose view, enhanced filtering, sliding-window streaming for large SELECTs, configurable bytea display, and structured in-grid editing with explicit commit confirmation
• 🛡️ Auto-LIMIT — Intelligent query protection (configurable, default 1000 rows)
• 🌍 Foreign Data Wrappers — Manage foreign servers, user mappings & tables
• 🤖 AI-Powered — Zero-configuration NexQL Free AI (Smart/Engineer/Architect tiers), plus GitHub Models, OpenAI, Anthropic, Gemini, and VS Code LM. Generate, optimize, explain & analyze with guided follow-ups.
• 🧩 Flexible SQL Assistant Layout — Open SQL Assistant in editor tabs and keep multiple assistant tabs open simultaneously
• 🖱️ Drag & Drop Context — Drag tables, columns, functions, notebooks, or saved queries from the tree straight into the SQL Assistant as @mentions, or drop onto a notebook cell to insert a formatted reference
• 🖼️ Vision AI — Paste or upload images directly in the SQL Assistant; sent to vision-capable AI providers
• 📎 File Preview — Click attached file chips to open them as preview tabs in the editor
• 📤 Export Data — Export results to CSV, JSON, or Excel
• 🔌 MCP Server — Expose your database as read-only tools to Copilot, Cursor, Claude Desktop, and other MCP agents, with a fixed local port/token option for external clients

---

🎯 Why NexQL?

🎨 Modern Interface

• Beautiful, intuitive UI designed for developers
• Real-time dashboard with live metrics
• Context-aware operations
• Seamless VS Code integration

⚡ Powerful Features

• Interactive SQL notebooks
• 🤖 AI-powered Copilot & agentic support
• Table intelligence & performance insights
• Complete CRUD operations
• EXPLAIN CodeLens for query analysis

🛡️ Production-Ready Safety

• Environment tagging (Production/Staging/Dev)
• Read-only mode enforcement
• Query safety analyzer with risk scoring
• Auto-LIMIT for SELECT queries
• Status bar risk indicators

📊 Performance Insights

• Table profile with size & statistics
• Real-time activity monitoring
• Index usage analytics
• Bloat detection & warnings
• Query performance history & alerts
• Complete table definitions

---

📋 Feature Matrix

| Area | NexQL v2.2.1+ | Notes | |---|---|---| | Core PostgreSQL object operations | ✅ | Tables, views, mat views, functions, roles, extensions, FDWs, and more | | AI-assisted SQL workflows | ✅ | Generate, optimize, explain, and analyze with notebook-first execution | | Production safety controls | ✅ | Read-only mode, risk scoring, confirmation prompts, Auto-LIMIT | | Real-time monitoring dashboard | ✅ | Activity and health views in VS Code | | Interactive SQL notebooks | ✅ | Native .pgsql notebook execution with completions | | In-grid result editing parity with desktop IDEs | ⚠️ Partial | Stronger commit flow and tooling in v1.2.x; full parity still evolving | | ERD/schema visualization parity | ⚠️ Partial | Schema designer exists; ERD depth still evolving | | Advanced replication administration | ⚠️ Partial | Additional publication/subscription depth planned |

---

🌐 Platform Compatibility

NexQL works with any database that speaks the PostgreSQL wire protocol — not just self-hosted Postgres.

| Platform | Status | Tip | |---|---|---| | PostgreSQL 12–17 | ✅ Fully supported | Integration-tested every release | | Neon | ✅ Works | Use the direct (non--pooler) endpoint, SSL require | | Supabase | ✅ Works | Use direct or session pooler (port 5432); avoid transaction pooler (6543) | | TimescaleDB / Timescale Cloud | ✅ Fully compatible | It's a Postgres extension — everything works | | YugabyteDB (YSQL) | ✅ Mostly works | Port 5433; version-gated features fall back automatically | | AWS RDS / Aurora, Cloud SQL / AlloyDB, Azure Flexible | ✅ Works | Set SSL Mode require |

📖 Full matrix, connection guides, and caveats: [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md). First-class platform support (auto-detection, capability-aware menus, connection-string paste) is planned — see [the roadmap](docs/roadmap/4.postgres-compatible-platforms-roadmap.md).

---

🚀 Quick Start

# Install from VS Code
ext install ric-v.postgres-explorer

# Or via command line
code --install-extension ric-v.postgres-explorer

Then: PostgreSQL icon → Add Connection → Enter details → Connect!

---

Telemetry Setup

NexQL ships with a privacy-first telemetry client designed for anonymous product analytics.

• No SQL text, schema/object names, hostnames, database names, usernames, or credentials are collected.
• VS Code global telemetry setting is a hard gate; when disabled globally, NexQL telemetry is disabled.
• Event payloads are allowlisted and bucketed (durations/result sizes) to avoid raw sensitive values.

Configure telemetry mode

Set these in VS Code settings:

• postgresExplorer.telemetry.mode: off | basic | detailed (default basic)
• postgresExplorer.telemetry.allowUsage: allow anonymous usage counters (default true)
• postgresExplorer.telemetry.allowPerformance: allow anonymized performance buckets (default false)

Configure PostHog sink (optional)

For remote telemetry ingestion:

• postgresExplorer.telemetry.posthogHost: default https://us.i.posthog.com
• postgresExplorer.telemetry.posthogApiKey: your PostHog project key

If posthogApiKey is empty, telemetry stays local (debug sink only).

What to expect from telemetry

• Lifecycle: extension/session start and end events
• Activity: command and feature usage counters
• Connections: opened/closed/error with coarse error category
• Query execution: success/failure with duration/result-size buckets (detailed/performance-enabled mode)
• AI usage: provider-level success/failure counters

---

📚 Documentation Map

• README.md - Product overview, installation, development, and troubleshooting
• docs/COMPATIBILITY.md - Platform compatibility matrix (Neon, Supabase, TimescaleDB, YugabyteDB, RDS, …)
• docs/ARCHITECTURE.md - System architecture and component/data-flow details
• docs/STYLING_GUIDE.md - Centralized styling/templates and UI refactoring patterns
• docs/WEBSITE_CONTEXT.md - Website architecture and content context
• docs/API_STABILITY.md - v1.x API stability and deprecation policy
• docs/SECURITY_REVIEW.md - v1.0 security controls and release checklist
• docs/RELEASE_NOTES_v2.0.0.md - v2.0 highlights and release notes (rebranding, licensing & subscription)
• docs/RELEASE_NOTES_v1.0.0.md - v1.0 highlights and release notes
• docs/MIGRATION_GUIDE_0.x_to_1.0.0.md - upgrade path from 0.9.x to 1.0.0
• SECURITY.md - Security policy and vulnerability reporting guidance
• CHANGELOG.md - Release notes and what changed across versions

Stable: v2.2.1 | Nightly: v2.2.1+ — Drag-and-drop context from the explorer into chat/notebooks, a safer silent sign-in flow for NexQL Free AI, and a fixed MCP port/token option for external agent clients. See [CHANGELOG.md](CHANGELOG.md); v2.0 launch materials remain in [Release Notes](docs/RELEASENOTESv2.0.0.md) and older v1.0 details in [v1.0.0 Release Notes](docs/RELEASENOTESv1.0.0.md).

---

🏗️ Project Structure

NexQL/
├── src/
│   ├── extension.ts          # Extension entry point
│   ├── commands/             # Command implementations
│   │   ├── tables.ts         # Table operations
│   │   ├── views.ts          # View operations
│   │   ├── functions.ts      # Function operations
│   │   ├── connection.ts     # Connection commands
│   │   ├── notebook.ts       # Notebook commands
│   │   ├── helper.ts         # Shared helper utilities
│   │   ├── sql/              # SQL template modules
│   │   │   ├── tables.ts     # Table SQL templates
│   │   │   ├── views.ts      # View SQL templates
│   │   │   ├── functions.ts  # Function SQL templates
│   │   │   ├── indexes.ts    # Index SQL templates
│   │   │   └── ...           # Other SQL templates
│   │   └── ...
│   ├── providers/            # VS Code providers
│   │   ├── DatabaseTreeProvider.ts   # Tree view provider
│   │   ├── NotebookKernel.ts         # Notebook kernel
│   │   ├── ChatViewProvider.ts       # AI chat provider
│   │   ├── SqlCompletionProvider.ts  # IntelliSense
│   │   └── ...
│   ├── services/             # Business logic
│   │   ├── ConnectionManager.ts      # Connection handling
│   │   └── SecretStorageService.ts   # Credential storage
│   ├── dashboard/            # Dashboard webview
│   ├── common/               # Shared utilities
│   └── test/                 # Unit tests
├── resources/                # Icons & screenshots
├── docs/                     # Documentation & landing page
├── dist/                     # Compiled output (bundled)
├── out/                      # Compiled output (tsc)
├── package.json              # Extension manifest
├── tsconfig.json             # TypeScript config
└── webpack.config.js         # Webpack config

---

💾 Saved Queries Library

Organize, manage, and reuse your most important queries with intelligent tagging and context preservation.

Features

• 🏷️ Tag-Based Organization — Group queries by topic (e.g., "analytics", "maintenance", "daily-reports")
• 🔗 Connection Context — Queries remember their original connection, database, and schema
• 📓 Quick Reopening — Click "Open in Notebook" to restore the query with full context in a new notebook
• ✏️ Edit Anytime — Modify title, description, tags, and SQL without creating duplicates
• 🤖 AI Metadata — Auto-generate titles, descriptions, and tags using AI
• 📊 Rich Metadata Display — Hover to see creation date, last used, database, and schema

Usage

1. Save Query: Click "Save Query" CodeLens button on any SQL cell in a notebook
2. Add Metadata: Enter title, description, and tags (AI can help auto-generate)
3. Organize: Use tags to group related queries
4. Reuse: Click a saved query → "Open in Notebook" to restore with original context
5. Edit: Right-click any saved query → "Edit Query" to modify it

---

🤖 AI-Powered Operations

NexQL integrates advanced AI capabilities directly into your workflow, but keeps YOU in control.

🚀 NexQL Free AI — Zero-Config (Default)

No API keys, no provider accounts, no setup. NexQL Free AI is the default AI provider, powered by managed models behind a secure gateway proxy. Three tiered models available:

• 🧠 Smart (free) — Daily-use AI for queries, explanations, and schema help. ~600K tokens/month.
• 🔧 Engineer (Sponsor · $2/month) — Advanced model for tough optimization and migration problems. ~3M tokens/month (~5× free).
• 🏗️ Architect (Singularity · $9/month) — The best AI for database engineering. ~10M tokens/month (~16× free).

Configure your AI provider: Open VS Code Settings → search postgresExplorer.ai.chat.provider or run NexQL: Open AI Settings from the Command Palette. AI Settings documentation →

🔐 Bring Your Own Provider

Prefer your own keys? NexQL supports GitHub Models, OpenAI, Anthropic, Gemini, VS Code LM, Ollama, LM Studio, and custom endpoints. See [AI Settings](#-ai-powered-operations) for per-provider configuration.

🔐 GitHub Models via GitHub Sign-In

Use GitHub Models without manually managing a PAT in normal VS Code authentication flows.

• Native Sign-In: Connect with your GitHub account from AI Settings.
• Model Catalog Access: List and select available GitHub-hosted models.
• Session-Based Auth: Uses VS Code GitHub authentication sessions instead of storing provider tokens.

🧩 SQL Assistant Tabs

Use SQL Assistant where you work, not only in the sidebar.

• Open in Editor Tab: Run SQL Assistant: Open in Editor Tab from Command Palette.
• Parallel Assistants: Open multiple SQL Assistant tabs for separate tasks (e.g., optimization, migration, and schema exploration).

🪄 Generate Query (Natural Language → SQL)

Describe what you need in plain English (e.g., "Show me top 10 users by order count"), and NexQL will generate the SQL for you using your schema context.

• Command Palette: AI: Generate Query
• Context-Aware: The AI understands your table schemas, columns, and relationships.

⚡ Performance Optimization

Click the Optimize button on any successful query result.

• Explain Scripts: Generates EXPLAIN ANALYZE commands for deeper profiling.
• Static Analysis: Suggests missing indexes, query rewrites, or schema improvements.

📊 Data Analysis

Click the Analyze Data button in result tables.

• Clean Workflow: Automatically exports data to a temporary CSV and attaches it to the chat.
• Actionable Insights: AI summarizes patterns, trends, and outliers in your result sets.

✨ Error Handling (Explain & Fix)

When a query fails, get instant help directly in the error cell.

• Explain Error: Translates cryptic Postgres errors into plain English.
• Fix Query: Suggests corrected SQL to resolve the error.

🔌 MCP Server — New in v2.2.0

NexQL ships a built-in Model Context Protocol (MCP) server that exposes your connected PostgreSQL database as live-indexed tools, consumable by Copilot, Cursor, Claude Desktop, and any other MCP-compatible AI agent.

-

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dev-asterix
• Source: dev-asterix/NexQL
• License: MIT
• Homepage: http://nexql.astrx.dev/

Install and usage instructions live in the source repository linked above.