Skip to content

feat(vet): Run rules against a managed database #2751

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 8 commits into from
Sep 22, 2023
Merged

feat(vet): Run rules against a managed database #2751

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0d8d73d
feat(vet): Support managed databases
kyleconroy Sep 21, 2023
8dfde57
feat(vet): Run rules against a managed database
kyleconroy Sep 21, 2023
c20dc5a
remove skip
kyleconroy Sep 21, 2023
e27afd3
fix read file error
kyleconroy Sep 21, 2023
e8812d8
Add managed to JSON schema
kyleconroy Sep 21, 2023
a3aa231
Use different hostname for region discovery
kyleconroy Sep 21, 2023
d12a8a6
Add first pass at docs
kyleconroy Sep 22, 2023
ffaf99e
docs: second pass at managed-databases.md
andrewmbenton Sep 22, 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
Prev Previous commit
docs: second pass at managed-databases.md
  • Loading branch information
@andrewmbenton
andrewmbenton committed Sep 22, 2023
commit ffaf99eb1db9291d53a81a3c6faf6205c7708290
35 changes: 20 additions & 15 deletions docs/howto/managed-databases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,24 @@
*Added in v1.22.0*

`sqlc` can create and maintain hosted databases for your project. These
databases can be used for linting queries. Right now, only PostgreSQL is
supported, with MySQL on the way.
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. Beyond linting queries, managed
databases can be created per test suite or even per test, providing a real,
isolated PostgreSQL database for a test run, no cleanup required.
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,
providing a real, isolated database for a test run. No cleanup required.

Interested in trying out managed databases? Sign up [here](https://docs.google.com/forms/d/e/1FAIpQLSdxoMzJ7rKkBpuez-KyBcPNyckYV-5iMR--FRB7WnhvAmEvKg/viewform) or send us an email
at <mailto:[email protected]>.

## Configuring managed databases

To configured a managed database, remove the `uri` key, replacing it with the
`managed` key set to `true`. Set the `project` key to your project ID, obtained
via the sqlc Dashboard.
To configure `sqlc` to use a managed database, 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 sqlc.dev Dashboard.

```yaml
version: '2'
Expand All @@ -33,19 +36,22 @@ sql:

## Authentication

You'll also need to create an access token and make it available via the
`SQLC_AUTH_TOKEN` environment variable.
`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 sqlc.dev Dashboard.

```shell
export SQLC_AUTH_TOKEN=sqlc_xxxxxxxx
```

## Linting queries

In managed mode, `sqlc vet` will create a database with the provided schema and
use that database when running lint rules. If you don't currently have any
rules, the [built-in sqlc/db-prepare] rule verifies each of your queries against
the database by creating a prepared statement.
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).

If you don't yet have any vet rules, the [built-in sqlc/db-prepare rule](vet.md#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:

```yaml
version: '2'
Expand All @@ -60,4 +66,3 @@ sql:
rules:
- sqlc/db-prepare
```