Skip to content

Commit 7ca892f

Browse files
kyleconroykyleconroy
authored
docs: Add release notes for v1.19.0 (#2406)
* docs: Add v1.19 release notes * docs: Add docs for sqlc vet
1 parent 5134490 commit 7ca892f

16 files changed

+562
-24
lines changed

‎docs/_static/customize.css

+14
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,17 @@
11
.wy-side-nav-search img {
22
padding: 5px 60px !important;
33
}
4+
5+
#banner {
6+
text-align: center;
7+
background: #2980b9;
8+
border: 1px solid rgb(52, 49, 49);
9+
color: #F0F0F4;
10+
padding: 10px;
11+
margin-bottom: 1.618em;
12+
}
13+
14+
#banner > div > a {
15+
color: #F0F0F4;
16+
text-decoration: underline;
17+
}

‎docs/_templates/breadcrumbs.html

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{% extends "!breadcrumbs.html" %}
2+
3+
{% block breadcrumbs %}
4+
{% if show_banner %}
5+
<header id="banner">
6+
<div>✨ We're now working full-time on sqlc. Read more <a href="https://sqlc.dev/posts/2023/07/06/working-on-sqlc-full-time">here</a>.</div>
7+
</header>
8+
{% endif %}
9+
{{ super() }}
10+
{% endblock %}

‎docs/_templates/layout.html

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{% extends "!layout.html" %}
2+
23
{% block extrahead %}
34
<script defer data-domain="docs.sqlc.dev" src="https://plausible.io/js/plausible.js"></script>
45
{{ super() }}
5-
{% endblock %}
6+
{% endblock %}

‎docs/conf.py

+6-2
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
# add these directories to sys.path here. If the directory is relative to the
1111
# documentation root, use os.path.abspath to make it absolute, like shown here.
1212
#
13-
# import os
13+
import os
1414
# import sys
1515
# sys.path.insert(0, os.path.abspath('.'))
1616
import sphinx_rtd_theme
@@ -22,7 +22,7 @@
2222
author = 'Kyle Conroy'
2323

2424
# The full version, including alpha/beta/rc tags
25-
release = '1.18.0'
25+
release = '1.19.0'
2626

2727

2828
# -- General configuration ---------------------------------------------------
@@ -61,6 +61,10 @@
6161
'logo_only': True,
6262
}
6363

64+
html_context = {
65+
'show_banner': 'SHOW_LAUNCH_BANNER' in os.environ,
66+
}
67+
6468
def setup(app):
6569
app.add_css_file('customize.css')
6670

‎docs/guides/plugins.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Authoring plugins
22

3-
To use plugins, you must be using [Version 2](../reference/config.html) of
3+
To use plugins, you must be using [Version 2](../reference/config.md) of
44
the configuration file. The top-level `plugins` array defines the available
55
plugins.
66

