🚀 Orbit.nvim

A database IDE for Neovim

Your database revolves around your editor, not the other way around.

Orbit runs statements through your existing database CLI, retains one connection per profile where the CLI supports it, keeps profiles per query buffer, browses schemas, completes cached objects, and renders JSON results in a navigable grid.

Contents

• What It Does
• Requirements
• Installation
• Quick Start
• Connection Profiles
• Workspace Workflow
• Commands
• Keybindings
• Completion
• Structure Panel
• Execution And Results
• Configuration

What It Does

• Open one dedicated workspace tab with a searchable profile and schema browser.
• Run a whole statement or a visual selection asynchronously without leaving Neovim.
• Bind each query buffer to its own connection profile.
• Browse tables, views, and columns; run connector-specific object actions; create a bound sample statement; copy qualified object names.
• Inspect and copy raw result values, including structured JSON values.
• Confirm potentially mutating statements before they run.
• Complete cached tables, views, columns, and table aliases, clause-aware, through a blink.cmp source.
• Browse reusable SQL files from multiple named saved-query locations.

Requirements

• Neovim 0.10 or later.
• No required third-party Neovim plugins.
• The CLI required by each connection profile:

Profile kind	CLI	Notes
trino	trino	Orbit requests JSON output.
sqlite	sqlite3	Requires a build that supports -json.
postgres	psql	Requires a version that supports --csv.
vertica	vsql	Uses HTML table output.

Installation

With lazy.nvim:

{
  "mrpbennett/orbit.nvim",
  opts = {},
}

Or call setup from your Neovim configuration:

require("orbit").setup()

Quick Start

1. Run :OrbitProfiles. This creates ~/.local/share/orbit.nvim/profiles.json with owner-only (0600) permissions and opens it for editing.
2. Add a connection profile using the format below.
3. Open :OrbitWorkspace or a SQL buffer.
4. Bind a profile with :OrbitProfile, or press <CR> on a profile in the workspace.
5. Run :OrbitExecute, or use <leader>E in Normal or Visual mode in a SQL buffer.

If a query buffer has no profile, executing it opens profile selection and retries after you choose one.

Supported Connectors

Kind	Required options	Optional options	Schema support
trino	server, user, catalog	schema, schema_patterns, executable, arguments, confirm_mutations	Tables, views, and columns from information_schema. Omitting schema browses the catalog except information_schema.
sqlite	path	schema_patterns, executable, arguments, confirm_mutations	Tables and views from sqlite_master, plus columns from PRAGMA table_info, under main.
postgres	database	schema_patterns, host, port, user, password, sslmode, executable, arguments, confirm_mutations	Tables and views outside PostgreSQL system schemas, plus columns, primary keys, foreign keys, and indexes.
vertica	host, user, database	schema_patterns, port, password, sslmode, executable, arguments, confirm_mutations	User tables and views, plus columns, primary keys, foreign keys, projections, and view definitions.

executable replaces the CLI binary and arguments adds an array of string arguments before Orbit's generated arguments. This is useful for wrappers or CLI-specific authentication flags. For SQLite, PostgreSQL, and Vertica, Orbit retains one interactive CLI connection per profile; statements, schema browsing, and completion prewarming share it and are serialized per profile. A changed profile definition, failed CLI, :OrbitDisconnect, or Neovim exit closes the connection; the next request reconnects automatically. Trino statements instead run one trino CLI invocation per statement, serialized per profile, because the trino CLI does not flush its output while held open on a retained connection.

Schema browsing and completion cache rows only while the connection profile's kind and options are unchanged. Updating a profile clears its prior schema rows before Orbit acquires replacements. Connector metadata that is unavailable for an object, such as Trino primary keys, is shown as unavailable rather than treated as a statement failure. Explicit Workspace refreshes run after pending acquisitions and coalesce with other refresh requests.

schema_patterns restricts the tables and views shown by Orbit's Workspace schema browser, but does not change database permissions or restrict statements you run manually. For Trino, it maps each catalog to an array of exact schema names; use an empty array to include every non-system schema from that catalog. PostgreSQL, SQLite, and Vertica use a non-empty array of exact schema names instead. SQLite's only available schema is main.

Connection Profiles

