snapshot of https://github.com/sqlc-dev/sqlc.git (main, 2026-09-16; blobs > 131072B omitted)

docs/guides/development.md

@@ -0,0 +1,61 @@
+# Developing sqlc
+
+## Building
+
+For local development, install `sqlc` under an alias. We suggest `sqlc-dev`.
+
+```
+go build -o ~/go/bin/sqlc-dev ./cmd/sqlc
+```
+
+Install `sqlc-gen-json` to avoid test failure.
+
+```
+go build -o ~/go/bin/sqlc-gen-json ./cmd/sqlc-gen-json
+```
+
+## Running Tests
+
+```
+go test ./...
+```
+
+To run the tests in the examples folder, use the `examples` tag.
+
+```
+go test --tags=examples ./...
+```
+
+These tests require locally-running database instances. Run these databases
+using [Docker Compose](https://docs.docker.com/compose/).
+
+```
+docker compose up -d
+```
+
+The tests use the following environment variables to connect to the
+database
+
+### For PostgreSQL
+
+```
+Variable     Default Value
+-------------------------
+PG_HOST      127.0.0.1
+PG_PORT      5432
+PG_USER      postgres
+PG_PASSWORD  mysecretpassword
+PG_DATABASE  dinotest
+```
+
+### For MySQL
+
+```
+Variable     Default Value
+-------------------------
+MYSQL_HOST      127.0.0.1
+MYSQL_PORT      3306
+MYSQL_USER      root
+MYSQL_ROOT_PASSWORD  mysecretpassword
+MYSQL_DATABASE  dinotest
+```

docs/guides/migrating-off-hosted-managed-databases.md

@@ -0,0 +1,71 @@
+# Migrating off hosted managed databases
+ 
+Starting in sqlc 1.27.0, [managed databases](../howto/managed-databases.md) will require a database server URI in the configuration file.
+
+This guide walks you through migrating to a locally running database server.
+
+## Run a database server locally
+
+There are many options for running a database server locally, but this guide
+will use [Docker Compose](https://docs.docker.com/compose/), as it can support
+both MySQL and PostgreSQL.
+
+If you're using macOS and PostgreSQL, [Postgres.app](https://postgresapp.com/) is also a good option.
+
+For MySQL, create a `docker-compose.yml` file with the following contents:
+
+```yaml
+version: "3.8"
+services:
+  mysql:
+    image: "mysql/mysql-server:8.0"
+    ports:
+      - "3306:3306"
+    restart: always
+    environment:
+      MYSQL_DATABASE: dinotest
+      MYSQL_ROOT_PASSWORD: mysecretpassword
+      MYSQL_ROOT_HOST: '%'
+```
+
+For PostgreSQL, create a `docker-compose.yml` file with the following contents:
+
+```yaml
+version: "3.8"
+services:
+  postgresql:
+    image: "postgres:16"
+    ports:
+      - "5432:5432"
+    restart: always
+    environment:
+      POSTGRES_DB: postgres
+      POSTGRES_PASSWORD: mysecretpassword
+      POSTGRES_USER: postgres
+```
+
+```sh
+docker compose up -d
+```
+
+## Upgrade sqlc
+
+You must be running sqlc v1.31.1 or greater to have access to the `servers`
+configuration.
+
+## Add servers to configuration
+
+```diff
+version: '2'
+cloud:
+  project: '<PROJECT_ID>'
++ servers:
++ - name: mysql
++   uri: mysql://localhost:3306
++ - name: postgres
++   uri: postgres://localhost:5432/postgres?sslmode=disable
+```
+
+## Re-generate the code
+
+Run `sqlc generate`. A database with the `sqlc_managed_` prefix will be automatically created and used for query analysis. 

docs/guides/migrating-to-sqlc-gen-kotlin.md

@@ -0,0 +1,119 @@
+# Migrating to sqlc-gen-kotlin
+ 
+Starting in sqlc 1.16.0, built-in Kotlin support has been deprecated. It will
+be fully removed in 1.17.0 in favor of sqlc-gen-kotlin.
+
+This guide will walk you through migrating to the [sqlc-gen-kotlin](https://github.com/sqlc-dev/sqlc-gen-kotlin) plugin,
+which involves three steps.
+
+1. Add the sqlc-gen-kotlin plugin
+2. Migrate each package
+3. Re-generate the code
+
+## Add the sqlc-gen-kotlin plugin
+
+In your configuration file, add a `plugins` array if you don't have one
+already. Add the following configuration for the plugin:
+
+```json
+{
+  "version": "2",
+  "plugins": [
+    {
+      "name": "kt",
+      "wasm": {
+        "url": "https://downloads.sqlc.dev/plugin/sqlc-gen-kotlin_1.0.0.wasm",
+        "sha256": "7620dc5d462de41fdc90e2011232c842117b416c98fd5c163d27c5738431a45c"
+      }
+    }
+  ]
+}
+```
+
+```yaml
+version: "2"
+plugins:
+- name: "kt"
+  wasm:
+    url: "https://downloads.sqlc.dev/plugin/sqlc-gen-kotlin_1.0.0.wasm"
+    sha256: "7620dc5d462de41fdc90e2011232c842117b416c98fd5c163d27c5738431a45c"
+```
+
+## Migrate each package
+
+Your package configuration should currently looks something like this for JSON.
+
+```json
+  "sql": [
+    {
+      "schema": "schema.sql",
+      "queries": "query.sql",
+      "engine": "postgresql",
+      "gen": {
+        "kotlin": {
+          "out": "src/main/kotlin/com/example/foo",
+          "package": "com.example.foo"
+        }
+      }
+    }
+  ]
+```
+
+Or this if you're using YAML.
+
+```yaml
+  sql:
+  - schema: "schema.sql"
+    queries: "query.sql"
+    engine: "postgresql"
+    gen:
+      kotlin:
+        out: "src/main/kotlin/com/example/foo"
+        package: "com.example.foo"
+```
+
+To use the plugin, you'll need to replace the `gen` mapping with the `codegen`
+collection. Add the `plugin` field, setting it to `kt`. All fields other than
+`out` need to be moved into the `options` mapping.
+
+After you're done, it should look like this for JSON.
+
+```json
+  "sql": [
+    {
+      "schema": "schema.sql",
+      "queries": "query.sql",
+      "engine": "postgresql",
+      "codegen": [
+        {
+          "out": "src/main/kotlin/com/example/foo",
+          "plugin": "kt",
+          "options": {
+            "package": "com.example.foo"
+          }
+        }
+      ]
+    }
+  ]
+```
+
+Or this for YAML.
+
+```yaml
+  sql:
+  - schema: "schema.sql"
+    queries: "query.sql"
+    engine: "postgresql"
+    codegen:
+    - plugin: "kt"
+      out: "src/main/kotlin/com/example/foo"
+      options:
+        package: "com.example.foo"
+```
+
+## Re-generate the code
+
+Run `sqlc generate`. The plugin will produce the same output, so you shouldn't
+see any changes. The first time `sqlc generate` is run, the plugin must be
+downloaded and compiled, resulting in a slightly longer runtime. Subsequent
+`generate` calls will be fast.

docs/guides/migrating-to-sqlc-gen-python.md

@@ -0,0 +1,131 @@
+# Migrating to sqlc-gen-python
+ 
+Starting in sqlc 1.16.0, built-in Python support has been deprecated. It will
+be fully removed in 1.17.0 in favor of sqlc-gen-python.
+
+This guide will walk you through migrating to the [sqlc-gen-python](https://github.com/sqlc-dev/sqlc-gen-python) plugin,
+which involves three steps.
+
+1. Add the sqlc-gen-python plugin
+2. Migrate each package
+3. Re-generate the code
+
+## Add the sqlc-gen-python plugin
+
+In your configuration file, add a `plugins` array if you don't have one
+already. Add the following configuration for the plugin:
+
+```json
+{
+  "version": "2",
+  "plugins": [
+    {
+      "name": "py",
+      "wasm": {
+        "url": "https://downloads.sqlc.dev/plugin/sqlc-gen-python_1.0.0.wasm",
+        "sha256": "aca83e1f59f8ffdc604774c2f6f9eb321a2b23e07dc83fc12289d25305fa065b"
+      }
+    }
+  ]
+}
+```
+
+```yaml
+version: "2"
+plugins:
+  - name: "py"
+    wasm:
+      url: "https://downloads.sqlc.dev/plugin/sqlc-gen-python_1.0.0.wasm"
+      sha256: "aca83e1f59f8ffdc604774c2f6f9eb321a2b23e07dc83fc12289d25305fa065b"
+```
+
+## Migrate each package
+
+Your package configuration should currently looks something like this for JSON.
+
+```json
+  "sql": [
+    {
+      "schema": "schema.sql",
+      "queries": "query.sql",
+      "engine": "postgresql",
+      "gen": {
+        "python": {
+          "out": "src",
+          "package": "foo",
+          "emit_sync_querier": true,
+          "emit_async_querier": true,
+          "query_parameter_limit": 5
+        }
+      }
+    }
+  ]
+```
+
+Or this if you're using YAML.
+
+```yaml
+  sql:
+  - schema: "schema.sql"
+    queries: "query.sql"
+    engine: "postgresql"
+    gen:
+      python:
+        out: "src"
+        package: "foo"
+        emit_sync_querier: true
+        emit_async_querier: true
+        query_parameter_limit: 5
+```
+
+To use the plugin, you'll need to replace the `gen` mapping with the `codegen`
+collection. Add the `plugin` field, setting it to `py`. All fields other than
+`out` need to be moved into the `options` mapping.
+
+After you're done, it should look like this for JSON.
+
+```json
+  "sql": [
+    {
+      "schema": "schema.sql",
+      "queries": "query.sql",
+      "engine": "postgresql",
+      "codegen": [
+        {
+          "out": "src",
+          "plugin": "py",
+          "options": {
+            "package": "authors",
+            "emit_sync_querier": true,
+            "emit_async_querier": true,
+            "query_parameter_limit": 5
+          }
+        }
+      ]
+    }
+  ]
+```
+
+Or this for YAML.
+
+```yaml
+  sql:
+  - schema: "schema.sql"
+    queries: "query.sql"
+    engine: "postgresql"
+    codegen:
+    - plugin: "py"
+      out: "src"
+      options:
+        package: "foo"
+        emit_sync_querier: true
+        emit_async_querier: true
+        query_parameter_limit: 5
+```
+
+## Re-generate the code
+
+Run `sqlc generate`. The plugin will produce the same output, so you shouldn't
+see any changes. The first time `sqlc generate` is run, the plugin must be
+downloaded and compiled, resulting in a slightly longer runtime. Subsequent
+`generate` calls will be fast.

docs/guides/plugins.md

@@ -0,0 +1,104 @@
+# Using plugins
+
+To use plugins, you must be using [Version 2](../reference/config.md#version-2) of
+the configuration file. The top-level `plugins` array defines the available
+plugins.
+
+## WASM plugins
+
+> WASM plugins are fully sandboxed; they do not have access to the network,
+> filesystem, or environment variables.
+
+In the `codegen` section, the `out` field dictates what directory will contain
+the new files. The `plugin` key must reference a plugin defined in the
+top-level `plugins` map. Any `options` are serialized to a string as JSON and
+passed on to the plugin itself.
+
+
+```yaml
+version: '2'
+plugins:
+- name: greeter
+  wasm:
+    url: https://github.com/sqlc-dev/sqlc-gen-greeter/releases/download/v0.1.0/sqlc-gen-greeter.wasm
+    sha256: afc486dac2068d741d7a4110146559d12a013fd0286f42a2fc7dcd802424ad07
+sql:
+- schema: schema.sql
+  queries: query.sql
+  engine: postgresql
+  codegen:
+  - out: gen
+    plugin: greeter
+    options:
+      lang: en-US
+```
+
+For a complete working example see the following files:
+- [sqlc-gen-greeter](https://github.com/sqlc-dev/sqlc-gen-greeter)
+  - A WASM plugin (written in Rust) that outputs a friendly message
+- [wasm_plugin_sqlc_gen_greeter](https://github.com/sqlc-dev/sqlc/tree/main/internal/endtoend/testdata/wasm_plugin_sqlc_gen_greeter)
+  - An example project showing how to use a WASM plugin
+
+## Process plugins
+
+> Process-based plugins offer minimal security. Only use plugins that you
+> trust. Better yet, only use plugins that you've written yourself.
+
+In the `codegen` section, the `out` field dictates what directory will contain
+the new files. The `plugin` key must reference a plugin defined in the
+top-level `plugins` map. Any `options` are serialized to a string as JSON and
+passed on to the plugin itself.
+
+```yaml
+version: '2'
+plugins:
+- name: jsonb
+  process:
+    cmd: sqlc-gen-json
+sql:
+- schema: schema.sql
+  queries: query.sql
+  engine: postgresql
+  codegen:
+  - out: gen
+    plugin: jsonb
+    options:
+      indent: "  "
+      filename: codegen.json
+```
+
+For a complete working example see the following files:
+- [sqlc-gen-json](https://github.com/sqlc-dev/sqlc/tree/main/cmd/sqlc-gen-json)
+  - A process-based plugin that serializes the CodeGenRequest to JSON
+- [process_plugin_sqlc_gen_json](https://github.com/sqlc-dev/sqlc/tree/main/internal/endtoend/testdata/process_plugin_sqlc_gen_json)
+  - An example project showing how to use a process-based plugin
+- [process_plugin_sqlc_gen_json](https://github.com/sqlc-dev/sqlc/tree/main/internal/endtoend/testdata/process_plugin_format_json/)
+  - An example project showing how to use a process-based plugin using json
+
+## Environment variables
+
+By default, plugins do not inherit access to environment variables. Instead,
+you can configure access on a per-variable basis. For example, if your plugin
+needs the `PATH` environment variable, add `PATH` to the `env` list in the
+`plugins` collection.
+
+```yaml
+version: '2'
+sql:
+- schema: schema.sql
+  queries: query.sql
+  engine: postgresql
+  codegen:
+  - out: gen
+    plugin: test
+plugins:
+- name: test
+  env:
+  - PATH
+  wasm:
+    url: https://github.com/sqlc-dev/sqlc-gen-test/releases/download/v0.1.0/sqlc-gen-test.wasm
+    sha256: 138220eae508d4b65a5a8cea555edd155eb2290daf576b7a8b96949acfeb3790
+```
+
+A variable named `SQLC_VERSION` is always included in the plugin's
+environment, set to the version of the `sqlc` executable invoking it.

docs/guides/privacy.md

@@ -0,0 +1,55 @@
+# Privacy and data collection
+
+These days, it feels like every piece of software is tracking you. From your
+browser, to your phone, to your terminal, programs collect as much data about
+you as possible and send it off to the cloud for analysis.
+
+We believe the best way to keep data safe is to never collect it in the first
+place.
+
+## Our Privacy Pledge
+
+The `sqlc` command line tool does not collect any information. It
+does not send crash reports to a third-party. It does not gather anonymous
+aggregate user behaviour analytics.
+
+No analytics. 
+No finger-printing.
+No tracking.
+
+Not now and not in the future.
+
+### Distribution Channels
+
+We distribute sqlc using popular package managers such as
+[Homebrew](https://brew.sh/) and [Snapcraft](https://snapcraft.io/). These
+package managers and their associated command-line tools do collect usage
+metrics.
+
+We use these services to make it easy to for users to install sqlc. There will
+always be an option to download sqlc from a stable URL.
+
+## Hosted Services
+
+We provide a few hosted services in addition to the sqlc command line tool.
+
+### sqlc.dev
+
+* Hosted on [GitHub Pages](https://pages.github.com/)
+* Analytics with [Plausible](https://plausible.io/privacy-focused-web-analytics)
+
+### docs.sqlc.dev
+
+* Hosted on [Read the Docs](https://readthedocs.org/)
+* Analytics with [Plausible](https://plausible.io/privacy-focused-web-analytics)
+
+### play.sqlc.dev
+
+* Hosted on [Heroku](https://heroku.com)
+* Playground data stored in [Google Cloud Storage](https://cloud.google.com/storage)
+  * Automatically deleted after 30 days
+
+### app.sqlc.dev / api.sqlc.dev
+
+* Hosted on [Heroku](https://heroku.com)
+* Error tracking and tracing with [Sentry](https://sentry.io)

docs/guides/using-go-and-pgx.md

@@ -0,0 +1,125 @@
+# Using Go and pgx
+
+> [!NOTE]
+> `pgx/v5` is supported starting from v1.18.0.
+
+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 maintenance mode.
+
+## Getting started
+
+To start generating code that uses pgx, set the `sql_package` field in
+your `sqlc.yaml` configuration file. Valid options are `pgx/v4` or
+`pgx/v5`
+
+```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 `query.sql` file.
+
+```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.
+
+```bash
+sqlc generate
+```
+
+## Generated code walkthrough
+
+The generated code is very similar to the code generated when using
+`lib/pq`. However, instead of using `database/sql`, the code uses
+pgx types directly.
+
+```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)
+}
+```
+
+> [!NOTE]
+> For production applications, consider using pgxpool for connection pooling:
+>
+> ```go
+> import (
+>     "github.com/jackc/pgx/v5/pgxpool"
+>     "example.com/sqlc-tutorial/db"
+> )
+>
+> func main() {
+>     pool, err := pgxpool.New(context.Background(), os.Getenv("DATABASE_URL"))
+>     if err != nil {
+>         fmt.Fprintf(os.Stderr, "Unable to create connection pool: %v\n", err)
+>         os.Exit(1)
+>     }
+>     defer pool.Close()
+>
+>     q := db.New(pool)
+>     // Use q the same way as with single connections
+> }
+> ```