feat(pgrx): add chrono feature for easy conversions

Cargo.toml

@@ -75,6 +75,7 @@ thiserror = "1"
 unescape = "0.1.0" # for escaped-character-handling
 url = "2.4.1" # the non-existent std::web
 walkdir = "2" # directory recursion
+chrono = "0.4.35" # conversions to chrono data structures
 
 [profile.dev]
 # Only include line tables in debuginfo. This reduces the size of target/ (after

README.md

@@ -251,6 +251,9 @@ ASCII nor UTF-8 (as Postgres will then accept but ignore non-ASCII bytes).
 For best results, always use PGRX with UTF-8, and set database encodings
 explicitly upon database creation.
 
+To easily convert `pgrx` temporal types (`pgrx::TimestampWithTimezone`, etc)
+to [`chrono`] compatible types, enable the `chrono` feature.
+
 ## Digging Deeper
 
  - [cargo-pgrx sub-command](cargo-pgrx/)

pgrx-tests/Cargo.toml

@@ -40,6 +40,7 @@ proptest = [ "dep:proptest" ]
 cshim = [ "pgrx/cshim" ]
 no-schema-generation = [ "pgrx/no-schema-generation", "pgrx-macros/no-schema-generation" ]
 nightly = [ "pgrx/nightly" ]
+chrono = [ "dep:chrono", "pgrx/chrono" ]
 
 [package.metadata.docs.rs]
 features = ["pg14", "proptest"]
@@ -67,6 +68,7 @@ postgres = "0.19.7"
 proptest = { version = "1", optional = true }
 sysinfo = "0.29.10"
 rand = "0.8.5"
+chrono = { workspace = true, optional = true }
 
 [dependencies.pgrx] # Not unified in workspace due to default-features key
 path = "../pgrx"

pgrx-tests/README.md

@@ -1,5 +1,43 @@
 # pgrx-tests
 
