From 6011d5642d95199d7319fa0a0e5960e9ac3128c2 Mon Sep 17 00:00:00 2001
From: Tom Payne <twpayne@gmail.com>
Date: Mon, 5 Feb 2024 18:02:46 +0100
Subject: [PATCH] docs: Add instructions for PostGIS/GEOS

---
 docs/reference/datatypes.md | 65 +++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/docs/reference/datatypes.md b/docs/reference/datatypes.md
index 4dfade11a5..bca076eaae 100644
--- a/docs/reference/datatypes.md
+++ b/docs/reference/datatypes.md
@@ -208,6 +208,71 @@ type Book struct {
 
 ### PostGIS
 
+#### Using `github.com/twpayne/go-geos` (pgx/v5 only)
+
+sqlc can be configured to use the [geos](https://github.com/twpayne/go-geos)
+package for working with PostGIS geometry types in [GEOS](https://libgeos.org/).
+
+There are three steps:
+
+1. Configure sqlc to use `*github.com/twpayne/go-geos.Geom` for geometry types.
+2. Call `github.com/twpayne/pgx-geos.Register` on each
+   `*github.com/jackc/pgx/v5.Conn`.
+3. Annotate your SQL with `::geometry` typecasts, if needed.
+
+```sql
+-- Multipolygons in British National Grid (epsg:27700)
+create table shapes(
+  id serial,
+  name varchar,
+  geom geometry(Multipolygon, 27700)
+);
+
+-- name: GetCentroids :many
+SELECT id, name, ST_Centriod(geom)::geometry FROM shapes;
+```
+
+```json
+{
+  "version": 2,
+  "gen": {
+    "go": {
+      "overrides": [
+        {
+          "db_type": "geometry",
+          "go_type": {
+            "import": "github.com/twpayne/go-geos",
+            "package": "geos",
+            "pointer": true,
+            "type": "Geom"
+          },
+          "nullable": true
+        }
+      ]
+    }
+  }
+}
+```
+
+```go
+import (
+    "github.com/twpayne/go-geos"
+    pgxgeos "github.com/twpayne/pgx-geos"
+)
+
+// ...
+
+config.AfterConnect = func(ctx context.Context, conn *pgx.Conn) error {
+    if err := pgxgeos.Register(ctx, conn, geos.NewContext()); err != nil {
+        return err
+    }
+    return nil
+}
+```
+
+
+#### Using `github.com/twpayne/go-geom`
+
 sqlc can be configured to use the [geom](https://github.com/twpayne/go-geom)
 package for working with PostGIS geometry types.