From b3767a2796864a73f8a0227247c26c41b384360a Mon Sep 17 00:00:00 2001
From: Kyle Conroy <kyle@sqlc.dev>
Date: Mon, 23 Oct 2023 15:04:28 -0700
Subject: [PATCH 1/3] docs: Document database-backed query analyzer

---
 docs/howto/generate.md                       | 68 ++++++++++++++++++++
 docs/howto/upload.md                         |  4 +-
 docs/howto/vet.md                            | 10 +--
 docs/index.rst                               | 20 ++++--
 docs/reference/config.md                     | 15 ++++-
 docs/tutorials/getting-started-postgresql.md |  2 +-
 6 files changed, 105 insertions(+), 14 deletions(-)
 create mode 100644 docs/howto/generate.md

diff --git a/docs/howto/generate.md b/docs/howto/generate.md
new file mode 100644
index 0000000000..cb30a31adf
--- /dev/null
+++ b/docs/howto/generate.md
@@ -0,0 +1,68 @@
+# `generate` - Generating code
+
+`sqlc generate` parses SQL, analyzes the results, and outputs code. Your schema and queries are stored in separate SQL files. The paths to these files live in a `sqlc.yaml` configuration file.
+
+```yaml
+version: "2"
+sql:
+  - engine: "postgresql"
+    queries: "query.sql"
+    schema: "schema.sql"
+    gen:
+      go:
+        package: "tutorial"
+        out: "tutorial"
+        sql_package: "pgx/v5"
+```
+
+We've written extensive docs on [retrieving](select.md), [inserting](insert.md),
+[updating](update.md), and [deleting](delete.md) rows. 
+
+By default, the analysis is run using our built-in query engine. While fast, this engine can't handle some complex queries and type-inference.
+
+## Using a managed database
+
+```{note}
+Managed databases are powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
+```
+
+By opting in to [managed database](managed-databases.md), the default analysis is enhanced with metadata from a running database connection. Type inference is improved and query analysis succeeds on a larger set of queries.
+
+```yaml
+version: "2"
+cloud:
+  project: "<PROJECT_ID>"
+sql:
+  - engine: "postgresql"
+    queries: "query.sql"
+    schema: "schema.sql"
+    database:
+      managed: true
+    gen:
+      go:
+        package: "tutorial"
+        out: "tutorial"
+        sql_package: "pgx/v5"
+```
+
+The database analyzer currently supports PostgreSQL, with [MySQL](https://github.com/sqlc-dev/sqlc/issues/2902) and [SQLite](https://github.com/sqlc-dev/sqlc/issues/2903)
+support planned in the future.
+
+## Using a database connection
+
+The analyzer uses the configured [database](../reference/config.md#database), whether it be managed or a connection URI.
+
+```yaml
+version: "2"
+sql:
+  - engine: "postgresql"
+    queries: "query.sql"
+    schema: "schema.sql"
+    database:
+      uri: "postgres://postgres:${PG_PASSWORD}@localhost:5432/postgres"
+    gen:
+      go:
+        package: "tutorial"
+        out: "tutorial"
+        sql_package: "pgx/v5"
+```
diff --git a/docs/howto/upload.md b/docs/howto/upload.md
index e432df4556..0cf5d4a47c 100644
--- a/docs/howto/upload.md
+++ b/docs/howto/upload.md
@@ -1,4 +1,4 @@
-# Uploading projects
+# `upload` - Uploading projects
 
 ```{note}
 Project uploads are powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
@@ -18,7 +18,7 @@ After creating a project, add the project ID to your sqlc configuration file.
 ```yaml
 version: "2"
 cloud:
-  project: "<PROJECT-ID>"
+  project: "<PROJECT_ID>"
 ```
 
 You'll also need to create an auth token and make it available via the
diff --git a/docs/howto/vet.md b/docs/howto/vet.md
index 72c537cddd..3bf2048459 100644
--- a/docs/howto/vet.md
+++ b/docs/howto/vet.md
@@ -1,4 +1,4 @@
-# Linting queries
+# `vet` - Linting queries
 
 *Added in v1.19.0*
 
@@ -43,7 +43,7 @@ message Parameter
 ```
 
 In addition to this basic information, when you have a PostgreSQL or MySQL
-[database connection configured](../reference/config.html#database)
+[database connection configured](../reference/config.md#database)
 each CEL expression has access to the output from running `EXPLAIN ...` on your query
 via the `postgresql.explain` and `mysql.explain` variables.
 This output is quite complex and depends on the structure of your query but sqlc attempts
@@ -95,7 +95,7 @@ rules:
 The CEL expression environment has two variables containing `EXPLAIN ...` output,
 `postgresql.explain` and `mysql.explain`. `sqlc` only populates the variable associated with
 your configured database engine, and only when you have a
-[database connection configured](../reference/config.html#database).
+[database connection configured](../reference/config.md#database).
 
 For the `postgresql` engine, `sqlc` runs
 
@@ -171,7 +171,7 @@ before running `sqlc vet` with rules that depend on `EXPLAIN ...` output.
 
 ### sqlc/db-prepare
 
-When a [database](../reference/config.html#database) connection is configured, you can
+When a [database](../reference/config.md#database) connection is configured, you can
 run the built-in `sqlc/db-prepare` rule. This rule will attempt to prepare
 each of your queries against the connected database and report any failures.
 
@@ -215,7 +215,7 @@ example](https://github.com/sqlc-dev/sqlc/blob/main/examples/authors/sqlc.yaml).
 ## Running lint rules
 
 When you add the name of a defined rule to the rules list
-for a [sql package](https://docs.sqlc.dev/en/stable/reference/config.html#sql),
+for a [sql package](../reference/config.md#sql),
 `sqlc vet` will evaluate that rule against every query in the package.
 
 In the example below, two rules are defined but only one is enabled.
diff --git a/docs/index.rst b/docs/index.rst
index 566d87d84f..3bd9e87567 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,6 +36,15 @@ code ever again.
    tutorials/getting-started-postgresql.md
    tutorials/getting-started-sqlite.md
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Commands
+   :hidden:
+
+   howto/generate.md
+   howto/vet.md
+   howto/upload.md
+
 .. toctree::
    :maxdepth: 2
    :caption: How-to Guides
@@ -57,10 +66,12 @@ code ever again.
    howto/overrides.md
    howto/rename.md
 
-   howto/vet.md
+.. toctree::
+   :maxdepth: 3
+   :caption: sqlc Cloud
+   :hidden:
+
    howto/managed-databases.md
-   howto/ci-cd.md
-   howto/upload.md
 
 .. toctree::
    :maxdepth: 3
@@ -81,7 +92,8 @@ code ever again.
    :caption: Conceptual Guides
    :hidden:
 
+   howto/ci-cd.md
    guides/using-go-and-pgx.rst
-   guides/development.md
    guides/plugins.md
+   guides/development.md
    guides/privacy.md
diff --git a/docs/reference/config.md b/docs/reference/config.md
index e90747cbb0..b0f1c68005 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -16,7 +16,7 @@ sql:
       package: "authors"
       out: "postgresql"
   database:
-    uri: "postgresql://postgres:postgres@localhost:5432/postgres"
+    managed: true
   rules:
     - sqlc/db-prepare
 - schema: "mysql/schema.sql"
@@ -46,6 +46,8 @@ Each mapping in the `sql` collection has the following keys:
   - A mapping to configure database connections. See [database](#database) for the supported keys.
 - `rules`:
   - A collection of rule names to run via `sqlc vet`. See [rules](#rules) for configuration options.
+- `analzyer`:
+  - A mapping to configure query analysis. See [analyzer](#analyzer) for the supported keys.
 - `strict_function_checks`
   - If true, return an error if a called SQL function does not exist. Defaults to `false`.
 
@@ -85,6 +87,8 @@ sql:
 
 The `database` mapping supports the following keys:
 
+- `managed`:
+  - If true, connect to a [managed database](../howto/managed-databases.md).
 - `uri`:
   - Database connection URI
 
@@ -105,7 +109,14 @@ sql:
       package: authors
       out: postgresql
 ```
- 
+
+### analyzer
+
+The `analyzer` mapping supports the following keys:
+
+- `database`:
+  -  If false, do not use the configured database for query analysis. Defaults to `true`.
+  
 ### gen
 
 The `gen` mapping supports the following keys:
diff --git a/docs/tutorials/getting-started-postgresql.md b/docs/tutorials/getting-started-postgresql.md
index d4898d203b..371783860c 100644
--- a/docs/tutorials/getting-started-postgresql.md
+++ b/docs/tutorials/getting-started-postgresql.md
@@ -32,7 +32,7 @@ following contents:
 ```yaml
 version: "2"
 cloud:
-  project: "<your project id>"
+  project: "<PROJECT_ID>"
 sql:
   - engine: "postgresql"
     queries: "query.sql"

From 9fc7ec2504b055f160669248c0640345f95c40be Mon Sep 17 00:00:00 2001
From: Andrew Benton <andrew@sqlc.dev>
Date: Mon, 23 Oct 2023 16:16:27 -0700
Subject: [PATCH 2/3] a second pass

---
 docs/howto/generate.md   | 32 +++++++++++++++++++++-----------
 docs/howto/vet.md        | 25 +++++++++++++++++++------
 docs/reference/config.md |  4 +++-
 3 files changed, 43 insertions(+), 18 deletions(-)

diff --git a/docs/howto/generate.md b/docs/howto/generate.md
index cb30a31adf..d3ca6de3c7 100644
--- a/docs/howto/generate.md
+++ b/docs/howto/generate.md
@@ -18,15 +18,23 @@ sql:
 We've written extensive docs on [retrieving](select.md), [inserting](insert.md),
 [updating](update.md), and [deleting](delete.md) rows. 
 
-By default, the analysis is run using our built-in query engine. While fast, this engine can't handle some complex queries and type-inference.
+By default, sqlc runs its analysis using a built-in query analysis engine. While fast, this engine can't handle some complex queries and type-inference.
 
-## Using a managed database
+You can configure sqlc to use a database connection for enhanced analysis using metadata from that database.
+
+The database-backed analyzer currently supports PostgreSQL, with [MySQL](https://github.com/sqlc-dev/sqlc/issues/2902) and [SQLite](https://github.com/sqlc-dev/sqlc/issues/2903)
+support planned in the future.
+
+## Enhanced analysis with managed databases
 
 ```{note}
 Managed databases are powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
 ```
 
-By opting in to [managed database](managed-databases.md), the default analysis is enhanced with metadata from a running database connection. Type inference is improved and query analysis succeeds on a larger set of queries.
+With [managed databases](managed-databases.md) configured, `generate` will automatically create a hosted ephemeral database with your
+schema and use that database to improve its query analysis. And sqlc will cache its analysis locally
+on a per-query basis to speed up future `generate` runs. This saves you the trouble of running and maintaining a database with
+an up-to-date schema. Here's a minimal working configuration:
 
 ```yaml
 version: "2"
@@ -40,17 +48,18 @@ sql:
       managed: true
     gen:
       go:
-        package: "tutorial"
-        out: "tutorial"
+        out: "db"
         sql_package: "pgx/v5"
 ```
 
-The database analyzer currently supports PostgreSQL, with [MySQL](https://github.com/sqlc-dev/sqlc/issues/2902) and [SQLite](https://github.com/sqlc-dev/sqlc/issues/2903)
-support planned in the future.
+## Enhanced analysis using your own database
 
-## Using a database connection
+You can opt-in to database-backed analysis using your own database, by providing a `uri` in your sqlc
+[database](../reference/config.md#database) configuration.
 
-The analyzer uses the configured [database](../reference/config.md#database), whether it be managed or a connection URI.
+The `uri` string can contain references to environment variables using the `${...}`
+syntax. In the following example, the connection string will have the value of
+the `PG_PASSWORD` environment variable set as its password.
 
 ```yaml
 version: "2"
@@ -62,7 +71,8 @@ sql:
       uri: "postgres://postgres:${PG_PASSWORD}@localhost:5432/postgres"
     gen:
       go:
-        package: "tutorial"
-        out: "tutorial"
+        out: "db"
         sql_package: "pgx/v5"
 ```
+
+Databases configured with a `uri` must have an up-to-date schema for query analysis to work correctly, and `sqlc` does not apply schema migrations your database.
diff --git a/docs/howto/vet.md b/docs/howto/vet.md
index 3bf2048459..ff6ff3ceb0 100644
--- a/docs/howto/vet.md
+++ b/docs/howto/vet.md
@@ -163,9 +163,14 @@ rules:
   rule: "!has(postgresql.explain)" # A dummy rule to trigger explain
 ```
 
-Please note that `sqlc` does not manage or migrate your database. Use your
-migration tool of choice to create the necessary database tables and objects
-before running `sqlc vet` with rules that depend on `EXPLAIN ...` output.
+Please note that databases configured with a `uri` must have an up-to-date
+schema for `vet` to work correctly, and `sqlc` does not apply schema migrations
+to your database. Use your migration tool of choice to create the necessary
+tables and objects before running `sqlc vet` with rules that depend on
+`EXPLAIN ...` output.
+
+Alternatively, configure [managed databases](managed-databases.md) to have
+`sqlc` create hosted ephemeral databases with the correct schema automatically.
 
 ## Built-in rules
 
@@ -178,7 +183,7 @@ each of your queries against the connected database and report any failures.
 ```yaml
 version: 2
 sql:
-  - schema: "query.sql"
+  - schema: "schema.sql"
     queries: "query.sql"
     engine: "postgresql"
     gen:
@@ -191,12 +196,20 @@ sql:
       - sqlc/db-prepare
 ```
 
-Databases configured with a `uri` must have an up-to-date schema, and `sqlc` does not apply schema migrations your database. You can configure [managed databases](managed-databases.md) instead to have `sqlc` create and migrate databases automatically.
+Please note that databases configured with a `uri` must have an up-to-date
+schema for `vet` to work correctly, and `sqlc` does not apply schema migrations
+to your database. Use your migration tool of choice to create the necessary
+tables and objects before running `sqlc vet` with the `sqlc/db-prepare` rule.
+
+Alternatively, configure [managed databases](managed-databases.md) to have
+`sqlc` create hosted ephemeral databases with the correct schema automatically.
 
 ```yaml
 version: 2
+cloud:
+  project: "<PROJECT_ID>"
 sql:
-  - schema: "query.sql"
+  - schema: "schema.sql"
     queries: "query.sql"
     engine: "postgresql"
     gen:
diff --git a/docs/reference/config.md b/docs/reference/config.md
index b0f1c68005..e4e012679b 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -7,6 +7,8 @@ file must be in the directory where the `sqlc` command is run.
 
 ```yaml
 version: "2"
+cloud:
+  project: "<PROJECT_ID>"
 sql:
 - schema: "postgresql/schema.sql"
   queries: "postgresql/query.sql"
@@ -88,7 +90,7 @@ sql:
 The `database` mapping supports the following keys:
 
 - `managed`:
-  - If true, connect to a [managed database](../howto/managed-databases.md).
+  - If true, connect to a [managed database](../howto/managed-databases.md). Defaults to `false`.
 - `uri`:
   - Database connection URI
 

From 520076f2b257d45920b310af60bff5072b8d7d0d Mon Sep 17 00:00:00 2001
From: Andrew Benton <andrew@sqlc.dev>
Date: Mon, 23 Oct 2023 16:18:44 -0700
Subject: [PATCH 3/3] minor update to generate

---
 docs/howto/generate.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/howto/generate.md b/docs/howto/generate.md
index d3ca6de3c7..447343ac98 100644
--- a/docs/howto/generate.md
+++ b/docs/howto/generate.md
@@ -75,4 +75,5 @@ sql:
         sql_package: "pgx/v5"
 ```
 
-Databases configured with a `uri` must have an up-to-date schema for query analysis to work correctly, and `sqlc` does not apply schema migrations your database.
+Databases configured with a `uri` must have an up-to-date schema for query analysis to work correctly, and `sqlc` does not apply schema migrations your database. Use your migration tool of choice to create the necessary
+tables and objects before running `sqlc generate`.