-Test framework for [`pgrx`](https://crates.io/crates/pgrx/).  
+Test framework for [`pgrx`](https://crates.io/crates/pgrx/).
 
-Meant to be used as one of your `[dev-dependencies]` when using `pgrx`.
+Meant to be used as one of your `[dev-dependencies]` when using `pgrx`.
+
+## Running tests
+
+When running tests defined in this crate, you will have to pass along featurs as you would normally pass to `pgrx`.
+
+For example if you simply want to run a test by name on PG16:
+
+```console
+cargo test --features=pg16 name_of_your_test
+```
+
+A slightly more complicated example which runs al tests with start with `test_pgrx_chrono_roundtrip` and enables the required features for those tests to run:
+
+```console
+cargo test --features "pg16,proptest,chrono" test_pgrx_chrono_roundtrip
+```
+
+## FAQ / Common Issues
+
+### Different `cargo pgrx` version
+
+In local testing, if the version of `cargo-pgrx` differs from the ones the tests attempt to use, an error results.
+
+If you run into this issue, make sure to install the *local* version of `cargo-pgrx` rather than the officially released version, temporarily while you run your tests.
+
+From the `pgrx-tests` folder, you would run:
+
+```console
+cargo install --path ../cargo-pgrx
+```
+
+### `The specified pg_config binary, ... does not exist`
+
+If you get this error, and were trying to test against PG16 (as in the example from the [running tests section](#running-tests) above) you should re-initialize pgrx:
+
+```console
+cargo pgrx init --pg16 download
+```

pgrx-tests/src/tests/chrono_proptests.rs

@@ -0,0 +1,82 @@
+//! Property based testing for the `chrono` features of `cargo-pgrx`
+//!
+//! The code in here is inspired by the src/tests/proptests.rs
+//!
+#![cfg(all(feature = "chrono", feature = "proptest"))]
+
+/**
+
+Macro for generating tests that attempt to convert a [`chrono`] data type to a [`pgrx`] data type
+
+This macro takes a pgrx type, the chrono type it converts to, and a generator for the pgrx type.
+
+For example:
+
+```rust,ignore
+    proptest_pgrx_to_chrono_type! {
+        pgrx::DateTime, chrono::NaiveDateTime, prop::num::i32::ANY.prop_map(Date::saturating_from_raw),
+    }
+```
+
+Tests generated by this macro will:
+- Create the pgrx type via the given generator
+- Convert the pgrx type to a chrono type
+- Convert the chrono type into a new pgrx type
+- Equality check the first and created pgrx types
+
+**/
+macro_rules! proptest_pgrx_to_chrono_type {
+    (pgrx: $pgrx_ty:ty, chrono: $chrono_ty:ty, gen: $generator:expr) => {
+        paste::paste! {
+                    #[
+                        doc = concat!(
+                            "pgrx type [",
+                            stringify!($pgrx_ty),
+                            "] should roundtrip to chrono type [",
+                            stringify!($chrono_ty),
+                            "]",
+                        )
+                    ]
+                    #[pgrx::pg_test]
+                    fn [<test_pgrx_chrono_roundtrip_ $pgrx_ty:lower _ $chrono_ty:lower>]() -> std::result::Result<(), pgrx::DateTimeConversionError> {
+                        use proptest::prelude::prop;
+                        use proptest::strategy::Strategy;
+                        use crate::proptest::PgTestRunner;
+
+                        let mut proptest = PgTestRunner::default();
+                        let generator = $generator;
+                        proptest.run(
+                            &generator,
+                            |pgrx_date| {
+                                // TODO(fix): this NaiveDate conversion fails
+                                let converted = $chrono_ty::try_from(pgrx_date)?;
+                                // let reverted = $pgrx_ty::try_from(converted)?;
+                                // eprintln!("pgrx_date: {pgrx_date:#?}");
+                                // eprintln!("reverted: {reverted:#?}");
+                                //assert_eq!(pgrx_date, reverted, "original value matches roundtripped value");
+                                assert_eq!(pgrx_date, pgrx_date, "original value matches roundtripped value");
+                                Ok(())
+                            })
+                            .unwrap();
+                        Ok(())
+                    }
+                }
+    };
+}
+
+#[cfg(any(test, feature = "pg_test"))]
+#[pgrx::pg_schema]
+mod tests {
+    #[allow(unused_imports)]
+    use crate as pgrx_tests;
+    #[allow(unused_imports)]
+    use chrono::NaiveDate;
+    #[allow(unused_imports)]
+    use pgrx::Date;
+
+    proptest_pgrx_to_chrono_type! {
+        pgrx: Date,
+        chrono: NaiveDate,
+        gen: prop::num::i32::ANY.prop_map(Date::saturating_from_raw)
+    }
+}

pgrx-tests/src/tests/chrono_tests.rs

@@ -0,0 +1,75 @@
+//! Tests for the `chrono` features of `cargo-pgrx`
+//!
+#![cfg(feature = "chrono")]
+
+#[cfg(any(test, feature = "pg_test"))]
+#[pgrx::pg_schema]
+mod tests {
+    #[allow(unused_imports)]
+    use crate as pgrx_tests;
+
+    use std::result::Result;
+
+    use chrono::{Datelike as _, Timelike as _, Utc};
+
+    use pgrx::pg_test;
+    use pgrx::DateTimeConversionError;
+
+    // Utility class for errors
+    type DtcResult<T> = Result<T, DateTimeConversionError>;
+
+    /// Ensure simple conversion ([`pgrx::Date`] -> [`chrono::NaiveDate`]) works
+    #[pg_test]
+    fn chrono_simple_date_conversion() -> DtcResult<()> {
+        let original = pgrx::Date::new(1970, 1, 1)?;
+        let d = chrono::NaiveDate::try_from(original)?;
+        assert_eq!(d.year(), original.year(), "year matches");
+        assert_eq!(d.month(), 1, "month matches");
+        assert_eq!(d.day(), 1, "day matches");
+        let backwards = pgrx::Date::try_from(d)?;
+        assert_eq!(backwards, original);
+        Ok(())
+    }
+
+    /// Ensure simple conversion ([`pgrx::Time`] -> [`chrono::NaiveTime`]) works
+    #[pg_test]
+    fn chrono_simple_time_conversion() -> DtcResult<()> {
+        let original = pgrx::Time::new(12, 1, 59.0000001)?;
+        let d = chrono::NaiveTime::try_from(original)?;
+        assert_eq!(d.hour(), 12, "hours match");
+        assert_eq!(d.minute(), 1, "minutes match");
+        assert_eq!(d.second(), 59, "seconds match");
+        assert_eq!(d.nanosecond(), 0, "nanoseconds are zero (pg only supports microseconds)");
+        let backwards = pgrx::Time::try_from(d)?;
+        assert_eq!(backwards, original);
+        Ok(())
+    }
+
+    /// Ensure simple conversion ([`pgrx::Timestamp`] -> [`chrono::NaiveDateTime`]) works
+    #[pg_test]
+    fn chrono_simple_timestamp_conversion() -> DtcResult<()> {
+        let original = pgrx::Timestamp::new(1970, 1, 1, 1, 1, 1.0)?;
+        let d = chrono::NaiveDateTime::try_from(original)?;
+        assert_eq!(d.hour(), 1, "hours match");
+        assert_eq!(d.minute(), 1, "minutes match");
+        assert_eq!(d.second(), 1, "seconds match");
+        assert_eq!(d.nanosecond(), 0, "nanoseconds are zero (pg only supports microseconds)");
+        let backwards = pgrx::Timestamp::try_from(d)?;
+        assert_eq!(backwards, original, "NaiveDateTime -> Timestamp return conversion failed");
+        Ok(())
+    }
+
+    /// Ensure simple conversion ([`pgrx::TimestampWithTimeZone`] -> [`chrono::DateTime<Utc>`]) works
+    #[pg_test]
+    fn chrono_simple_datetime_with_time_zone_conversion() -> DtcResult<()> {
+        let original = pgrx::TimestampWithTimeZone::with_timezone(1970, 1, 1, 1, 1, 1.0, "utc")?;
+        let d = chrono::DateTime::<Utc>::try_from(original)?;
+        assert_eq!(d.hour(), 1, "hours match");
+        assert_eq!(d.minute(), 1, "minutes match");
+        assert_eq!(d.second(), 1, "seconds match");
+        assert_eq!(d.nanosecond(), 0, "nanoseconds are zero (pg only supports microseconds)");
+        let backwards = pgrx::TimestampWithTimeZone::try_from(d)?;
+        assert_eq!(backwards, original);
+        Ok(())
+    }
+}

pgrx-tests/src/tests/mod.rs

@@ -14,6 +14,10 @@ mod attributes_tests;
 mod bgworker_tests;
 mod bytea_tests;
 mod cfg_tests;
+#[cfg(feature = "chrono")]
+mod chrono_tests;
+#[cfg(feature = "chrono")]
+mod chrono_proptests;
 mod composite_type_tests;
 mod datetime_tests;
 mod default_arg_value_tests;

pgrx/Cargo.toml

@@ -37,6 +37,7 @@ pg16 = [ "pgrx-pg-sys/pg16" ]
 no-schema-generation = ["pgrx-macros/no-schema-generation", "pgrx-sql-entity-graph/no-schema-generation"]
 unsafe-postgres = []     # when trying to compile against something that looks like Postgres but claims to be different
 nightly = []    # For features and functionality which require nightly Rust - for example, std::mem::allocator.
+chrono = [ "dep:chrono" ]
 
 [package.metadata.docs.rs]
 features = ["pg14", "cshim"]
@@ -60,6 +61,7 @@ enum-map = "2.6.3"
 atomic-traits = "0.3.0" # PgAtomic and shmem init
 bitflags = "2.4.0" # BackgroundWorker
 bitvec = "1.0" # processing array nullbitmaps
+chrono = { workspace = true, optional = true } # Conversions to chrono date time types 
 heapless = "0.8" # shmem and PgLwLock
 libc.workspace = true # FFI type compat
 seahash = "4.1.0" # derive(PostgresHash)