The profile file is the source of truth for named connection profiles. Its default location is ~/.local/share/orbit.nvim/profiles.json; set profile_path in setup() to use another location. Orbit refuses to load a file that is not mode 0600.

Profiles are JSON, versioned at 1, and names must be unique:

PostgreSQL

{
  "version": 1,
  "profiles": [
    {
      "name": "app-db",
      "kind": "postgres",
      "options": {
        "database": "postgres",
        "host": "postgres.example.com",
        "port": 5432,
        "user": "postr",
        "password": "somePassword",
        "sslmode": "require"
      }
    }
  ]
}

Vertica

{
  "version": 1,
  "profiles": [
    {
      "name": "warehouse",
      "kind": "vertica",
      "options": {
        "host": "vertica.example.com",
        "port": 5433,
        "database": "warehouse",
        "user": "alice",
        "password": "somePassword",
        "sslmode": "require"
      }
    }
  ]
}

SQLite

{
  "version": 1,
  "profiles": [
    {
      "name": "local",
      "kind": "sqlite",
      "options": {
        "path": "/home/projects/data.db"
      }
    }
  ]
}

Trino

{
  "version": 1,
  "profiles": [
    {
      "name": "analytics",
      "kind": "trino",
      "arguments": ["--password"]
      "options": {
        "server": "https://trino.example.com:8443",
        "user": "alice",
        "catalog": "hive",
        "schema": "analytics",
        "schema_patterns": {
          "hive": ["analytics", "reporting"],
          "iceberg": []
          // add more catalogs as needed...
          // see Trino Multi-Catalog Schema Browser
        },
      }
    }
  ]
}

Trino Multi-Catalog Schema Browser

Trino profiles still require catalog as the CLI's default catalog, but schema_patterns can browse schemas from multiple catalogs. Orbit retains each object's catalog for column inspection, copied names, and generated sample statements:

{
  "catalog": "gridhive",
  "schema_patterns": {
    "catalog_1": ["data_v2"],
    "catalog_2": ["aggr", "cleanroom", "report"],
    "iceberg": ["cleanroom"],
    "sqlserver_rep": ["dbo"]
  }
}

An empty array, such as "catalog_1": [], includes every non-system schema from that catalog. Omit a catalog entirely to hide it.

Authentication

PostgreSQL profiles may include options.password. Orbit passes it only to psql as PGPASSWORD, never as a command-line argument. The profile file is owner-protected (0600), but a password remains sensitive; use your system's credential management or a ~/.pgpass file if you prefer not to store it in JSON.

Vertica profiles may include options.password. Orbit passes it only to vsql as VSQL_PASSWORD, never as a command-line argument.

Configure Trino authentication exactly as you do for the Trino CLI, including its --password flag, environment variables, tokens, keyrings, or credential providers it uses.

Orbit passes profile values to the CLI as literal arguments. It does not expand $VAR or ${VAR} inside JSON. Other Trino CLI authentication mechanisms, such as tokens or external credential providers, continue to work through their normal CLI configuration.

Note

Connection profiles can contain sensitive settings, including PostgreSQL passwords. Orbit requires the profile file to be mode 0600; do not copy it into a repository or share it.

Workspace Workflow

:OrbitWorkspace opens a dedicated Orbit tabpage with a profile/schema browser and a normal SQL editing window. Run it again to toggle that browser. :OrbitWorkspaceClose closes only that tabpage.

1. Press <CR> on a profile to select it and bind it to the active query buffer.
2. Optionally press l to load its schema for browsing and completion.
3. Press n to open a new SQL buffer already bound to the selected profile.
4. Execute a statement. Results appear in the reusable bottom result grid.

Set saved_query_dirs to add ordered, named recursive trees of .sql files to the sidebar:

saved_query_dirs = {
  { Work = "~/queries/work" },
  { Personal = "~/queries/personal" },
}

Each entry must contain one unique display name and directory. Orbit preserves the configured order, expands paths such as ~, and shows each location as a separate top-level tree collapsed by default. Select a profile, then press <CR> on a saved query to open it in the Workspace query window bound to that profile; loading the schema is not required. Press r on any saved-query directory to rescan only its top-level location.

From a workspace query buffer, / focuses the workspace filter. Elsewhere, / retains normal Neovim search behavior.

Commands

