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!
If you prefer to watch a video than to browse through docs, I made a video, which you can watch here
requires nvim>=0.10
-
packer.nvim:
use { "kndndrj/nvim-dbee", requires = { "MunifTanjim/nui.nvim", }, run = function() -- Install tries to automatically detect the install method. -- if it fails, try calling it with one of these parameters: -- "curl", "wget", "bitsadmin", "go" require("dbee").install() end, config = function() require("dbee").setup(--[[optional config]]) end }
-
lazy.nvim:
{ "kndndrj/nvim-dbee", dependencies = { "MunifTanjim/nui.nvim", }, build = function() -- Install tries to automatically detect the install method. -- if it fails, try calling it with one of these parameters: -- "curl", "wget", "bitsadmin", "go" require("dbee").install() end, config = function() require("dbee").setup(--[[optional config]]) end, },
Click to expand
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.
Click to expand
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:
- just install with the
"go"option (this performsgo buildunder the hood):require("dbee").install("go")
- Download an already compiled binary from one of urls in the install manifest
go install(the install location will vary depending on your local go configuration):go install github.com/kndndrj/nvim-dbee/dbee@<version>
- Clone and build
# Clone the repository and cd into the "go subfolder" git clone <this_repo> cd <this_repo>/dbee # Build the binary (optional output path) go build [-o ~/.local/share/nvim/dbee/bin/dbee]
You can pass an optional table parameter to setup() function.
Here are the defaults:
Call the setup() function with an optional config parameter.
Brief reference (click to expand):
-- 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.
Here are a few steps to quickly get started:
-
call the
setup()function in yourinit.lua -
Specify connections using one or more sources (reffer to this section).
-
When you restart the editor, call
lua require("dbee").open()to open the UI. -
Navigate to the drawer (tree) and use the following key-bindings to perform different actions depending on the context (the mappings can all be changed in the config):
-
All nodes:
- Press
oto toggle the tree node. - Press
rto manually refresh the tree.
- Press
-
Connections:
- Press
cwto edit the connection - Press
ddto delete it (if source supports saving, it's also removed from there - see more below.) - Press
<CR>to perform an action - view history or look at helper queries. Pressing<CR>directly on the connection node will set it as the active one
- Press
-
Scratchpads:
- Press
<CR>on thenewnode to create a new scratchpad. - When you try to save it to disk (
:w), the path is automatically filled for you. You can change the name to anything you want, if you save it to the suggested directory, it will load the next time you open DBee. - Press
cwto rename the scratchpad. - Press
ddto delete it (also from disk). - Pressing
<CR>on an existing scratchpad in the drawer will open it in the editor pane.
- Press
-
Help:
- Just view the key bindings.
-
-
Once you selected the connection and created a scratchpad, you can navigate to the editor pane (top-right by default) and start writing queries. In editor pane, you can use the following actions:
- Highlight some text in visual mode and press
BB- this will run the selected query on the active connection. - If you press
BBin normal mode, you run the whole scratchpad on the active connection.
- Highlight some text in visual mode and press
-
If the request was successful, the results should appear in the "result" buffer (bottom right by default). If the total number of results was lower than the
page_sizeparameter in config (100 by default), all results should already be present. If there are more thanpage_sizeresults, you can "page" through them using one of the following:
| Navigation using lua script (even if your cursor is outside the result buffer) |
Description | Default key mapping (cursor should be inside result buffer) |
|---|---|---|
require("dbee").api.ui.result_page_next() |
Go to next page | L |
require("dbee").api.ui.result_page_prev() |
Go to the previous page | H |
require("dbee").api.ui.result_page_last() |
Go to the last page | E |
require("dbee").api.ui.result_page_first() |
Go to the first page | F |
-
Once in the "result" buffer, you can yank the results with the following keys:
yajyank current row as json (or row range in visual mode)yacyank current row as CSV (or row range in visual mode)yaJto yank all rows as jsonyaCto yank all rows as CSV
-
The current result (of the active connection) can also be saved to a file, yank-register or buffer using
require("dbee").store()lua function or:Dbee storeEx command. Here are some examples:-- All rows as CSV to current buffer: require("dbee").store("csv", "buffer", { extra_arg = 0 }) -- Results from row 2 to row 7 as json to file (index is zero based): require("dbee").store("json", "file", { from = 2, to = 7, extra_arg = "path/to/file.json" }) -- Yank the first row as table require("dbee").store("table", "yank", { from = 0, to = 1 }) -- Yank the last 2 rows as CSV -- (negative indices are interpreted as length+1+index - same as nvim_buf_get_lines()) -- Be aware that using negative indices requires for the -- iterator of the result to be drained completely, which might affect large result sets. require("dbee").store("csv", "yank", { from = -3, to = -1 })
-
Once you are done or you want to go back to where you were, you can call
require("dbee").close().
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:
-
MemorySourcejust loads the connections you give it as an argument. -
EnvSourceloads connection from an environment variable Just export the variable you gave to the loader and you are good to go:export DBEE_CONNECTIONS='[ { "name": "DB from env", "url": "mysql://...", "type": "mysql" } ]'
-
FileSourceloads connections from a given json file. It also supports editing and adding connections interactively
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).
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:
envfor retrieving environment variables andexecfor evaluating shell commands.
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",
} }Dbee comes with it's own API interface. It is split into two parts:
- core (interacting with core of the plugin),
- ui (interacting with ui of the plugin).
You can access it like this:
require("dbee").api.core.some_func()
require("dbee").api.ui.some_func()-
nvim-projectorTo use dbee with projector, use this extension.
Reffer to ARCHITECTURE.md for a brief overview of the architecture.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent