Home

Awesome

<!-- DOCGEN_IGNORE_START --> <!-- This tag controlls what's ignored by the docgen workflow. -->

Linting Status Docgen Status Backend Frontend

"Buy Me A Coffee"

<!-- DOCGEN_IGNORE_END -->

Neovim DBee

Database Client for NeoVim!

Execute Your Favourite Queries From the Comfort of Your Editor!

Backend in Go!

Frontend in Lua!

Doesn't rely on CLI tools!

Get Results FAST With Under-the-hood Iterator!

Bees Love It!

Alpha Software - Expect Breaking Changes!

<!-- DOCGEN_IGNORE_START -->

Screenshot

<!-- DOCGEN_IGNORE_END --> <!-- DOCGEN_IGNORE_START -->

Video Introduction

If you prefer to watch a video than to browse through docs, I made a video, which you can watch here

<!-- DOCGEN_IGNORE_END -->

Installation

requires nvim>=0.10

Platform Support

<!-- DOCGEN_IGNORE_START --> <details> <summary>Click to expand</summary> <!-- DOCGEN_IGNORE_END -->

This project aims to be as cross-platform as possible, but there are some limitations (for example some of the go dependencies only work on certain platforms). To address this issue, the client implementations are detached from the main logic and they register themselves to dbee backend on plugin start. This allows the use of build constraints, which we use to exclued certain client implementations on certain platforms.

The CI pipeline tries building the binary for GOARCH/GOOS combinations specified in targets.json - if the builds succeed, they are stored in a remote bucket on a separate branch per run. Additionally, the install manifest gets created.

To increase cgo cross-platform support, the pipeline uses zig as a C compiler.

To check if your platform is currently supported, check out the mentioned manifest and the targets file.

<!-- DOCGEN_IGNORE_START --> </details> <!-- DOCGEN_IGNORE_END -->

Manual Binary Installation

<!-- DOCGEN_IGNORE_START --> <details> <summary>Click to expand</summary> <!-- DOCGEN_IGNORE_END -->

The installation examples include the build/run functions, which get triggered once the plugin updates. This should be sufficient for the majority of users. If that doesn't include you, then you have a few options:

<!-- DOCGEN_IGNORE_START --> </details> <!-- DOCGEN_IGNORE_END -->

Configuration

You can pass an optional table parameter to setup() function.

Here are the defaults:

<!--DOCGEN_CONFIG_START--> <!-- Contents from lua/dbee/config.lua are inserted between these tags for docgen. -->

config.lua

<!--DOCGEN_CONFIG_END-->

Usage

Call the setup() function with an optional config parameter.

<!-- DOCGEN_IGNORE_START --> <details> <summary>Brief reference (click to expand):</summary> <!-- DOCGEN_IGNORE_END -->
-- Open/close/toggle the UI.
require("dbee").open()
require("dbee").close()
require("dbee").toggle()
-- Run a query on the currently active connection.
require("dbee").execute(query)
-- Store the current result to file/buffer/yank-register (see "Getting Started").
require("dbee").store(format, output, opts)

The same functions are also available through the :Dbee user command.

<!-- DOCGEN_IGNORE_START --> </details> <!-- DOCGEN_IGNORE_END -->

Getting Started

Here are a few steps to quickly get started:

Navigation using lua script <br/> (even if your cursor is outside the result buffer)DescriptionDefault key mapping <br/> (cursor should be inside result buffer)
require("dbee").api.ui.result_page_next()Go to next pageL
require("dbee").api.ui.result_page_prev()Go to the previous pageH
require("dbee").api.ui.result_page_last()Go to the last pageE
require("dbee").api.ui.result_page_first()Go to the first pageF

Specifying Connections

Connection represents an instance of the database client (i.e. one database). This is how it looks like:

{
  id = "optional_identifier" -- only mandatory if you edit a file by hand. IT'S YOUR JOB TO KEEP THESE UNIQUE!
  name = "My Database",
  type = "sqlite", -- type of database driver
  url = "~/path/to/mydb.db",
}

The connections are loaded to dbee using so-called "sources". They can be added to dbee using the setup() function:

  require("dbee").setup {
    sources = {
      require("dbee.sources").MemorySource:new({
        {
          name = "...",
          type = "...",
          url = "...",
        },
        -- ...
      }),
      require("dbee.sources").EnvSource:new("DBEE_CONNECTIONS"),
      require("dbee.sources").FileSource:new(vim.fn.stdpath("cache") .. "/dbee/persistence.json"),
    },
    -- ...
  },

The above sources are just built-ins. Here is a short description of them:

If the source supports saving and editing you can add connections manually using the "add" item in the drawer. Fill in the values and write the buffer (:w) to save the connection. By default, this will save the connection to the global connections file and will persist over restarts (because default FileSource supports saving)

Another option is to use "edit" item in the tree and just edit the source manually.

If you aren't satisfied with the default capabilities, you can implement your own source. You just need to fill the Source interface and pass it to config at setup (:h dbee.sources).

Secrets

If you don't want to have secrets laying around your disk in plain text, you can use the special placeholders in connection strings (this works using any method for specifying connections).

Each connection parameter is passed through go templating engine, which has two available functions:

The template syntax for functions is the following: {{ <func> "<param>" }}. If you are dealing with json, you need to escape double quotes, so it's sometimes better to use backticks instead ({{ <func> `<param>` }}).

Example:

Using the DBEE_CONNECTIONS environment variable for specifying connections and exporting secrets to environment:

# Define connections
export DBEE_CONNECTIONS='[
    {
        "name": "{{ exec `echo Hidden Database` }}",
        "url": "postgres://{{ env \"SECRET_DB_USER\" }}:{{ env `SECRET_DB_PASS` }}@localhost:5432/{{ env `SECRET_DB_NAME` }}?sslmode=disable",
        "type": "postgres"
    }
]'

# Export secrets
export SECRET_DB_NAME="secretdb"
export SECRET_DB_USER="secretuser"
export SECRET_DB_PASS="secretpass"

If you start neovim in the same shell, this will evaluate to the following connection:

{ {
  name = "Hidden Database",
  url = "postgres://secretuser:secretpass@localhost:5432/secretdb?sslmode=disable",
  type = "postgres",
} }

API

Dbee comes with it's own API interface. It is split into two parts:

You can access it like this:

require("dbee").api.core.some_func()
require("dbee").api.ui.some_func()

Extensions

<!-- DOCGEN_IGNORE_START -->

Development

Reffer to ARCHITECTURE.md for a brief overview of the architecture.

<!-- DOCGEN_IGNORE_END -->