libpqxx 数据类型扩展指南为 PostgreSQL 文本转换系统定制 C 类型的完整实现【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOnelibpqxx 与 PostgreSQL 之间的数据通信几乎全部以文本格式进行本指南围绕 libpqxx 7.7.3 官方文档《Supporting additional data types》展开系统讲解其字符串转换string conversion机制的运行原理以及如何通过特化pqxx::type_name、pqxx::nullness、pqxx::string_traits三个核心模板为任意 C 类型包括第三方库类型、标准库尚未覆盖的类型接入 PostgreSQL 的文本格式。读完本文你将能够为自定义类型编写可编译、可运行、可进 SQL 查询与结果读取的完整转换支持并理解to_buf/into_buf/size_buffer缓冲区契约、可选的is_unquoted_safe优化以及二进制参数param_format的取舍逻辑。一、转换系统总览一切皆文本libpqxx 与数据库的通信大多以文本形式进行当你把一个整数值写进查询时是通过to_string把它转换成文本当你想把某个查询结果字段当作浮点数读取时则是从文本格式转换回浮点类型。这些转换遍布 libpqxx 的各个角落其核心模板与实现集中在 include/pqxx/strconv.hxx源文档树中的副本见 include/pqxx/doc/datatypes.md。转换系统内置支持大量 C 类型同时是可扩展的你可以在自己应用的范围内教会libpqxx 把更多类型的值与 PostgreSQL 的字符串格式互相转换。这非常实用但也并不简单——你需要特化若干模板而且这个扩展 API 可能随 libpqxx 的任何一个大版本发布而改变官方文档明确警告了这一点因此迁移到新大版本时需要注意检查相关特化的兼容性。二、类型驱动的转换值、类型与异常在应用中一次转换完全由你指定的 C 类型驱动。值的 SQL 类型与转换无关字符串本身也不会携带任何类型标识。因此如果从数据库 SELECT 出一个 64 位整数而你尝试把它转换成 C 的short只会有两种结果要么数字小到能塞进short转换成功要么抛出转换异常pqxx::conversion_error。反过来数据库表里可能是一个文本列但某个字段恰好看起来像数字——你完全可以把它转换成整数或浮点类型。对转换而言唯一重要的是实际的值和目标类型。大多数情况下模板可以从你传入的参数推断出类型auto x to_string(99); // int → std::string某些场景则必须显式实例化模板auto y from_stringint(99); // 显式指定目标类型为 int从源码看这两个函数是 libpqxx 的通用入口from_string最终委托给string_traitsTYPE::from_string(text)见 strconv.hxx#L292-L296同时还有一个双参数重载from_string(text, value)通过引用参数就地写结果strconv.hxx#L321-L324to_string则负责不带有千位分隔符等花哨格式、完全不受 locale 影响的纯文本输出strconv.hxx#L327-L333。三、支持一个新类型完整步骤假设你有某种想要存入数据库或从数据库取回的 SQL 类型需要做哪些事首先明确一点你并不总是需要完整的双向支持。例如你可能只需要转成字符串而不需要从字符串转回来。转换是在编译期定义的因此不必害怕不完整——漏掉其中某一步不会在运行时崩溃也不会破坏数据最坏的结果只是你的代码无法编译通过。一个完整的转换需要四件事一个 C 类型可以是自定义的也可以是第三方库的甚至是标准库中 libpqxx 尚未支持的类型特化pqxx::type_name变量指定类型的人类可读名称——所有在错误消息等文本中提及该类型的代码都要用到它特化pqxx::nullness模板说明该类型是否有内置的 null 值特化pqxx::string_traits模板在这里定义真正的转换逻辑。下面逐项展开。四、你的类型不要求自研、不要求改类由于 C 类型决定了正确的转换一种类型对应一组转换你需要的是一个尚未定义过转换的类型。这个类型不一定要是你自己创建的——转换逻辑的设计目标就是可以围绕任意类型构建完全可以为一个定义在别处的类型编写转换类型内部也不需要增加任何特殊方法或成员。这正是 libpqxx 能够支持int等内置类型的原因。4.1 枚举类型一个宏搞定如果类型是枚举上述工作全部可以省略只需在翻译单元靠近顶部的位置、位于全局命名空间中调用预处理器宏PQXX_DECLARE_ENUM_CONVERSION并把类型作为参数传入#include pqxx/strconv enum class Color { Red, Green, Blue }; namespace pqxx { PQXX_DECLARE_ENUM_CONVERSION(Color); }该宏定义于 strconv.hxx#L271-L274做了两件事把string_traitsENUM特化为继承自pqxx::internal::enum_traitsENUM同时给出type_nameENUM的字符串值。底层enum_traitsstrconv.hxx#L223-L255把转换委托给枚举底层整数类型std::underlying_type_tENUM的string_traits即以数字字符串的形式表示枚举值。需要更多定制时才手动从enum_traits派生。4.2 包装类型免费的附带支持库还为std::optionalT、std::shared_ptrT、std::unique_ptrT提供了现成的特化。只要你为T定义了转换这些包装类型也就自动获得了转换能力std::nullopt/空指针自然映射为 SQL NULL。五、特化type_name给错误消息一个可读的名字转换出错时libpqxx 会为使用者组装错误消息其中有时会包含被转换类型的名称。为此存在一个模板变量pqxx::type_name对任意类型T应当提供一份特化给出T的人类可读名称namespace pqxx { template std::string const type_nameT{T}; }注意这确实意味着你需要在pqxx命名空间内定义一些东西未来版本的 libpqxx 可能会把这部分挪到独立的命名空间。该模板的默认实现位于 strconv.hxx#L81-L82它会通过std::type_info::name()配合编译器相关的 demangle 生成名称。务必在翻译单元早期、任何可能触发 libpqxx 需要该名称的代码之前定义它——这样需要用到类型名的 libpqxx 代码才能看见你的定义。六、特化nullness类型有没有内置 nullpqxx::nullness是一个结构体模板strconv.hxx#L92-L110描述你的类型是否有天然的null 值如果有还提供产生与识别 null 值的成员函数。有三种典型场景。6.1 场景一没有内置 null最常见大多数类型没有内置 null 值。此时直接从pqxx::no_null派生你的 nullness traits 即可namespace pqxx { template struct nullnessT : pqxx::no_nullT {}; }pqxx::no_nullstrconv.hxx#L114-L144默认提供has_null false、always_null false并且is_null恒返回false。像int、std::string这类类型想表示 SQL null就得用std::optionalint这类带 null 的包装。有意思的是枚举类型甚至不用手动写——库已为所有枚举提供了基于no_null的偏特化strconv.hxx#L204-L207。6.2 场景二有自然的 null 值如果类型确实有天然的 null 值定义就复杂一些namespace pqxx { template struct nullnessT { static constexpr bool has_null{true}; static constexpr bool always_null{false}; static bool is_null(T const value) { // 返回 value 是否为 null。 return ...; } [[nodiscard]] static T null() { // 返回一个 null 值。 return ...; } }; }你可能会疑惑既然有了产生 null 值的null()为什么还要is_null()来判断因为两个 null 值未必相等T可能有多个不同的 null 值或者重载了比较运算符——就像 SQL 中 NULL 不等于 NULL 一样。所以不要拿值与null()的结果做相等比较来判断是否为 null。6.3 场景三永远为 null 的类型还有一种情况类型总是表示 null 值例如std::nullptr_t和std::nullopt_t。此时把always_null设为true当然同时也要设has_null并且不需要定义任何实际的转换函数。七、特化string_traits核心转换逻辑这部分工作量最大恒为 null 的类型可以跳过但这种情况很少见。需要特化pqxx::string_traits模板其完整接口定义见 strconv.hxx#L154-L201namespace pqxx { template struct string_traitsT { static T from_string(std::string_view text); static zview to_buf(char *begin, char *end, T const value); static char *into_buf(char *begin, char *end, T const value); static std::size_t size_buffer(T const value) noexcept; }; }需要编写这些成员函数中的全部或足以让代码编译通过的一部分。下面逐一说明其契约。7.1from_string从文本解析最简单把字符串解析为T类型的值并返回。要点传入的字符串不保证以零字节结尾它就是一段从头到尾不含尾的std::string_view。测试时务必覆盖字符串末尾没有零字节的情况字符串完全可能不是合法的T值——出错很正常。此时应抛出pqxx::conversion_error当然也可能遇到其他错误抛其他异常也没问题但当明确是这不是T的正确格式时请抛conversion_error。7.2to_buf把值写成 PostgreSQL 认识的字符串调用者会提供一个缓冲区供你写入字符串区间为begin到end不含end是左闭右开区间不要访问*end。若缓冲区不足以完成转换抛出pqxx::conversion_overrun。不必精确你可以稍微悲观一些、多要求一点空间但只要有溢出风险就必须抛异常不强制使用缓冲区。例如pqxx::string_traitsbool::to_buf直接返回编译期常量字符串完全忽略缓冲区即使使用了缓冲区字符串也不必从缓冲区开头写起。例如整数转换先从缓冲区末尾写最低位数字再往前写更高位——纯粹是当时写起来更顺手返回pqxx::zview。它本质上是std::string_view唯一区别是zview保证在string_view之后紧跟一个有效的零字节。该零字节不计入 size但它一定存在。源码中zview直接从std::string_view派生并额外提供c_str()等成员见 include/pqxx/zview.hxx#L37。以下不变量必须成立void invariant(zview z) { assert(z[std::size(z)] 0); }结尾零字节必须写在end之前。如果结尾零都放不进缓冲区那就是空间不足、无法完成转换警惕 locale。如果使用sprintf等标准库特性它们可能服从系统当前 locale同一个整数 1000000 在你这儿是1000000在别人那儿可能是1,000,000、1.000.000在印度系统上甚至是1,00,000。进出数据库的值必须使用非本地化格式。请直接使用 libpqxx 的pqxx::from_string、pqxx::to_string、pqxx::to_buf来完成这类转换。7.3into_buf更严格的版本into_buf是to_buf的严格版所有要求相同但额外要求必须把字符串写入缓冲区、并且恰好从begin开始。因此它只返回一个简单指针结尾零之后的地址。调用者想用字符串就去begin找想往缓冲区剩余部分写下一个值就从你返回的位置开始。常见写法是让to_buf直接调用into_buf——库为此提供了generic_to_buf辅助函数strconv.hxx#L439-L447它会调用into_buf并基于返回值构造正确的zview。7.4size_buffer预估缓冲区大小这里估计把一个T转成字符串需要多少缓冲区空间能精确就精确但悲观一点也没关系。与其花大量时间精确计算不如多浪费几个字节而因为少估了缓冲区导致转换失败是最糟的缓冲区大小要包含结尾零如果你的to_buf需要超出存储结果的空间也要一并计入尽量让size_buffer成为constexpr函数——这样调用者可以在编译期就知道大小从而在栈上分配缓冲区。八、可选优化一特化is_unquoted_safe把数组array或组合类型composite转成字符串时libpqxx 可能需要对值加引号并转义特殊字符这是有开销的。但有些类型——如整型和浮点型——其字符串表示永远不可能包含引号、逗号、反斜杠等特殊字符此时在数组或组合类型中无需加引号、也无需转义。如果你的类型属于这一类可以告诉 libpqxxnamespace pqxx { template inline constexpr bool is_unquoted_safeMY_TYPE{true}; }转换该类字段的代码随后就能使用更简单、更高效的路径。该模板的默认值定义于 strconv.hxx#L407。省略它永远安全——这纯粹是一个优化开关仅在你有十足把握时才打开。如果类型字符串表示中可能包含逗号、分号、圆括号、花括号、引号、反斜杠、换行符或任何可能需要转义的字符千万不要声明它为 unquoted-safe。九、可选进阶特化param_format与二进制参数这一项一般不需要操心只有在你编写表示原始二进制数据的类型或者编写一个某些特化可能包含原始二进制数据的模板时才需要阅读。调用参数化语句或带参数的预备语句prepared statement时libpqxx 需要把你的参数传递给底层 C 级 PostgreSQL 客户端库 libpq。传递参数有两种格式text文本与binary二进制。文本格式下所有值都用字符串表示由服务器再转换成其内部二进制表示——这正是字符串转换系统的工作也是绝大多数参数类型的处理方式。但有一种情况不同当参数是一段连续的原始字节、且对应 SQL 类型为BYTEA时虽然也存在文本格式libpqxx 为了效率会绕过它。服务器可以直接使用完全相同形式的二进制数据无需任何转换或额外处理而且二进制数据在传输中体积也压缩了一半详见配套文档 binary-data.md。有人会问为什么不把所有类型都按二进制处理官方文档给出的解释是一般情况并不那么清晰二进制格式没有公开文档、不保证跨平台一致、也不保证长期稳定而且很难可靠地检测格式是否用错更重要的是转换未必像听起来那么直白高效。因此通用场景下 libpqxx 坚持使用文本格式只有原始二进制数据是明确的净收益。param_format函数模板就是做这个决策的默认实现见 strconv.hxx#L422为可能是二进制字符串的类型特化它其余类型用默认值。这里可能一词很关键包装模板std::shared_ptrT、std::optionalT等是另一种类型的包装std::optionalT是否二进制取决于T是否二进制。为这类模板建支持时往往需要实现param_format基于对象的决策二进制与否是针对给定对象判断的不必然取决于类型本身。比如std::variant可能装int也可能装二进制字符串不看到具体对象无法决定容器是难题std::vectorT该不该按二进制传即使T是二进制类型目前也没有办法以二进制格式传递数组所以容器总是按文本传递。十、从零到可用一个完整的最小示例把前文所有步骤串起来为一个自定义类型point平面坐标添加完整转换支持应包含type_name、基于no_null的nullness以及实现from_string/to_buf/into_buf/size_buffer的string_traits#include pqxx/strconv #include string_view struct point { double x, y; }; namespace pqxx { template std::string const type_namepoint{point}; template struct nullnesspoint : pqxx::no_nullpoint {}; template struct string_traitspoint { static point from_string(std::string_view text) { // 解析 (x,y) 形式的字符串格式不对就抛 pqxx::conversion_error。 ... } static zview to_buf(char *begin, char *end, point const value) { // 在 [begin, end) 内写入 (x,y)保证末尾零字节位于 end 之前 // 返回包含结尾零的 zview。空间不足抛 pqxx::conversion_overrun。 ... } static char *into_buf(char *begin, char *end, point const value) { // 同 to_buf但必须从 begin 开始写返回结尾零之后的地址。 ... } static std::size_t size_buffer(point const value) noexcept { // 返回足够容纳结果含结尾零的空间大小尽量 constexpr。 ... } }; }完成特化后pqxx::to_string(point{1.0, 2.0})、pqxx::from_stringpoint((1,2))、带参查询的参数传递以及把结果字段直接读入point变量等场景都会自动生效。由于string_traits特化是模板特化任何看见它的代码都会获得支持——这也是为什么特化定义要放在翻译单元早期。同理如果你也声明了is_unquoted_safepoint数组与组合类型中的point输出还能走更快的不加引号路径。十一、扩展类型在 libpqxx 使用链路中的位置掌握了类型扩展后可以顺带了解这些转换在整个库中的使用位置便于排查问题结果读取field/row/result把数据库文本转换为 C 值时最终经由from_string链路参见 accessing-results.md参数传递带参语句与预备语句的参数经由param_format决定文本/二进制见 parameters.md 与 prepared-statement.md批量流式读写stream_from/stream_to对批量数据的高效文本传输同样依赖这些转换参考 streams.md底层字符串工具pqxx::zview的完整接口见 include/pqxx/zview.hxx所有转换模板的原型见 include/pqxx/strconv.hxx。最后再次强调官方文档的告诫该扩展 API 可能随 libpqxx 任何大版本发布而改变。编写特化代码时请以当前仓库版本libpqxx 7.7.3位于 ext/libpqxx-7.7.3的头文件为准并在升级大版本后重新核对type_name、nullness、string_traits的接口签名。【免费下载链接】ZeroTierOneA Smart Ethernet Switch for Earth项目地址: https://gitcode.com/GitHub_Trending/ze/ZeroTierOne创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考