diff --git a/zh_CN/integration/datalayers-with-grafana.md b/zh_CN/integration/datalayers-with-grafana.md index 42cd3b46..4e10a572 100644 --- a/zh_CN/integration/datalayers-with-grafana.md +++ b/zh_CN/integration/datalayers-with-grafana.md @@ -6,19 +6,40 @@ description: "介绍如何将 Datalayers 集成到 Grafana,包括插件安装 本文介绍如何将 Datalayers 与 Grafana 集成,实现时序数据查询、可视化分析和 Dashboard 构建。该方案适用于监控看板、设备数据展示、工业指标分析等场景。 -我们提供 **手动部署** 与 **Docker Compose 一键部署**,下面将分别介绍这两种部署方式。 +Datalayers 提供两种接入方式: -## 手动部署 +- 通过 PostgreSQL 数据源接入。 +- 通过 Datalayers 数据源插件接入。 + +## 使用 PostgreSQL 数据源接入 + +Datalayers 兼容 PostgreSQL 协议,因此可以直接在 Grafana 中选择内置的 PostgreSQL 数据源并完成连接。 + +### 接入条件 + +- 已安装 Datalayers,并已启用 PostgreSQL 协议监听服务 +- 已安装 Grafana,且可以正常访问 Grafana Web 界面 +- 已获取 Datalayers 实例地址、PostgreSQL 协议端口、用户名和密码 + +### 配置方法 + +在 Grafana 中进入 Data sources 页面,新增 PostgreSQL 数据源后,填写 Datalayers 实例地址、端口、数据库名、用户名和密码。保存成功后,即可在 Grafana 中基于 SQL 查询创建图表与 Dashboard。 + +## 使用 Datalayers 插件接入 + +如果你希望在 Grafana 中获得更贴合 Datalayers 的使用体验,建议使用 Datalayers 数据源插件。以下步骤以 Ubuntu 和 amd64 平台为例进行说明。 ### 环境准备 -- Grafana 版本必须 >= 9.2.5。 +- Grafana 版本不低于 `9.2.5` +- 已安装 Datalayers,并可通过命令行工具访问实例 +- 已获取 Datalayers 实例地址、端口、用户名和密码 -### 安装 Datalayers +### 准备示例数据 此处我们以 Ubuntu 操作系统、amd64 平台为例,请前往 [下载页](https://datalayers.cn/download?broker=ubuntu) 下载对应平台的 `deb` 安装包。 -安装完成后,可以通过我们提供的命令行工具写入一些示例数据: +安装完成后,可以通过命令行工具写入一些示例数据,便于后续在 Grafana 中验证查询与可视化效果。 首先,通过以下命令连接到数据库: @@ -32,10 +53,16 @@ dlsql -h 127.0.0.1 -u admin -p public create database demo; ``` -再创建一个表: +切换到该数据库: + +``` bash +use demo; +``` + +再创建示例表: ``` bash -CREATE TABLE demo.sensor_info ( +CREATE TABLE sensor_info ( ts TIMESTAMP(9) NOT NULL DEFAULT CURRENT_TIMESTAMP, sn STRING, speed DOUBLE, @@ -46,7 +73,7 @@ CREATE TABLE demo.sensor_info ( with (ttl='10d'); ``` -写入一些示例数据,当然为了数据更丰富,你可以多写入一点随机数据: +写入一些示例数据。为了便于观察图表变化,你也可以写入更多随机数据: ``` bash INSERT INTO sensor_info(sn, speed, temperature) VALUES('100', 22.12, 30.8), ('101', 34.12, 40.6), ('102', 56.12, 52.3); @@ -60,11 +87,9 @@ INSERT INTO sensor_info(sn, speed, temperature) VALUES('100', 22.12, 30.8), ('10 请前往 [Grafana 官网下载页](https://grafana.com/grafana/download) 获取安装包。 -此处我们下载并安装 Linux 的 开源版本 11.2.0: - ![download grafana](../assets/datalayers-with-grafana/download_grafana.png) -> 安装好 Grafana 之后就可以进行插件的安装了,建议安装前先停止你的 Grafana 服务。 +> 建议在安装插件前先停止 Grafana 服务,完成安装后再重新启动。 ### 安装 Datalayers 数据源插件 @@ -82,12 +107,13 @@ bash -c "$(curl -fsSL \ # 参数为 Datalayers 连接相关配置:`-h` 为地址和端口,`-u` 为用户名,`-p` 为密码,请根据实际情况修改 ``` -该脚本将为你自动安装插件,并在当前目录生成相关配置文件,脚本运行结束后,请根据脚本提示,进入到你的 Grafana 实例目录,启动 Grafana 服务。 +该脚本会自动安装插件,并在当前目录生成相关配置文件。脚本执行完成后,请根据终端提示进入 Grafana 实例目录并启动 Grafana 服务。 ::: ::: tab 手动安装 -下载[Grafana 插件](https://github.com/datalayers-io/grafana-datalayers-datasource/releases) 并解压到本地,例如 `./myplugins`。 -编辑你的 `grafana.ini`,找到并修改如下配置: + +- 下载 [Grafana 插件](https://github.com/datalayers-io/grafana-datalayers-datasource/releases) 并解压到本地目录,例如 `./myplugins`。 +- 编辑 `grafana.ini`,找到并修改如下配置: ```ini [paths] @@ -97,13 +123,11 @@ plugins = YOUR_UNZIP_DIRECTORY/myplugins allow_loading_unsigned_plugins = datalayersio-datasource ``` -修改配置后,需要重启 Grafana 服务。 - -打开浏览器,登录到 Grafana,通常是默认的 `3000` 端口。 +- 保存配置并重启 Grafana 服务。 -- 添加数据源 +- 打开浏览器并登录到 Grafana,默认访问地址通常为 `http://127.0.0.1:3000`。 -点击左侧菜单 `Connections - Data sources`, 然后点击 `Add new data source` 按钮, 找到 `Datalayers` 数据源: +- 在左侧菜单中进入 `Connections > Data sources`,点击 `Add new data source`,然后搜索并选择 `Datalayers` 数据源。 ![find datasource](../assets/find_datasource.png) @@ -113,61 +137,46 @@ allow_loading_unsigned_plugins = datalayersio-datasource ### 配置插件 -此时 Grafana 和 Datalayers 数据源插件均已就绪,请通过本地浏览器,登录到 Grafana。 +此时 Grafana 和 Datalayers 数据源插件均已就绪,请在浏览器中登录 Grafana,并完成数据源配置。 -请按照下方图示填入对应的数据库地址+端口、用户名+密码、默认的数据库名称,如果开启了 TLS 还需要填写证书。 +请按照下方图示填写数据库地址和端口、用户名和密码,以及默认数据库名称;如果实例开启了 TLS,还需要补充证书相关配置。 ![config plugin](../assets/datalayers-with-grafana/config_datasource.png) -配置完成后,你可以点击 `Save & test` 按钮保存并测试连通性。 +配置完成后,点击 `Save & test` 验证连通性。若测试失败,请优先检查实例地址、端口、认证信息以及 Grafana 与 Datalayers 之间的网络是否连通。 ### 数据查询 -我们之前已经写入了一些示例数据,你可以通过 Datalayers 数据源插件进行一些查询。 +前面已经写入了示例数据,此时可以通过 Datalayers 数据源插件执行查询。 ![select all](../assets/datalayers-with-grafana/select_all_example.jpg) -图中使用 `Home - Explore` 面板查询数据,在默认可视化构建模式下可生成 `select * from demo.test` 这类查询语句。 +图中使用 `Home > Explore` 面板查询数据。在默认可视化构建模式下,可以自动生成类似 `select * from demo.sensor_info` 的查询语句。 -当然也可以切换到 SQL 编辑器模式,编写更复杂的查询语句。 +如果需要更复杂的分析逻辑,也可以切换到 SQL 编辑器模式,自行编写查询语句。 ![select data use sql-editor](../assets/datalayers-with-grafana/switch_to_sql_editor.jpg) -你也可以使用函数对数据进行聚合等操作,详见[SQL 函数](../sql-reference/aggregation.md)。 +你也可以结合聚合函数进行统计分析,详见 [SQL 函数](../sql-reference/aggregation.md)。 -在插件的编辑器模式中,你可以使用一些 Grafana 变量,请点击帮助按钮查看: +在插件编辑器模式中,还可以使用 Grafana 变量。可点击帮助按钮查看变量说明与用法: ![help button](../assets/datalayers-with-grafana/plugin_help.png) ::: tip -请注意,在 Grafana 插件中查询语句建议通过 . 的方式来指定数据库。 +在 Grafana 插件中,建议通过 `数据库名.表名` 的形式引用对象,例如 `demo.sensor_info`,以避免默认数据库切换带来的歧义。 ::: ### 添加 Dashboard -现在,你也可以使用 `Grafana - Dashboards` 功能开始添加一个 Dashboard,如下图: +完成查询验证后,即可在 Grafana 中创建 Dashboard,如下图所示: ![select data use sql-editor](../assets/datalayers-with-grafana/dashboard.jpg) -在此界面可进行更精细的调整,调整完成后可以点击 `Apply` 应用这个 `Panel`,当你添加了较多的 `Panel`,就可以通过 Grafana 强大的自定义编辑功能组合成一个丰富的 Dashboard。 - -## Docker Compose 一键部署 - -如果您希望免去安装和配置 Datalayers 与 Grafana 的过程,可以通过我们提供的 Docker Compose 方案进行零配置快速体验。 - -首先你需要拉取这个 [开源项目](https://github.com/datalayers-io/datalayers-with-grafana)。它使用 Docker 将 Datalayers 及其相关镜像整合到一个 `docker-compose` 文件中,从而快速启动这些服务。 - -``` bash -git clone https://github.com/datalayers-io/datalayers-with-grafana.git -``` - -然后请跟随 README 文档完成启动、快速写入示例数据的过程。 - -当你完成上述步骤后,就已经自动完成了上述所有的安装、配置、写入示例数据步骤,你可以直接进行数据查询、添加 Dashboard 相关操作。 - -通过将 Datalayers 与 Grafana 结合,可以更高效地完成时序数据可视化、指标分析与业务看板构建。 +在该界面中,你可以进一步调整查询语句、时间范围、图表类型和显示样式。单个 Panel 调整完成后点击 `Apply` 保存;当添加多个 Panel 后,即可组合出完整的业务监控或设备分析 Dashboard。 ## 相关文档 - 如果你还没有准备测试数据,请参考 [Datalayers 命令行工具 dlsql 使用指南](../getting-started/command-line-tool.md) -- 如果你希望使用图形化数据库工具排查查询结果,请参考 [Datalayers 集成 DBeaver 指南](./datalayers-with-dbeaver.md) +- 如果你希望使用图形化数据库工具排查查询结果,请参考 [Datalayers 集成 DBeaver 使用指南](./datalayers-with-dbeaver.md) +- 如果你需要进一步了解聚合查询与 SQL 能力,请参考 [SQL 参考](../sql-reference/data-type.md) diff --git a/zh_CN/releases/changes.md b/zh_CN/releases/changes.md index d04b4f07..3102c866 100644 --- a/zh_CN/releases/changes.md +++ b/zh_CN/releases/changes.md @@ -4,6 +4,22 @@ description: "Datalayers 版本更新日志(Changelog):按版本列出新 --- # 版本更新日志 +## 2.4.5 + +发布日期: 2026-08-04 + +本版本重点完善了 PostgreSQL 兼容性适配。 + +### 功能增强 + +- PostgreSQL 兼容性提升,现在 Grafana 中可使用 PostgreSQL 协议与 Datalayers 进行交互。 + +### 问题修复 + +- Prepared Statement 优化:修复服务重启后因客户端缓存可能执行失败的问题。 +- PostgreSQL SQL Hint 修复:PostgreSQL 协议支持 SQL Hint,提升兼容性与执行稳定性。 +- 聚合稳定性修复:修复 `count` 查询在特定场景(SQL Hint)下可能触发 panic 的问题。 + ## 2.4.4 发布日期: 2026-07-22