Neovim DBee

适用于NeoVim的数据库客户端!

在编辑器中舒适地执行你喜爱的查询!

后端使用Go语言!

前端使用Lua语言!

不依赖CLI工具!

通过底层迭代器快速获取结果!

蜜蜂们都喜欢它!

Alpha版软件 - 预计会有重大变更!

安装

需要 nvim>=0.10

packer.nvim:

use {
  "kndndrj/nvim-dbee",
  requires = {
    "MunifTanjim/nui.nvim",
  },
  run = function()
    -- 安装程序会尝试自动检测安装方法。
    -- 如果失败,可以尝试使用以下参数之一调用:
    --    "curl", "wget", "bitsadmin", "go"
    require("dbee").install()
  end,
  config = function()
    require("dbee").setup(--[[可选配置]])
  end
}

lazy.nvim:

{
  "kndndrj/nvim-dbee",
  dependencies = {
    "MunifTanjim/nui.nvim",
  },
  build = function()
    -- 安装程序会尝试自动检测安装方法。
    -- 如果失败,可以尝试使用以下参数之一调用:
    --    "curl", "wget", "bitsadmin", "go"
    require("dbee").install()
  end,
  config = function()
    require("dbee").setup(--[[可选配置]])
  end,
},

平台支持

本项目旨在尽可能实现跨平台,但存在一些限制(例如某些Go依赖项仅适用于特定平台)。为解决这个问题,客户端实现与主逻辑分离,并在插件启动时向dbee后端注册自身。这允许使用构建约束,我们用它来在某些平台上排除特定的客户端实现。

CI管道尝试为targets.json中指定的GOARCH/GOOS组合构建二进制文件 - 如果构建成功,它们将存储在单独分支的远程存储桶中。此外,还会创建安装清单。

为提高cgo跨平台支持,管道使用zig作为C编译器。

要检查你的平台是否当前受支持,请查看上述清单和目标文件。

手动二进制安装

安装示例包含在插件更新时触发的build/run函数。这对大多数用户来说应该足够了。如果你不在此列,那么你有几个选择:

只需使用"go"选项安装(这在底层执行go build):
```
require("dbee").install("go")
```
从安装清单中的一个URL下载已编译的二进制文件
go install (安装位置将根据你的本地go配置而变):
```
go install github.com/kndndrj/nvim-dbee/dbee@<版本>
```

克隆并构建

# 克隆仓库并进入"go子文件夹"
git clone <此仓库>
cd <此仓库>/dbee
# 构建二进制文件(可选输出路径)
go build [-o ~/.local/share/nvim/dbee/bin/dbee]

配置

你可以向setup()函数传递一个可选的表参数。

以下是默认值:

使用方法

调用setup()函数并传入可选的配置参数。

-- 打开/关闭/切换UI。
require("dbee").open()
require("dbee").close()
require("dbee").toggle()
-- 在当前活动连接上运行查询。
require("dbee").execute(query)
-- 将当前结果存储到文件/缓冲区/复制寄存器(参见"入门指南")。
require("dbee").store(format, output, opts)

这些函数也可以通过:Dbee用户命令使用。

入门指南

以下是快速入门的几个步骤:

在你的init.lua中调用setup()函数
使用一个或多个源指定连接(参考此部分)。
重启编辑器后,调用lua require("dbee").open()打开UI。
导航到抽屉(树)并使用以下键绑定根据上下文执行不同操作(所有映射都可以在配置中更改):
- 所有节点:
  - 按o切换树节点。
  - 按r手动刷新树。
- 连接:
  - 按cw编辑连接
  - 按dd删除它(如果源支持保存,它也会从那里删除 - 详见下文。)
  - 按<CR>执行操作 - 查看历史记录或查看帮助查询。直接在连接节点上按<CR>将其设置为活动连接
- 草稿本:
  - 在new节点上按<CR>创建新的草稿本。
  - 当你尝试将其保存到磁盘(:w)时,路径会自动填充。你可以将名称更改为任何你想要的,如果你将其保存到建议的目录,下次打开DBee时它会加载。
  - 按cw重命名草稿本。
  - 按dd删除它(也从磁盘上删除)。
  - 在抽屉中的现有草稿本上按<CR>将在编辑器窗格中打开它。
- 帮助:
  - 只查看键绑定。
