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脚本导航<br/>(即使光标在结果缓冲区外)	描述	默认键映射<br/>(光标应在结果缓冲区内)
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获取架构的简要概述。