docs: some v1.19.0 release copyediting (#2409)

* docs: some v1.19.0 release copyediting

* Update changelog.md

---------

Co-authored-by: Kyle Conroy <kyle@sqlc.dev>

Author: andrewmbenton

docs/howto/ci-cd.md

@@ -1,14 +1,15 @@
-# Suggested CI/CD setup
+# Using sqlc in CI/CD
 
 If your project has more than a single developer, we suggest running `sqlc` as
-part of your CI/CD pipeline. The two commands you'll want to run are `diff` and `vet`
+part of your CI/CD pipeline. The two subcommands you'll want to run are `diff` and `vet`.
 
-`sqlc diff` ensures that code is up to date. New developers to a project may
-forget to run `sqlc generate`. They also might edit generated code. `diff` will
-catch both scenarios.
+`sqlc diff` ensures that your generated code is up to date. New developers to a project may
+forget to run `sqlc generate` after adding a query or updating a schema. They also might
+edit generated code. `sqlc diff` will catch both errors by comparing the expected output
+from `sqlc generate` to what's on disk.
 
 ```diff
-% sqlc-dev diff
+% sqlc diff
 --- a/postgresql/query.sql.go
 +++ b/postgresql/query.sql.go
 @@ -55,7 +55,7 @@
@@ -20,16 +21,16 @@ catch both scenarios.
  `
 ```
 
-`sqlc vet` runs a set of lint checks against your SQL queries. These checks are
+`sqlc vet` runs a set of lint rules against your SQL queries. These rules are
 helpful in catching anti-patterns before they make it into production. Please
-see the [vet](vet.md) documentation for a complete guide on adding checks to your
-project.
+see the [vet](vet.md) documentation for a complete guide to adding lint rules
+for your project.
 
 ## General setup
 
 Install `sqlc` using the [suggested instructions](../overview/install).
 
-Create two steps in your pipelines, one for `sqlc diff`and one for `sqlc vet`.
+Create two steps in your pipeline, one for `sqlc diff`and one for `sqlc vet`.
 
 ## GitHub Actions
 
@@ -38,7 +39,9 @@ GitHub Action to install `sqlc`. The action uses the built-in
 [tool-cache](https://github.com/actions/toolkit/blob/main/packages/tool-cache/README.md)
 to speed up the installation process.
 
-The following workflow runs `sqlc diff` on every push.
+## GitHub Workflows
+
+The following GitHub Workflow configuration runs `sqlc diff` on every push.
 
 ```yaml
 name: sqlc
@@ -54,8 +57,9 @@ jobs:
     - run: sqlc diff
 ```
 
-We also encourage running [`sqlc vet`](vet.md). To get the most value out of
-`vet`, you'll want to set up a running database.
+The following GitHub Workflow configuration runs [`sqlc vet`](vet.md) on every push.
+You can use `sqlc vet` without a database connection, but you'll need one if your
+`sqlc` configuration references the built-in `sqlc/db-prepare` lint rule.
 
 ```yaml
 name: sqlc

docs/howto/vet.md

@@ -5,12 +5,12 @@
 `sqlc vet` runs queries through a set of lint rules.
 
 Rules are defined in the `sqlc` [configuration](../reference/config) file. They consist
-of a name, message, and an expression. If the expression evaluates to `true`, an
-error is reported. These expressions are evaluated using
-[cel-go](https://github.com/google/cel-go).
+of a name, message, and a [Common Expression Language (CEL)](https://github.com/google/cel-spec)
+expression. Expressions are evaluated using [cel-go](https://github.com/google/cel-go).
+If an expression evaluates to `true`, an error is reported using the given message.
 
-Each expression has access to a query object, which is defined as the following
-struct:
+Each expression has access to variables from your sqlc configuration and queries,
+defined in the following struct:
 
 ```proto
 message Config
@@ -33,18 +33,17 @@ message Query
   repeated Parameter params = 4;
 }
 
-
 message Parameter
 {
   int32 number = 1;
 }
 ```
 
-This struct may be expanded in the future to include more query information.
-We may also add information from a running database, such as the result from
-`EXPLAIN`.
+This struct will likely expand in the future to include more query information.
+We may also add information returned from a running database, such as the result from
+`EXPLAIN ...`.
 
-While these examples are simplistic, they give you an idea on what types of
+While these examples are simplistic, they give you a flavor of the types of
 rules you can write.
 
 ```yaml
@@ -85,9 +84,9 @@ rules:
 
 ### sqlc/db-prepare
 
-When a [database](../reference/config.html#database) in configured, the `sqlc/db-preapre`
-rule will attempt to prepare each of your queries against the connected
-database. Any failures will be reported to standard error.
+When a [database](../reference/config.html#database) connection is configured, you can
+run the built-in `sqlc/db-preapre` rule. This rule will attempt to prepare
+each of your queries against the connected database and report any failures.
 
 ```yaml
 version: 2
@@ -108,5 +107,6 @@ sql:
 To see this in action, check out the [authors
 example](https://github.com/kyleconroy/sqlc/blob/main/examples/authors/sqlc.yaml).
 
-Please note that `sqlc` does not manage or migrate the database. Use your
-migration tool of choice to create the necessary database tables and objects.
+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`.

docs/reference/changelog.md

@@ -8,14 +8,14 @@ Released 2023-07-06
 
 #### sqlc vet
 
-[`vet`](../howto/vet.md) runs queries through a set of lint rules.
+[`sqlc vet`](../howto/vet.md) runs queries through a set of lint rules.
 
-Rules are defined in the `sqlc` [configuration](config.html#rules) file. They consist
-of a name, message, and an expression. If the expression evaluates to `true`, an
-error is reported. These expressions are evaluated using
-[cel-go](https://github.com/google/cel-go).
+Rules are defined in the `sqlc` [configuration](config.md) file. They consist
+of a name, message, and a [Common Expression Language (CEL)](https://github.com/google/cel-spec)
+expression. Expressions are evaluated using [cel-go](https://github.com/google/cel-go).
+If an expression evaluates to `true`, an error is reported using the given message.
 
-While these examples are simplistic, they give you an idea on what types of
+While these examples are simplistic, they give you a flavor of the types of
 rules you can write.
 
 ```yaml
@@ -55,12 +55,12 @@ rules:
 ##### Database connectivity
 
 `vet` also marks the first time that `sqlc` can connect to a live, running
-database server. This functionality will be expanded over time, but for now it
+database server. We'll expand this functionality over time, but for now it
 powers the `sqlc/db-prepare` built-in rule.
 
-When a [database](config.html#database) in configured, the `sqlc/db-preapre`
-rule will attempt to prepare each of your queries against the connected
-database. Any failures will be reported to standard error.
+When a [database](config.html#database) is configured, the
+`sqlc/db-preapre` rule will attempt to prepare each of your
+queries against the connected database and report any failures.
 
 ```yaml
 version: 2
@@ -81,8 +81,9 @@ sql:
 To see this in action, check out the [authors
 example](https://github.com/kyleconroy/sqlc/blob/main/examples/authors/sqlc.yaml).
 
-Please note that `sqlc` does not manage or migrate the database. Use your
-migration tool of choice to create the necessary database tables and objects.
+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`.
 
 #### Omit unused structs
 

docs/reference/config.md

@@ -43,7 +43,7 @@ Each mapping in the `sql` collection has the following keys:
 - `gen`:
   - A mapping to configure built-in code generators. See [gen](#gen) for the supported keys.
 - `database`:
-  - A mapping configure database connections. See [database](#database) for the supported 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.
 - `strict_function_checks`
@@ -86,11 +86,11 @@ sql:
 The `database` mapping supports the following keys:
 
 - `uri`:
-  - Database connection URL
+  - Database connection URI
 
-The URI can contain references to environment variables using the `${...}`
-syntax. In the following example, the connection string will set the value of
-the password to the value set in the `PG_PASSWORD` environment variable.
+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'
@@ -344,9 +344,10 @@ Each mapping in the `rules` collection has the following keys:
 - `rule`:
   - A [Common Expression Language (CEL)](https://github.com/google/cel-spec) expression. Required.
 - `message`:
-  - An optional message shown when the rule returns true.
+  - An optional message shown when this rule evaluates to `true`.
 
-See the [vet](../howto/vet.md) documentation for help writing custom rules.
+See the [vet](../howto/vet.md) documentation for a list of built-in rules and
+help writing custom rules.
 
 ```yaml
 version: 2