选择连接并创建草稿本后,你可以导航到编辑器窗格(默认在右上角)并开始编写查询。在编辑器窗格中,你可以使用以下操作:
- 在可视模式下高亮一些文本并按BB - 这将在活动连接上运行所选查询。
- 如果你在普通模式下按BB,你将在活动连接上运行整个草稿本。
如果请求成功,结果应该出现在"结果"缓冲区(默认在右下角)。如果结果总数低于配置中的page_size参数(默认为100),所有结果应该已经存在。如果结果超过page_size,你可以使用以下方法"翻页":

使用lua脚本导航 (即使光标在结果缓冲区外)	描述	默认键映射 (光标应在结果缓冲区内)
`require("dbee").api.ui.result_page_next()`	转到下一页	L
`require("dbee").api.ui.result_page_prev()`	转到上一页	H
`require("dbee").api.ui.result_page_last()`	转到最后一页	E
`require("dbee").api.ui.result_page_first()`	转到第一页	F

在"结果"缓冲区中,你可以使用以下键复制结果:
- yaj 复制当前行为json格式(或在可视模式下复制行范围)
- yac 复制当前行为CSV格式(或在可视模式下复制行范围)
- yaJ 复制所有行为json格式
- yaC 复制所有行为CSV格式
当前结果(活动连接的)也可以使用require("dbee").store()lua函数或:Dbee store Ex命令保存到文件、复制寄存器或缓冲区。以下是一些示例:

-- 将所有行作为CSV输出到当前缓冲区:
require("dbee").store("csv", "buffer", { extra_arg = 0 })
-- 将第2行到第7行的结果作为json输出到文件(索引从0开始):
require("dbee").store("json", "file", { from = 2, to = 7, extra_arg = "path/to/file.json"  })
-- 复制第一行作为表格
require("dbee").store("table", "yank", { from = 0, to = 1 })
-- 复制最后2行作为CSV
-- (负索引被解释为length+1+index - 与nvim_buf_get_lines()相同)
-- 请注意,使用负索引需要完全耗尽结果的迭代器,这可能会影响大型结果集。
require("dbee").store("csv", "yank", { from = -3, to = -1 })

完成操作或想要返回之前的位置时,可以调用require("dbee").close()。

指定连接

连接代表数据库客户端的一个实例(即一个数据库)。它的结构如下:

{
  id = "optional_identifier" -- 只有在手动编辑文件时才是必需的。保持这些ID唯一是你的责任!
  name = "My Database",
  type = "sqlite", -- 数据库驱动类型
  url = "~/path/to/mydb.db",
}

连接通过所谓的"源"加载到dbee中。可以使用setup()函数将它们添加到dbee:

  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"),
    },
    -- ...
  },

上面的源只是内置的。以下是它们的简短描述:

MemorySource只加载你作为参数给它的连接。

EnvSource从环境变量加载连接。只需导出你给加载器的变量,就可以使用了:

  export DBEE_CONNECTIONS='[
      {
          "name": "DB from env",
          "url": "mysql://...",
          "type": "mysql"
      }
  ]'

FileSource从给定的json文件加载连接。它还支持交互式编辑和添加连接

如果源支持保存和编辑,你可以使用抽屉中的"add"项手动添加连接。填写值并写入缓冲区(:w)以保存连接。默认情况下,这将把连接保存到全局连接文件,并在重启后保持不变(因为默认的FileSource支持保存)

另一个选项是使用树中的"edit"项,手动编辑源。

如果你对默认功能不满意,可以实现自己的源。你只需要实现Source接口,并在设置时将其传递给配置(:h dbee.sources)。

秘密

如果你不想在磁盘上以明文形式存储秘密,可以在连接字符串中使用特殊占位符(这适用于指定连接的任何方法)。

每个连接参数都通过go模板引擎传递,该引擎有两个可用函数:

env用于检索环境变量
exec用于评估shell命令

函数的模板语法如下:{{ <func> "<param>" }}。如果你处理的是json,你需要转义双引号,所以有时使用反引号更好({{ <func> `<param>` }})。

示例:

使用DBEE_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 SECRET_DB_NAME="secretdb"
export SECRET_DB_USER="secretuser"
export SECRET_DB_PASS="secretpass"

如果在同一个shell中启动neovim,这将评估为以下连接:

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

API

Dbee带有自己的API接口。它分为两部分:

core (与插件核心交互),
ui (与插件UI交互)。

你可以这样访问它:

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

扩展

nvim-projector 要将dbee与projector一起使用,请使用这个扩展。
nvim-cmp 这里是一个支持dbee的补全插件。

开发

参考ARCHITECTURE.md获取架构的简要概述。