Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: some v1.19.0 release copyediting #2409

Merged
merged 2 commits into from
Jul 6, 2023
Merged

docs: some v1.19.0 release copyediting #2409

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
85ac58b
docs: some v1.19.0 release copyediting
andrewmbenton Jul 6, 2023
6aad449
Update changelog.md
kyleconroy Jul 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 17 additions & 13 deletions docs/howto/ci-cd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 @@
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
Expand Down
30 changes: 15 additions & 15 deletions docs/howto/vet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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`.
25 changes: 13 additions & 12 deletions docs/reference/changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down
15 changes: 8 additions & 7 deletions docs/reference/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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
Expand Down