PgStudio

Prerequisites

• Node.js ≥ 18.0.0
• VS Code ≥ 1.105.0
• PostgreSQL for local and integration testing
• Docker for the compatibility test matrix

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 <code>packages/pro</code> checkout is present.

Install the published extension

```bash

Setup

```bash 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 <code>packages/pro</code> inside the Core checkout. The Core build scripts alias <code>@nexql/pro</code> to that path when present; see NexQL Pro or the project maintainers for access and packaging instructions.

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:

```bash

📦 Building and publishing

```bash

Build a VSIX

npx vsce package

🚀 Quick start

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.

Configure telemetry

Set these in VS Code settings:

• <code>postgresExplorer.telemetry.mode</code>: <code>off | basic | detailed</code> — default: <code>basic</code>
• <code>postgresExplorer.telemetry.allowUsage</code>: anonymous usage counters — default: <code>true</code>
• <code>postgresExplorer.telemetry.allowPerformance</code>: anonymized performance buckets — default: <code>false</code>

Optional PostHog sink

• <code>postgresExplorer.telemetry.posthogHost</code>: defaults to <code>https://us.i.posthog.com</code>
• <code>postgresExplorer.telemetry.posthogApiKey</code>: your PostHog project key

If <code>posthogApiKey</code> 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.

---

📺 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.

---

Run the extension

1. Open the Core project in VS Code.
2. Press <code>F5</code> to launch an Extension Development Host.
3. Or use Run and Debug → Run Extension.

Useful debugging surfaces:

• Output panel: <code>Ctrl+Shift+U</code> → select NexQL.
• Extension-host DevTools: <code>Ctrl+Shift+I</code>.
• Webview DevTools: right-click inside a webview → Inspect.

---

From VS Code

ext install ric-v.postgres-explorer

Publish to VS Code Marketplace

npx vsce publish

🔧 Troubleshooting