Your first fifteen minutes.

Install it in a minute.

NexQL is a VS Code extension. Install it from the Marketplace, or from Open VSX if your editor reads that instead.

Or paste this into VS Code’s Quick Open (Ctrl+P), or run the second line in a terminal.

ext install ric-v.postgres-explorer

$ code --install-extension ric-v.postgres-explorer

Where NexQL shows up

A NexQL icon appears in the activity bar. It opens four views; the last three start collapsed.

• ConnectionsThe database tree. Open by default.
• NotebooksYour .pgsql notebooks, with folders.
• Saved QueriesThe query library.
• Query HistoryWhat ran, and how long it took.

NexQL Bot, the AI assistant, has its own icon in the activity bar. Pick the NexQL icon, add a connection in the next stop, and the Connections view fills in.

NexQL Bot, the live dashboard and the visual designers ship in the published build (Marketplace and Open VSX). The MIT-licensed core is the open-source foundation under it.

Add your first connection.

Three ways in. All three end with a connection in the Connections view. Set its environment now, while you are in the form.

1. 1

   Add PostgreSQL Connection

   Command Palette, or the + button on the Connections view. Ctrl+Alt+A (Cmd+Alt+A on macOS).

   Opens the connection form. Fill in host, port, database, user and password, or paste a postgresql:// URL and press Apply URL. Press Test Connection; once it passes, Add Connection appears.

2. 2

   Import Connection from DATABASE_URL (.env)

   The … menu on the Connections view.

   Scans .env, .env.local, .env.development and .env.production in your workspace for DATABASE_URL-style keys. Pick one if there are several, or paste a URL if there are none, then name it.

3. 3

   Add Connection from Clipboard URL

   Command Palette, or the … menu on the Connections view.

   Copy a postgres:// or postgresql:// URL first. Choose Add connection to save it as is, or Open in connection editor to review the fields before saving.

Import and Clipboard save the connection straight away, with no environment label and no SSH tunnel. Right-click the new connection and choose Edit Connection to add them.

Set the environment now

In the form, Environment is a dropdown: None, Development, Staging or Production. NexQL uses it to tint the status bar and to decide when to ask before a write (stop 6). Picking Production also shows a banner that offers to switch on Read-Only Mode. Try the choices below.

SSL and SSH

• SSL Mode is under Advanced Options: Default (prefer), disable, allow, prefer, require, verify-ca, verify-full. Choose verify-ca or verify-full and the form asks for a CA certificate path, plus an optional client certificate and key.
• SSH Tunnel is its own section: tick Enable SSH Tunnel, then give the SSH host, port (22 by default), user and the path to your private key.
• Managed Postgres (Neon, Supabase, AWS RDS and others) usually wants require or stronger.

Where the password goes

The form says it under the field: Stored in VS Code secret storage. That is VS Code’s encrypted SecretStorage, not your settings file.

Walk the schema.

The Connections view is a live tree of the catalog. Right-click anything to see what you can do with it.

Expand a connection to reach its databases, then schemas, then tables, views, functions and the rest. Use Refresh Connections in the view toolbar if the tree looks stale; it also polls for schema changes every 30 seconds. To jump straight to an object, run Search Schema Objects (Ctrl+Shift+O).

What right-click on a table offers

Scripts holds SELECT Script, INSERT Script, UPDATE Script, DELETE Script, CREATE Script. Maintenance holds VACUUM, ANALYZE, REINDEX. Table Designer, Schema Diff, Import Data and Attach to NexQL Bot are part of the published build.

Open the table’s data

Click the table icon on the row, or right-click and choose View Table Data. For a SQL view of the same table, use Scripts → SELECT Script, or New PostgreSQL Notebook to start a notebook already pointed at it. Selecting an object also opens its definition in the Definition Viewer; turn that off with nexql.ddlViewer.openOnSelection.

Run your first query.

Queries live in .pgsql notebooks. Each cell keeps its own results, so you can come back to them.

1. Run New PostgreSQL Notebook from the Command Palette (Ctrl+Alt+N), or use the notebook icon on a connection, schema or table. You get a .pgsql notebook tied to that connection.
2. Type SQL into a cell. This one works on any database:

SELECT table_schema, table_name
FROM information_schema.tables
WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
ORDER BY 1, 2;

