From 2baa0b6731f65f7cf8b8b408ff7447bf0324d592 Mon Sep 17 00:00:00 2001
From: Kyle Conroy <kyle@conroy.org>
Date: Wed, 29 Mar 2023 10:11:45 -0700
Subject: [PATCH] docs: Add first pass at pgx documentation

---
 docs/guides/using-go-and-pgx.rst | 113 +++++++++++++++++++++++++++++++
 docs/index.rst                   |   1 +
 2 files changed, 114 insertions(+)
 create mode 100644 docs/guides/using-go-and-pgx.rst

diff --git a/docs/guides/using-go-and-pgx.rst b/docs/guides/using-go-and-pgx.rst
new file mode 100644
index 0000000000..a4964a8bf7
--- /dev/null
+++ b/docs/guides/using-go-and-pgx.rst
@@ -0,0 +1,113 @@
+================
+Using Go and pgx
+================
+
+.. note::
+   Experimental support for :code:`pgx/v5` was added in v1.17.2. Full support will be
+   included in v1.18.0. Until then, you'll need to pass the :code:`--experimental`
+   flag to :code:`sqlc generate`.
+
+
+pgx is a pure Go driver and toolkit for PostgreSQL. It's become the default
+PostgreSQL package for many Gophers since lib/pq was put into maitience mode.
+
+^^^^^^^^^^^^^^^
+Getting started
+^^^^^^^^^^^^^^^
+
+To start generating code that uses pgx, set the :code:`sql_package` field in
+your :code:`sqlc.yaml` configuration file. Valid options are :code:`pgx/v4` or
+:code:`pgx/v5`
+
+.. code-block:: yaml
+
+    version: "2"
+    sql:
+      - engine: "postgresql"
+        queries: "query.sql"
+        schema: "query.sql"
+        gen:
+          go:
+            package: "db"
+            sql_package: "pgx/v5"
+            out: "db"
+
+If you don't have an existing sqlc project on hand, create a directory with the
+configuration file above and the following :code:`query.sql` file.
+
+.. code-block:: sql
+
+    CREATE TABLE authors (
+      id   BIGSERIAL PRIMARY KEY,
+      name text      NOT NULL,
+      bio  text
+    );
+
+    -- name: GetAuthor :one
+    SELECT * FROM authors
+    WHERE id = $1 LIMIT 1;
+    
+    -- name: ListAuthors :many
+    SELECT * FROM authors
+    ORDER BY name;
+    
+    -- name: CreateAuthor :one
+    INSERT INTO authors (
+      name, bio
+    ) VALUES (
+      $1, $2
+    )
+    RETURNING *;
+    
+    -- name: DeleteAuthor :exec
+    DELETE FROM authors
+    WHERE id = $1;
+
+
+Generating the code will now give you pgx-compatible database access methods.
+
+.. code-block:: bash
+
+   sqlc generate --experimental
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Generated code walkthrough
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The generated code is very similar to the code generated when using
+:code:`lib/pq`. However, instead of using :code:`database/sql`, the code uses
+pgx types directly.
+
+.. code-block:: go
+
+    package main
+    
+    import (
+    	"context"
+    	"fmt"
+    	"os"
+    
+    	"github.com/jackc/pgx/v5"
+        
+    	"example.com/sqlc-tutorial/db"
+    )
+    
+    func main() {
+    	// urlExample := "postgres://username:password@localhost:5432/database_name"
+    	conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))
+    	if err != nil {
+    		fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
+    		os.Exit(1)
+    	}
+    	defer conn.Close(context.Background())
+
+    	q := db.New(conn)
+    
+    	author, err := q.GetAuthor(context.Background(), 1)
+    	if err != nil {
+    		fmt.Fprintf(os.Stderr, "GetAuthor failed: %v\n", err)
+    		os.Exit(1)
+    	}
+    
+    	fmt.Println(author.Name)
+    }
diff --git a/docs/index.rst b/docs/index.rst
index 6c6b40a910..7f6c7db3b8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -74,6 +74,7 @@ code ever again.
    :caption: Conceptual Guides
    :hidden:
 
+   guides/using-go-and-pgx.rst
    guides/development.md
    guides/plugins.md
    guides/privacy.md