From 2aea32dc3ccfb5afb0129bf72e07c4bde9dba2c3 Mon Sep 17 00:00:00 2001
From: urso <steffen@xata.io>
Date: Wed, 10 Jul 2024 14:57:06 +0200
Subject: [PATCH 1/4] ci: run scripts per example

---
 ci/run.sh                         | 154 +++++++++++-------------------
 examples/char_count_zig/ci/run.sh |  63 ++++++++++++
 examples/pgaudit_zig/ci/run.sh    |  56 +++++++++++
 examples/spi_sql/ci/run.sh        |  57 +++++++++++
 4 files changed, 233 insertions(+), 97 deletions(-)
 create mode 100755 examples/char_count_zig/ci/run.sh
 create mode 100755 examples/pgaudit_zig/ci/run.sh
 create mode 100755 examples/spi_sql/ci/run.sh

diff --git a/ci/run.sh b/ci/run.sh
index 9c86a51..7d1136d 100755
--- a/ci/run.sh
+++ b/ci/run.sh
@@ -3,115 +3,75 @@
 #set -x
 set -o pipefail
 
-test_pgzx() {
-	rc=0
-	run_unit_tests ./ || rc=1
-	extension_drop pgzx_unit
-	return $rc
-}
-
-test_char_count_zig() {
-	extension_create char_count_zig
-	trap "extension_drop char_count_zig" INT TERM
-
-	rc=0
-	run_regression_tests ./examples/char_count_zig || rc=1
-	run_unit_tests ./examples/char_count_zig || rc=1
-
-	extension_drop char_count_zig
-	return $rc
-}
-
-test_pgaudit_zig() {
-	run_unit_tests ./examples/pgaudit_zig
-}
-
-test_spi_sql() {
-	local rc=0
-	run_regression_tests ./examples/spi_sql || rc=1
-	return $rc
-}
-
-extension_build() {
-	cwd=$(pwd)
-	cd "$1" || return 1
-	zig build -freference-trace -p "$PG_HOME" || return 1
-	cd "$cwd" || return 1
-}
-
-extension_create() {
-	echo "Create extension $1"
-	psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS $1"
-}
+examples=(./examples/*)
 
-extension_drop() {
-	echo "Drop extension $1"
-	psql -U postgres -c "DROP EXTENSION IF EXISTS $1"
+fail() {
+	echo "$1" >&2
+	exit 1
 }
 
-run_regression_tests() {
-	echo "Run regression tests"
-
+build_example() {
 	cwd=$(pwd)
 	cd "$1" || return 1
-	zig build pg_regress --verbose || return 1
+	./ci/run.sh build || return 1
 	cd "$cwd" || return 1
 }
 
-run_unit_tests() {
-	echo "Run unit tests"
-
+run_example() {
 	cwd=$(pwd)
 	cd "$1" || return 1
-	zig build -freference-trace -p "$PG_HOME" unit || return 1
+	./ci/run.sh || return 1
 	cd "$cwd" || return 1
 }
 
-run_test_suites() {
-	for t in "$@"; do
-		echo ""
-		echo "# Run $t"
-		if ! $t; then
-			return 1
-		fi
-	done
-}
-
-fail() {
-	echo "$1" >&2
-	exit 1
-}
-
-main() {
-	echo "Build and install extension"
-	eval "$(pgenv)"
-
-	log_init_size=0
-	if [ -f "$PG_CLUSTER_LOG_FILE" ]; then
-		log_init_size=$(stat -c %s "$PG_CLUSTER_LOG_FILE")
-	fi
-	echo "Server log size: $log_init_size"
-
-	extension_build ./examples/char_count_zig || fail "Failed to build char_count_zig"
-	extension_build ./examples/pgaudit_zig || fail "Failed to build pgaudit_zig"
-	extension_build ./examples/spi_sql || fail "Failed to build spi_sql"
-
-	echo "Start PostgreSQL"
-	pgstart || fail "Failed to start PostgreSQL"
-	trap pgstop TERM INT EXIT
-
-	ok=true
-	run_test_suites test_pgzx test_char_count_zig test_pgaudit_zig test_spi_sql || ok=false
-
-	if ! $ok; then
-		printf "\n\nServer log:"
-
-		log_size=$(stat -c %s "$PG_CLUSTER_LOG_FILE")
-		tail -c $((log_size - log_init_size)) "$PG_CLUSTER_LOG_FILE"
-		fail "Regression tests failed"
-	fi
-
-	echo "Success!"
+test_pgzx() {
+	rc=0
+	zig build -freference-trace -p "$PG_HOME" unit || rc=1
+	psql -U postgres -c "DROP EXTENSION IF EXISTS pgzx_unit"
+	return $rc
 }
 
-main
+echo "Build and install extension"
+eval "$(pgenv)"
+
+log_init_size=0
+if [ -f "$PG_CLUSTER_LOG_FILE" ]; then
+	log_init_size=$(stat -c %s "$PG_CLUSTER_LOG_FILE")
+fi
+echo "Server log size: $log_init_size"
+
+# build examples
+echo "${examples[@]}"
+build_jobs=()
+for example in "${examples[@]}"; do
+	echo -e "\n\nBuild example $example"
+	build_example "$example" &
+	build_jobs+=($!)
+done
+for job in "${build_jobs[@]}"; do
+	wait "$job" || fail "Failed to build example"
+done
+
+echo -e "\n\nStart PostgreSQL"
+pgstart || fail "Failed to start PostgreSQL"
+trap pgstop TERM INT EXIT
+
+echo -e "\n\nRun pgzx unit tests:"
+test_pgzx || fail "Failed to run pgzx unit tests"
+
+for example in "${examples[@]}"; do
+	echo -e "\n\nRun example CI script $example"
+	run_example "$example" || fail "Failed to run CI script for $example"
+done
+
+ok=true
+
+if ! $ok; then
+	printf "\n\nServer log:"
+
+	log_size=$(stat -c %s "$PG_CLUSTER_LOG_FILE")
+	tail -c $((log_size - log_init_size)) "$PG_CLUSTER_LOG_FILE"
+	fail "Regression tests failed"
+fi
+
+echo "Success!"
diff --git a/examples/char_count_zig/ci/run.sh b/examples/char_count_zig/ci/run.sh
new file mode 100755
index 0000000..4c7e340
--- /dev/null
+++ b/examples/char_count_zig/ci/run.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+
+#set -x
+set -o pipefail
+
+EXTENSION_NAME=char_count_zig
+
+build() {
+	echo "Build extension $EXTENSION_NAME"
+	zig build -freference-trace -p "$PG_HOME" || return 1
+}
+
+create_extension() {
+	echo "Create extension $EXTENSION_NAME"
+	psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS $EXTENSION_NAME"
+}
+
+extension_drop() {
+	echo "Drop extension $EXTENSION_NAME"
+	psql -U postgres -c "DROP EXTENSION IF EXISTS $EXTENSION_NAME"
+}
+
+regression_tests() {
+	echo "Run regression tests: $EXTENSION_NAME"
+	zig build pg_regress --verbose || return 1
+}
+
+unit_tests() {
+	echo "Run unit tests: $EXTENSION_NAME"
+	zig build -freference-trace -p "$PG_HOME" unit || return 1
+}
+
+all() {
+	build && create_extension && unit_tests && regression_tests && extension_drop
+}
+
+# optional command. Use all if not specified
+command=${1:-all}
+
+#shellcheck disable=SC1007
+HELP= <<EOF
+Usage: $0 [command]
+
+commands (default 'all'):
+  all - build nand run tests
+  build - build and install extension
+  create_extension - create extension
+  extension_drop - drop extension
+  regression_tests - run regression tests
+  unit_tests - run unit tests
+  help - show this help message
+EOF
+
+case $command in
+	all) all ;;
+	build) build ;;
+	create_extension) create_extension ;;
+	extension_drop) extension_drop ;;
+	regression_tests) regression_tests ;;
+	unit_tests) unit_tests ;;
+	help) echo "$HELP" ;;
+	*) echo "$HELP" ;;
+esac
diff --git a/examples/pgaudit_zig/ci/run.sh b/examples/pgaudit_zig/ci/run.sh
new file mode 100755
index 0000000..600a581
--- /dev/null
+++ b/examples/pgaudit_zig/ci/run.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+#set -x
+set -o pipefail
+
+EXTENSION_NAME=pgaudit_zig
+
+build() {
+	echo "Build extension $EXTENSION_NAME"
+	zig build -freference-trace -p "$PG_HOME" || return 1
+}
+
+create_extension() {
+	echo "Create extension $EXTENSION_NAME"
+	psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS $EXTENSION_NAME"
+}
+
+extension_drop() {
+	echo "Drop extension $EXTENSION_NAME"
+	psql -U postgres -c "DROP EXTENSION IF EXISTS $EXTENSION_NAME"
+}
+
+unit_tests() {
+	echo "Run unit tests: $EXTENSION_NAME"
+	zig build -freference-trace -p "$PG_HOME" unit || return 1
+}
+
+all() {
+	build && create_extension && unit_tests && extension_drop
+}
+
+# optional command. Use all if not specified
+command=${1:-all}
+
+#shellcheck disable=SC1007
+HELP= <<EOF
+Usage: $0 [command]
+
+commands (default 'all'):
+  all - build nand run tests
+  build - build and install extension
+  create_extension - create extension
+  extension_drop - drop extension
+  unit_tests - run unit tests
+  help - show this help message
+EOF
+
+case $command in
+	all) all ;;
+	build) build ;;
+	create_extension) create_extension ;;
+	extension_drop) extension_drop ;;
+	unit_tests) unit_tests ;;
+	help) echo "$HELP" ;;
+	*) echo "$HELP" ;;
+esac
diff --git a/examples/spi_sql/ci/run.sh b/examples/spi_sql/ci/run.sh
new file mode 100755
index 0000000..036451a
--- /dev/null
+++ b/examples/spi_sql/ci/run.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+
+#set -x
+set -o pipefail
+
+EXTENSION_NAME=char_count_zig
+
+build() {
+	echo "Build extension $EXTENSION_NAME"
+	zig build -freference-trace -p "$PG_HOME" || return 1
+}
+
+create_extension() {
+	echo "Create extension $EXTENSION_NAME"
+	psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS $EXTENSION_NAME"
+}
+
+extension_drop() {
+	echo "Drop extension $EXTENSION_NAME"
+	psql -U postgres -c "DROP EXTENSION IF EXISTS $EXTENSION_NAME"
+}
+
+regression_tests() {
+	echo "Run regression tests: $EXTENSION_NAME"
+	zig build pg_regress --verbose || return 1
+}
+
+all() {
+	build && create_extension && regression_tests && extension_drop
+}
+
+# optional command. Use all if not specified
+command=${1:-all}
+
+#shellcheck disable=SC1007
+HELP= <<EOF
+Usage: $0 [command]
+
+commands (default 'all'):
+  all - build nand run tests
+  build - build and install extension
+  create_extension - create extension
+  extension_drop - drop extension
+  regression_tests - run regression tests
+  help - show this help message
+EOF
+
+case $command in
+	all) all ;;
+	build) build ;;
+	create_extension) create_extension ;;
+	extension_drop) extension_drop ;;
+	regression_tests) regression_tests ;;
+	unit_tests) unit_tests ;;
+	help) echo "$HELP" ;;
+	*) echo "$HELP" ;;
+esac

From 609654626093227fe02a0e8fad24ff63d1480f78 Mon Sep 17 00:00:00 2001
From: urso <steffen@xata.io>
Date: Wed, 10 Jul 2024 20:24:58 +0200
Subject: [PATCH 2/4] typo

---
 examples/spi_sql/ci/run.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/spi_sql/ci/run.sh b/examples/spi_sql/ci/run.sh
index 036451a..4095885 100755
--- a/examples/spi_sql/ci/run.sh
+++ b/examples/spi_sql/ci/run.sh
@@ -3,7 +3,7 @@
 #set -x
 set -o pipefail
 
-EXTENSION_NAME=char_count_zig
+EXTENSION_NAME=spi_sql
 
 build() {
 	echo "Build extension $EXTENSION_NAME"

From 7156da4d4732c1a9eaefeb04cb6644ea0fe85d15 Mon Sep 17 00:00:00 2001
From: urso <steffen@xata.io>
Date: Wed, 10 Jul 2024 21:46:10 +0200
Subject: [PATCH 3/4] examples: sqlfns

---
 examples/sqlfns/README.md                 |   2 +
 examples/sqlfns/build.zig                 |  53 ++++++++
 examples/sqlfns/build.zig.zon             |  13 ++
 examples/sqlfns/ci/run.sh                 |  57 ++++++++
 examples/sqlfns/expected/sqlfns_test.out  |  99 ++++++++++++++
 examples/sqlfns/extension/sqlfns--0.1.sql |  27 ++++
 examples/sqlfns/extension/sqlfns.control  |   6 +
 examples/sqlfns/sql/sqlfns_test.sql       |  29 +++++
 examples/sqlfns/src/hello_world.zig       |   9 ++
 examples/sqlfns/src/main.zig              | 151 ++++++++++++++++++++++
 10 files changed, 446 insertions(+)
 create mode 100644 examples/sqlfns/README.md
 create mode 100644 examples/sqlfns/build.zig
 create mode 100644 examples/sqlfns/build.zig.zon
 create mode 100755 examples/sqlfns/ci/run.sh
 create mode 100644 examples/sqlfns/expected/sqlfns_test.out
 create mode 100644 examples/sqlfns/extension/sqlfns--0.1.sql
 create mode 100644 examples/sqlfns/extension/sqlfns.control
 create mode 100644 examples/sqlfns/sql/sqlfns_test.sql
 create mode 100644 examples/sqlfns/src/hello_world.zig
 create mode 100644 examples/sqlfns/src/main.zig

diff --git a/examples/sqlfns/README.md b/examples/sqlfns/README.md
new file mode 100644
index 0000000..2461523
--- /dev/null
+++ b/examples/sqlfns/README.md
@@ -0,0 +1,2 @@
+# sqlfns - Sample extension showing how to create function that can be called from Postgres
+
diff --git a/examples/sqlfns/build.zig b/examples/sqlfns/build.zig
new file mode 100644
index 0000000..f8ac2b0
--- /dev/null
+++ b/examples/sqlfns/build.zig
@@ -0,0 +1,53 @@
+const std = @import("std");
+
+// Load pgzx build support. The build utilities use pg_config to find all dependencies
+// and provide functions go create and test extensions.
+const PGBuild = @import("pgzx").Build;
+
+pub fn build(b: *std.Build) void {
+    // Project meta data
+    const name = "sqlfns";
+    const version = .{ .major = 0, .minor = 1 };
+
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    // Load the pgzx module and initialize the build utilities
+    const dep_pgzx = b.dependency("pgzx", .{ .target = target, .optimize = optimize });
+    const pgzx = dep_pgzx.module("pgzx");
+    var pgbuild = PGBuild.create(b, .{ .target = target, .optimize = optimize });
+
+    const build_options = b.addOptions();
+    build_options.addOption(bool, "testfn", b.option(bool, "testfn", "Register test function") orelse false);
+
+    // Register the dependency with the build system
+    // and add pgzx as module dependency.
+    {
+        const ext = pgbuild.addInstallExtension(.{
+            .name = name,
+            .version = version,
+            .root_source_file = b.path("src/main.zig"),
+            .root_dir = ".",
+        });
+        ext.lib.root_module.addImport("pgzx", pgzx);
+        ext.lib.root_module.addOptions("build_options", build_options);
+
+        b.getInstallStep().dependOn(&ext.step);
+    }
+
+    // Configure pg_regress based testing for the current extension.
+    {
+        const extest = pgbuild.addRegress(.{
+            .db_user = "postgres",
+            .db_port = 5432,
+            .root_dir = ".",
+            .scripts = &[_][]const u8{
+                "sqlfns_test",
+            },
+        });
+
+        // Make regression tests available to `zig build`
+        var regress = b.step("pg_regress", "Run regression tests");
+        regress.dependOn(&extest.step);
+    }
+}
diff --git a/examples/sqlfns/build.zig.zon b/examples/sqlfns/build.zig.zon
new file mode 100644
index 0000000..2fd4f93
--- /dev/null
+++ b/examples/sqlfns/build.zig.zon
@@ -0,0 +1,13 @@
+.{
+    .name = "sqlfns",
+    .version = "0.1.0",
+    .paths = .{
+        "extension",
+        "src",
+    },
+    .dependencies = .{
+        .pgzx = .{
+            .path = "./../..",
+        },
+    },
+}
diff --git a/examples/sqlfns/ci/run.sh b/examples/sqlfns/ci/run.sh
new file mode 100755
index 0000000..8be58ce
--- /dev/null
+++ b/examples/sqlfns/ci/run.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+
+#set -x
+set -o pipefail
+
+EXTENSION_NAME=sqlfns
+
+build() {
+	echo "Build extension $EXTENSION_NAME"
+	zig build -freference-trace -p "$PG_HOME" || return 1
+}
+
+create_extension() {
+	echo "Create extension $EXTENSION_NAME"
+	psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS $EXTENSION_NAME"
+}
+
+extension_drop() {
+	echo "Drop extension $EXTENSION_NAME"
+	psql -U postgres -c "DROP EXTENSION IF EXISTS $EXTENSION_NAME"
+}
+
+regression_tests() {
+	echo "Run regression tests: $EXTENSION_NAME"
+	zig build pg_regress --verbose || return 1
+}
+
+all() {
+	build && create_extension && regression_tests && extension_drop
+}
+
+# optional command. Use all if not specified
+command=${1:-all}
+
+#shellcheck disable=SC1007
+HELP= <<EOF
+Usage: $0 [command]
+
+commands (default 'all'):
+  all - build nand run tests
+  build - build and install extension
+  create_extension - create extension
+  extension_drop - drop extension
+  regression_tests - run regression tests
+  help - show this help message
+EOF
+
+case $command in
+	all) all ;;
+	build) build ;;
+	create_extension) create_extension ;;
+	extension_drop) extension_drop ;;
+	regression_tests) regression_tests ;;
+	unit_tests) unit_tests ;;
+	help) echo "$HELP" ;;
+	*) echo "$HELP" ;;
+esac
diff --git a/examples/sqlfns/expected/sqlfns_test.out b/examples/sqlfns/expected/sqlfns_test.out
new file mode 100644
index 0000000..30fea6b
--- /dev/null
+++ b/examples/sqlfns/expected/sqlfns_test.out
@@ -0,0 +1,99 @@
+CREATE EXTENSION sqlfns;
+SET search_path TO sqlfns;
+SELECT hello_world_c(NULL);
+ hello_world_c 
+---------------
+ Hello World
+(1 row)
+
+SELECT hello_world_c('pgzx');
+ hello_world_c 
+---------------
+ Hello, pgzx!
+(1 row)
+
+SELECT hello_world_zig(NULL);
+ hello_world_zig 
+-----------------
+ Hello World
+(1 row)
+
+SELECT hello_world_zig('pgzx');
+ hello_world_zig 
+-----------------
+ Hello, pgzx!
+(1 row)
+
+SELECT hello_world_zig(NULL);
+ hello_world_zig 
+-----------------
+ Hello World
+(1 row)
+
+SELECT hello_world_zig('pgzx');
+ hello_world_zig 
+-----------------
+ Hello, pgzx!
+(1 row)
+
+SELECT hello_world_zig_null(NULL);
+ hello_world_zig_null 
+----------------------
+ 
+(1 row)
+
+SELECT hello_world_zig_null('pgzx');
+ hello_world_zig_null 
+----------------------
+ Hello, pgzx!
+(1 row)
+
+SELECT hello_world_zig_datum(NULL);
+ hello_world_zig_datum 
+-----------------------
+ 
+(1 row)
+
+SELECT hello_world_zig_datum('pgzx');
+ hello_world_zig_datum 
+-----------------------
+ Hello, pgzx!
+(1 row)
+
+SELECT hello_world_anon(NULL);
+ hello_world_anon 
+------------------
+ Hello World
+(1 row)
+
+SELECT hello_world_anon('pgzx');
+ hello_world_anon 
+------------------
+ Hello, pgzx!
+(1 row)
+
+SELECT hello_world_mod(NULL);
+ hello_world_mod 
+-----------------
+ Hello World
+(1 row)
+
+SELECT hello_world_mod('pgzx');
+ hello_world_mod 
+-----------------
+ Hello, pgzx!
+(1 row)
+
+SELECT hello_world_file(NULL);
+ hello_world_file 
+------------------
+ Hello World
+(1 row)
+
+SELECT hello_world_file('pgzx');
+ hello_world_file 
+------------------
+ Hello, pgzx!
+(1 row)
+
+DROP EXTENSION sqlfns;
diff --git a/examples/sqlfns/extension/sqlfns--0.1.sql b/examples/sqlfns/extension/sqlfns--0.1.sql
new file mode 100644
index 0000000..07b7c0c
--- /dev/null
+++ b/examples/sqlfns/extension/sqlfns--0.1.sql
@@ -0,0 +1,27 @@
+CREATE FUNCTION hello_world_c(name text) RETURNS text
+AS 'MODULE_PATHNAME'
+LANGUAGE C;
+
+CREATE FUNCTION hello_world_zig(name text) RETURNS text
+AS 'MODULE_PATHNAME'
+LANGUAGE C;
+
+CREATE FUNCTION hello_world_zig_null(name text) RETURNS text
+AS 'MODULE_PATHNAME'
+LANGUAGE C;
+
+CREATE FUNCTION hello_world_zig_datum(name text) RETURNS text
+AS 'MODULE_PATHNAME'
+LANGUAGE C;
+
+CREATE FUNCTION hello_world_anon(name text) RETURNS text
+AS 'MODULE_PATHNAME'
+LANGUAGE C;
+
+CREATE FUNCTION hello_world_mod(name text) RETURNS text
+AS 'MODULE_PATHNAME'
+LANGUAGE C;
+
+CREATE FUNCTION hello_world_file(name text) RETURNS text
+AS 'MODULE_PATHNAME'
+LANGUAGE C;
diff --git a/examples/sqlfns/extension/sqlfns.control b/examples/sqlfns/extension/sqlfns.control
new file mode 100644
index 0000000..7603962
--- /dev/null
+++ b/examples/sqlfns/extension/sqlfns.control
@@ -0,0 +1,6 @@
+comment = 'pgzx: SQL Functions test extension'
+default_version = '0.1'
+module_pathname = '$libdir/sqlfns'
+relocatable = false
+superuser = false
+schema = 'sqlfns'
diff --git a/examples/sqlfns/sql/sqlfns_test.sql b/examples/sqlfns/sql/sqlfns_test.sql
new file mode 100644
index 0000000..3e09359
--- /dev/null
+++ b/examples/sqlfns/sql/sqlfns_test.sql
@@ -0,0 +1,29 @@
+CREATE EXTENSION sqlfns;
+
+SET search_path TO sqlfns;
+
+SELECT hello_world_c(NULL);
+SELECT hello_world_c('pgzx');
+
+SELECT hello_world_zig(NULL);
+SELECT hello_world_zig('pgzx');
+
+SELECT hello_world_zig(NULL);
+SELECT hello_world_zig('pgzx');
+
+SELECT hello_world_zig_null(NULL);
+SELECT hello_world_zig_null('pgzx');
+
+SELECT hello_world_zig_datum(NULL);
+SELECT hello_world_zig_datum('pgzx');
+
+SELECT hello_world_anon(NULL);
+SELECT hello_world_anon('pgzx');
+
+SELECT hello_world_mod(NULL);
+SELECT hello_world_mod('pgzx');
+
+SELECT hello_world_file(NULL);
+SELECT hello_world_file('pgzx');
+
+DROP EXTENSION sqlfns;
diff --git a/examples/sqlfns/src/hello_world.zig b/examples/sqlfns/src/hello_world.zig
new file mode 100644
index 0000000..f5bec91
--- /dev/null
+++ b/examples/sqlfns/src/hello_world.zig
@@ -0,0 +1,9 @@
+const std = @import("std");
+const pgzx = @import("pgzx");
+
+pub fn hello_world_file(name: ?[:0]const u8) ![:0]const u8 {
+    return if (name) |n|
+        try std.fmt.allocPrintZ(pgzx.mem.PGCurrentContextAllocator, "Hello, {s}!", .{n})
+    else
+        "Hello World";
+}
diff --git a/examples/sqlfns/src/main.zig b/examples/sqlfns/src/main.zig
new file mode 100644
index 0000000..c2c22a0
--- /dev/null
+++ b/examples/sqlfns/src/main.zig
@@ -0,0 +1,151 @@
+// With this extension we want to show you how you can use pgzx to create
+// and export functions to PostgreSQL.
+
+// First we want to import some dependencies and declare this shared library as a postgres module via PG_MODULE_MAGIC.
+
+const std = @import("std");
+const pgzx = @import("pgzx");
+const pg = pgzx.c;
+
+comptime {
+    pgzx.PG_MODULE_MAGIC();
+}
+
+// Exorted functions with C calling convention
+// ===========================================
+
+// It is always possible to export a function by writing a C function directly.
+// The functions accepts the FunctionCallInfoData struct and must return a Datum and no Zig errors.
+//
+
+export fn pg_finfo_hello_world_c() callconv(.C) [*c]const pg.Pg_finfo_record {
+    return pgzx.fmgr.FunctionV1();
+}
+
+export fn hello_world_c(fcinfo: pg.FunctionCallInfo) callconv(.C) pg.Datum {
+    // When using the C interface we can not use any of the PG_RETURN or PG_GETARG macros directly.
+    //
+    // This function accepts a 'string' of type 'text' and returns a new string of type 'text'.
+    // We start by getting the first argument of the function call.
+    //
+    // The pgzx.fmgr and ppgzx.fmgr.args modules provide a set of functions to
+    // work with the FunctionCallInfoData struct.
+
+    const arg = pgzx.fmgr.args.mustGetArgNullable(fcinfo, 0) catch {
+        pgzx.elog.ErrorThrow(@src(), "missing argument", .{});
+        unreachable;
+    };
+
+    const message = if (arg.isnull) "Hello World" else blk: {
+        const name = pgzx.datum.getDatumTextSliceZ(arg.value) catch |e| {
+            pgzx.elog.throwAsPostgresError(@src(), e);
+            unreachable;
+        };
+
+        const allocator = pgzx.mem.PGCurrentContextAllocator;
+        const hello = std.fmt.allocPrintZ(allocator, "Hello, {s}!", .{name}) catch |e| {
+            pgzx.elog.throwAsPostgresError(@src(), e);
+            unreachable;
+        };
+        break :blk hello;
+    };
+
+    return pgzx.datum.sliceToDatumTextZ(message) catch |e| {
+        pgzx.elog.throwAsPostgresError(@src(), e);
+        unreachable;
+    };
+}
+
+// Use PG_FUNCTION_V1 to declare and export a zig function
+// =======================================================
+
+// Let's write the same function using the fmgr module to declare and export the module for us.
+//
+// Similar to extension written in C we use PG_FUNCTION_V1 to declare the function. This will produce a wrapper
+// also exporting our function to PostgreSQL. The wrapper checks the argument and return type of your function
+// and implements argument unpacking, return value packing and Zig error to PostgreSQL error conversion.
+
+comptime {
+    pgzx.PG_FUNCTION_V1("hello_world_zig", hello_world_zig);
+}
+
+fn hello_world_zig(name: ?[:0]const u8) ![:0]const u8 {
+    return if (name) |n|
+        try std.fmt.allocPrintZ(pgzx.mem.PGCurrentContextAllocator, "Hello, {s}!", .{n})
+    else
+        "Hello World";
+}
+
+// We can also write a variant that will return `NULL` when the argument is null. All we have to do is to return an optional value like so:
+
+comptime {
+    pgzx.PG_FUNCTION_V1("hello_world_zig_null", hello_world_zig_null);
+}
+
+fn hello_world_zig_null(name: ?[:0]const u8) !?[:0]const u8 {
+    return if (name) |n|
+        try std.fmt.allocPrintZ(pgzx.mem.PGCurrentContextAllocator, "Hello, {s}!", .{n})
+    else
+        null;
+}
+
+// It is also possible to capture the FunctionCallInfo as an argument to your function. You want to do this if
+// you want to use the configured collation, check the context node, or
+// manually parse arguments manually.
+//
+// In this example we will accept and return a Datum. This requires to mark a
+// NULL return in the FunctionCallInfo.
+
+comptime {
+    pgzx.PG_FUNCTION_V1("hello_world_zig_datum", hello_world_zig_datum);
+}
+
+fn hello_world_zig_datum(fcinfo: pg.FunctionCallInfo, arg: ?pg.Datum) !pg.Datum {
+    if (arg == null) {
+        fcinfo.*.isnull = true;
+        return 0;
+    }
+
+    const name = try pgzx.datum.getDatumTextSliceZ(arg.?);
+    const message = try std.fmt.allocPrintZ(pgzx.mem.PGCurrentContextAllocator, "Hello, {s}!", .{name});
+    return try pgzx.datum.sliceToDatumTextZ(message);
+}
+
+// PG_EXPORT: Export all public functions from a struct
+// ====================================================
+
+// Exporting a number of functions can become a bit tedious over time.
+// The `PG_EXPORT` function can be used to automatically export all public functions from a struct.
+
+// Here we export a function from an anonymous struct.
+comptime {
+    pgzx.PG_EXPORT(struct {
+        pub fn hello_world_anon(name: ?[:0]const u8) ![:0]const u8 {
+            return if (name) |n|
+                try std.fmt.allocPrintZ(pgzx.mem.PGCurrentContextAllocator, "Hello, {s}!", .{n})
+            else
+                "Hello World";
+        }
+    });
+}
+
+// Or a names struct:
+
+comptime {
+    pgzx.PG_EXPORT(mod_hello_world);
+}
+
+const mod_hello_world = struct {
+    pub fn hello_world_mod(name: ?[:0]const u8) ![:0]const u8 {
+        return if (name) |n|
+            try std.fmt.allocPrintZ(pgzx.mem.PGCurrentContextAllocator, "Hello, {s}!", .{n})
+        else
+            "Hello World";
+    }
+};
+
+// In Zig when importing a file, the file is treated as a struct. Let's try this:
+
+comptime {
+    pgzx.PG_EXPORT(@import("hello_world.zig"));
+}

From 370a3ccf9085b72596e7c271bae32381e4c38a0a Mon Sep 17 00:00:00 2001
From: urso <steffen@xata.io>
Date: Thu, 11 Jul 2024 12:46:17 +0200
Subject: [PATCH 4/4] typo

---
 examples/sqlfns/src/main.zig | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/examples/sqlfns/src/main.zig b/examples/sqlfns/src/main.zig
index c2c22a0..d1d7d9b 100644
--- a/examples/sqlfns/src/main.zig
+++ b/examples/sqlfns/src/main.zig
@@ -90,11 +90,14 @@ fn hello_world_zig_null(name: ?[:0]const u8) !?[:0]const u8 {
 }
 
 // It is also possible to capture the FunctionCallInfo as an argument to your function. You want to do this if
-// you want to use the configured collation, check the context node, or
-// manually parse arguments manually.
+// you want to use the string collation, check the context node, or
+// parse arguments manually.
 //
-// In this example we will accept and return a Datum. This requires to mark a
+// In this example we will also accept and return a Datum. This requires us to mark a
 // NULL return in the FunctionCallInfo.
+//
+// Note: alternatively we could returns a `?pg.Datum` and just return `null`.
+// We use the FunctionCallInfo to demonstrate access how to access them.
 
 comptime {
     pgzx.PG_FUNCTION_V1("hello_world_zig_datum", hello_world_zig_datum);
@@ -115,9 +118,11 @@ fn hello_world_zig_datum(fcinfo: pg.FunctionCallInfo, arg: ?pg.Datum) !pg.Datum
 // ====================================================
 
 // Exporting a number of functions can become a bit tedious over time.
-// The `PG_EXPORT` function can be used to automatically export all public functions from a struct.
+// The `PG_EXPORT` function can be used to automatically export all public
+// functions from a struct.
 
 // Here we export a function from an anonymous struct.
+
 comptime {
     pgzx.PG_EXPORT(struct {
         pub fn hello_world_anon(name: ?[:0]const u8) ![:0]const u8 {
@@ -129,7 +134,7 @@ comptime {
     });
 }
 
-// Or a names struct:
+// We can also export functions from a named struct:
 
 comptime {
     pgzx.PG_EXPORT(mod_hello_world);
@@ -144,7 +149,7 @@ const mod_hello_world = struct {
     }
 };
 
-// In Zig when importing a file, the file is treated as a struct. Let's try this:
+// In Zig when importing a file, the file is also treated as a struct. Let's try this:
 
 comptime {
     pgzx.PG_EXPORT(@import("hello_world.zig"));