Use sqlc to implement PostgreSQL driver.

Makefile

@@ -3,8 +3,14 @@
 # to run them locally when making specific optimisations.
 CI_RUN_BENCHMARKS ?= false
 
+GENERATED_FILES += driver/sql/postgres/pgjournal/internal/xdb/queries.sql.go
+GENERATED_FILES += driver/sql/postgres/pgkv/internal/xdb/queries.sql.go
+
 -include .makefiles/Makefile
 -include .makefiles/pkg/go/v1/Makefile
 
 .makefiles/%:
 	@curl -sfL https://makefiles.dev/v1 | bash /dev/stdin "$@"
+
+%.sql.go: %.sql
+	sqlc generate --file $(@D)/sqlc.yaml

driver/sql/postgres/internal/commonschema/doc.go

@@ -0,0 +1,3 @@
+// Package commonschema contains common PostgreSQL schema elements used by
+// multiple persistencekit drivers.
+package commonschema

driver/sql/postgres/pgkv/schema.go → driver/sql/postgres/internal/commonschema/schema.go

@@ -1,4 +1,4 @@
-package pgkv
+package commonschema
 
 import (
 	"context"
@@ -11,17 +11,28 @@ import (
 //go:embed schema.sql
 var schema string
 
-// createSchema creates the PostgreSQL schema elements required by [BinaryStore].
-func createSchema(
+// Create creates the PostgreSQL schema elements required by
+// all PostgreSQL-based stores.
+func Create(
 	ctx context.Context,
 	db *sql.DB,
+	additional ...string,
 ) error {
 	return pgerror.Retry(
 		ctx,
 		db,
 		func(tx *sql.Tx) error {
-			_, err := tx.ExecContext(ctx, schema)
-			return err
+			if _, err := tx.ExecContext(ctx, schema); err != nil {
+				return err
+			}
+
+			for _, q := range additional {
+				if _, err := tx.ExecContext(ctx, q); err != nil {
+					return err
+				}
+			}
+
+			return nil
 		},
 		// Even though we use IF NOT EXISTS in the DDL, we still need to handle
 		// conflicts due to a data race bug in PostgreSQL.

driver/sql/postgres/internal/commonschema/schema.sql

@@ -0,0 +1,19 @@
+CREATE SCHEMA IF NOT EXISTS persistencekit;
+
+-- see `commonschema.Uint64` type
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1
+        FROM information_schema.domains
+        WHERE domain_schema = 'persistencekit'
+        AND domain_name = 'uint64'
+    ) THEN
+
+        CREATE DOMAIN persistencekit.uint64
+        AS BIGINT
+        DEFAULT -1::BIGINT << 63;
+
+    END IF;
+END
+$$;

driver/sql/postgres/internal/commonschema/uint64.go

@@ -0,0 +1,30 @@
+package commonschema
+
+import (
+	"database/sql/driver"
+	"fmt"
+	"math"
+)
+
+// Uint64 is a uint64 that is represented as a SIGNED BIGINT (64-bit)
+// integer in PostgreSQL (which is PostgreSQL's largest integer type).
+//
+// The encoding preserves order, such that sorting on the encoded values will
+// produce the same order as sorting on the original unsigned values. This is
+// the only guarantee provided by this type.
+type Uint64 uint64
+
+// Scan implements [sql.Scanner].
+func (p *Uint64) Scan(src any) error {
+	if src, ok := src.(int64); ok {
+		*p = Uint64(uint64(src) + uint64(math.MaxInt64) + 1)
+		return nil
+	}
+
+	return fmt.Errorf("cannot scan %T into bigint.Unsigned", src)
+}
+
+// Value implements [driver.Valuer].
+func (p Uint64) Value() (driver.Value, error) {
+	return int64(p - (math.MaxInt64 + 1)), nil
+}

driver/sql/postgres/pgjournal/internal/xdb/doc.go

@@ -0,0 +1,2 @@
+// Package xdb contains the schema and queries for the journal store.
+package xdb

driver/sql/postgres/pgjournal/internal/xdb/queries.sql

@@ -0,0 +1,60 @@
+-- name: UpsertJournal :one
+INSERT INTO persistencekit.journal (
+    name
+) VALUES (
+    sqlc.arg('name')
+) ON CONFLICT (name) DO UPDATE SET
+    name = EXCLUDED.name
+RETURNING id;
+
+-- name: UpdateBegin :execrows
+UPDATE persistencekit.journal
+SET "begin" = sqlc.arg('begin')
+WHERE id = sqlc.arg('journal_id')
+AND "begin" < sqlc.arg('begin');
+
+-- name: IncrementEnd :execrows
+UPDATE persistencekit.journal
+SET "end" = "end" + 1
+WHERE id = sqlc.arg('journal_id')
+AND "end" = sqlc.arg('end');
+
+-- name: SelectBounds :one
+SELECT
+    "begin",
+    "end"
+FROM persistencekit.journal
+WHERE id = sqlc.arg('journal_id');
+
+-- name: SelectRecord :one
+SELECT
+    record
+FROM persistencekit.journal_record
+WHERE journal_id = sqlc.arg('journal_id')
+AND position = sqlc.arg('position');
+
+-- name: SelectRecords :many
+SELECT
+    position,
+    record
+FROM persistencekit.journal_record
+WHERE journal_id = sqlc.arg('journal_id')
+AND position >= sqlc.arg('position')
+ORDER BY position
+LIMIT 500;
+
+-- name: InsertRecord :exec
+INSERT INTO persistencekit.journal_record (
+    journal_id,
+    position,
+    record
+) VALUES (
+    sqlc.arg('journal_id'),
+    sqlc.arg('position'),
+    sqlc.arg('record')
+);
+
+-- name: DeleteRecords :exec
+DELETE FROM persistencekit.journal_record
+WHERE journal_id = sqlc.arg('journal_id')
+AND position < sqlc.arg('end');