Command	Description
:OrbitProfiles	Create, protect, and edit the profile file.
:OrbitProfile	Search profiles and bind one to the current query buffer.
:OrbitSelectProfile	Alias for :OrbitProfile.
:OrbitExecute	Execute the single unambiguous statement in the current buffer.
:'<,'>OrbitExecute	Execute the selected line range.
:OrbitCancel	Cancel the statement running in the current buffer.
:OrbitDisconnect	Close the connection for the current buffer's profile.
:OrbitStructure	Toggle the current query buffer's Structure panel.
:OrbitWorkspace	Open the workspace or toggle its profile/schema browser.
:OrbitWorkspaceClose	Close the Orbit workspace tabpage.

Whole-buffer execution rejects ambiguous multi-statement content. Select the exact statement in Visual mode, then run :OrbitExecute or <leader>E.

Keybindings

Configurable Mappings

Orbit installs the following defaults:

Mode and scope	Mapping	Action
Normal, global	<leader>D	Open the workspace or toggle its profile/schema browser.
Normal, SQL buffer	<leader>E	Execute the buffer statement.
Visual, SQL buffer	<leader>E	Execute the visual selection.
Normal, Structure panel	<leader>E	Execute the highlighted Structure element.
Normal, SQL buffer	<leader>P	Select a connection profile.
Normal, SQL buffer	<leader>X	Cancel the running statement.

Configure action mappings through keymaps. execute also applies in the Structure panel; cancel, select_profile, and the disabled-by-default structure action are buffer-local in SQL buffers, while workspace is global. Set an action to false to disable it.

require("orbit").setup({
  keymaps = {
    execute = "<leader>E",
    workspace = "<leader>D",
    select_profile = "<leader>P",
    cancel = "<leader>X",
    structure = false,
  },
})

Workspace Sidebar

Key	Action
l	Expand the selected profile, schema, object group, table metadata folder, or object.
h	Collapse the selected node.
<CR>	Select and bind a profile to the current query buffer, or open a saved query bound to the selected profile.
n	Create a query buffer bound to the selected profile.
s	Open a bound sample statement for the selected table or view.
a	Select a connector-supported action for the selected table or view.
y	Copy the qualified selected table or view name.
P	Preview the selected saved query without opening or binding it.
/	Filter profiles, schema objects, and saved queries.
r	Reload the profile file and refresh the selected profile schema, or rescan saved queries.
Z	Collapse the open profile schema tree.
?	Show help.
q	Close the workspace.

Expanding a table reveals its available metadata folders. SQLite provides columns, primary keys, foreign keys, and indexes; Vertica provides columns, primary keys, foreign keys, and projections. Each folder loads on demand. Views remain under the schema's views group and expose their columns.

Structure Panel

:OrbitStructure opens a fixed-width panel at the far-right edge of the current tabpage and focuses it. Running the command again closes the panel. The panel works in ordinary SQL tabs and in the Orbit Workspace, follows the active query buffer, and updates as statements are edited.

By default, statements are grouped under expanded DDL, DML, SELECT, and Other headings and sorted alphabetically within each group. Each row keeps its expand/collapse marker and adds a semantic icon distinguishing category groups, statement categories, WITH containers, CTEs, query blocks, and clauses. Statement parents start collapsed. A leading WITH clause expands into its named CTEs, and each CTE owns one query block per top-level UNION, INTERSECT, or EXCEPT branch. Query blocks expose their SELECT, FROM, WHERE, GROUP BY, HAVING, WINDOW, ORDER BY, LIMIT, and OFFSET clauses. Parenthesized SELECT and WITH blocks recurse beneath their owning clause, while ordinary function calls and grouped expressions remain inline. The outer query block appears beside the WITH container. Orbit ignores comments in labels and highlights the deepest visible element containing the query-buffer cursor.

Key	Action
h	Collapse the selected node, or move to its parent.
l	Expand the selected node, or move to its first child.
j, k	Move through visible tree nodes.
zh, zl	Scroll horizontally through a complete SQL label.
<leader>E	Execute the highlighted element using the configured keymaps.execute mapping.
<CR>	Return to the query buffer and navigate to the selected element.
/	Filter statement labels using case-insensitive substring matching.
<Esc>	Clear the filter, or close the panel when no filter is active.
q	Close the panel and return to the query buffer.