3. Press Ctrl+Enter to run the cell, or Shift+Enter to run it and move to the next.
4. Read the result below the cell. The grid has filtering, column statistics and a transpose view; the footer has All, Copy (as CSV), Import, Export and Ask AI.

SELECT table_schema, table_name
FROM   information_schema.tables
WHERE  table_schema NOT IN ('pg_catalog', 'information_schema')
ORDER BY 1, 2;

Export and keep

• Export in the result footer writes the result out as CSV, JSON or Excel.
• The cell toolbar has Save Query to Library (it lands in Saved Queries), Explain Analyze and Toggle Full Dataset Mode.
• Export Notebook (HTML / Gist) in the notebook toolbar shares the whole notebook.
• Pick another database for the notebook with Switch Notebook Connection.

Keyboard shortcuts

Ctrl+Enter and Shift+Enter are VS Code’s notebook defaults; the rest are NexQL’s own. Query Tool opens a notebook unless postgresExplorer.query.defaultExperience is set to queryStudio.

Turn on the assistant.

NexQL Bot works out of the box with no key and no account. Bring your own provider when you want to. It writes SQL; you press play.

• Open NexQL Bot from its activity bar icon, or run NexQL Bot: Open in Editor Tab to give it a full tab.
• No key needed. The default provider is NexQL Free AI (postgresExplorer.ai.chat.provider is nexql-free). Ask a question and you are done.
• Give it your schema. Click Attach to NexQL Bot on a table, view or schema in the tree, or drag tables, columns and notebooks into the chat. The answer is grounded in what is really in your database.
• Nothing runs until you press play. The assistant proposes SQL and you review it in a notebook cell first.

Good first questions

• which tables have no primary key?
• how do orders relate to customers?
• top customers by revenue this quarter
• which indexes are we paying for and not using?

From a notebook, the cell toolbar also has Ask AI and Chat with Query. The commands NexQL: AI: Generate Query and NexQL: AI: Optimize Query are in the Command Palette.

Bring your own provider

Run AI Settings from the Command Palette, pick a provider, and add its key or endpoint. Keys go into VS Code SecretStorage, never into settings.json. The Bot and notebook AI each have a provider setting, so you can use different ones.

• NexQL Free AI
• VS Code LM
• GitHub Models
• Cursor
• OpenCode
• OpenAI
• Anthropic
• Gemini
• Ollama
• LM Studio
• Custom endpoint

{
  // Default: "nexql-free". Others: "openai", "anthropic", "gemini", "ollama", ...
  "postgresExplorer.ai.chat.provider": "anthropic",
  // Notebook AI (Ask AI on a cell) has its own provider
  "postgresExplorer.ai.notebook.provider": "anthropic"
}

Ollama and LM Studio run models on your own machine. Add postgresExplorer.ai.chat.model to pick a model; leave it empty for the provider’s default.

Be careful on production.

Label the environment, turn on read-only where it fits, and keep auto-LIMIT on. These are the settings that do the work.

UPDATE orders SET status = 'void' WHERE id = 4182;

The settings behind it

Open Preferences: Open User Settings (JSON) and add what you want. These are the defaults, apart from queryTimeout, which is off by default.

{
  // Append LIMIT to SELECTs that have none (default: true)
  "postgresExplorer.query.autoLimitEnabled": true,
  // Rows that auto-LIMIT allows (default: 1000)
  "postgresExplorer.performance.defaultLimit": 1000,
  // Stop queries after this many ms (default: 0, no timeout)
  "postgresExplorer.queryTimeout": 30000
}

{
  // Tint the status bar by environment (default: true)
  "postgresExplorer.sentinel.statusBarAccent": true,
  // Tint the title bar and activity bar too (default: true)
  "postgresExplorer.sentinel.chromeAccent": true,
  // [P] [S] [D] badges on notebook tabs (default: true)
  "postgresExplorer.sentinel.tabBadges": true,
  // Notify when the focused notebook changes environment (default: false)
  "postgresExplorer.sentinel.notifyOnTransition": true
}

Sentinel is the name for the environment signals. NexQL: Sentinel: Toggle Notebook Context Strip and NexQL: Sentinel: Open Sentinel Settings are in the Command Palette. The environment itself, and read-only, are per connection, so they live in the connection form rather than in settings.json.