# NexQL Core > Intelligent PostgreSQL tooling for VS Code | Build, explore, and query Postgres faster - **Type:** MCP server - **Install:** `agentstack add mcp-nexql-oss-nexql-core` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [NexQL-OSS](https://agentstack.voostack.com/s/nexql-oss) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [NexQL-OSS](https://github.com/NexQL-OSS) - **Source:** https://github.com/NexQL-OSS/NexQL-core - **Website:** http://nexql.astrx.dev/ ## Install ```sh agentstack add mcp-nexql-oss-nexql-core ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 🐘 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**](https://nexql.astrx.dev/) β€’ [πŸ›’ **Marketplace**](https://marketplace.visualstudio.com/items?itemName=ric-v.postgres-explorer) β€’ [🀝 **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 `SELECT`s, 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 ```bash # 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/RELEASE_NOTES_v2.0.0.md) and older v1.0 details in [v1.0.0 Release Notes](docs/RELEASE_NOTES_v1.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 ``` --- ## πŸ’Ύ 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 β†’](https://nexql.astrx.dev/#ai) ### πŸ” 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. - **Auto-Discovery** β€” Registers with VS Code's M … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [NexQL-OSS](https://github.com/NexQL-OSS) - **Source:** [NexQL-OSS/NexQL-core](https://github.com/NexQL-OSS/NexQL-core) - **License:** MIT - **Homepage:** http://nexql.astrx.dev/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-nexql-oss-nexql-core - Seller: https://agentstack.voostack.com/s/nexql-oss - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.