插件〉SQLite

数据源

社区

SQLite

概览
安装
变更日志
相关内容

Grafana SQLite 数据源

这是一个 Grafana 后端插件，允许使用 SQLite 数据库作为数据源。SQLite 数据库需要能够被运行 Grafana 的设备的文件系统访问。

插件安装
支持时间格式化列
宏
警报
常见问题 - FAQ
开发和贡献
支持项目
更多文档和链接

插件安装

对于大多数用户来说，推荐的安装插件的方法是使用 grafana CLI

运行此命令：grafana-cli plugins install frser-sqlite-datasource
重启 Grafana 服务器。
要确保插件已安装，请检查已安装数据源的列表。点击主菜单中的“Plugins”项。核心数据源和已安装数据源都会显示出来。

对于其他安装选项（例如安装尚未在 Grafana 注册表中发布但在 Github 中的版本），请参阅./docs/installation.md。

支持时间格式化列

SQLite 没有原生的“时间”格式。它依赖字符串和数字来表示时间和日期。然而，特别是对于时间序列，Grafana 需要一个实际的时间类型，因此该插件提供了一种推断真实时间戳的方法。这可以在查询编辑器中通过提供应格式化为时间戳的列的名称来设置。

该插件支持两种不同的输入，可以根据应格式化为“时间”的列中值的类型转换为“时间”

数字输入：假定为 Unix 时间戳 / Unix epoch。这表示以**秒**为单位的时间（请确保您的时间戳不是毫秒）。更多信息在此：https://en.wikipedia.org/wiki/Unix_time
字符串输入：值应按照 **RFC3339** 格式化，例如 "2006-01-02T15:04:05Z07:00"。可能会出现边缘情况，此处使用的解析库是事实的来源：https://golang.ac.cn/pkg/time/#pkg-constants。

存储为 Unix epoch 的时间戳应该开箱即用，但字符串格式可能需要调整您当前的格式。下面的示例展示了如何将“日期”列转换为可解析的时间戳

WITH converted AS (
   -- a row looks like this (value, date): 1.45, '2020-12-12'
   SELECT value,  date || 'T00:00:00Z' AS datetime FROM raw_table
)
SELECT datetime, value FROM converted ORDER BY datetime ASC

宏

此插件支持受内置 Grafana 数据源启发的宏（例如 https://grafana.org.cn/docs/grafana/latest/datasources/postgres/#macros）。

然而，由于每个宏都需要从头重新实现，因此只支持以下宏。此插件尚不支持其他宏（您可能期望来自其他 SQL 数据库）。

$__unixEpochGroupSeconds(unixEpochColumnName, intervalInSeconds)

示例：$__unixEpochGroupSeconds("time", 10)

将被替换为 GROUP BY 子句中可用的表达式。例如：cast(("time" / 10) as int) * 10

$__unixEpochGroupSeconds(unixEpochColumnName, intervalInSeconds, NULL)

示例：$__unixEpochGroupSeconds(timestamp, 10, NULL)

这与上面的示例相同，但带有一个填充参数，以便为 Grafana 添加该系列中缺失的点，并将 NULL 用作值。

如果提供了多个时间列，则选择第一个列作为确定间隙填充的列。“第一个”在此上下文中是指 SELECT 语句中的第一个。此列不能有 NULL 值，并且必须按升序排序。

警报

该插件支持 Grafana 的警报功能。与内置数据源类似，警报不支持变量，因为它们通常在前端替换，而警报不涉及前端。为了允许时间过滤，此插件支持变量 $__from 和 $__to。有关这些变量的更多信息，请参阅：https://grafana.org.cn/docs/grafana/latest/variables/variable-types/global-variables/#__from-and-__to。但是，警报不支持这些变量的格式化（例如 ${__from:date:iso}）。

常见问题 - FAQ

这是常见问题或问题的列表。有关答案和更多详细信息，请参阅./docs/faq.md。

查询示例

一些帮助您开始使用 SQL 和 SQLite 的示例可以在./docs/examples.md 中找到。

这些示例包括以下内容：

按 Grafana UI 中指定的时间过滤
创建有间隙的时间序列
将日期转换为时间戳
...

开发和贡献

欢迎任何贡献。有关本地设置的一些信息可以在 DEVELOPMENT.md 文件中找到。

支持项目

本项目作为开源项目免费开发。并将保持这种方式。

如果您喜欢使用此插件并希望支持开发，请查看 Github 赞助页面。这允许通过月度或一次性捐款来赞助项目。

变更日志

本项目所有值得注意的更改都将记录在此文件中。

格式基于Keep a Changelog，并遵循语义化版本控制。

[3.5.0] - 2024-03-08

新增

添加了为查询变量使用 "__text" 和 "__value" 列的功能

[3.4.0] - 2023-12-26

感谢此版本中的贡献者

@eeddaann

新增

添加了对 Grafana 注释的支持

[3.3.3] - 2023-07-21

变更

