Skip to main content

yang_db/postgres/
field.rs

1/// 字段类型标记(PostgreSQL)
2///
3/// 与 MySQL 后端保持一致的字段类型枚举。`Blob` 在 PostgreSQL 中对应 `BYTEA`,
4/// `Json` 对应 `JSON`/`JSONB`,其余沿用通用语义。
5#[derive(Debug, Clone, PartialEq)]
6#[non_exhaustive]
7pub enum FieldType {
8    /// 标准类型(无需特殊处理)
9    Standard,
10    /// BOOLEAN 类型(空数组/全 NULL 数组需要它绑定为 `bool[]`)
11    Bool,
12    /// JSON / JSONB 类型
13    Json,
14    /// JSONB 类型(插入时与 JSON 同样按原生 serde_json 值绑定)
15    Jsonb,
16    /// TIMESTAMP(无时区)类型
17    DateTime,
18    /// TIMESTAMPTZ(带时区)类型
19    TimestampTz,
20    /// DATE 类型
21    Date,
22    /// TIME 类型
23    Time,
24    /// UUID 类型
25    Uuid,
26    /// 以整数存储的时间戳
27    Timestamp,
28    /// NUMERIC / DECIMAL 类型
29    Decimal,
30    /// BYTEA 类型
31    Blob,
32    /// TEXT 类型
33    Text,
34    /// 数组类型(元素类型递归描述,如 `TEXT[]` → `Array(Box::new(Text))`)
35    Array(Box<FieldType>),
36    /// INET:IPv4/IPv6 主机地址或网络地址
37    Inet,
38    /// CIDR:IPv4/IPv6 网络段
39    Cidr,
40    /// MACADDR:6 字节 MAC 地址
41    MacAddr,
42    /// MACADDR8:8 字节 MAC 地址(PostgreSQL 10+)
43    MacAddr8,
44    /// BIT:定长位串
45    Bit,
46    /// VARBIT:变长位串
47    Varbit,
48    /// 范围类型(`RANGE`):元素类型递归描述,如 `int4range` → `Range(Standard)`、
49    /// `tsrange` → `Range(DateTime)`。
50    ///
51    /// 无整数宽度提示的 [`FieldType::Standard`] 视为 PostgreSQL 默认的 32 位整数
52    /// 范围 `int4range`;其余可映射元素类型见 [`FieldType::postgres_type_name`]。
53    Range(Box<FieldType>),
54    /// 多范围类型(`MULTIRANGE`,PostgreSQL 14+):元素类型递归描述,
55    /// 如 `int4multirange` → `Multirange(Standard)`。
56    Multirange(Box<FieldType>),
57}
58
59impl FieldType {
60    /// 返回该字段类型对应的 PostgreSQL 类型名(`format_type` 风格,如
61    /// `integer`、`text[]`),用于 DDL 生成与类型核对。
62    ///
63    /// [`FieldType::Standard`] 表示没有额外类型提示,返回 `None`;数组按
64    /// 递归元素类型追加 `[]`(元素类型未知时同样返回 `None`)。
65    pub fn postgres_type_name(&self) -> Option<String> {
66        Some(match self {
67            Self::Standard => return None,
68            Self::Bool => "boolean".to_string(),
69            Self::Array(inner) => format!("{}[]", inner.postgres_type_name()?),
70            Self::Json => "json".to_string(),
71            Self::Jsonb => "jsonb".to_string(),
72            Self::DateTime => "timestamp".to_string(),
73            Self::TimestampTz => "timestamptz".to_string(),
74            Self::Date => "date".to_string(),
75            Self::Time => "time".to_string(),
76            Self::Uuid => "uuid".to_string(),
77            // 以整数存储的 Unix 时间戳,SQL 侧对应 BIGINT。
78            Self::Timestamp => "bigint".to_string(),
79            Self::Decimal => "numeric".to_string(),
80            Self::Blob => "bytea".to_string(),
81            Self::Text => "text".to_string(),
82            Self::Inet => "inet".to_string(),
83            Self::Cidr => "cidr".to_string(),
84            Self::MacAddr => "macaddr".to_string(),
85            Self::MacAddr8 => "macaddr8".to_string(),
86            Self::Bit => "bit".to_string(),
87            Self::Varbit => "varbit".to_string(),
88            Self::Range(inner) => range_type_name(inner, false)?.to_string(),
89            Self::Multirange(inner) => range_type_name(inner, true)?.to_string(),
90        })
91    }
92}
93
94/// 元素类型 → PostgreSQL 内置范围/多范围类型名。
95///
96/// 只映射有确定范围类型的内置标量;其余(文本、JSON、数组、嵌套范围等)返回
97/// `None`,避免把未知类型静默猜成某个范围。
98fn range_type_name(element: &FieldType, multirange: bool) -> Option<&'static str> {
99    Some(match (element, multirange) {
100        (FieldType::Standard, false) => "int4range",
101        (FieldType::Standard, true) => "int4multirange",
102        (FieldType::Timestamp, false) => "int8range",
103        (FieldType::Timestamp, true) => "int8multirange",
104        (FieldType::Decimal, false) => "numrange",
105        (FieldType::Decimal, true) => "nummultirange",
106        (FieldType::DateTime, false) => "tsrange",
107        (FieldType::DateTime, true) => "tsmultirange",
108        (FieldType::TimestampTz, false) => "tstzrange",
109        (FieldType::TimestampTz, true) => "tstzmultirange",
110        (FieldType::Date, false) => "daterange",
111        (FieldType::Date, true) => "datemultirange",
112        _ => return None,
113    })
114}
115
116/// PostgreSQL 会话 GUC 基线。
117///
118/// 本常量只声明基线值,基线由**连接建立方**([`crate::postgres::Database`] 的
119/// `after_connect` 钩子)应用,本 crate 不在每次查询时重复 `SET`。基线目标是让
120/// 文本格式与 Rust 侧编解码保持确定:
121///
122/// - `TimeZone=UTC`:`TIMESTAMPTZ` 文本输出与 `now()` 展示统一为 UTC;
123/// - `DateStyle=ISO, YMD`:日期文本格式与 `chrono` 的 ISO 解析一致,且与建连时
124///   实际下发的 `SET DateStyle = 'ISO, YMD'` 保持一致;
125/// - `IntervalStyle=postgres`:`INTERVAL` 文本格式固定;
126/// - `extra_float_digits=3`:浮点文本往返不丢精度(PostgreSQL 12+ 默认值 1
127///   已够用,这里显式固定以覆盖旧版本实例);
128/// - `standard_conforming_strings=on`:反斜杠按字面处理,避免字符串转义歧义。
129pub const SESSION_GUC_BASELINE: &[(&str, &str)] = &[
130    ("TimeZone", "UTC"),
131    ("DateStyle", "ISO, YMD"),
132    ("IntervalStyle", "postgres"),
133    ("extra_float_digits", "3"),
134    ("standard_conforming_strings", "on"),
135];
136
137/// JOIN 类型
138#[derive(Debug, Clone)]
139#[non_exhaustive]
140pub enum JoinType {
141    Inner,
142    Left,
143    Right,
144}
145
146/// JOIN 子句
147#[derive(Debug, Clone)]
148pub struct JoinClause {
149    /// JOIN 类型
150    pub join_type: JoinType,
151    /// 连接的表名(已校验的标识符原文,未加引号;渲染期经 `quote_identifier` 校验+转义)
152    pub table: String,
153    /// ON 条件
154    pub on: String,
155}
156
157/// ORDER BY 子句
158#[derive(Debug, Clone)]
159pub struct OrderClause {
160    /// 字段名
161    pub field: String,
162    /// 是否升序
163    pub asc: bool,
164}
165
166#[cfg(test)]
167#[allow(clippy::unwrap_used, clippy::expect_used)]
168mod tests {
169    use super::*;
170
171    #[test]
172    fn postgres_type_name_maps_existing_and_new_types() {
173        let cases = [
174            (FieldType::Bool, "boolean"),
175            (FieldType::Json, "json"),
176            (FieldType::Jsonb, "jsonb"),
177            (FieldType::DateTime, "timestamp"),
178            (FieldType::TimestampTz, "timestamptz"),
179            (FieldType::Date, "date"),
180            (FieldType::Time, "time"),
181            (FieldType::Uuid, "uuid"),
182            (FieldType::Timestamp, "bigint"),
183            (FieldType::Decimal, "numeric"),
184            (FieldType::Blob, "bytea"),
185            (FieldType::Text, "text"),
186            (FieldType::Inet, "inet"),
187            (FieldType::Cidr, "cidr"),
188            (FieldType::MacAddr, "macaddr"),
189            (FieldType::MacAddr8, "macaddr8"),
190            (FieldType::Bit, "bit"),
191            (FieldType::Varbit, "varbit"),
192        ];
193        for (field_type, expected) in cases {
194            assert_eq!(
195                field_type.postgres_type_name().as_deref(),
196                Some(expected),
197                "{field_type:?} 应映射到 PostgreSQL 类型名 {expected}"
198            );
199        }
200    }
201
202    #[test]
203    fn postgres_type_name_is_recursive_for_arrays() {
204        assert_eq!(
205            FieldType::Array(Box::new(FieldType::Text))
206                .postgres_type_name()
207                .as_deref(),
208            Some("text[]")
209        );
210        assert_eq!(
211            FieldType::Array(Box::new(FieldType::Inet))
212                .postgres_type_name()
213                .as_deref(),
214            Some("inet[]")
215        );
216        assert_eq!(
217            FieldType::Array(Box::new(FieldType::Blob))
218                .postgres_type_name()
219                .as_deref(),
220            Some("bytea[]")
221        );
222        // 元素类型无明确映射时,数组也没有可命名的 PostgreSQL 类型。
223        assert_eq!(
224            FieldType::Array(Box::new(FieldType::Standard)).postgres_type_name(),
225            None
226        );
227        assert_eq!(FieldType::Standard.postgres_type_name(), None);
228    }
229
230    #[test]
231    fn postgres_type_name_maps_builtin_range_and_multirange_types() {
232        let ranges = [
233            (FieldType::Standard, "int4range", "int4multirange"),
234            (FieldType::Timestamp, "int8range", "int8multirange"),
235            (FieldType::Decimal, "numrange", "nummultirange"),
236            (FieldType::DateTime, "tsrange", "tsmultirange"),
237            (FieldType::TimestampTz, "tstzrange", "tstzmultirange"),
238            (FieldType::Date, "daterange", "datemultirange"),
239        ];
240        for (element, range, multirange) in ranges {
241            assert_eq!(
242                FieldType::Range(Box::new(element.clone()))
243                    .postgres_type_name()
244                    .as_deref(),
245                Some(range),
246                "Range({element:?}) 应映射到 {range}"
247            );
248            assert_eq!(
249                FieldType::Multirange(Box::new(element))
250                    .postgres_type_name()
251                    .as_deref(),
252                Some(multirange)
253            );
254        }
255
256        // 没有内置范围类型的元素必须显式返回 None,而不是猜测。
257        for element in [FieldType::Text, FieldType::Json, FieldType::Uuid] {
258            assert_eq!(
259                FieldType::Range(Box::new(element.clone())).postgres_type_name(),
260                None
261            );
262            assert_eq!(
263                FieldType::Multirange(Box::new(element)).postgres_type_name(),
264                None
265            );
266        }
267    }
268
269    #[test]
270    fn session_guc_baseline_pins_deterministic_formats() {
271        assert_eq!(
272            SESSION_GUC_BASELINE,
273            [
274                ("TimeZone", "UTC"),
275                ("DateStyle", "ISO, YMD"),
276                ("IntervalStyle", "postgres"),
277                ("extra_float_digits", "3"),
278                ("standard_conforming_strings", "on"),
279            ]
280            .as_slice(),
281            "会话 GUC 基线是类型编解码确定性的契约,变更需同步文档与集成测试"
282        );
283    }
284
285    /// 基线的 DateStyle 必须与建连时实际下发的 `SET DateStyle` 一致(ISO, YMD)。
286    #[test]
287    fn session_guc_baseline_datestyle_matches_set_statement() {
288        let datestyle = SESSION_GUC_BASELINE
289            .iter()
290            .find(|(name, _)| *name == "DateStyle")
291            .map(|(_, value)| *value)
292            .expect("基线必须包含 DateStyle");
293        assert_eq!(datestyle, "ISO, YMD");
294    }
295}