Skip to content

docs: Add managed dbs to CI/CD and vet guides #2896

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

Merged
kyleconroy merged 5 commits into from
Oct 21, 2023
Merged

docs: Add managed dbs to CI/CD and vet guides #2896

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d303a07
docs: Add managed dbs to CI/CD and vet guides
kyleconroy Oct 20, 2023
8af7fdb
Update docs/howto/ci-cd.md
kyleconroy Oct 20, 2023
fd4748b
Update docs/howto/ci-cd.md
kyleconroy Oct 20, 2023
9942bae
Update docs/howto/ci-cd.md
kyleconroy Oct 20, 2023
41187f5
Update docs/howto/vet.md
kyleconroy Oct 20, 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
56 changes: 42 additions & 14 deletions docs/howto/ci-cd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# 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 subcommands you'll want to run are `diff` and `vet`.
part of your CI/CD pipeline. The three subcommands you'll want to run are `diff`, `vet` and `upload`

`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.
`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 diff
Expand All @@ -26,11 +26,15 @@ helpful in catching anti-patterns before they make it into production. Please
see the [vet](vet.md) documentation for a complete guide to adding lint rules
for your project.

`sqlc upload` pushs your database schema and queries to sqlc Cloud. Once
Comment thread
kyleconroy marked this conversation as resolved.
Outdated
uploaded, we ensure that future releases of sqlc do not break your code. Learn
more about uploading projects [here](upload.md)

## General setup

Install `sqlc` using the [suggested instructions](../overview/install).

Create two steps in your pipeline, one for `sqlc diff`and one for `sqlc vet`.
Create two steps in your pipeline, one for `sqlc diff`and one for `sqlc vet`. Run `sqlc upload` after merge on your `main` branch.
Comment thread
kyleconroy marked this conversation as resolved.
Outdated

## GitHub Actions

Expand All @@ -39,10 +43,6 @@ 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.

## GitHub Workflows

We suggest running `diff`, `vet` and `upload` as part of your workflow.

### diff

The following GitHub Workflow configuration runs `sqlc diff` on every push.
Expand All @@ -63,7 +63,7 @@ jobs:

### vet

The following GitHub Workflow configuration runs [`sqlc vet`](vet.md) on every push.
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.

Expand Down Expand Up @@ -100,10 +100,38 @@ jobs:
- run: sqlc vet
```

#### Managed databases

```{note}
Managed databases are powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
```

If you're using [managed databases](managed-databases.md), the `services` block
in the previous workflow isn't required.

```yaml
name: sqlc
on: [push]
jobs:
vet:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: sqlc-dev/setup-sqlc@v3
with:
sqlc-version: '1.22.0'
- run: sqlc vet
Copy link
Copy Markdown
Collaborator

@andrewmbenton andrewmbenton Oct 20, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we need the env here for SQLC_AUTH_TOKEN right?

```

### upload

The following GitHub Workflow configuration runs [`sqlc upload`](upload.md) on
every push to `main`.
```{note}
Project uploads are powered by [sqlc Cloud](https://dashboard.sqlc.dev). Sign up for [free](https://dashboard.sqlc.dev) today.
```

The following GitHub Workflow configuration runs `sqlc upload`(upload.md) on
Comment thread
kyleconroy marked this conversation as resolved.
Outdated
every push to `main`. Create an auth token via the
[dashboard](https://dashboard.sqlc.dev).

```yaml
name: sqlc
Expand All @@ -120,4 +148,4 @@ jobs:
- run: sqlc upload
env:
SQLC_AUTH_TOKEN: ${{ secrets.SQLC_AUTH_TOKEN }}
```
```
37 changes: 26 additions & 11 deletions docs/howto/vet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,16 @@

`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 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`, `sqlc vet` will report an error using the given message.
Rules are defined in the `sqlc` [configuration](../reference/config) 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`, `sqlc vet` will report an error using the given message.

## Defining lint rules

Each lint rule's CEL expression has access to information from your sqlc configuration and queries
via variables defined in the following proto messages.
Each lint rule's CEL expression has access to information from your sqlc
configuration and queries via variables defined in the following proto messages.

```proto
message Config
Expand Down Expand Up @@ -190,13 +191,27 @@ sql:
- sqlc/db-prepare
```

When connecting to a database via URI, `sqlc` does not migrate your database. By switching to [managed databases](managed-databases.md), sqlc will create and migrate databases automatically.
Comment thread
kyleconroy marked this conversation as resolved.
Outdated

```yaml
version: 2
sql:
Copy link
Copy Markdown
Collaborator

@andrewmbenton andrewmbenton Oct 20, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
sql:
cloud:
project: <your project id>
sql:

- schema: "query.sql"
queries: "query.sql"
engine: "postgresql"
gen:
go:
package: "authors"
out: "db"
database:
managed: true
rules:
- sqlc/db-prepare
```

To see this in action, check out the [authors
example](https://github.com/sqlc-dev/sqlc/blob/main/examples/authors/sqlc.yaml).

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 the `sqlc/db-prepare` rule.

## Running lint rules

When you add the name of a defined rule to the rules list
Expand Down Expand Up @@ -238,4 +253,4 @@ For any query, you can tell `sqlc vet` not to evaluate lint rules using the
/* @sqlc-vet-disable */
SELECT * FROM authors
WHERE id = ? LIMIT 1;
```
```