离线环境DuckDB手动安装拓展

最近做新项目的时候用到了 DuckDB，这是一个支持 OLAP（联机分析处理）的本地数据库，性能快、数据占用磁盘小，结合了一定 ElasticSearch 和 SQLite 的优点。而且支持扩展（Extensions），可以实现很多额外功能。比如：mysql 拓展可以让 DuckDB 直接与 MySQL 交互读取数据，提高效率。

DuckDB 用起来很不错，不过在考虑部署应用程序的时候发现一个问题，离线环境下加载拓展比较麻烦。

一般情况下（比如开发环境），首次用 LOAD 命令加载拓展时，DuckDB 会自动从公网上下载拓展的文件到本地。但部署的机器上只有内网，故只能提前手动下载好 DuckDB 的拓展文件，然后把拓展随应用程序一同打包部署。

这里写篇文章做下相关记录。

关于下载地址

DuckDB 官网并没有像 Chrome 那样提供拓展中心，没法直接下，粗略搜了下网上也没有找到有用的内容。不过好在花了点时间翻阅下文档库后，在 拓展-高级安装方式 中找到了获取对应拓展下载地址的方式（原文的例子是用于亚马逊 Lambda 方式部署），也可以曲线救国。

备注：准确的说 DuckDB 是有核心拓展群（官方管理）和社区拓展之分。社区拓展基本都能在Github找到一些线索，这里只说说核心拓展（Core Extensions）怎么手动下载、离线安装。

手动下载拓展

前置知识：DuckDB 程序和拓展都区分操作系统和平台。而且程序与拓展的版本必须对应（比如：1.2.2 的程序只能加载 1.2.2 版本拓展，不能加载 1.3.0 的拓展）。

下载前首先要确定好三项信息：拓展名、DuckDB 版本号、平台名称。

拓展名

这个不用多说，也就是正常使用DuckDB时 INSTALL \ LOAD 命令后面跟的名称。 所有的 DuckDB 拓展列表、说明也可以在文档库：Core Extensions 的列表中找到。 有一点要额外注意的是，有一些拓展存在别名（见列表的 Alias 列），后面下载的时候直接用原名称（对应列表中 Name 一栏）即可。

DuckDB 版本号

直接看下载连接，或者看客户端库（比如Java、Python的包等）版本号就能知道。 如果目标机器上是直接运行 DuckDB 的二进制文件（比如Windows上直接运行duckdb.exe），也可以在命令行执行 .\duckdb --version来查看

平台名称

官方文档库有给出列表，详细的平台名称可以在文档库构建-概述中找到。

根据目标操作系统和处理器架构查表即可。这里也顺带贴出来，官方完全支持平台的共有六种：

举个例子，比如要找在Linux系统、x86处理器上使用的拓展，对应的平台名就是 linux_amd64。

有了版本号、平台名称，接着我们可以去构建出拓展的下载地址了。

下载地址格式为：http://extensions.duckdb.org/v<DuckDB版本>/<平台名称>/<拓展名>.duckdb_extension.gz，将尖括号的部分替换为对应的部分即可。比如：http://extensions.duckdb.org/v1.3.0/windows_amd64/json.duckdb_extension.gz。

用这个构建出的URL下载解压后，会得到一个.duckdb_extension 后缀的文件，这就是我们要找的拓展文件。上传到目标机器上即可。

如果有多个拓展，则重复以上步骤下载好全部的拓展文件。

直接复制

如果有条件运行对应平台架构的DuckDB程序（二进制文件）且可以联网，也可以直接通过程序下载。

以下载x86版本的Windows用拓展举个例子。在可以联网的Windows上下载好DuckDB，直接启动程序，运行 INSTALL 命令安装拓展。

等待下载完成后，可以在默认目录下找到 DuckDB 存放的所有拓展。

拓展的默认存放位置是在当前用户目录下的 ~/.duckdb/extensions/<DuckDB版本>/<平台名称>/。

用户目录在 Linux/Mac下对应的是：~/.duckdb/...，Windows下对应的是：%UserProfile%/.duckdb/...

.duckdb_extension 结尾的文件就是拓展，复制出来上传到目标机器。 .duckdb_extension.info 的文件用不到，可以不复制。

当然这样的缺点是不能下载其他系统或者平台的扩展，建议还是用前一种方式。

使用拓展

在目标机器放好拓展后，使用时略有一点小区别。需要手动指定路径加载一次，执行SQL命令：LOAD '拓展路径'。例如：

LOAD '/home/root/ddb/mysql.duckdb_extension';

每次连接到DuckDB后（一般在Java是JDBC连接、其他语言是ODBC等）只用执行一次即可。注意这里指定的是解压后的拓展的路径，而不是拓展的名字，路径两侧要带单引号。

这样DuckDB就会跳过搜索默认路径和下载，直接加载拓展了。官方文档给的示例中是可以写相对路径的。不过考虑到客户端的工作路径可能会变，建议还是用绝对路径吧。

如果没有报错（抛出异常）就是加载成功了。其他地方没有不同，可以正常使用各种拓展的功能了。

P.S. 最后顺带提一句，还有一种离线“部署”思路，把拓展文件按上一章节提到的路径复制到相应的目录，使用时仍然执行 LOAD 拓展名 也是可以用的。就是部署和维护的时候可能麻烦一点。