使用 grafana/create-plugin 工具更新了前端包

[3.3.2] - 2023-07-19

修复

没有内容的查询（即 "-- not a query"）不再导致插件挂起

变更

更新了底层 sqlite 库

[3.3.1] - 2023-07-01

修复

在每次查询后关闭数据库连接（v3.3.0 中的 bug）

变更

功能回归：没有内容的查询（即 "-- not a query"）导致插件挂起

[3.3.0] - 2023-06-11

变更

更新了 sqlite 包版本以允许设置限制
添加了设置 SQLITE_LIMIT_ATTACHED 的选项（当前默认值为 10）。在未来的版本中，默认值将降至 0。

[3.2.0] - 2023-05-25

变更

更新了 go 版本和 go grafana 插件 sdk
使用 grafana 插件 sdk mage 文件构建插件
更新 grafana 插件 npm 包

[3.1.4] - 2023-05-17

未更改任何面向用户的部分。唯一的区别是为了适应新的 Grafana 插件检查而更改了元数据。

[3.1.3] - 2023-05-06

变更

将 go SQLite 包更新至 v1.22.1 以修复 SQLite 中的时区问题

[3.1.2] - 2022-09-11

变更

更新了 go SQLite 包

[3.1.1] - 2022-09-11

变更

从数据帧中移除了 "name" 元数据

[3.1.0] - 2022-07-09

变更

使用不同的组件作为 SQL 编辑器
更新了 Readme 并添加了更多文档（例如示例查询）
改进了文件夹路径上数据库检查的错误消息

感谢本项目的赞助者

一次性捐助：@nikolaialex

[3.0.1] - 2022-03-15

此版本应无功能变更。一些底层包已更新，应能提高稳定性和安全性，但没有其他明显影响。

变更

修复了 readme 中的一些拼写错误
移除了插件的 Grafana 版本上限约束
更新了后端的 grafana 插件 sdk
更新了前端的 grafana buildkit 和测试工具版本

[3.0.0] - 2022-02-26

此版本切换到了一个新的底层 SQLite 库：https://pkg.go.dev/modernc.org/sqlite。这对常规查询应无重大影响，但可能会影响更微妙的配置（例如路径选项）。有关更多信息，请参阅下方的 Changed 部分。

此库不依赖 CGO，这使得跨系统交叉编译变得容易得多。通过这种方式，插件现在拥有更简单的构建过程，并支持更多平台（请参阅下方 Added 部分的信息）

新增

新增了以下平台的发布版本：用于 ARM（Apple Silicon）的 Darwin (MacOS) 和用于 AMD64 的 FreeBSD

变更

将底层 SQLite 库更改为：https://pkg.go.dev/modernc.org/sqlite。虽然常规 SQLite 功能，特别是查询应该保持不变，但路径选项现在需要检查与新库的兼容性。有关选项的更多信息，请参阅上述链接。

已移除

不再为 ARM v7 单独创建发布版本。ARM v6 应适用于所有设备。如果您的设备不适用，请提交新 issue。

[2.2.1] - 2021-12-14

新增

新增了一个选项 securePathOptions，以防用户想要保护某些选项（通常是凭据）。示例请参见：https://github.com/mattn/go-sqlite3#connection-string

[2.2.0] - 2021-11-16

插件现在支持向 SQLite 连接字符串添加路径前缀和选项。

新增

可以在连接字符串中提供前缀和选项的功能。示例请参见：https://github.com/mattn/go-sqlite3#connection-string

变更

略微更改了插件健康检查（添加数据源时），以提供更好的错误消息。
查询期间的转换错误现在以 DEBUG 级别记录，以避免日志文件过大。

[2.1.1] - 2021-10-24

此版本增加了对 Unix 时间亚秒级精度的支持。

新增

在 SQLite 中使用数字值表示时间戳（Unix 时间戳）时，插件现在支持亚秒级精度（纳秒级精度）

[2.1.0] - 2021-08-08

此版本将 JSON 扩展添加到编译的 SQLite 代码中。

新增

SQLite 的 JSON 扩展

[2.0.2] - 2021-08-07

此版本针对 Grafana v8.1.0 进行了测试，并修复了查询变量问题。

修复

查询变量现在也可以在 Grafana v8.X.X 中使用

[2.0.1] - 2021-07-27

此版本修复了一些长期存在的问题，这些问题阻止了插件警报功能的正常使用，尽管该功能已启用。

修复

使用 $__from 和 $__to 变量进行警报
修复查询的缓存 bug（用于警报）

[2.0.0] - 2021-05-07

当前所有 Raspberry Pi Zero 和 1 型号都采用 ARMv6 架构。所有其他型号（2 Mod. B v1.2、3 和 4）都采用 64 位 ARMv8 架构。由于只有 Raspberry Pi 2 Mod. B 具有 ARMv7 架构，因此不再将其用作默认值。Raspberry Pi 2 Mod. B 将需要手动安装，而其他所有型号将通过 Grafana CLI 处理。