docs: Document database-backed query analyzer

sqlc-dev · kyleconroy · Oct 24, 2023 · Oct 23, 2023 · Oct 23, 2023 · Oct 23, 2023
commit b3767a2796864a73f8a0227247c26c41b384360a
diff --git a/docs/howto/generate.md 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
10000
: "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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -32,7 +32,7 @@ following contents:
 ```yaml
 version: "2"
 cloud:
-  project: "<your project id>"
+  project: "<PROJECT_ID>"
 sql:
   - engine: "postgresql"
     queries: "query.sql"