Skip to main content

prax_postgres/
types.rs

1//! Type conversions for PostgreSQL.
2
3use std::str::FromStr;
4
5use prax_query::filter::FilterValue;
6use tokio_postgres::types::{IsNull, Kind, ToSql, Type};
7
8use crate::error::{PgError, PgResult};
9
10/// Polymorphic integer binding. `FilterValue::Int` always carries an i64
11/// (the widest scalar variant), but Postgres strictly validates client
12/// bindings against column types: binding an i64 to an `INT4` column
13/// fails with `WrongType { postgres: Int4, rust: "i64" }`. This wrapper
14/// inspects the target column type at bind time and narrows to i16 /
15/// i32 / i64 with a bounds check before forwarding to tokio-postgres'
16/// own impls.
17#[derive(Debug)]
18struct PgInt(i64);
19
20impl ToSql for PgInt {
21    fn to_sql(
22        &self,
23        ty: &Type,
24        out: &mut bytes::BytesMut,
25    ) -> Result<IsNull, Box<dyn std::error::Error + Sync + Send>> {
26        match *ty {
27            Type::INT2 => {
28                let v: i16 = self
29                    .0
30                    .try_into()
31                    .map_err(|_| format!("value {} overflows INT2", self.0))?;
32                v.to_sql(ty, out)
33            }
34            Type::INT4 => {
35                let v: i32 = self
36                    .0
37                    .try_into()
38                    .map_err(|_| format!("value {} overflows INT4", self.0))?;
39                v.to_sql(ty, out)
40            }
41            Type::INT8 => self.0.to_sql(ty, out),
42            _ => Err(format!("cannot bind integer to postgres type {ty:?}").into()),
43        }
44    }
45
46    fn accepts(ty: &Type) -> bool {
47        matches!(*ty, Type::INT2 | Type::INT4 | Type::INT8)
48    }
49
50    tokio_postgres::types::to_sql_checked!();
51}
52
53/// Polymorphic string binding. `FilterValue::String` always carries a
54/// Rust `String`, but Postgres rejects a String bound to a UUID column
55/// (`WrongType { postgres: Uuid, rust: "alloc::string::String" }`).
56/// This wrapper inspects the target column type at bind time and
57/// converts as appropriate; for plain TEXT/VARCHAR/CHAR/NAME and other
58/// types it forwards the String directly.
59#[derive(Debug)]
60struct PgString(String);
61
62impl PgString {
63    /// Whether a `PgString` can bind to `ty`. Must match the arms of
64    /// `PgString::to_sql` below: the specially-parsed types, user-defined
65    /// enums, and everything `String` itself accepts.
66    fn binds_to(ty: &Type) -> bool {
67        matches!(
68            *ty,
69            Type::UUID | Type::TIMESTAMPTZ | Type::TIMESTAMP | Type::DATE | Type::TIME
70        ) || matches!(ty.kind(), Kind::Enum(_))
71            || <String as ToSql>::accepts(ty)
72    }
73}
74
75impl ToSql for PgString {
76    fn to_sql(
77        &self,
78        ty: &Type,
79        out: &mut bytes::BytesMut,
80    ) -> Result<IsNull, Box<dyn std::error::Error + Sync + Send>> {
81        match *ty {
82            Type::UUID => {
83                let parsed = ::uuid::Uuid::from_str(&self.0).map_err(|e| {
84                    format!("FilterValue::String('{}') is not a valid UUID: {e}", self.0)
85                })?;
86                parsed.to_sql(ty, out)
87            }
88            // chrono types round-trip through `FilterValue::String`
89            // (see `prax-query/src/filter.rs`). Postgres rejects a String
90            // bound to TIMESTAMPTZ/TIMESTAMP/DATE/TIME with WrongType,
91            // so re-parse and forward through tokio-postgres' chrono
92            // FromSql/ToSql impls.
93            Type::TIMESTAMPTZ => {
94                let parsed: ::chrono::DateTime<::chrono::Utc> =
95                    ::chrono::DateTime::parse_from_rfc3339(&self.0)
96                        .map_err(|e| {
97                            format!(
98                                "FilterValue::String('{}') is not a valid RFC3339 \
99                                 datetime for TIMESTAMPTZ: {e}",
100                                self.0
101                            )
102                        })?
103                        .with_timezone(&::chrono::Utc);
104                parsed.to_sql(ty, out)
105            }
106            Type::TIMESTAMP => {
107                let parsed =
108                    ::chrono::NaiveDateTime::parse_from_str(&self.0, "%Y-%m-%dT%H:%M:%S%.f")
109                        .map_err(|e| {
110                            format!(
111                                "FilterValue::String('{}') is not a valid \
112                         ISO-8601 naive datetime for TIMESTAMP: {e}",
113                                self.0
114                            )
115                        })?;
116                parsed.to_sql(ty, out)
117            }
118            Type::DATE => {
119                let parsed =
120                    ::chrono::NaiveDate::parse_from_str(&self.0, "%Y-%m-%d").map_err(|e| {
121                        format!(
122                            "FilterValue::String('{}') is not a valid \
123                             YYYY-MM-DD date for DATE: {e}",
124                            self.0
125                        )
126                    })?;
127                parsed.to_sql(ty, out)
128            }
129            Type::TIME => {
130                let parsed =
131                    ::chrono::NaiveTime::parse_from_str(&self.0, "%H:%M:%S%.f").map_err(|e| {
132                        format!(
133                            "FilterValue::String('{}') is not a valid \
134                                 HH:MM:SS time for TIME: {e}",
135                            self.0
136                        )
137                    })?;
138                parsed.to_sql(ty, out)
139            }
140            _ => {
141                // User-defined `ENUM` columns reach this arm; their
142                // wire format is just utf-8 bytes, so write the
143                // string body directly. Plain TEXT/VARCHAR/CHAR/NAME
144                // also takes this path through `String: ToSql`.
145                if matches!(ty.kind(), Kind::Enum(_)) {
146                    out.extend_from_slice(self.0.as_bytes());
147                    Ok(IsNull::No)
148                } else {
149                    self.0.to_sql(ty, out)
150                }
151            }
152        }
153    }
154
155    fn accepts(_ty: &Type) -> bool {
156        true
157    }
158
159    tokio_postgres::types::to_sql_checked!();
160}
161
162/// Untyped NULL binding. `FilterValue::Null` must bind successfully against
163/// a column of any type (nullable UUID, custom ENUM, TIMESTAMPTZ, INT4,
164/// ...), but `Option::<String>::None`'s `accepts()` delegates to
165/// `String::accepts()`, which only covers TEXT/VARCHAR/CHAR/NAME/UNKNOWN.
166/// tokio-postgres runs that `accepts()` check before `to_sql` is ever
167/// called, so a NULL bound against e.g. a nullable UUID column fails with
168/// "error serializing parameter N" even though NULL has no type-specific
169/// wire representation to get wrong. This wrapper accepts every type and
170/// always signals `IsNull::Yes`.
171#[derive(Debug)]
172struct PgNull;
173
174impl ToSql for PgNull {
175    fn to_sql(
176        &self,
177        _ty: &Type,
178        _out: &mut bytes::BytesMut,
179    ) -> Result<IsNull, Box<dyn std::error::Error + Sync + Send>> {
180        Ok(IsNull::Yes)
181    }
182
183    fn accepts(_ty: &Type) -> bool {
184        true
185    }
186
187    tokio_postgres::types::to_sql_checked!();
188}
189
190/// One element of a `FilterValue::Array` parameter. Delegates to the scalar
191/// binders so each element adapts to the array's element type (e.g. a
192/// `PgString` into `uuid[]`). `Vec<PgElem>: ToSql` (tokio-postgres) supplies
193/// the array wire format and rejects non-array target types.
194#[derive(Debug)]
195enum PgElem {
196    Null(PgNull),
197    Bool(bool),
198    Int(PgInt),
199    Float(f64),
200    String(PgString),
201    Json(serde_json::Value),
202    Bytes(Vec<u8>),
203}
204
205impl PgElem {
206    fn try_from_value(value: &FilterValue) -> PgResult<Self> {
207        Ok(match value {
208            FilterValue::Null => Self::Null(PgNull),
209            FilterValue::Bool(b) => Self::Bool(*b),
210            FilterValue::Int(i) => Self::Int(PgInt(*i)),
211            FilterValue::Float(f) => Self::Float(*f),
212            FilterValue::String(s) => Self::String(PgString(s.clone())),
213            FilterValue::Json(j) => Self::Json(j.clone()),
214            FilterValue::Bytes(b) => Self::Bytes(b.clone()),
215            FilterValue::List(_) | FilterValue::Array(_) => {
216                return Err(PgError::type_conversion(
217                    "nested arrays are not supported in FilterValue::Array",
218                ));
219            }
220            _ => {
221                return Err(PgError::type_conversion(
222                    "unsupported FilterValue variant in FilterValue::Array",
223                ));
224            }
225        })
226    }
227}
228
229impl ToSql for PgElem {
230    fn to_sql(
231        &self,
232        ty: &Type,
233        out: &mut bytes::BytesMut,
234    ) -> Result<IsNull, Box<dyn std::error::Error + Sync + Send>> {
235        // Element-wise `to_sql` is called unchecked by tokio-postgres' array
236        // impl, so every arm must verify the element type itself.
237        fn check(
238            ok: bool,
239            kind: &str,
240            ty: &Type,
241        ) -> Result<(), Box<dyn std::error::Error + Sync + Send>> {
242            if ok {
243                Ok(())
244            } else {
245                Err(format!("cannot bind {kind} array element to postgres type {ty:?}").into())
246            }
247        }
248        match self {
249            Self::Null(v) => v.to_sql(ty, out),
250            Self::Bool(v) => {
251                check(<bool as ToSql>::accepts(ty), "bool", ty)?;
252                v.to_sql(ty, out)
253            }
254            Self::Int(v) => v.to_sql(ty, out),
255            Self::Float(v) => {
256                check(<f64 as ToSql>::accepts(ty), "float", ty)?;
257                v.to_sql(ty, out)
258            }
259            Self::String(v) => {
260                check(PgString::binds_to(ty), "string", ty)?;
261                v.to_sql(ty, out)
262            }
263            Self::Json(v) => {
264                check(<serde_json::Value as ToSql>::accepts(ty), "json", ty)?;
265                v.to_sql(ty, out)
266            }
267            Self::Bytes(v) => {
268                check(<Vec<u8> as ToSql>::accepts(ty), "bytes", ty)?;
269                v.to_sql(ty, out)
270            }
271        }
272    }
273
274    fn accepts(_ty: &Type) -> bool {
275        true
276    }
277
278    tokio_postgres::types::to_sql_checked!();
279}
280
281/// Convert a FilterValue to a type that can be used as a PostgreSQL parameter.
282pub fn filter_value_to_sql(value: &FilterValue) -> PgResult<Box<dyn ToSql + Sync + Send>> {
283    match value {
284        FilterValue::Null => Ok(Box::new(PgNull)),
285        FilterValue::Bool(b) => Ok(Box::new(*b)),
286        FilterValue::Int(i) => Ok(Box::new(PgInt(*i))),
287        FilterValue::Float(f) => Ok(Box::new(*f)),
288        FilterValue::String(s) => Ok(Box::new(PgString(s.clone()))),
289        FilterValue::Json(j) => Ok(Box::new(j.clone())),
290        FilterValue::List(_) => {
291            // Typed IN filters expand to scalar placeholders upstream
292            // (prax-query/src/filter.rs), so this arm only fires for
293            // hand-built raw queries via `Sql::bind`.
294            Err(PgError::type_conversion(
295                "FilterValue::List cannot be bound as one parameter; use Filter::In for IN (...) or FilterValue::Array with = ANY($1)",
296            ))
297        }
298        FilterValue::Bytes(b) => Ok(Box::new(b.clone())),
299        FilterValue::Array(items) => {
300            let elems = items
301                .iter()
302                .map(PgElem::try_from_value)
303                .collect::<PgResult<Vec<_>>>()?;
304            Ok(Box::new(elems))
305        }
306        _ => Err(PgError::type_conversion("unsupported FilterValue variant")),
307    }
308}
309
310/// Convert filter values to PostgreSQL parameters.
311pub fn filter_values_to_params(
312    values: &[FilterValue],
313) -> PgResult<Vec<Box<dyn ToSql + Sync + Send>>> {
314    values.iter().map(filter_value_to_sql).collect()
315}
316
317/// PostgreSQL type mapping utilities.
318pub mod pg_types {
319    use super::*;
320
321    /// Get the PostgreSQL type for a Rust type name.
322    pub fn rust_type_to_pg(rust_type: &str) -> Option<Type> {
323        match rust_type {
324            "i16" => Some(Type::INT2),
325            "i32" => Some(Type::INT4),
326            "i64" => Some(Type::INT8),
327            "f32" => Some(Type::FLOAT4),
328            "f64" => Some(Type::FLOAT8),
329            "bool" => Some(Type::BOOL),
330            "String" | "&str" => Some(Type::TEXT),
331            "Vec<u8>" | "&[u8]" => Some(Type::BYTEA),
332            "chrono::NaiveDate" => Some(Type::DATE),
333            "chrono::NaiveTime" => Some(Type::TIME),
334            "chrono::NaiveDateTime" => Some(Type::TIMESTAMP),
335            "chrono::DateTime<chrono::Utc>" => Some(Type::TIMESTAMPTZ),
336            "uuid::Uuid" => Some(Type::UUID),
337            "serde_json::Value" => Some(Type::JSONB),
338            _ => None,
339        }
340    }
341
342    /// Get the Rust type for a PostgreSQL type.
343    pub fn pg_type_to_rust(pg_type: &Type) -> &'static str {
344        match *pg_type {
345            Type::BOOL => "bool",
346            Type::INT2 => "i16",
347            Type::INT4 => "i32",
348            Type::INT8 => "i64",
349            Type::FLOAT4 => "f32",
350            Type::FLOAT8 => "f64",
351            Type::TEXT | Type::VARCHAR | Type::CHAR | Type::NAME => "String",
352            Type::BYTEA => "Vec<u8>",
353            Type::DATE => "chrono::NaiveDate",
354            Type::TIME => "chrono::NaiveTime",
355            Type::TIMESTAMP => "chrono::NaiveDateTime",
356            Type::TIMESTAMPTZ => "chrono::DateTime<chrono::Utc>",
357            Type::UUID => "uuid::Uuid",
358            Type::JSON | Type::JSONB => "serde_json::Value",
359            _ => "unknown",
360        }
361    }
362}
363
364#[cfg(test)]
365mod tests {
366    use super::*;
367
368    #[test]
369    fn bytes_binds_as_bytea() {
370        let param = filter_value_to_sql(&FilterValue::Bytes(vec![0, 255])).unwrap();
371        let mut buf = bytes::BytesMut::new();
372        param.to_sql_checked(&Type::BYTEA, &mut buf).unwrap();
373        assert_eq!(&buf[..], &[0u8, 255][..]);
374    }
375
376    #[test]
377    fn nested_list_or_array_in_array_is_rejected() {
378        for inner in [FilterValue::List(vec![]), FilterValue::Array(vec![])] {
379            let err = filter_value_to_sql(&FilterValue::Array(vec![inner]))
380                .expect_err("nested collections must error");
381            assert!(matches!(err, PgError::TypeConversion(_)));
382            assert!(err.to_string().contains("nested"), "{err}");
383        }
384    }
385
386    fn bind_array(
387        items: Vec<FilterValue>,
388        ty: &Type,
389    ) -> (
390        Result<IsNull, Box<dyn std::error::Error + Sync + Send>>,
391        bytes::BytesMut,
392    ) {
393        let param = filter_value_to_sql(&FilterValue::Array(items)).unwrap();
394        let mut buf = bytes::BytesMut::new();
395        let res = param.to_sql_checked(ty, &mut buf);
396        (res, buf)
397    }
398
399    #[test]
400    fn array_binds_as_int_array() {
401        let items = vec![FilterValue::Int(1), FilterValue::Null];
402        let (res, buf) = bind_array(items.clone(), &Type::INT4_ARRAY);
403        res.unwrap();
404        // Header: ndim=1, has_null=1, elem oid INT4 (23); dim len 2, lbound 1;
405        // then elem 1 (len 4, value 1) and a NULL (len -1).
406        let mut expected = Vec::new();
407        for v in [1i32, 1, 23, 2, 1, 4, 1, -1] {
408            expected.extend_from_slice(&v.to_be_bytes());
409        }
410        assert_eq!(&buf[..], &expected[..]);
411        // Non-array target types are rejected, not panicked on.
412        assert!(bind_array(items, &Type::INT4).0.is_err());
413    }
414
415    #[test]
416    fn array_wrong_element_kind_errors() {
417        let cases = [
418            (FilterValue::Bool(true), Type::TEXT_ARRAY),
419            (FilterValue::Float(1.5), Type::INT4_ARRAY),
420            (FilterValue::Bytes(vec![1]), Type::TEXT_ARRAY),
421            (
422                FilterValue::Json(serde_json::json!({"a": 1})),
423                Type::INT4_ARRAY,
424            ),
425            (FilterValue::String("x".into()), Type::INT4_ARRAY),
426            (FilterValue::Int(1), Type::TEXT_ARRAY),
427        ];
428        for (item, ty) in cases {
429            let (res, _) = bind_array(vec![item.clone()], &ty);
430            assert!(res.is_err(), "{item:?} into {ty:?} must error");
431        }
432    }
433
434    /// Bind a one-element array and decode it back with `FromSql`.
435    fn assert_roundtrip<T>(item: FilterValue, ty: &Type, expected: T)
436    where
437        T: for<'a> tokio_postgres::types::FromSql<'a> + PartialEq + std::fmt::Debug,
438    {
439        let (res, buf) = bind_array(vec![item.clone()], ty);
440        res.unwrap_or_else(|e| panic!("{item:?} into {ty:?}: {e}"));
441        let decoded = <Vec<T> as tokio_postgres::types::FromSql>::from_sql(ty, &buf)
442            .unwrap_or_else(|e| panic!("decoding {item:?} as {ty:?}: {e}"));
443        assert_eq!(decoded, vec![expected], "{item:?} into {ty:?}");
444    }
445
446    #[test]
447    fn array_matching_element_kinds_bind() {
448        assert_roundtrip(FilterValue::Bool(true), &Type::BOOL_ARRAY, true);
449        assert_roundtrip(FilterValue::Float(1.5), &Type::FLOAT8_ARRAY, 1.5f64);
450        assert_roundtrip(
451            FilterValue::Bytes(vec![1, 2]),
452            &Type::BYTEA_ARRAY,
453            vec![1u8, 2],
454        );
455        assert_roundtrip(
456            FilterValue::Json(serde_json::json!({"a": 1})),
457            &Type::JSONB_ARRAY,
458            serde_json::json!({"a": 1}),
459        );
460        assert_roundtrip(
461            FilterValue::String("x".into()),
462            &Type::TEXT_ARRAY,
463            "x".to_string(),
464        );
465        assert_roundtrip(FilterValue::Int(7), &Type::INT8_ARRAY, 7i64);
466    }
467
468    #[test]
469    fn string_array_elements_adapt_to_element_type() {
470        let uuid = "67e55044-10b1-426f-9247-bb680e5fe0c8";
471        assert_roundtrip(
472            FilterValue::String(uuid.into()),
473            &Type::UUID_ARRAY,
474            ::uuid::Uuid::from_str(uuid).unwrap(),
475        );
476        assert_roundtrip(
477            FilterValue::String("2024-01-02T03:04:05Z".into()),
478            &Type::TIMESTAMPTZ_ARRAY,
479            ::chrono::DateTime::parse_from_rfc3339("2024-01-02T03:04:05Z")
480                .unwrap()
481                .with_timezone(&::chrono::Utc),
482        );
483        assert_roundtrip(
484            FilterValue::String("2024-01-02T03:04:05.5".into()),
485            &Type::TIMESTAMP_ARRAY,
486            ::chrono::NaiveDateTime::parse_from_str(
487                "2024-01-02T03:04:05.5",
488                "%Y-%m-%dT%H:%M:%S%.f",
489            )
490            .unwrap(),
491        );
492        assert_roundtrip(
493            FilterValue::String("2024-01-02".into()),
494            &Type::DATE_ARRAY,
495            ::chrono::NaiveDate::from_ymd_opt(2024, 1, 2).unwrap(),
496        );
497        assert_roundtrip(
498            FilterValue::String("03:04:05".into()),
499            &Type::TIME_ARRAY,
500            ::chrono::NaiveTime::from_hms_opt(3, 4, 5).unwrap(),
501        );
502    }
503
504    #[test]
505    fn enum_array_binds_string_elements_verbatim() {
506        let mood = Type::new(
507            "mood".into(),
508            990_001,
509            Kind::Enum(vec!["happy".into(), "sad".into()]),
510            "public".into(),
511        );
512        let mood_array = Type::new("_mood".into(), 990_002, Kind::Array(mood), "public".into());
513        let (res, buf) = bind_array(vec![FilterValue::String("happy".into())], &mood_array);
514        res.unwrap();
515        // ndim=1, has_null=0, elem oid, dim len 1, lbound 1, elem len 5, body.
516        let mut expected = Vec::new();
517        for v in [1i32, 0, 990_001, 1, 1, 5] {
518            expected.extend_from_slice(&v.to_be_bytes());
519        }
520        expected.extend_from_slice(b"happy");
521        assert_eq!(&buf[..], &expected[..]);
522    }
523
524    #[test]
525    fn string_array_invalid_values_error() {
526        let cases = [
527            ("not-a-uuid", Type::UUID_ARRAY),
528            ("2024-13-45", Type::DATE_ARRAY),
529            ("nope", Type::DATE_ARRAY),
530            ("25:61:61", Type::TIME_ARRAY),
531            ("2024-01-02", Type::TIMESTAMPTZ_ARRAY),
532            ("garbage", Type::TIMESTAMP_ARRAY),
533        ];
534        for (s, ty) in cases {
535            let (res, _) = bind_array(vec![FilterValue::String(s.into())], &ty);
536            assert!(res.is_err(), "{s:?} into {ty:?} must error");
537        }
538    }
539
540    #[test]
541    fn list_bind_error_points_to_alternatives() {
542        let err = filter_value_to_sql(&FilterValue::List(vec![]))
543            .err()
544            .unwrap();
545        let msg = err.to_string();
546        assert!(
547            msg.contains("Filter::In") && msg.contains("ANY($1)"),
548            "{msg}"
549        );
550    }
551
552    #[test]
553    fn test_filter_value_to_sql() {
554        let result = filter_value_to_sql(&FilterValue::Int(42));
555        assert!(result.is_ok());
556
557        let result = filter_value_to_sql(&FilterValue::String("test".to_string()));
558        assert!(result.is_ok());
559
560        let result = filter_value_to_sql(&FilterValue::Bool(true));
561        assert!(result.is_ok());
562    }
563
564    #[test]
565    fn string_array_binds_as_a_text_array() {
566        // What `Vec<String>` (a `String[]` field) lowers to.
567        let array = FilterValue::Array(vec![
568            FilterValue::String("read".into()),
569            FilterValue::String("write".into()),
570        ]);
571        let param = filter_value_to_sql(&array).expect("string array binds");
572        let mut buf = bytes::BytesMut::new();
573        let encoded = param
574            .to_sql_checked(&Type::TEXT_ARRAY, &mut buf)
575            .expect("encodes as TEXT[]");
576        assert!(matches!(encoded, IsNull::No));
577        assert!(
578            param
579                .to_sql_checked(&Type::VARCHAR_ARRAY, &mut bytes::BytesMut::new())
580                .is_ok()
581        );
582        // A text array never satisfies a scalar column.
583        assert!(
584            param
585                .to_sql_checked(&Type::TEXT, &mut bytes::BytesMut::new())
586                .is_err()
587        );
588    }
589
590    #[test]
591    fn empty_array_binds_as_an_empty_text_array() {
592        let param = filter_value_to_sql(&FilterValue::Array(vec![])).expect("empty array binds");
593        assert!(
594            param
595                .to_sql_checked(&Type::TEXT_ARRAY, &mut bytes::BytesMut::new())
596                .is_ok()
597        );
598    }
599
600    #[test]
601    fn string_list_is_rejected_in_favour_of_array() {
602        let list = FilterValue::List(vec![FilterValue::String("read".into())]);
603        assert!(filter_value_to_sql(&list).is_err());
604    }
605
606    #[test]
607    fn test_pg_type_mapping() {
608        use pg_types::*;
609
610        assert_eq!(rust_type_to_pg("i32"), Some(Type::INT4));
611        assert_eq!(rust_type_to_pg("String"), Some(Type::TEXT));
612        assert_eq!(rust_type_to_pg("bool"), Some(Type::BOOL));
613
614        assert_eq!(pg_type_to_rust(&Type::INT4), "i32");
615        assert_eq!(pg_type_to_rust(&Type::TEXT), "String");
616    }
617}