‎docs/howto/ci-cd.md

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Suggested CI/CD setup
2+
3+
If your project has more than a single developer, we suggest running `sqlc` as
4+
part of your CI/CD pipeline. The two commands you'll want to run are `diff` and `vet`
5+
6+
`sqlc diff` ensures that code is up to date. New developers to a project may
7+
forget to run `sqlc generate`. They also might edit generated code. `diff` will
8+
catch both scenarios.
9+
10+
```diff
11+
% sqlc-dev diff
12+
--- a/postgresql/query.sql.go
13+
+++ b/postgresql/query.sql.go
14+
@@ -55,7 +55,7 @@
15+
16+
const listAuthors = `-- name: ListAuthors :many
17+
SELECT id, name, bio FROM authors
18+
-ORDER BY name
19+
+ORDER BY bio
20+
`
21+
```
22+
23+
`sqlc vet` runs a set of lint checks against your SQL queries. These checks are
24+
helpful in catching anti-patterns before they make it into production. Please
25+
see the [vet](vet.md) documentation for a complete guide on adding checks to your
26+
project.
27+
28+
## General setup
29+
30+
Install `sqlc` using the [suggested instructions](../overview/install).
31+
32+
Create two steps in your pipelines, one for `sqlc diff`and one for `sqlc vet`.
33+
34+
## GitHub Actions
35+
36+
We provide the [setup-sqlc](https://github.com/marketplace/actions/setup-sqlc)
37+
GitHub Action to install `sqlc`. The action uses the built-in
38+
[tool-cache](https://github.com/actions/toolkit/blob/main/packages/tool-cache/README.md)
39+
to speed up the installation process.
40+
41+
The following workflow runs `sqlc diff` on every push.
42+
43+
```yaml
44+
name: sqlc
45+
on: [push]
46+
jobs:
47+
diff:
48+
runs-on: ubuntu-latest
49+
steps:
50+
- uses: actions/checkout@v3
51+
- uses: sqlc-dev/setup-sqlc@v3
52+
with:
53+
sqlc-version: '1.19.0'
54+
- run: sqlc diff
55+
```
56+
57+
We also encourage running [`sqlc vet`](vet.md). To get the most value out of
58+
`vet`, you'll want to set up a running database.
59+
60+
```yaml
61+
name: sqlc
62+
on: [push]
63+
jobs:
64+
vet:
65+
runs-on: ubuntu-latest
66+
services:
67+
postgres:
68+
image: "postgres:15"
69+
env:
70+
POSTGRES_DB: postgres
71+
POSTGRES_PASSWORD: postgres
72+
POSTGRES_USER: postgres
73+
ports:
74+
- 5432:5432
75+
# needed because the postgres container does not provide a healthcheck
76+
options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
77+
env:
78+
PG_PORT: ${{ job.services.postgres.ports['5432'] }}
79+
80+
steps:
81+
- uses: actions/checkout@v3
82+
- uses: sqlc-dev/setup-sqlc@v3
83+
with:
84+
sqlc-version: '1.19.0'
85+
# Connect and migrate your database here. This is an example which runs
86+
# commands from a `schema.sql` file.
87+
- run: psql -h localhost -U postgres -p $PG_PORT -d postgres -f schema.sql
88+
env:
89+
PGPASSWORD: postgres
90+
- run: sqlc vet
91+
```

‎docs/howto/vet.md

+112
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Linting queries
2+
3+
*Added in v1.19.0*
4+
5+
`sqlc vet` runs queries through a set of lint rules.
6+
7+
Rules are defined in the `sqlc` [configuration](../reference/config) file. They consist
8+
of a name, message, and an expression. If the expression evaluates to `true`, an
9+
error is reported. These expressions are evaluated using
10+
[cel-go](https://github.com/google/cel-go).
11+
12+
Each expression has access to a query object, which is defined as the following
13+
struct:
14+
15+
```proto
16+
message Config
17+
{
18+
string version = 1;
19+
string engine = 2 ;
20+
repeated string schema = 3;
21+
repeated string queries = 4;
22+
}
23+
24+
message Query
25+
{
26+
// SQL body
27+
string sql = 1;
28+
// Name of the query
29+
string name = 2;
30+
// One of :many, :one, :exec, etc.
31+
string cmd = 3;
32+
// Query parameters, if any
33+
repeated Parameter params = 4;
34+
}
35+
36+
37+
message Parameter
38+
{
39+
int32 number = 1;
40+
}
41+
```
42+
43+
This struct may be expanded in the future to include more query information.
44+
We may also add information from a running database, such as the result from
45+
`EXPLAIN`.
46+
47+
While these examples are simplistic, they give you an idea on what types of
48+
rules you can write.
49+
50+
```yaml
51+
version: 2
52+
sql:
53+
- schema: "query.sql"
54+
queries: "query.sql"
55+
engine: "postgresql"
56+
gen:
57+
go:
58+
package: "authors"
59+
out: "db"
60+
rules:
61+
- no-pg
62+
- no-delete
63+
- only-one-param
64+
- no-exec
65+
rules:
66+
- name: no-pg
67+
message: "invalid engine: postgresql"
68+
rule: |
69+
config.engine == "postgresql"
70+
- name: no-delete
71+
message: "don't use delete statements"
72+
rule: |
73+
query.sql.contains("DELETE")
74+
- name: only-one-param
75+
message: "too many parameters"
76+
rule: |
77+
query.params.size() > 1
78+
- name: no-exec
79+
message: "don't use exec"
80+
rule: |
81+
query.cmd == "exec"
82+
```
83+
84+
## Built-in rules
85+
86+
### sqlc/db-prepare
87+
88+
When a [database](../reference/config.html#database) in configured, the `sqlc/db-preapre`
89+
rule will attempt to prepare each of your queries against the connected
90+
database. Any failures will be reported to standard error.
91+
92+
```yaml
93+
version: 2
94+
sql:
95+
- schema: "query.sql"
96+
queries: "query.sql"
97+
engine: "postgresql"
98+
gen:
99+
go:
100+
package: "authors"
101+
out: "db"
102+
database:
103+
uri: "postgresql://postgres:password@localhost:5432/postgres"
104+
rules:
105+
- sqlc/db-prepare
106+
```
107+
108+
To see this in action, check out the [authors
109+
example](https://github.com/kyleconroy/sqlc/blob/main/examples/authors/sqlc.yaml).
110+
111+
Please note that `sqlc` does not manage or migrate the database. Use your
112+
migration tool of choice to create the necessary database tables and objects.

‎docs/index.rst

+2
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ code ever again.
5454
howto/ddl.md
5555
howto/structs.md
5656

57+
howto/vet.md
58+
howto/ci-cd.md
5759
howto/upload.md
5860

5961
.. toctree::

‎docs/overview/install.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -48,10 +48,10 @@ docker run --rm -v "%cd%:/src" -w /src kjconroy/sqlc generate
4848

4949
## Downloads
5050

51-
Get pre-built binaries for *v1.18.0*:
51+
Get pre-built binaries for *v1.19.0*:
5252

53-
- [Linux](https://github.com/kyleconroy/sqlc/releases/download/v1.18.0/sqlc_1.18.0_linux_amd64.tar.gz)
54-
- [macOS](https://github.com/kyleconroy/sqlc/releases/download/v1.18.0/sqlc_1.18.0_darwin_amd64.zip)
55-
- [Windows (MySQL only)](https://github.com/kyleconroy/sqlc/releases/download/v1.18.0/sqlc_1.18.0_windows_amd64.zip)
53+
- [Linux](https://github.com/kyleconroy/sqlc/releases/download/v1.19.0/sqlc_1.19.0_linux_amd64.tar.gz)
54+
- [macOS](https://github.com/kyleconroy/sqlc/releases/download/v1.19.0/sqlc_1.19.0_darwin_amd64.zip)
55+
- [Windows (MySQL only)](https://github.com/kyleconroy/sqlc/releases/download/v1.19.0/sqlc_1.19.0_windows_amd64.zip)
5656

5757
See [downloads.sqlc.dev](https://downloads.sqlc.dev/) for older versions.

0 commit comments

Comments
 (0)