Simple Neovim plugin for the universal command-line database interface usql. It depends on yarepl.nvim for the heavy lifting and adds helpers to make it easier to work with SQL and USQL files:

• Provide yarepl command and formatter for usql.
• Database connection selector using vim.ui, telescope, or snacks picker if available.
• SSH tunneling on top of usql database connections.
• Keymaps to work with usql repl:
  • (SelectConnection)
  • (SendStatement)
  • (SendBuffer)

• Neovim >= 0.10.0
• usql
• nvim-treesitter
  • nvim-treesitter SQL parser :TSInstall sql.
  • nvim-treesitter USQL parser.
• yarepl.nvim
• telescope.nvim (optional)
• snacks.nvim (optional)
• lualine.nvim (optional)
• ssh client (optional): Used to create SSH tunnels.

Via lazy.nvim:

{
    'hsanson/usql.nvim',
    ft = "sql",
    opts = {
        -- Path to usql binary,
        usql_path = "usql",

        -- Absolute path to usql config.yaml file.
        config_path = "$HOME/.config/usql/config.yaml",

        -- Lualine component configuration
        lualine = {
            fg = "#10B1FE",
            icon = "",
        }
    }
},

In your YAREPL configuration add usql meta:

{
  "milanglacier/yarepl.nvim",
  config = function()
    local yarepl = require("yarepl")
    local usql = require("usql.yarepl")

    yarepl.setup({
      metas = {
        usql = { cmd = usql.cmd, formatter = usql.formatter },
      },
    })

  end
}

Create key map to open connection selector:

vim.keymap.set("n",
  "<localleader>rt",
  "<Plug>(SelectConnection)",
  { desc = "Select DB connection" }
  )

Create key maps to send SQL statement under cursor and whole buffer:

vim.keymap.set("n",
  "<localleader>rs",
  "<Plug>(SendStatement)",
  { desc = "Send SQL Statement" }
  )

vim.keymap.set("n",
  "<localleader>rf",
  "<Plug>(SendBuffer)",
  { desc = "Send current buffer" }
  )

If you have snacks.nvim installed, you can use the Snacks picker for connection selection. The plugin will automatically detect and use Snacks if available.

You can also call the Snacks picker directly:

local usql_snacks = require("snacks._extensions.usql")
usql_snacks.connections()

Or integrate it into your own picker setup:

vim.keymap.set("n", "<leader>db", function()
  require("snacks._extensions.usql").connections({
    layout = "dropdown" -- optional: specify layout
  })
end, { desc = "Select database connection" })

Alternatively, use the convenience function from the main usql module:

vim.keymap.set("n", "<leader>db", function()
  require("usql").select_connection_snacks({
    layout = "dropdown" -- optional: specify layout
  })
end, { desc = "Select database connection with Snacks picker" })

Create other YAREPL key maps to send visual and motions as explained in YAREPL Wiki.

1. Open a sql file.
2. Open usql REPL with whichever key map you set.
3. Execute <localleader>rt to open connection selector and select the connection you want to use.
4. Move the cursor to any SQL statement.
5. Execute <localleader>rs to run SQL statement under the cursor.
6. Execute <localleader>rf to run all SQL statements in the current buffer.

This plugin reads usql default YAML configuration file to retrieve the list of available database connections. In addition to usql configuration parameters, this plugin supports additional keys:

The display parameter is used for display in the connections selector and lualine status. If not present the connection YAML key is used instead.

Example configuration:

connections:
  my_dev_db:
    display: Local DB
    protocol: postgresql
    hostname: localhost
    port: 5432
    database: my_dev
    username: my_username
    password: secret_password

This plugin enhances usql by adding the capability of defining SSH tunnels in the database configuration. If a database connection has the ssh_config key, this plugin will create and SSH tunnel and instruct usql to use the tunnel when connecting to the database.

Example:

connections:
  my_dev_db:
    display: Local DB
    protocol: postgresql
    hostname: [database hostname]
    port: 5432
    database: my_dev
    username: my_username
    password: secret_password
    ssh_config:
        ssh_host: 192.168.56.50
        ssh_port: 22
        ssh_user: admin
        ssh_key: ~/.ssh/id_rsa

Add usql component to your lualine configuration to show current connection in the status line:

sections = {
    lualine_y = {
      { 'usql' },
    },
}