1use std::borrow::Cow;
39use std::fmt;
40
41#[derive(Debug, Clone)]
43pub enum RowError {
44 ColumnNotFound(String),
46 TypeConversion { column: String, message: String },
48 UnexpectedNull(String),
50}
51
52impl fmt::Display for RowError {
53 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
54 match self {
55 Self::ColumnNotFound(col) => write!(f, "column '{}' not found", col),
56 Self::TypeConversion { column, message } => {
57 write!(f, "type conversion error for '{}': {}", column, message)
58 }
59 Self::UnexpectedNull(col) => write!(f, "unexpected null in column '{}'", col),
60 }
61 }
62}
63
64impl std::error::Error for RowError {}
65
66pub trait RowRef {
71 fn get_i32(&self, column: &str) -> Result<i32, RowError>;
73
74 fn get_i32_opt(&self, column: &str) -> Result<Option<i32>, RowError>;
76
77 fn get_i64(&self, column: &str) -> Result<i64, RowError>;
79
80 fn get_i64_opt(&self, column: &str) -> Result<Option<i64>, RowError>;
82
83 fn get_f64(&self, column: &str) -> Result<f64, RowError>;
85
86 fn get_f64_opt(&self, column: &str) -> Result<Option<f64>, RowError>;
88
89 fn get_bool(&self, column: &str) -> Result<bool, RowError>;
91
92 fn get_bool_opt(&self, column: &str) -> Result<Option<bool>, RowError>;
94
95 fn get_str(&self, column: &str) -> Result<&str, RowError>;
100
101 fn get_str_opt(&self, column: &str) -> Result<Option<&str>, RowError>;
103
104 fn get_string(&self, column: &str) -> Result<String, RowError> {
106 self.get_str(column).map(|s| s.to_string())
107 }
108
109 fn get_string_opt(&self, column: &str) -> Result<Option<String>, RowError> {
111 self.get_str_opt(column)
112 .map(|opt| opt.map(|s| s.to_string()))
113 }
114
115 fn get_bytes(&self, column: &str) -> Result<&[u8], RowError>;
117
118 fn get_bytes_opt(&self, column: &str) -> Result<Option<&[u8]>, RowError>;
120
121 fn get_cow_str(&self, column: &str) -> Result<Cow<'_, str>, RowError> {
123 self.get_str(column).map(Cow::Borrowed)
124 }
125
126 fn get_datetime_utc(&self, column: &str) -> Result<chrono::DateTime<chrono::Utc>, RowError> {
127 Err(unsupported_get(column, "datetime_utc"))
128 }
129 fn get_datetime_utc_opt(
130 &self,
131 column: &str,
132 ) -> Result<Option<chrono::DateTime<chrono::Utc>>, RowError> {
133 Err(unsupported_get(column, "datetime_utc_opt"))
134 }
135 fn get_naive_datetime(&self, column: &str) -> Result<chrono::NaiveDateTime, RowError> {
136 Err(unsupported_get(column, "naive_datetime"))
137 }
138 fn get_naive_datetime_opt(
139 &self,
140 column: &str,
141 ) -> Result<Option<chrono::NaiveDateTime>, RowError> {
142 Err(unsupported_get(column, "naive_datetime_opt"))
143 }
144 fn get_naive_date(&self, column: &str) -> Result<chrono::NaiveDate, RowError> {
145 Err(unsupported_get(column, "naive_date"))
146 }
147 fn get_naive_date_opt(&self, column: &str) -> Result<Option<chrono::NaiveDate>, RowError> {
148 Err(unsupported_get(column, "naive_date_opt"))
149 }
150 fn get_naive_time(&self, column: &str) -> Result<chrono::NaiveTime, RowError> {
151 Err(unsupported_get(column, "naive_time"))
152 }
153 fn get_naive_time_opt(&self, column: &str) -> Result<Option<chrono::NaiveTime>, RowError> {
154 Err(unsupported_get(column, "naive_time_opt"))
155 }
156 fn get_uuid(&self, column: &str) -> Result<uuid::Uuid, RowError> {
157 Err(unsupported_get(column, "uuid"))
158 }
159 fn get_uuid_opt(&self, column: &str) -> Result<Option<uuid::Uuid>, RowError> {
160 Err(unsupported_get(column, "uuid_opt"))
161 }
162 fn get_json(&self, column: &str) -> Result<serde_json::Value, RowError> {
163 Err(unsupported_get(column, "json"))
164 }
165 fn get_json_opt(&self, column: &str) -> Result<Option<serde_json::Value>, RowError> {
166 Err(unsupported_get(column, "json_opt"))
167 }
168 fn get_decimal(&self, column: &str) -> Result<rust_decimal::Decimal, RowError> {
169 Err(unsupported_get(column, "decimal"))
170 }
171 fn get_decimal_opt(&self, column: &str) -> Result<Option<rust_decimal::Decimal>, RowError> {
172 Err(unsupported_get(column, "decimal_opt"))
173 }
174
175 fn get_vector(&self, column: &str) -> Result<Vec<f32>, RowError> {
183 Err(unsupported_get(column, "vector"))
184 }
185
186 fn get_string_array(&self, column: &str) -> Result<Vec<String>, RowError> {
193 Err(unsupported_get(column, "string_array"))
194 }
195
196 fn is_null(&self, column: &str) -> Result<bool, RowError> {
210 self.get_str_opt(column).map(|opt| opt.is_none())
211 }
212}
213
214fn unsupported_get(column: &str, getter: &str) -> RowError {
219 RowError::TypeConversion {
220 column: column.to_string(),
221 message: format!("{getter} not supported by this row type"),
222 }
223}
224
225pub fn into_row_error<T, E: std::fmt::Display>(
230 column: &str,
231 res: Result<T, E>,
232) -> Result<T, RowError> {
233 res.map_err(|e| RowError::TypeConversion {
234 column: column.to_string(),
235 message: e.to_string(),
236 })
237}
238
239pub trait FromRowRef<'a>: Sized {
244 fn from_row_ref(row: &'a impl RowRef) -> Result<Self, RowError>;
246}
247
248pub trait FromRow: Sized {
253 fn from_row(row: &impl RowRef) -> Result<Self, RowError>;
255}
256
257impl<T: FromRow> FromRowRef<'_> for T {
259 fn from_row_ref(row: &impl RowRef) -> Result<Self, RowError> {
260 T::from_row(row)
261 }
262}
263
264pub struct RowRefIter<'a, R: RowRef, T: FromRowRef<'a>> {
266 rows: std::slice::Iter<'a, R>,
267 _marker: std::marker::PhantomData<T>,
268}
269
270impl<'a, R: RowRef, T: FromRowRef<'a>> RowRefIter<'a, R, T> {
271 pub fn new(rows: &'a [R]) -> Self {
273 Self {
274 rows: rows.iter(),
275 _marker: std::marker::PhantomData,
276 }
277 }
278}
279
280impl<'a, R: RowRef, T: FromRowRef<'a>> Iterator for RowRefIter<'a, R, T> {
281 type Item = Result<T, RowError>;
282
283 fn next(&mut self) -> Option<Self::Item> {
284 self.rows.next().map(|row| T::from_row_ref(row))
285 }
286
287 fn size_hint(&self) -> (usize, Option<usize>) {
288 self.rows.size_hint()
289 }
290}
291
292impl<'a, R: RowRef, T: FromRowRef<'a>> ExactSizeIterator for RowRefIter<'a, R, T> {}
293
294#[derive(Debug, Clone)]
299pub enum RowData<'a> {
300 Borrowed(&'a str),
302 Owned(String),
304}
305
306impl<'a> RowData<'a> {
307 pub fn as_str(&self) -> &str {
309 match self {
310 Self::Borrowed(s) => s,
311 Self::Owned(s) => s,
312 }
313 }
314
315 pub fn into_owned(self) -> String {
317 match self {
318 Self::Borrowed(s) => s.to_string(),
319 Self::Owned(s) => s,
320 }
321 }
322
323 pub const fn borrowed(s: &'a str) -> Self {
325 Self::Borrowed(s)
326 }
327
328 pub fn owned(s: impl Into<String>) -> Self {
330 Self::Owned(s.into())
331 }
332}
333
334impl<'a> From<&'a str> for RowData<'a> {
335 fn from(s: &'a str) -> Self {
336 Self::Borrowed(s)
337 }
338}
339
340impl From<String> for RowData<'static> {
341 fn from(s: String) -> Self {
342 Self::Owned(s)
343 }
344}
345
346impl<'a> AsRef<str> for RowData<'a> {
347 fn as_ref(&self) -> &str {
348 self.as_str()
349 }
350}
351
352#[macro_export]
374macro_rules! impl_from_row {
375 ($type:ident { $($field:ident : i32),* $(,)? }) => {
376 impl $crate::row::FromRow for $type {
377 fn from_row(row: &impl $crate::row::RowRef) -> Result<Self, $crate::row::RowError> {
378 Ok(Self {
379 $(
380 $field: row.get_i32(stringify!($field))?,
381 )*
382 })
383 }
384 }
385 };
386 ($type:ident { $($field:ident : $field_type:ty),* $(,)? }) => {
387 impl $crate::row::FromRow for $type {
388 fn from_row(row: &impl $crate::row::RowRef) -> Result<Self, $crate::row::RowError> {
389 Ok(Self {
390 $(
391 $field: $crate::row::_get_typed_value::<$field_type>(row, stringify!($field))?,
392 )*
393 })
394 }
395 }
396 };
397}
398
399#[doc(hidden)]
401pub fn _get_typed_value<T: FromColumn>(row: &impl RowRef, column: &str) -> Result<T, RowError> {
402 T::from_column(row, column)
403}
404
405pub trait FromColumn: Sized {
407 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError>;
409}
410
411impl FromColumn for i32 {
412 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
413 row.get_i32(column)
414 }
415}
416
417impl FromColumn for u8 {
420 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
421 let v = row.get_i32(column)?;
422 u8::try_from(v).map_err(|_| RowError::TypeConversion {
423 column: column.to_string(),
424 message: format!("value {v} out of range for u8"),
425 })
426 }
427}
428
429impl FromColumn for i64 {
430 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
431 row.get_i64(column)
432 }
433}
434
435impl FromColumn for f64 {
436 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
437 row.get_f64(column)
438 }
439}
440
441impl FromColumn for bool {
442 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
443 row.get_bool(column)
444 }
445}
446
447impl FromColumn for String {
448 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
449 row.get_string(column)
450 }
451}
452
453impl FromColumn for Vec<u8> {
454 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
455 row.get_bytes(column).map(|b| b.to_vec())
456 }
457}
458
459impl FromColumn for chrono::DateTime<chrono::Utc> {
460 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
461 row.get_datetime_utc(column)
462 }
463}
464impl FromColumn for chrono::NaiveDateTime {
465 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
466 row.get_naive_datetime(column)
467 }
468}
469impl FromColumn for chrono::NaiveDate {
470 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
471 row.get_naive_date(column)
472 }
473}
474impl FromColumn for chrono::NaiveTime {
475 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
476 row.get_naive_time(column)
477 }
478}
479impl FromColumn for uuid::Uuid {
480 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
481 row.get_uuid(column)
482 }
483}
484impl FromColumn for serde_json::Value {
485 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
486 row.get_json(column)
487 }
488}
489impl FromColumn for rust_decimal::Decimal {
490 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
491 row.get_decimal(column)
492 }
493}
494
495impl FromColumn for Vec<f32> {
501 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
502 row.get_vector(column)
503 }
504}
505
506impl FromColumn for Vec<String> {
510 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
511 row.get_string_array(column)
512 }
513}
514
515impl<T: FromColumn> FromColumn for Option<T> {
528 fn from_column(row: &impl RowRef, column: &str) -> Result<Self, RowError> {
529 if row.is_null(column)? {
530 Ok(None)
531 } else {
532 T::from_column(row, column).map(Some)
533 }
534 }
535}
536
537#[cfg(test)]
538mod tests {
539 use super::*;
540
541 struct MockRow {
543 data: std::collections::HashMap<String, String>,
544 }
545
546 impl RowRef for MockRow {
547 fn get_i32(&self, column: &str) -> Result<i32, RowError> {
548 self.data
549 .get(column)
550 .ok_or_else(|| RowError::ColumnNotFound(column.to_string()))?
551 .parse()
552 .map_err(|e| RowError::TypeConversion {
553 column: column.to_string(),
554 message: format!("{}", e),
555 })
556 }
557
558 fn get_i32_opt(&self, column: &str) -> Result<Option<i32>, RowError> {
559 match self.data.get(column) {
560 Some(v) if v == "NULL" => Ok(None),
561 Some(v) => v.parse().map(Some).map_err(|e| RowError::TypeConversion {
562 column: column.to_string(),
563 message: format!("{}", e),
564 }),
565 None => Ok(None),
566 }
567 }
568
569 fn get_i64(&self, column: &str) -> Result<i64, RowError> {
570 self.data
571 .get(column)
572 .ok_or_else(|| RowError::ColumnNotFound(column.to_string()))?
573 .parse()
574 .map_err(|e| RowError::TypeConversion {
575 column: column.to_string(),
576 message: format!("{}", e),
577 })
578 }
579
580 fn get_i64_opt(&self, column: &str) -> Result<Option<i64>, RowError> {
581 match self.data.get(column) {
582 Some(v) if v == "NULL" => Ok(None),
583 Some(v) => v.parse().map(Some).map_err(|e| RowError::TypeConversion {
584 column: column.to_string(),
585 message: format!("{}", e),
586 }),
587 None => Ok(None),
588 }
589 }
590
591 fn get_f64(&self, column: &str) -> Result<f64, RowError> {
592 self.data
593 .get(column)
594 .ok_or_else(|| RowError::ColumnNotFound(column.to_string()))?
595 .parse()
596 .map_err(|e| RowError::TypeConversion {
597 column: column.to_string(),
598 message: format!("{}", e),
599 })
600 }
601
602 fn get_f64_opt(&self, column: &str) -> Result<Option<f64>, RowError> {
603 match self.data.get(column) {
604 Some(v) if v == "NULL" => Ok(None),
605 Some(v) => v.parse().map(Some).map_err(|e| RowError::TypeConversion {
606 column: column.to_string(),
607 message: format!("{}", e),
608 }),
609 None => Ok(None),
610 }
611 }
612
613 fn get_bool(&self, column: &str) -> Result<bool, RowError> {
614 let v = self
615 .data
616 .get(column)
617 .ok_or_else(|| RowError::ColumnNotFound(column.to_string()))?;
618 match v.as_str() {
619 "true" | "t" | "1" => Ok(true),
620 "false" | "f" | "0" => Ok(false),
621 _ => Err(RowError::TypeConversion {
622 column: column.to_string(),
623 message: "invalid boolean".to_string(),
624 }),
625 }
626 }
627
628 fn get_bool_opt(&self, column: &str) -> Result<Option<bool>, RowError> {
629 match self.data.get(column) {
630 Some(v) if v == "NULL" => Ok(None),
631 Some(v) => match v.as_str() {
632 "true" | "t" | "1" => Ok(Some(true)),
633 "false" | "f" | "0" => Ok(Some(false)),
634 _ => Err(RowError::TypeConversion {
635 column: column.to_string(),
636 message: "invalid boolean".to_string(),
637 }),
638 },
639 None => Ok(None),
640 }
641 }
642
643 fn get_str(&self, column: &str) -> Result<&str, RowError> {
644 self.data
645 .get(column)
646 .map(|s| s.as_str())
647 .ok_or_else(|| RowError::ColumnNotFound(column.to_string()))
648 }
649
650 fn get_str_opt(&self, column: &str) -> Result<Option<&str>, RowError> {
651 match self.data.get(column) {
652 Some(v) if v == "NULL" => Ok(None),
653 Some(v) => Ok(Some(v.as_str())),
654 None => Ok(None),
655 }
656 }
657
658 fn get_bytes(&self, column: &str) -> Result<&[u8], RowError> {
659 self.data
660 .get(column)
661 .map(|s| s.as_bytes())
662 .ok_or_else(|| RowError::ColumnNotFound(column.to_string()))
663 }
664
665 fn get_bytes_opt(&self, column: &str) -> Result<Option<&[u8]>, RowError> {
666 match self.data.get(column) {
667 Some(v) if v == "NULL" => Ok(None),
668 Some(v) => Ok(Some(v.as_bytes())),
669 None => Ok(None),
670 }
671 }
672 }
673
674 #[test]
675 fn test_row_ref_get_i32() {
676 let mut data = std::collections::HashMap::new();
677 data.insert("id".to_string(), "42".to_string());
678 let row = MockRow { data };
679
680 assert_eq!(row.get_i32("id").unwrap(), 42);
681 }
682
683 #[test]
684 fn test_row_ref_get_str_zero_copy() {
685 let mut data = std::collections::HashMap::new();
686 data.insert("email".to_string(), "test@example.com".to_string());
687 let row = MockRow { data };
688
689 let email = row.get_str("email").unwrap();
690 assert_eq!(email, "test@example.com");
691 }
694
695 #[test]
696 fn test_row_data() {
697 let borrowed: RowData = RowData::borrowed("hello");
698 assert_eq!(borrowed.as_str(), "hello");
699
700 let owned: RowData = RowData::owned("world".to_string());
701 assert_eq!(owned.as_str(), "world");
702 }
703
704 struct ArrayRow(MockRow);
707
708 impl RowRef for ArrayRow {
709 fn get_i32(&self, c: &str) -> Result<i32, RowError> {
710 self.0.get_i32(c)
711 }
712 fn get_i32_opt(&self, c: &str) -> Result<Option<i32>, RowError> {
713 self.0.get_i32_opt(c)
714 }
715 fn get_i64(&self, c: &str) -> Result<i64, RowError> {
716 self.0.get_i64(c)
717 }
718 fn get_i64_opt(&self, c: &str) -> Result<Option<i64>, RowError> {
719 self.0.get_i64_opt(c)
720 }
721 fn get_f64(&self, c: &str) -> Result<f64, RowError> {
722 self.0.get_f64(c)
723 }
724 fn get_f64_opt(&self, c: &str) -> Result<Option<f64>, RowError> {
725 self.0.get_f64_opt(c)
726 }
727 fn get_bool(&self, c: &str) -> Result<bool, RowError> {
728 self.0.get_bool(c)
729 }
730 fn get_bool_opt(&self, c: &str) -> Result<Option<bool>, RowError> {
731 self.0.get_bool_opt(c)
732 }
733 fn get_str(&self, c: &str) -> Result<&str, RowError> {
734 self.0.get_str(c)
735 }
736 fn get_str_opt(&self, c: &str) -> Result<Option<&str>, RowError> {
737 self.0.get_str_opt(c)
738 }
739 fn get_bytes(&self, c: &str) -> Result<&[u8], RowError> {
740 self.0.get_bytes(c)
741 }
742 fn get_bytes_opt(&self, c: &str) -> Result<Option<&[u8]>, RowError> {
743 self.0.get_bytes_opt(c)
744 }
745 fn get_string_array(&self, c: &str) -> Result<Vec<String>, RowError> {
746 let raw = self.get_str(c)?;
747 Ok(if raw.is_empty() {
748 vec![]
749 } else {
750 raw.split(',').map(str::to_string).collect()
751 })
752 }
753 }
754
755 fn array_row(pairs: &[(&str, &str)]) -> ArrayRow {
756 let data = pairs
757 .iter()
758 .map(|(k, v)| (k.to_string(), v.to_string()))
759 .collect();
760 ArrayRow(MockRow { data })
761 }
762
763 #[test]
764 fn vec_string_decodes_through_get_string_array() {
765 let row = array_row(&[("scopes", "read,write"), ("none", "")]);
766 assert_eq!(
767 Vec::<String>::from_column(&row, "scopes").unwrap(),
768 vec!["read".to_string(), "write".to_string()]
769 );
770 assert!(Vec::<String>::from_column(&row, "none").unwrap().is_empty());
771 }
772
773 #[test]
774 fn option_vec_string_maps_null_to_none() {
775 let row = array_row(&[("scopes", "NULL"), ("tags", "a")]);
776 assert_eq!(
777 Option::<Vec<String>>::from_column(&row, "scopes").unwrap(),
778 None
779 );
780 assert_eq!(
781 Option::<Vec<String>>::from_column(&row, "tags").unwrap(),
782 Some(vec!["a".to_string()])
783 );
784 }
785
786 #[test]
787 fn default_string_array_method_errors() {
788 let mut data = std::collections::HashMap::new();
789 data.insert("scopes".into(), "read".into());
790 let row = MockRow { data };
791 assert!(matches!(
792 Vec::<String>::from_column(&row, "scopes"),
793 Err(RowError::TypeConversion { message, .. }) if message.contains("string_array")
794 ));
795 }
796
797 #[test]
798 fn default_datetime_method_errors() {
799 let mut data = std::collections::HashMap::new();
800 data.insert("created_at".into(), "2026-04-27T00:00:00Z".into());
801 let row = MockRow { data };
802 assert!(matches!(
803 row.get_datetime_utc("created_at"),
804 Err(RowError::TypeConversion { .. })
805 ));
806 }
807
808 #[test]
809 fn from_column_u8_range_checks() {
810 let mut data = std::collections::HashMap::new();
811 data.insert("ok".to_string(), "255".to_string());
812 data.insert("big".to_string(), "256".to_string());
813 data.insert("neg".to_string(), "-1".to_string());
814 let row = MockRow { data };
815 assert_eq!(u8::from_column(&row, "ok").unwrap(), 255);
816 assert!(matches!(
817 u8::from_column(&row, "big"),
818 Err(RowError::TypeConversion { .. })
819 ));
820 assert!(matches!(
821 u8::from_column(&row, "neg"),
822 Err(RowError::TypeConversion { .. })
823 ));
824 }
825}