zongben/dbout.nvim

github

database

35

0

1

0

CREATED

2025-09-15

UPDATED

2026-06-18

---

Dbout.nvim

dbout.nvim is a Neovim plugin that helps you connect to databases, execute SQL queries, and display the results in JSON format. No need to switch to external tools. Everything happens inside Neovim, making your workflow faster and smoother.

https://github.com/user-attachments/assets/21d4295a-897b-422a-aa69-2d6cde4e555d

Key Features

• JSON Result Display: View query results in a structured JSON format for easy reading and native highlighting.
• No More Connection Strings In Your Neovim Config: All your database connections are securely saved locally on your machine.
• Buffer-Isolated Connections: Every database query buffer maintains its own isolated connection state.

Supported Databases

• SQLite
• PostgreSQL
• MySQL
• MSSQL

Installation

Requirements:

• Nodejs

With lazy.nvim:

{
  "zongben/dbout.nvim",
  build = "npm install",
  lazy = "VeryLazy",
  cmd = { "Dbout" },
  config = function()
    require("dbout").setup({})
  end,
}

Configuration

The default configuration is as follows:

{
  ui = {
    -- See layout configuration section.
    layout = {
      inspector = 1,
      viewer = 3,
    },
    -- Open utility panels by default when a buffer attaches to a connection.
    init_open = {
      inspector = true,
      viewer = true,
    },
  },
  viewer = {
    history = {
      enabled = true,
      limit = 10,
    },
  },
  -- Set empty string to disable keymap.
  keymaps = {
    global = {
      toggle_inspector = "<F12>",
      toggle_viewer = "<F11>",
      close = "q",
    },
    queryer = {
      query = "<F5>",
      format = "<F2>",
    },
    inspector = {
      next_tab = "L",
      previous_tab = "H",
      inspect = "I",
      back = "<BS>",
      refresh = "R",
    },
    viewer = {
      next_history = "}",
      previous_history = "{",
      delete_history = "<C-d>",
    },
  },
  -- Called when a queryer buffer attaches to a connection.
  -- Use this to configure your preferred LSP.
  -- This function provides connection details to help set up the LSP.
  on_attach = function(conn, bufnr)
    -- conn is a table
    -- {
    --   name, db_type, host, port, user, password, database, connstr
    -- }
  end
}

Layout Configuration

The layout coordinates positions using a 3-column system (1 = Left, 2 = Middle/Relative, 3 = Right).

Position:     1               2               3
       +---------------+---------------+---------------+
       |               |               |               |
       |     LEFT      |   RELATIVE    |     RIGHT     |
       |   (Global)    |   (Attached)  |   (Global)    |
       |               |               |               |
       +---------------+---------------+---------------+

• If both the viewer and inspector are set to 1, the newer panel opens on the left.
• If both are set to 3, vice versa (the newer opens on the right).
• However, both panels cannot be set to 2 simultaneously.

Usage

Use the following commands for database connection management:

:Dbout OpenConnection - Open a new buffer and connect to selected database connection
:Dbout NewConnection - Create a new database connection
:Dbout DeleteConnection - Delete an existing connection
:Dbout EditConnection - Edit an existing connection
:Dbout AttachConnection - Attach to selected connection in the current buffer (this is very useful after opening a .sql file)

After opening or attaching a connection, a buffer for that database connection is created, named Queryer.
Inside the Queryer buffer:

F2 - Format SQL
F5 - Execute the current SQL query and open viewer with query result

The Inspector is a buffer used for inspecting database objects.
Within the Inspector buffer:

H and L - Switch between tabs
I - Inspect more details, such as table columns, triggers, views, etc.
R - Refresh inspector for clear caches.

Telescope Extension

For users with Telescope installed, you can load the dbout extension for easier database connection management:

require("telescope").load_extension("dbout")

--default config
require("telescope").setup({
  extensions = {
    dbout = {
      keymaps = {
        open_connection = "<cr>",
        new_connection = "n",
        delete_connection = "d",
        edit_connection = "e",
        attach_connection = "a",
      },
    },
  },
})

Then, you can open the database connection picker by calling :Telescope dbout or require("telescope").extensions.dbout.dbout()

Snacks Sources

For users with Snacks installed, dbout automatically registers its sources. You can open the database connection manager simply by calling :Dbout

--default config
require("dbout.snacks").setup({
  keymaps = {
    open_connection = "<cr>",
    new_connection = "n",
    delete_connection = "d",
    edit_connection = "e",
    attach_connection = "a",
  },
})

-- You can also configure the source:
Snacks.picker.sources.dbout = {
  -- your options here
  -- For more details, see:
  -- https://github.com/folke/snacks.nvim/blob/main/docs/picker.md
}

TODO

• layout system
• inspector cache
• query history
• CSV output
• ui improvement
• mongodb support