Executing a statement, query block, or SELECT clause uses that element's exact source range. Other rows execute their containing top-level statement. Extracted query blocks and clauses are not guaranteed to be independently valid, so connector errors are shown through the normal diagnostic split.

Structure parsing is dependency-free and tolerant of incomplete SQL. It outlines reliably bounded query blocks and clauses rather than guessing at every SQL expression. Labels retain their complete normalized SQL even when they exceed structure_width; the panel remains fixed-width with wrapping disabled. PostgreSQL dollar-quoted bodies and SQLite trigger bodies are kept together; other dialect-specific procedural constructs may appear as best-effort entries.

Result Grid

Key	Action
h, j, k, l	Move between cells.
<CR>	Inspect the raw value in a floating window.
y	Copy the raw selected value.
q	Close the standalone grid, or return to the query editor in a workspace.

Workspace sample statements for PostgreSQL and SQLite base tables become editable when Orbit can load a primary key. Ad-hoc statements, views, Trino, and tables without a primary key remain read-only.

Key / command	Action
o, O	Insert a local row below or above the current row.
i, <CR>	Enter Insert mode in the focused cell; press Esc to keep the local edit.
dd	Mark the current row for local deletion.
V, j / k, d	Select complete rows and delete the selection.
u	Undo the most recent local edit.
:w	Confirm, transactionally save, and reload pending changes.
:wq	Save successfully, then close the Result grid.
:q!	Discard local changes and close.
:e!	Discard local changes and reload the table.

Edits are never sent to the database until :w. A failed write leaves the local Result grid unchanged. Type NULL as the complete cell value to write a SQL NULL value.

Normal Neovim scrolling remains available, including <C-d>, <C-u>, zh, and zl.

Schema Object Actions

Press a on a table or view in the Workspace schema browser to select an action supplied by its connection profile kind. Actions that inspect metadata open in the Result grid; sample actions create a bound query buffer instead.

• SQLite: sample statement, columns, primary keys, indexes, foreign keys, and object definition.
• PostgreSQL: sample statement, columns, primary keys, indexes, foreign keys, and view definition.
• Vertica: sample statement, columns, primary keys, foreign keys, projections, and view definition.
• Trino: sample statement and columns.

Available actions are intentionally connector-specific. Orbit does not present metadata actions that the selected CLI or database cannot support reliably.

Completion

Orbit's schema-aware completion (tables, views, columns, table aliases) is provided entirely through a blink.cmp source — there is no native/omnifunc fallback, so blink.cmp is required to get any Orbit completion suggestions. blink.cmp has no API for a plugin to register itself as a source at runtime, so add it to your own blink.cmp config:

{
  "saghen/blink.cmp",
  opts = {
    sources = {
      default = { "lsp", "path", "snippets", "buffer", "orbit" },
      providers = {
        orbit = { name = "orbit", module = "orbit.blink" },
      },
    },
  },
}

Once wired up, suggestions appear automatically as you type, no manual trigger needed. Completion is clause-aware: it parses the statement around your cursor (not just the current line) with a small dependency-free SQL tokenizer, so suggestions depend on where you are:

• Tables and views after any FROM-family clause (FROM, JOIN, UPDATE, INTO), and after schema./catalog.schema. qualifiers on connectors that support them (PostgreSQL, Trino).
• Trino catalogs configured as top-level schema_patterns keys are offered alongside direct relation suggestions. Selecting a catalog and schema completes progressively (catalog. → catalog.schema. → catalog.schema.table); without schema_patterns, only the profile's default catalog is offered.
• Columns in the SELECT list, WHERE, ON, GROUP BY, ORDER BY, INSERT INTO t (...), and UPDATE t SET ....
• Table aliases: SELECT u.| FROM users u resolves u to users's columns, including old-style comma joins (FROM a, b). With more than one table in scope, unqualified columns are offered from every table, each annotated with its source alias.
• The alias/table scope is limited to the statement your cursor is in; other statements in the same buffer (separated by ;) never leak into it. CTEs and derived tables (FROM (SELECT ...) sub) are recognized so they don't break parsing, but don't offer column completion.
• Suggestions are narrowed to whatever you've already typed (case-insensitive prefix match) before being handed to blink.cmp, so its own fuzzy scoring only ever sees genuinely relevant candidates.

