Telegraf SQL 输入插件支持的数据库驱动与 DSN 配置完整指南【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafTelegraf 的 SQL 输入插件inputs.sql通过driverdsn两个选项即可对接十余种主流关系型数据库将 SQL 查询结果直接转换为指标measurement / tags / fields / time。本篇指南以 docs/SQL_DRIVERS_INPUT.md 为骨架结合仓库中 驱动注册源码、插件核心实现 与集成测试系统讲解每个可用驱动的 DSN 格式、别名机制、类型转换规则与排障方法读完即可为任意受支持数据库写出可运行的 Telegraf 配置。一、理解driver与dsn双要素SQL 输入插件⭐ 自 Telegraf v1.19.0 引入分类为 datastore的顶层配置只有两个必填项[[inputs.sql]] driver mysql dsn username:passwordtcp(mysqlserver:3307)/dbname?paramvaluedriver指定使用哪个数据库驱动Telegraf 在编译期通过空导入blank import方式注册全部驱动见 plugins/inputs/sql/drivers.go。dsnData Source Name数据库连接串其格式完全由驱动决定且可能随驱动版本变化。同一个插件实例只能连接一个数据库但可以配置多个query小节执行不同查询。在 插件初始化逻辑 中若driver为空会直接报错missing SQL driver option若dsn为空则报missing data source name (DSN) option随后 Telegraf 会通过 Go 标准库database/sql的Drivers()列表校验驱动是否可用。二、支持的驱动总览下表完整列出当前仓库支持的数据库、可用驱动名、别名与示例 DSN来自 docs/SQL_DRIVERS_INPUT.md数据库driver别名aliases示例 DSNClickHouseclickhouse—tcp://host:port[?param1value...paramNvalue]CockroachDBcockroachpostgres/pgx见下文的 postgres 驱动FlightSQLflightsql—flightsql://[username[:password]]host:port?timeout10s[tokenTOKEN][param1value1...paramNvalueN]IBM Netezzanzgo—hostyour_nz_host port5480 useryour_nz_user passwordyour_nz_password dbnameyour_nz_db_name sslmodedisableMariaDBmariamysql见下文的 mysql 驱动Microsoft SQL Serversqlservermssqlsqlserver://username:passwordhost/instance?param1valueparam2valueMySQLmysql—[username[:password]][protocol[(address)]]/dbname[?param1value1...paramNvalueN]Oracleoracleoracleoracle://username:passwordhost:port/service?param1valueparam2valuePostgreSQLpostgrespgxpostgresql://[user[:password]][netloc][:port][,...][/dbname][?param1value1...]SAP HANAgo-hdbhanahdb://user:passwordhost:portSQLitesqlite—filename数据库文件名TiDBtidbmysql见下文的 mysql 驱动Verticavertica—vertica://(user):(password)(host):(port)/(database)[?arg1value...argNvalueN]驱动注册的源码证据drivers.go 通过空导入完成全部驱动的注册其实际导入路径即各驱动在 Go 生态中的实现库_ github.com/ClickHouse/clickhouse-go/v2 // clickhouse _ github.com/IBM/nzgo/v12 // nzgo _ github.com/SAP/go-hdb/driver // go-hdb _ github.com/apache/arrow-go/v18/arrow/flight/flightsql/driver // flightsql _ github.com/go-sql-driver/mysql // mysql _ github.com/jackc/pgx/v5/stdlib // pgx _ github.com/microsoft/go-mssqldb // sqlserver _ github.com/sijms/go-ora/v2 // oracle _ github.com/vertica/vertica-sql-go // vertica其中SQLite驱动modernc.org/sqlite是唯一一个单独放在 drivers_sqlite.go 中的它是纯 Go 实现并通过 build tags 限定了平台支持矩阵linux 的 386/amd64/arm/arm64/loong64/ppc64le/riscv64/s390xdarwin 与 freebsd 的 amd64/arm64以及 windows、openbsd 的部分架构编译 Telegraf 时会自动按目标平台裁剪。三、驱动别名机制一个配置名映射到底层驱动文档特别指出某些数据库是通过另一个驱动得到支持的如 CockroachDB 复用 PostgreSQL 驱动或为了直观起见提供了比底层驱动名更易记的名字如postgres之于pgx。因此配置时可以直接使用别名。这一机制在 sql.go 中有明确实现——Init()内部维护了一张别名映射表aliases : map[string]string{ cockroach: pgx, tidb: mysql, mssql: sqlserver, maria: mysql, postgres: pgx, oracle: oracle, } s.driverName s.Driver if driver, ok : aliases[s.Driver]; ok { s.driverName driver }也就是说配置driver maria、mysql或tidb时最终都会打开底层mysql驱动MariaDB、TiDB 与 MySQL 完全兼容同一驱动配置driver postgres、cockroach时打开的是pgx驱动配置driver mssql时打开的是sqlserver驱动oracle的别名与底层驱动名一致。如果配置的驱动名不在支持列表中Init()会返回类似driver xxx not supported use one of [...]的错误并列出当前编译内实际可用的全部驱动名含别名便于排查拼写问题。需要提醒的是别名与驱动名存在版本演进差异若某个文档列出的别名在当前版本不可用请以该错误信息列出的可用列表为准或直接使用底层驱动名。四、各驱动 DSN 深入说明文档强调表中给出的 DSN 只是示例具体参数与格式请以各驱动文档为准且 DSN 格式可能在驱动升级时发生变化。下面按驱动族逐一展开说明并结合仓库集成测试给出可复现的连接方式。4.1 MySQL 家族MySQL / MariaDB / TiDBdrivermysqlMariaDB 用mariaTiDB 用tidb均映射到底层mysql驱动DSN 通用格式[username[:password]][protocol[(address)]]/dbname[?param1value1...paramNvalueN]常见形态TCPusername:passwordtcp(host:3306)/dbname?parseTimetrueUnix 套接字username:passwordunix(/var/run/mysqld.sock)/dbname无密码本地root/nation示例配置中的简写形式集成测试 中正是用root:passwordtcp(addr)/foo这种 DSN 连接 MariaDB 容器完成验证配置示例来自 sample.conf[[inputs.sql]] driver maria dsn username:passwordtcp(mysqlserver:3307)/dbname?paramvalue4.2 PostgreSQL 家族PostgreSQL / CockroachDBdriverpostgres或底层pgxCockroachDB 用cockroach同映射到pgxDSN 格式libpq 连接串风格postgresql://[user[:password]][netloc][:port][,...][/dbname][?param1value1...]也支持 key-value 风格host... port... user... password... dbname... sslmodedisablePostgreSQL 的集成测试见 sql_test.go 起测试数据脚本位于 plugins/inputs/sql/testdata/postgres/expected.sql。4.3 Microsoft SQL Serverdriversqlserver别名mssql底层为github.com/microsoft/go-mssqldbDSN 格式sqlserver://username:passwordhost/instance?param1valueparam2valueinstance用于指定命名实例连接参数如encrypt、database通过 query string 传递。4.4 Oracledriveroracle底层为github.com/sijms/go-ora/v2DSN 格式oracle://username:passwordhost:port/service?param1valueparam2value注意是service服务名而非 SID端口默认 1521。4.5 ClickHousedriverclickhouse底层为github.com/ClickHouse/clickhouse-go/v2DSN 格式tcp://host:port[?param1value...paramNvalue]在 ClickHouse 测试建表脚本 中可以看到典型的 ClickHouse 表结构MergeTree 引擎、Int64/String字段可直接作为inputs.sql查询测试目标。4.6 FlightSQLdriverflightsql底层为 Apache Arrow 的github.com/apache/arrow-go/v18/arrow/flight/flightsql/driverDSN 格式flightsql://[username[:password]]host:port?timeout10s[tokenTOKEN][param1value1...paramNvalueN]支持timeout连接超时、token等参数适用于通过 Arrow Flight SQL 协议访问支持该协议的数据库服务。4.7 SAP HANAdrivergo-hdb文档列为别名hana底层为github.com/SAP/go-hdb/driverDSN 格式hdb://user:passwordhost:port属纯 Go 实现无需 CGO。4.8 IBM Netezzadrivernzgo底层为github.com/IBM/nzgo/v12DSN 格式key-value 风格hostyour_nz_host port5480 useryour_nz_user passwordyour_nz_password dbnameyour_nz_db_name sslmodedisable默认端口 5480sslmode控制 TLS 行为。4.9 SQLitedriversqlite底层为纯 Go 的modernc.org/sqliteDSN 格式直接写数据库文件名如dsn /var/lib/telegraf/metrics.db无需账号密码是无服务器嵌入式数据库的典型用法平台支持范围以 drivers_sqlite.go 的 build tags 为准。4.10 Verticadriververtica底层为github.com/vertica/vertica-sql-goDSN 格式vertica://(user):(password)(host):(port)/(database)[?arg1value...argNvalueN]五、类型转换机制驱动负责插件兜底文档明确指出Telegraf 依赖数据库驱动和 Go 标准database/sql框架完成类型转换。如果遇到转换问题请向项目提交 issue。具体到指标四个组成部分插件 README 给出了严格的类型约定并在 sql.go 的parse方法 中落地指标成分接受类型转换规则measurement仅string取measurement_column指定列的值缺省列时回退到measurement设置默认sqltimetime类型、数值或字符串数值/字符串按time_format解析支持unix、unix_ms、unix_us、unix_ns或任意 Go 时间格式默认unixtagsstring、bytes、各宽度整型、浮点、bool、time一律转成字符串空值trim 后为空的 tag 会被跳过fields同上bytes→string有符号/无符号整型→int64/uint64浮点→float64time→纳秒时间戳int64在parse的自动转换分支中可以看到具体实现[]byte转string、time.Time取UnixNano()、fmt.Stringer调用String()nil值的字段会被忽略不写入。显式类型转换优先如果不想依赖驱动的自动推断inputs.sql.query小节还提供了五组显式转换选项优先级高于自动转换且同一列不要同时出现在多组中否则结果类型未定义# field_columns_float [] # field_columns_int [] # field_columns_uint [] # field_columns_bool [] # field_columns_string []结合 Init() 可以看到这些列表在初始化时被编译为独立的 include-exclude 过滤器逐列匹配后调用internal.ToFloat64/ToInt64/ToUint64/ToBool/ToString做强制转换数值超范围ErrOutOfRange时只记警告而非中断采集。六、完整配置模板与可运行示例6.1 完整配置模板以下为 plugins/inputs/sql/sample.conf 的完整内容参数注释与默认值均已保留# Read metrics from SQL queries [[inputs.sql]] ## Database Driver ## See docs/SQL_DRIVERS_INPUT.md for a list of supported drivers. driver mysql ## Data source name for connecting ## The syntax and supported options depends on selected driver. dsn username:passwordtcp(mysqlserver:3307)/dbname?paramvalue ## Timeout for any operation ## Note that the timeout for queries is per query not per gather. # timeout 5s ## Connection time limits ## By default the maximum idle time and maximum lifetime of a connection is unlimited. # connection_max_idle_time 0s # connection_max_life_time 0s ## Connection count limits ## By default the number of open connections is not limited and the maximum idle ## connections will be inferred from the number of queries specified. # connection_max_open 0 # connection_max_idle auto ## Specifies plugin behavior regarding disconnected servers ## Available choices: ## - error: telegraf will return an error on startup if one of the servers is unreachable ## - ignore: telegraf will ignore unreachable servers on both startup and gather # disconnected_servers_behavior error [[inputs.sql.query]] ## Query to perform on the server query SELECT user,state,latency,score FROM Scoreboard WHERE application 0 ## Alternatively specify a file containing the SQL query. ## Only one of query and query_script can be specified! # query_script /path/to/sql/script.sql ## Name of the measurement # measurement sql ## Column name containing the name of the measurement ## Takes precedence over measurement if the query returns this column. # measurement_column ## Column name containing the time of the measurement ## If omitted, the time of the query will be used. # time_column ## Format of the time contained in time_column ## Must be unix, unix_ms, unix_us, unix_ns, or a golang time format. # time_format unix ## Column names containing tags # tag_columns_include [] # tag_columns_exclude [] ## Column names containing fields (explicit types) # field_columns_float [] # field_columns_int [] # field_columns_uint [] # field_columns_bool [] # field_columns_string [] ## Column names containing fields (automatic types) ## An empty include list is equivalent to [*]. # field_columns_include [] # field_columns_exclude []6.2 关键参数的源码级默认值在 sql.go 的init()与Init()中可以看到插件为顶层参数设置了默认值timeout≤ 0 时默认5s且是每条查询的超时而非整轮 gather 的超时connection_max_idle默认值为magicIdleCount即自动计算实际取len(Queries) 2即按查询数推导空闲连接数connection_max_open、connection_max_idle_time、connection_max_life_time默认 0 表示不限制disconnected_servers_behavior默认error可选ignore在Start/Gather阶段对不可达服务器采取的策略见 Start()query 小节measurement默认sqltime_format默认unix。6.3 查询执行流程从 Gather() 可以看到每个 query 会先在服务端PrepareprepareStatements若驱动不支持 prepare 则回退为未预编译查询仅告警不中断随后每个采集周期对每条查询启动一个 goroutine 并发执行插件启动时若服务器不可达且策略为ignore会在后续 Gather 周期持续尝试重连ping并补做 prepare。6.4 真实输出示例插件 README 使用 MariaDB 示例库与如下配置[[inputs.sql]] driver mysql dsn root:password/nation [[inputs.sql.query]] query SELECT * FROM guests measurement nation tag_columns_include [name] field_columns_exclude [name]输出如下name作为 tagguest_id作为 fieldnation,hostHugin,nameJohn guest_id1i 1611332164000000000 nation,hostHugin,nameJane guest_id2i 1611332164000000000 nation,hostHugin,nameJean guest_id3i 1611332164000000000 nation,hostHugin,nameStorm guest_id4i 1611332164000000000 nation,hostHugin,nameBeast guest_id5i 16113321640000000006.5 使用秘密存储保护 DSNdsn支持从 secret store 引用密码等敏感信息见 CONFIGURATION.md 的 secret store 章节。在源码层面Dsn字段类型为config.Secretsql.gosetupConnection()中通过Get()取密文后立即Destroy()清空内存避免明文长期驻留。七、排障指南7.1 提示驱动不支持Init()会报告driver xxx not supported use one of [...]错误信息中会列出当前构建实际可用的全部驱动与别名。常见原因驱动名拼写错误、该驱动在你的平台构建中被裁剪尤其注意 SQLite 的平台 build tags、或使用了未注册的别名。7.2 我的数据库不受支持怎么办文档明确说明Telegraf 目前无法支持 CGO 驱动CGO 会给二进制分发与交叉编译带来大量负担。因此接入新数据库的前提是存在针对 Go 标准database/sql框架的纯 Go 驱动。如果找到了这样的驱动请通过 issue 或 pull request 告知项目维护者。7.3 文档有误或发现 Bug文档有误请开 issue或直接提交 pull request 修正发现 Bug请开 issue附上驱动、DSN 形态与报错信息或提交 pull request类型转换异常由于 Telegraf 依赖驱动与database/sql框架的类型转换遇到转换问题同样建议先确认驱动版本与 DSN 参数如 MySQL 的parseTime再开 issue。7.4 更多帮助如果以上手段都无效可以到 Telegraf 官方论坛或社区聊天渠道求助——带上驱动名、完整 DSN 脱敏版本、Telegraf 版本与最小复现配置通常能最快定位问题。八、小结SQL 输入插件以driverdsn两个参数对接 13 种数据库其核心设计可以概括为三点同一套指标映射逻辑measurement/time/tags/fields 的统一转换、别名抽象层postgres/maria/mssql/cockroach/tidb等映射到底层驱动、纯 Go 驱动约束拒绝 CGO。理解 docs/SQL_DRIVERS_INPUT.md 中的驱动表与 sql.go 的实现就能快速完成任一受支持数据库的指标采集配置遇到 DSN 细节问题请以对应驱动文档各驱动链接见上方表格仓库内对应导入路径见 drivers.go为最终依据。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考