From 3fe89b8062caada827d9241329ce6800af3f55f1 Mon Sep 17 00:00:00 2001
From: Andrew Benton <andrew@sqlc.dev>
Date: Fri, 3 Nov 2023 10:35:59 -0700
Subject: [PATCH] docs: Update README to explain building from source and
 migrating

---
 README.md | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 135 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 79bdc17..e449a4a 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,12 @@
-## Usage
+# sqlc-gen-go
 
 > [!IMPORTANT]  
 > This repository is read-only. It contains a working Go codegen plugin extracted from https://github.com/sqlc-dev/sqlc which you can fork and modify to meet your needs.
 
+See [Building from source](#building-from-source) and [Migrating from sqlc's built-in Go codegen](#migrating-from-sqlcs-built-in-go-codegen) if you want to use a modified fork in your project.
+
+## Usage
+
 ```yaml
 version: '2'
 plugins:
@@ -21,3 +25,133 @@ sql:
       package: db
       sql_package: pgx/v5
 ```
+
+## Building from source
+
+Assuming you have the Go toolchain set up, from the project root you can simply `make all`.
+
+```sh
+make all
+```
+
+This will produce a standalone binary and a WASM blob in the `bin` directory.
+They don't depend on each other, they're just two different plugin styles. You can
+use either with sqlc, but we recommend WASM and all of the configuration examples
+here assume you're using a WASM plugin.
+
+To use a local WASM build with sqlc, just update your configuration with a `file://`
+URL pointing at the WASM blob in your `bin` directory:
+
+```yaml
+plugins:
+- name: golang
+  wasm:
+    url: file:///path/to/bin/sqlc-gen-go.wasm
+    sha256: ""
+```
+
+As-of sqlc v1.24.0 the `sha256` is optional, but without it sqlc won't cache your
+module internally which will impact performance.
+
+## Migrating from sqlc's built-in Go codegen
+
+We’ve worked hard to make switching to sqlc-gen-go as seamless as possible. Let’s say you’re generating Go code today using a sqlc.yaml configuration that looks something like this:
+
+```yaml
+version: 2
+sql:
+- schema: "query.sql"
+  queries: "query.sql"
+  engine: "postgresql"
+  gen:
+    go:
+      package: "db"
+      out: "db"
+      emit_json_tags: true
+      emit_pointers_for_null_types: true
+      query_parameter_limit: 5
+      overrides:
+      - column: "authors.id"
+        go_type: "your/package.SomeType"
+      rename:
+        foo: "bar"
+```
+
+To use the sqlc-gen-go WASM plugin for Go codegen, your config will instead look something like this:
+
+```yaml
+version: 2
+plugins:
+- name: golang
+  wasm:
+    url: "https://downloads.sqlc.dev/plugin/sqlc-gen-go_1.0.0.wasm"
+    sha256: "dbe302a0208afd31118fffcc268bd39b295655dfa9e3f385d2f4413544cfbed1"
+sql:
+- schema: "query.sql"
+  queries: "query.sql"
+  engine: "postgresql"
+  codegen:
+  - plugin: golang
+    out: "db"
+    options:
+      package: "db"
+      emit_json_tags: true
+      emit_pointers_for_null_types: true
+      query_parameter_limit: 5
+      overrides:
+      - column: "authors.id"
+        go_type: "your/package.SomeType"
+      rename:
+        foo: "bar"
+```
+
+The differences are:
+* An additional top-level `plugins` list with an entry for the Go codegen WASM plugin. If you’ve built the plugin from source you’ll want to use a `file://` URL. The `sha256` field is required, but will be optional in the upcoming sqlc v1.24.0 release.
+* Within the `sql` block, rather than `gen` with `go` nested beneath you’ll have a `codegen` list with an entry referencing the plugin name from the top-level `plugins` list. All options from the current `go` configuration block move as-is into the `options` block within `codegen`. The only special case is `out`, which moves up a level into the `codegen` configuration itself.
+
+### Global overrides and renames
+
+If you have global overrides or renames configured, you’ll need to move those to the new top-level `options` field. Replace the existing `go` field name with the name you gave your plugin in the `plugins` list. We’ve used `"golang"` in this example.
+
+If your existing configuration looks like this:
+
+```yaml
+version: "2"
+overrides:
+  go:
+    rename:
+      id: "Identifier"
+    overrides:
+    - db_type: "timestamptz"
+      nullable: true
+      engine: "postgresql"
+      go_type:
+        import: "gopkg.in/guregu/null.v4"
+        package: "null"
+        type: "Time"
+...
+```
+
+Then your updated configuration would look something like this:
+
+```yaml
+version: "2"
+plugins:
+- name: golang
+  wasm:
+    url: "https://downloads.sqlc.dev/plugin/sqlc-gen-go_1.0.0.wasm"
+    sha256: "dbe302a0208afd31118fffcc268bd39b295655dfa9e3f385d2f4413544cfbed1"
+options:
+  golang:
+    rename:
+      id: "Identifier"
+    overrides:
+    - db_type: "timestamptz"
+      nullable: true
+      engine: "postgresql"
+      go_type:
+        import: "gopkg.in/guregu/null.v4"
+        package: "null"
+        type: "Time"
+...
+```
\ No newline at end of file