Building upon @yrashk's work in #902, this does a few small things, which caused a bunch of files (mostly tests and examples) to be updated.

First off, the various Spi functions like `Spi::get_one()` go back to returning `-> Result<Option<T>, Error>`.  This might seem counter to my comment at #902 (review), but there's an important thing Spi **must** support:  Any Datum **can be NULL**, which means we must return `Option<T>`.

So, the thing that makes this better is we also now have `impl<T, E> IntoDatum for Result<T, E> where T: IntoDatum, E: std::error::Error`.  This means any `#[pg_extern]` function can now return a `Result`, and if that Result represents an error, it is raised as a Postgres ERROR.

This is a big win for `#[pg_extern]`-style functions in general, and makes working with an Spi interface that returns `Result<Option<T>, Error>` pretty fluent as now you can just directly return the result from `Spi::get_XXX()` or you can use the `?` operator to nicely unwrap the error and then deal with the returned, possibly NULL, Datum.

Doing this, and updating the Spi API caused all sorts of code to be touched in the tests and examples.  As a result, there's (hacky) support for `#[pg_test]` functions being able to return `-> Result<(), pgx::spi::Error>`, which makes using Spi in the tests nearly the same, but now with a `?` operator and a `return Ok(())` at the end of such functions.

The examples that use SPI needed to be touched as well.  This is a pretty big breaking API change, afterall.

Author: eeeebbbbrrrr

pgx-examples/aggregate/src/lib.rs

@@ -157,20 +157,22 @@ mod tests {
     }
 
     #[pg_test]
