Getting Started

Dadbod Grip turns database tables into editable Vim buffers. It stages grid row edits, shows the SQL it will run, and sends the batch between BEGIN and COMMIT.

Requirements

Neovim 0.10 or newer.
The CLI for each adapter you use: psql, mysql, sqlite3, duckdb, or sqlcmd.
No other Neovim plugin is required. Picker and completion integrations are optional.

Run :checkhealth dadbod-grip after installation to see which database clients and optional AI providers are available.

Installation

lazy.nvim (recommended)

The plugin ships a Lazy spec that registers its commands. You do not need to copy a cmd list into your configuration.

{
  "joryeugene/dadbod-grip.nvim",
  opts = {},
}

To dogfood a local checkout while keeping the plugin identity stable:

{
  "joryeugene/dadbod-grip.nvim",
  dir = "~/Documents/github/dadbod-grip.nvim",
  opts = {},
}

packer.nvim

use { "joryeugene/dadbod-grip.nvim", tag = "v*" }

vim-plug

Plug 'joryeugene/dadbod-grip.nvim', { 'tag': 'v*' }

Connect to a database

Run :GripConnect, then select a known connection or paste one of these forms:

postgresql://user:${DB_PASSWORD}@host:5432/dbname
mysql://user:${DB_PASSWORD}@host:3306/dbname
mariadb://user:${DB_PASSWORD}@host:3306/dbname
sqlite:path/to/file.db
duckdb:path/to/file.duckdb
sqlserver://user:${DB_PASSWORD}@host:1433/dbname
mssql://user:${DB_PASSWORD}@host:1433/dbname

/path/to/file.csv
https://host/data.parquet
duckdb::memory:

Dadbod Grip recognizes Parquet, CSV, TSV, JSON, NDJSON, JSONL, XLSX, ORC, Arrow, and IPC files. Remote HTTPS and S3 sources run through DuckDB.

Connections saved from the picker go to .grip/connections.json. Global connections live in ~/.grip/connections.json. See Connections for scopes, opaque saved-query bindings, and secret placeholders.

Your first edit

Run :GripConnect and connect to a database.
Navigate the schema sidebar with j and k, then press <CR> to open a table.
Move to a cell and press i or <CR> to edit it.
Press gs to inspect the staged DML, then q to close the preview.
Press a to send the staged statements as one BEGIN/COMMIT batch. If the database client reports an error, inspect the database before retrying.

Try the built-in demo

Run :GripStart to recreate and open the Softrear Inc. demo. Dadbod Grip uses DuckDB when the duckdb client is available and falls back to SQLite through sqlite3. One of those clients must be on your PATH. Each run reseeds the database, so edits from an earlier demo session are discarded. The notebook opens at its first SQL block; press <C-CR> to execute it. The walkthrough includes a daily practice loop for finding, inspecting, exporting, and editing disposable data.

Configuration

Every option is optional. These are the current defaults:

require("dadbod-grip").setup({
  limit = 100,
  max_col_width = 40,
  timeout = 10000,
  completion = true,
  connections_path = nil,
  picker = "builtin",       -- "builtin", "telescope", or "snacks"
  pinned_max = nil,
  border = "rounded",
  cell_split = "horizontal",
  sticky_header = true,
  open_sidebar = true,
  show_running_time = true,
  show_result_time = true,
  show_hints = true,
  engine_timing = false,
})

Set open_sidebar = false to connect directly into the main workspace without opening the sidebar. The schema sidebar remains available through :GripSchema or gb.

timeout applies to database CLI calls. DuckDB work that may download an extension or read a remote URL receives a 60-second minimum for that network step, while connection health checks use five seconds.

Timing display

The loading indicator starts counting elapsed time after half a second. It measures the whole operation, including nested steps, rather than database progress. Set show_running_time = false to hide the number while keeping the loading indicator and operation label.

After a successful query, the result footer shows its client round-trip as Query: 17ms client. This measures the database-client call and result parsing. Metadata lookups, row counts, and rendering fall outside that duration, so it can be shorter than the running clock. After a successful write and reload, Write keeps the write’s client duration separately from the refreshed SELECT’s Query duration.

Set show_result_time = false to hide retained Query, Write, and action durations. Completed action text, row counts, pagination, and errors remain visible. Both timing options default to true and control display only; collection and history durations continue. Set engine_timing = true to collect separate DuckDB profiler latency.

Zen display

Set show_hints = false to hide automatic shortcut hints in results, the SQL pad, the schema sidebar, and Welcome. Run :GripZen to toggle this setting for the current session. Existing panes update without changing SQL text, keymaps, split layout, zoom, or either timing option. There is no default key binding for the command.

Column labels, staged changes, result status, filters, pagination, loading, and errors remain visible. Explicit help remains available through ? or your configured binding. Narrow result panes may use extra status rows to keep that information readable.

What opens automatically

With open_sidebar = true, a connection opens three surfaces:

The schema sidebar shows tables, columns, primary keys, foreign keys, and DDL actions.
The query pad keeps SQL available during the session. Save a named query with <C-s> when you want to reuse it after restarting Neovim.
The main workspace displays welcome content and result grids.

Run :Grip or :GripHome for Welcome. Its four action rows open the demo, connect a database, browse tables, or open SQL. Select a row with Tab/Shift-Tab or native j/k, then press Enter. With default keys, Welcome’s 1 opens schema, 2 opens SQL, and 3 opens the table picker.

The digits depend on the pane. For example, 2 from schema or results opens SQL, while 2 inside SQL opens history. In schema, 1 opens connections. Keys 4 through 9 provide ER and metadata views when a suitable table is available. Press ? for the current pane’s configured keys and <C-p> for the palette in SQL, schema, or results.

Press gb to focus schema and <Esc> there to close it. Use h/l to fold or expand groups, / to find hidden objects, and F to clear the search. Native <C-w> window navigation still works. Press gz in Welcome, SQL, schema, or results to zoom the pane; press it again to restore the split layout. Opening SQL from another zoomed pane also restores the splits.

With show_hints = true, result shortcut hints fit into two rows at the current window width and stay visible during horizontal table scrolling. Narrow panes prioritize help and core actions. Named queries and history persist; an unsaved pad and active result layout do not automatically return after Neovim exits.