Skip to content

docs: v2.4.5 #327

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yinbo3 merged 1 commit into from
Aug 4, 2026
Merged

docs: v2.4.5 #327

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 56 additions & 47 deletions zh_CN/integration/datalayers-with-grafana.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 中验证查询与可视化效果。

首先，通过以下命令连接到数据库：

Expand All @@ -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,
Expand All @@ -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);
Expand All @@ -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 数据源插件

Expand All @@ -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]
Expand All @@ -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)

Expand All @@ -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 插件中查询语句建议通过 <db_name>.<table_name> 的方式来指定数据库。
在 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)
16 changes: 16 additions & 0 deletions zh_CN/releases/changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down