-    fn test_integer_avg_state_sql() {
+    fn test_integer_avg_state_sql() -> Result<(), pgx::spi::Error> {
         Spi::run("CREATE TABLE demo_table (value INTEGER);");
         Spi::run("INSERT INTO demo_table (value) VALUES (1), (2), (3);");
-        let retval = Spi::get_one::<i32>("SELECT DEMOAVG(value) FROM demo_table;")
+        let retval = Spi::get_one::<i32>("SELECT DEMOAVG(value) FROM demo_table;")?
             .expect("SQL select failed");
         assert_eq!(retval, 2);
+        Ok(())
     }
     #[pg_test]
-    fn test_integer_avg_with_null() {
+    fn test_integer_avg_with_null() -> Result<(), pgx::spi::Error> {
         Spi::run("CREATE TABLE demo_table (value INTEGER);");
         Spi::run("INSERT INTO demo_table (value) VALUES (1), (NULL), (3);");
-        let retval = Spi::get_one::<i32>("SELECT DEMOAVG(value) FROM demo_table;")
+        let retval = Spi::get_one::<i32>("SELECT DEMOAVG(value) FROM demo_table;")?
             .expect("SQL select failed");
         assert_eq!(retval, 2);
+        Ok(())
     }
 }
 

pgx-examples/arrays/src/lib.rs

@@ -121,10 +121,11 @@ pub mod tests {
 
     #[pg_test]
     #[search_path(@extschema@)]
-    fn test_vec_of_customtype() {
+    fn test_vec_of_customtype() -> Result<(), pgx::spi::Error> {
         let customvec =
-            Spi::get_one::<Vec<SomeStruct>>("SELECT arrays.return_vec_of_customtype();")
+            Spi::get_one::<Vec<SomeStruct>>("SELECT arrays.return_vec_of_customtype();")?
                 .expect("SQL select failed");
         assert_eq!(customvec, vec![SomeStruct {}]);
+        Ok(())
     }
 }

pgx-examples/bytea/src/lib.rs

@@ -42,15 +42,17 @@ mod tests {
     use pgx::prelude::*;
 
     #[pg_test]
-    fn test_gzip_text() {
-        let result = Spi::get_one::<String>("SELECT gunzip_as_text(gzip('hi there'));").unwrap();
+    fn test_gzip_text() -> Result<(), pgx::spi::Error> {
+        let result = Spi::get_one::<String>("SELECT gunzip_as_text(gzip('hi there'));")?.unwrap();
         assert_eq!(result, "hi there");
+        Ok(())
     }
 
     #[pg_test]
-    fn test_gzip_bytes() {
-        let result = Spi::get_one::<&[u8]>("SELECT gunzip(gzip('hi there'::bytea));").unwrap();
+    fn test_gzip_bytes() -> Result<(), pgx::spi::Error> {
+        let result = Spi::get_one::<&[u8]>("SELECT gunzip(gzip('hi there'::bytea));")?.unwrap();
         assert_eq!(result, b"hi there");
+        Ok(())
     }
 }
 

pgx-examples/composite_type/src/lib.rs

@@ -257,58 +257,63 @@ mod tests {
     use pgx::AllocatedByRust;
 
     #[pg_test]
-    fn test_create_dog() {
+    fn test_create_dog() -> Result<(), pgx::spi::Error> {
         let retval = Spi::get_one::<PgHeapTuple<AllocatedByRust>>(
             "\
             SELECT create_dog('Nami', 0)
         ",
-        )
+        )?
         .expect("SQL select failed");
-        assert_eq!(retval.get_by_name::<&str>("name").unwrap().unwrap(), "Nami");
-        assert_eq!(retval.get_by_name::<i32>("scritches").unwrap().unwrap(), 0);
+        assert_eq!(retval.get_by_name::<&str>("name")?.unwrap(), "Nami");
+        assert_eq!(retval.get_by_name::<i32>("scritches")?.unwrap(), 0);
+        Ok(())
     }
 
     #[pg_test]
-    fn test_scritch_dog() {
+    fn test_scritch_dog() -> Result<(), pgx::spi::Error> {
         let retval = Spi::get_one::<PgHeapTuple<AllocatedByRust>>(
             "\
             SELECT scritch_dog(ROW('Nami', 1)::Dog)
         ",
-        )
+        )?
         .expect("SQL select failed");
-        assert_eq!(retval.get_by_name::<&str>("name").unwrap().unwrap(), "Nami");
-        assert_eq!(retval.get_by_name::<i32>("scritches").unwrap().unwrap(), 1);
+        assert_eq!(retval.get_by_name::<&str>("name")?.unwrap(), "Nami");
+        assert_eq!(retval.get_by_name::<i32>("scritches")?.unwrap(), 1);
+        Ok(())
     }
 
     #[pg_test]
-    fn test_make_friendship() {
+    fn test_make_friendship() -> Result<(), pgx::spi::Error> {
         let friendship = Spi::get_one::<PgHeapTuple<AllocatedByRust>>(
             "\
             SELECT make_friendship(ROW('Nami', 0)::Dog, ROW('Sally', 0)::Cat)
         ",
-        )
+        )?
         .expect("SQL select failed");
-        let dog: PgHeapTuple<AllocatedByRust> = friendship.get_by_name("dog").unwrap().unwrap();
-        assert_eq!(dog.get_by_name::<&str>("name").unwrap().unwrap(), "Nami");
+        let dog: PgHeapTuple<AllocatedByRust> = friendship.get_by_name("dog")?.unwrap();
+        assert_eq!(dog.get_by_name::<&str>("name")?.unwrap(), "Nami");
 
-        let cat: PgHeapTuple<AllocatedByRust> = friendship.get_by_name("cat").unwrap().unwrap();
-        assert_eq!(cat.get_by_name::<&str>("name").unwrap().unwrap(), "Sally");
+        let cat: PgHeapTuple<AllocatedByRust> = friendship.get_by_name("cat")?.unwrap();
+        assert_eq!(cat.get_by_name::<&str>("name")?.unwrap(), "Sally");
+        Ok(())
     }
 
     #[pg_test]
-    fn test_scritch_collector() {
+    fn test_scritch_collector() -> Result<(), pgx::spi::Error> {
         let retval = Spi::get_one::<i32>(
             "SELECT (scritchcollector(value)).scritches FROM UNNEST(ARRAY [1,2,3]) as value;",
-        )
+        )?
         .expect("SQL select failed");
         assert_eq!(retval, 6);
+        Ok(())
     }
 
     #[pg_test]
-    fn test_dog_add_operator() {
-        let retval = Spi::get_one::<i32>("SELECT (ROW('Nami', 0)::Dog + 1).scritches;")
+    fn test_dog_add_operator() -> Result<(), pgx::spi::Error> {
+        let retval = Spi::get_one::<i32>("SELECT (ROW('Nami', 0)::Dog + 1).scritches;")?
             .expect("SQL select failed");
         assert_eq!(retval, 1);
+        Ok(())
     }
 }
 

pgx-examples/custom_types/src/complex.rs

@@ -61,8 +61,8 @@ mod tests {
 
     #[cfg(not(feature = "no-schema-generation"))]
     #[pg_test]
-    fn test_known_animals_via_spi() {
-        let animals = Spi::get_one::<Animals>("SELECT known_animals();").unwrap();
+    fn test_known_animals_via_spi() -> Result<(), pgx::spi::Error> {
+        let animals = Spi::get_one::<Animals>("SELECT known_animals();")?.unwrap();
 
         assert_eq!(animals, known_animals());
 
@@ -72,6 +72,7 @@ mod tests {
                 names: vec!["Sally".into(), "Brandy".into(), "anchovy".into()],
                 age_lookup: hashmap! { 5 => "Sally".into(), 4 => "Brandy".into(), 3=> "anchovy".into()},
             }
-        )
+        );
+        Ok(())
     }
 }

pgx-examples/custom_types/src/ordered.rs

@@ -50,15 +50,15 @@ mod tests {
 
     #[cfg(not(feature = "no-schema-generation"))]
     #[pg_test]
-    fn test_ordering_via_spi() {
+    fn test_ordering_via_spi() -> Result<(), pgx::spi::Error> {
         let items = Spi::get_one::<Vec<OrderedThing>>(
             "SELECT array_agg(i ORDER BY i) FROM (VALUES \
                 ('{\"item\":\"foo\"}'::OrderedThing), \
                 ('{\"item\":\"bar\"}'::OrderedThing), \
                 ('{\"item\":\"Foo\"}'::OrderedThing), \
                 ('{\"item\":\"Bar\"}'::OrderedThing))\
                 items(i);",
-        )
+        )?
         .unwrap();
 
         assert_eq!(
@@ -69,6 +69,7 @@ mod tests {
                 OrderedThing { item: "bar".to_string() },
                 OrderedThing { item: "foo".to_string() },
             ]
-        )
+        );
+        Ok(())
     }
 }

pgx-examples/custom_types/src/rust_enum.rs

@@ -25,20 +25,21 @@ mod tests {
 
     #[cfg(not(feature = "no-schema-generation"))]
     #[pg_test]
-    fn test_some_enum() {
-        let val = Spi::get_one::<SomeEnum>(r#"SELECT '"hello world"'::SomeEnum"#).unwrap();
+    fn test_some_enum() -> Result<(), pgx::spi::Error> {
+        let val = Spi::get_one::<SomeEnum>(r#"SELECT '"hello world"'::SomeEnum"#)?.unwrap();
 
         assert!(matches!(
             val,
             SomeEnum::String(s) if s == "hello world"
         ));
 
-        let val =
-            Spi::get_one::<SomeEnum>(r#"SELECT '{"a": 1, "s": "hello world"}'::SomeEnum"#).unwrap();
+        let val = Spi::get_one::<SomeEnum>(r#"SELECT '{"a": 1, "s": "hello world"}'::SomeEnum"#)?
+            .unwrap();
 
         assert!(matches!(
             val,
             SomeEnum::Struct{a: 1, s } if s == "hello world"
         ));
+        Ok(())
     }
 }

pgx-examples/schemas/src/lib.rs

@@ -71,30 +71,33 @@ mod tests {
     use pgx::prelude::*;
 
     #[pg_test]
-    fn test_hello_default_schema() {
+    fn test_hello_default_schema() -> Result<(), pgx::spi::Error> {
         assert_eq!(
             "Hello from the schema where you installed this extension",
-            Spi::get_one::<&str>("SELECT hello_default_schema()").unwrap()
+            Spi::get_one::<&str>("SELECT hello_default_schema()")?.unwrap()
         );
+        Ok(())
     }
 
     #[pg_test]
-    fn test_my_type() {
+    fn test_my_type() -> Result<(), pgx::spi::Error> {
         assert_eq!(
             "test",
             // we don't need to qualify "MyType" because whatever schema it was created in
             // is applied to the "search_path" of this test function
-            Spi::get_one::<MyType>("SELECT '\"test\"'::MyType").unwrap().0
+            Spi::get_one::<MyType>("SELECT '\"test\"'::MyType")?.unwrap().0
         );
+        Ok(())
     }
 
     #[pg_test]
-    fn test_hello_some_schema() {
+    fn test_hello_some_schema() -> Result<(), pgx::spi::Error> {
         assert_eq!(
             "Hello from some_schema",
             // "hello_some_schema()" is in "some_schema", so it needs to be qualified
-            Spi::get_one::<&str>("SELECT some_schema.hello_some_schema()").unwrap()
+            Spi::get_one::<&str>("SELECT some_schema.hello_some_schema()")?.unwrap()
         );
+        Ok(())
     }
 
     #[pg_test]
@@ -107,26 +110,29 @@ mod tests {
                 c.select("SELECT '\"test\"'::MySomeSchemaType", None, None)
                     .first()
                     .get_one::<MySomeSchemaType>()
+                    .expect("get_one::<MySomeSchemaType>() failed")
                     .unwrap()
                     .0
             );
         });
     }
 
     #[pg_test]
-    fn test_my_pg_catalog_type() {
+    fn test_my_pg_catalog_type() -> Result<(), pgx::spi::Error> {
         assert_eq!(
             String::from("test"),
-            Spi::get_one::<MyPgCatalogType>("SELECT '\"test\"'::MyPgCatalogType").unwrap().0
-        )
+            Spi::get_one::<MyPgCatalogType>("SELECT '\"test\"'::MyPgCatalogType")?.unwrap().0
+        );
+        Ok(())
     }
 
     #[pg_test]
-    fn test_hello_public() {
+    fn test_hello_public() -> Result<(), pgx::spi::Error> {
         assert_eq!(
             "Hello from the public schema",
-            Spi::get_one::<&str>("SELECT hello_public()").unwrap()
-        )
+            Spi::get_one::<&str>("SELECT hello_public()")?.unwrap()
+        );
+        Ok(())
     }
 }
 

pgx-examples/spi/src/lib.rs

@@ -7,7 +7,7 @@ All rights reserved.
 Use of this source code is governed by the MIT license that can be found in the LICENSE file.
 */
 use pgx::prelude::*;
-use pgx::{info, IntoDatum};
+use pgx::{info, spi, IntoDatum};
 
 pgx::pg_module_magic!();
 
@@ -53,21 +53,20 @@ fn spi_return_query(
 }
 
 #[pg_extern(immutable, parallel_safe)]
-fn spi_query_random_id() -> Option<i64> {
-    Spi::get_one("SELECT id FROM spi.spi_example ORDER BY random() LIMIT 1").unwrap()
+fn spi_query_random_id() -> Result<Option<i64>, pgx::spi::Error> {
+    Spi::get_one("SELECT id FROM spi.spi_example ORDER BY random() LIMIT 1")
 }
 
 #[pg_extern]
-fn spi_query_title(title: &str) -> Option<i64> {
+fn spi_query_title(title: &str) -> Result<Option<i64>, pgx::spi::Error> {
     Spi::get_one_with_args(
         "SELECT id FROM spi.spi_example WHERE title = $1;",
         vec![(PgBuiltInOids::TEXTOID.oid(), title.into_datum())],
     )
-    .unwrap()
 }
 
 #[pg_extern]
-fn spi_query_by_id(id: i64) -> Option<String> {
+fn spi_query_by_id(id: i64) -> Result<Option<String>, spi::Error> {
     let (returned_id, title) = Spi::connect(|client| {
         let tuptable = client
             .select(
@@ -78,21 +77,18 @@ fn spi_query_by_id(id: i64) -> Option<String> {
             .first();
 
         tuptable.get_two::<i64, String>()
-    })
-    .unwrap();
-
-    info!("id={}", returned_id);
+    })?;
 
-    Some(title)
+    info!("id={:?}", returned_id);
+    Ok(title)
 }
 
 #[pg_extern]
-fn spi_insert_title(title: &str) -> i64 {
+fn spi_insert_title(title: &str) -> Result<Option<i64>, spi::Error> {
     Spi::get_one_with_args(
         "INSERT INTO spi.spi_example(title) VALUES ($1) RETURNING id",
         vec![(PgBuiltInOids::TEXTOID.oid(), title.into_datum())],
     )
-    .unwrap()
 }
 
 #[pg_extern]
@@ -108,6 +104,15 @@ fn spi_insert_title2(
     TableIterator::once(tuple)
 }
 
+#[pg_extern]
+fn spi_echo(value: Option<String>) -> Result<Option<String>, spi::Error> {
+    let result = Spi::get_one_with_args(
+        "SELECT $1",
+        vec![(PgOid::from(pg_sys::TEXTOID), value.into_datum())],
+    );
+    result
+}
+
 extension_sql!(
     r#"
 
@@ -124,15 +129,17 @@ mod tests {
     use pgx::prelude::*;
 
     #[pg_test]
-    fn test_spi_query_by_id_direct() {
-        assert_eq!(Some("This is a test".to_string()), spi_query_by_id(1))
+    fn test_spi_query_by_id_direct() -> Result<(), pgx::spi::Error> {
+        assert_eq!(Some("This is a test".to_string()), spi_query_by_id(1)?);
+        Ok(())
     }
 
     #[pg_test]
-    fn test_spi_query_by_id_via_spi() {
-        let result = Spi::get_one::<&str>("SELECT spi.spi_query_by_id(1)").unwrap();
+    fn test_spi_query_by_id_via_spi() -> Result<(), pgx::spi::Error> {
+        let result = Spi::get_one::<&str>("SELECT spi.spi_query_by_id(1)")?.unwrap();
 
-        assert_eq!("This is a test", result)
+        assert_eq!("This is a test", result);
+        Ok(())
     }
 }