Selecting a profile preloads tables and views in the background; expanding it in the Workspace schema browser fills more of the cache. Completion never runs the CLI while you type. SQL keywords and functions, formatting, and highlighting remain the responsibility of your existing SQL tooling.

Set completion = false in Orbit's setup() to disable the blink source's enabled() check.

Execution And Results

Orbit runs statements asynchronously through the selected profile's CLI. For SQLite, PostgreSQL, and Vertica, schema work and statements share one retained connection and execute one at a time; failures notify you and open a diagnostic window, and the next request starts a new connection. Trino statements each run their own trino CLI invocation, still serialized per profile. One running statement is allowed per query buffer; :OrbitCancel terminates the current CLI invocation (and, for SQLite, PostgreSQL, and Vertica, the retained connection) and pending work fails rather than running against an uncertain session.

Potentially mutating statements require confirmation by default. A single SELECT, SHOW, DESCRIBE, EXPLAIN, USE, or VALUES statement runs without confirmation; everything else requires it. This is a convenience guardrail, not a security boundary.

Result grids are reused per tabpage. They show up to result_limit rows and truncate displayed cell text to max_cell_width characters while retaining the raw value for copy and inspection.

Configuration

require("orbit").setup({
  completion = true,
  confirm_mutations = true,
  focus_results = false,
  profile_path = vim.fn.expand("~/.local/share/orbit.nvim/profiles.json"),
  result_limit = 200,
  result_height = 15,
  structure_view = {
    group_by_type = true,
    show_ddl = true,
    show_dml = true,
    show_other = true,
    show_select = true,
    sort_alphabetically = true,
  },
  structure_width = 40,
  saved_query_dirs = {
    { Work = "~/queries/work" },
    { Personal = "~/queries/personal" },
  },
  max_cell_width = 48,
  workspace_sidebar_width = 32,
  workspace_result_ratio = 0.30,
  winbar = false,
  icons = {
    clause = "󰅪",
    collapsed = ">",
    column = "󰠵",
    cte = "󰌷",
    expanded = "󰘖",
    folder = "󰉋",
    index = "",
    key = "",
    profile = "󰆼",
    query = "󰆋",
    query_block = "󰆋",
    result = "󰎟",
    saved_query = "󰆼",
    statement_ddl = "󰒓",
    statement_dml = "󰏫",
    statement_other = "󰌋",
    statement_select = "󰍉",
    table = "󰓫",
    view = "󰈈",
    with = "󰙅",
    workspace = "󱓞",
  },

})

Option	Default	Description
completion	true	Enable clause-aware completion via the blink.cmp source's enabled() (requires wiring orbit.blink into your own blink.cmp config; see Completion).
confirm_mutations	true	Ask before statements that are not recognised as read-only. A profile can override this with options.confirm_mutations.
focus_results	false	Focus a completed standalone result grid instead of keeping focus in the query buffer.
profile_path	~/.local/share/orbit.nvim/profiles.json	Location of the profile file.
result_limit	200	Maximum returned rows displayed in the result grid.
result_height	15	Height of a standalone result grid.
saved_query_dirs	{}	Ordered named directories of recursively discovered .sql files shown in the Workspace sidebar.
max_cell_width	48	Maximum displayed width of a result cell.
structure_view	All fields true	Structure display controls: group_by_type, show_ddl, show_dml, show_other, show_select, and sort_alphabetically.
structure_width	40	Width of the right-side Structure panel.
workspace_sidebar_width	32	Width of the workspace sidebar.
workspace_result_ratio	0.30	Fraction of editor height used by workspace results, with a six-line minimum.
winbar	false	Show Orbit status in SQL-window winbars.
keymaps	See above	Configurable action mappings.
icons	Nerd Font glyphs	Override tree, schema, Workspace, result, and Structure-panel icons shown above. The legacy query key supplies query_block when the precise key is omitted.

Within structure_view, show_ddl, show_dml, show_select, and show_other each control a complete statement subtree. group_by_type places enabled, non-empty categories in DDL, DML, SELECT, Other order. sort_alphabetically sorts statements within those groups, or across all statements when grouping is disabled; disabling it preserves source order within each group or across the ungrouped list.

For a custom statusline, call require("orbit").status(). It reports the bound profile and shows elapsed time while a statement is running.