From 288072094c14ec492646fbe5253006a487fdfa20 Mon Sep 17 00:00:00 2001
From: Andrew Benton <andrew@sqlc.dev>
Date: Fri, 20 Oct 2023 15:04:21 -0700
Subject: [PATCH] docs: Update managed databases doc to discuss codegen

---
 docs/howto/managed-databases.md | 90 ++++++++++++++++++++++++++++-----
 docs/howto/rename.md            |  2 +-
 docs/howto/structs.md           |  2 +-
 docs/reference/config.md        |  6 +--
 4 files changed, 81 insertions(+), 19 deletions(-)

diff --git a/docs/howto/managed-databases.md b/docs/howto/managed-databases.md
index 87c301738f..5297bd925c 100644
--- a/docs/howto/managed-databases.md
+++ b/docs/howto/managed-databases.md
@@ -6,19 +6,24 @@ Managed databases are powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign
 
 *Added in v1.22.0*
 
-`sqlc` can create and maintain hosted databases for your project. These
-databases are immediately useful for linting queries with [`sqlc vet`](vet.md)
-if your lint rules require a connection to a running database. PostgreSQL
-support is available today, with MySQL on the way.
-
-This feature is under active development, and we're interested in supporting
-other use-cases. Beyond linting queries, you can use sqlc managed databases
-in your tests to quickly stand up a database per test suite or even per test,
+`sqlc` can create and maintain short-lived hosted databases for your project.
+These ephemeral databases are immediately useful for powering sqlc's
+database-connected query analyzer, an opt-in feature that improves upon sqlc's
+built-in query analysis engine. PostgreSQL support is available today, with
+MySQL on the way.
+
+Once configured, `sqlc` will also use managed databases when linting queries
+with [`sqlc vet`](vet.html) in cases where your lint rules require a connection
+to a running database.
+
+Managed databases are under active development, and we're interested in
+supporting other use-cases. Outside of sqlc itself, you can use our managed
+databases in your tests to quickly stand up a database per test suite or even per test,
 providing a real, isolated database for a test run. No cleanup required.
 
 ## Configuring managed databases
 
-To configure `sqlc` to use a managed database, remove the `uri` key from your
+To configure `sqlc` to use managed databases, remove the `uri` key from your
 `database` configuration and replace it with the `managed` key set to `true`.
 Set the `project` key in your `cloud` configuration to the value of your
 project ID, obtained via the [dashboard](https://dashboard.sqlc.dev).
@@ -35,7 +40,7 @@ sql:
     managed: true
 ```
 
-## Authentication
+### Authentication
 
 `sqlc` expects to find a valid auth token in the value of the `SQLC_AUTH_TOKEN`
 environment variable. You can create an auth token via the [dashboard](https://dashboard.sqlc.dev).
@@ -44,13 +49,38 @@ environment variable. You can create an auth token via the [dashboard](https://d
 export SQLC_AUTH_TOKEN=sqlc_xxxxxxxx
 ```
 
+## Improving codegen
+
+Without a database connection, sqlc does its best to parse, analyze and compile your queries just using
+the schema you pass it and what it knows about the various database engines it supports. In many cases
+this works just fine, but for more advanced queries sqlc might not have enough information to produce good code.
+
+With managed databases configured, `sqlc 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 codegen runs. Here's a minimal working configuration:
+
+```yaml
+version: '2'
+cloud:
+  project: '<PROJECT_ID>'
+sql:
+- schema: schema.sql
+  queries: query.sql
+  engine: postgresql
+  database:
+    managed: true
+  gen:
+    go:
+      out: "db"
+```
+
 ## Linting queries
 
-With managed databases configured, `sqlc vet` will create a database with your
-package's schema and use that database when running lint rules that require a
-database connection, e.g. any [rule relying on `EXPLAIN ...` output](vet.md#rules-using-explain-output).
+With managed databases configured, `sqlc vet` will automatically create a hosted ephemeral database with your
+schema and use that database when running lint rules that require a
+database connection, e.g. any [rule relying on `EXPLAIN ...` output](vet.html#rules-using-explain-output).
 
-If you don't yet have any vet rules, the [built-in sqlc/db-prepare rule](vet.md#sqlc-db-prepare)
+If you don't yet have any vet rules, the [built-in sqlc/db-prepare rule](vet.html#sqlc-db-prepare)
 is a good place to start. It prepares each of your queries against the database
 to ensure the query is valid. Here's a minimal working configuration:
 
@@ -67,3 +97,35 @@ sql:
   rules:
   - sqlc/db-prepare
 ```
+
+## With other tools
+
+With managed databases configured, `sqlc createdb` will create a hosted ephemeral database with your
+schema and write the database's connection URI as a string to standard output (stdout). This allows you to use
+ephemeral databases with other tools that understand database connection strings.
+
+In the simplest case, you can use psql to poke around:
+
+```shell
+psql $(sqlc createdb)
+```
+
+Or if you're tired of waiting for us to resolve https://github.com/sqlc-dev/sqlc/issues/296,
+you can create databases ad hoc to use with pgtyped:
+
+```shell
+DATABASE_URL=$(sqlc createdb) npx pgtyped -c config.json
+```
+
+Here's a minimal working configuration if all you need to use is `sqlc createdb`:
+
+```yaml
+version: '2'
+cloud:
+  project: '<PROJECT_ID>'
+sql:
+- schema: schema.sql
+  engine: postgresql
+  database:
+    managed: true
+```
\ No newline at end of file
diff --git a/docs/howto/rename.md b/docs/howto/rename.md
index f2d03e6cba..0085de4e05 100644
--- a/docs/howto/rename.md
+++ b/docs/howto/rename.md
@@ -84,4 +84,4 @@ type Writer struct {
 ## Limitations
 
 Rename mappings apply to an entire package. Therefore, a column named `foo` and
-a table name `foo` can't be renamed different values.
\ No newline at end of file
+a table name `foo` can't map to different rename values.
\ No newline at end of file
diff --git a/docs/howto/structs.md b/docs/howto/structs.md
index caec740830..c0b203df97 100644
--- a/docs/howto/structs.md
+++ b/docs/howto/structs.md
@@ -50,4 +50,4 @@ type Author struct {
 
 ## More control
 
-See the Type Overrides section of the Configuration File docs for fine-grained control over struct field types and tags.
+See the guide to [Overriding types](./overrides.md) for fine-grained control over struct field types and tags.
diff --git a/docs/reference/config.md b/docs/reference/config.md
index c0ba543503..e90747cbb0 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -173,9 +173,9 @@ The `gen` mapping supports the following keys:
 - `overrides`:
   - It is a collection of definitions that dictates which types are used to map a database types.
 
-##### `overrides`
+##### overrides
 
-See [Overriding types](../howto/overrides.md) for in-depth guide to using type overrides. Each mapping of the `overrides` collection has the following keys:
+See [Overriding types](../howto/overrides.md) for an in-depth guide to using type overrides. Each mapping of the `overrides` collection has the following keys:
 
 - `db_type`:
   - The PostgreSQL or MySQL type to override. Find the full list of supported types in [postgresql_type.go](https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/golang/postgresql_type.go#L12) or [mysql_type.go](https://github.com/sqlc-dev/sqlc/blob/main/internal/codegen/golang/mysql_type.go#L12). Note that for Postgres you must use the pg_catalog prefixed names where available. Can't be used if the `column` key is defined.
@@ -318,7 +318,7 @@ rules:
       query.cmd == "exec"
 ```
   
-### global overrides
+### Global overrides
 
 Sometimes, the same configuration must be done across various specifications of
 code generation.  Then a global definition for type overriding and field