docs: Add release notes for v1.19.0 (#2406)

* docs: Add v1.19 release notes
* docs: Add docs for sqlc vet

docs/_static/customize.css

@@ -1,3 +1,17 @@
 .wy-side-nav-search img {
   padding: 5px 60px !important;
 }
+
+#banner {
+  text-align: center;
+  background: #2980b9;
+  border: 1px solid rgb(52, 49, 49);
+  color: #F0F0F4;
+  padding: 10px;
+  margin-bottom: 1.618em;
+}
+
+#banner > div > a {
+  color: #F0F0F4;
+  text-decoration: underline;
+}

docs/_templates/breadcrumbs.html

@@ -0,0 +1,10 @@
+{% extends "!breadcrumbs.html" %}
+
+{% block breadcrumbs %}
+{% if show_banner %}
+<header id="banner">
+  <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>
+</header>
+{% endif %}
+{{ super() }}
+{% endblock %}

docs/_templates/layout.html

@@ -1,5 +1,6 @@
 {% extends "!layout.html" %}
+
 {% block extrahead %}
 <script defer data-domain="docs.sqlc.dev" src="https://plausible.io/js/plausible.js"></script>
 {{ super() }}
-{% endblock %}
+{% endblock %}

docs/conf.py

@@ -10,7 +10,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
+import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 import sphinx_rtd_theme
@@ -22,7 +22,7 @@
 author = 'Kyle Conroy'
 
 # The full version, including alpha/beta/rc tags
-release = '1.18.0'
+release = '1.19.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -61,6 +61,10 @@
     'logo_only': True,
 }
 
+html_context = {
+    'show_banner': 'SHOW_LAUNCH_BANNER' in os.environ,
+}
+
 def setup(app):
     app.add_css_file('customize.css')
 

docs/guides/plugins.md

@@ -1,6 +1,6 @@
 # Authoring plugins
 
-To use plugins, you must be using [Version 2](../reference/config.html) of
+To use plugins, you must be using [Version 2](../reference/config.md) of
 the configuration file. The top-level `plugins` array defines the available
 plugins.
 

docs/howto/ci-cd.md

@@ -0,0 +1,91 @@
+# Suggested CI/CD setup
+
+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`
+
+`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.
+
+```diff
+% sqlc-dev diff
+--- a/postgresql/query.sql.go
++++ b/postgresql/query.sql.go
+@@ -55,7 +55,7 @@
+
+ const listAuthors = `-- name: ListAuthors :many
+ SELECT id, name, bio FROM authors
+-ORDER BY name
++ORDER BY bio
+ `
+```
+
+`sqlc vet` runs a set of lint checks against your SQL queries. These checks 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.
+
+## 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`.
+
+## GitHub Actions
+
+We provide the [setup-sqlc](https://github.com/marketplace/actions/setup-sqlc)
+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.
+
+```yaml
+name: sqlc
+on: [push]
+jobs:
+  diff:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: sqlc-dev/setup-sqlc@v3
+      with:
+        sqlc-version: '1.19.0'
+    - 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.
+
+```yaml
+name: sqlc
+on: [push]
+jobs:
+  vet:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: "postgres:15"
+        env:
+          POSTGRES_DB: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_USER: postgres
+        ports:
+        - 5432:5432
+        # needed because the postgres container does not provide a healthcheck
+        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+    env:
+      PG_PORT: ${{ job.services.postgres.ports['5432'] }}
+
+    steps:
+    - uses: actions/checkout@v3
+    - uses: sqlc-dev/setup-sqlc@v3
+      with:
+        sqlc-version: '1.19.0'
+      # Connect and migrate your database here. This is an example which runs
+      # commands from a `schema.sql` file.
+    - run: psql -h localhost -U postgres -p $PG_PORT -d postgres -f schema.sql
+      env:
+        PGPASSWORD: postgres
+    - run: sqlc vet
+```

docs/howto/vet.md

@@ -0,0 +1,112 @@
+# Linting queries
+
+*Added in v1.19.0*
+
+`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).
+
+Each expression has access to a query object, which is defined as the following
+struct:
+
+```proto
+message Config
+{
+  string version = 1;
+  string engine = 2 ;
+  repeated string schema = 3;
+  repeated string queries = 4;
+}
+
+message Query
+{
+  // SQL body
+  string sql = 1;
+  // Name of the query
+  string name = 2; 
+  // One of :many, :one, :exec, etc.
+  string cmd = 3;
+  // Query parameters, if any
+  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`.
+
+While these examples are simplistic, they give you an idea on what types of
+rules you can write.
+
+```yaml
+version: 2
+sql:
+  - schema: "query.sql"
+    queries: "query.sql"
+    engine: "postgresql"
+    gen:
+      go:
+        package: "authors"
+        out: "db"
+    rules:
+      - no-pg
+      - no-delete
+      - only-one-param
+      - no-exec
+rules:
+  - name: no-pg
+    message: "invalid engine: postgresql"
+    rule: |
+      config.engine == "postgresql"
+  - name: no-delete
+    message: "don't use delete statements"
+    rule: |
+      query.sql.contains("DELETE")
+  - name: only-one-param
+    message: "too many parameters"
+    rule: |
+      query.params.size() > 1
+  - name: no-exec
+    message: "don't use exec"
+    rule: |
+      query.cmd == "exec"
+```
+
+## Built-in 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.
+
+```yaml
+version: 2
+sql:
+  - schema: "query.sql"
+    queries: "query.sql"
+    engine: "postgresql"
+    gen:
+      go:
+        package: "authors"
+        out: "db"
+    database:
+      uri: "postgresql://postgres:password@localhost:5432/postgres"
+    rules:
+      - sqlc/db-prepare
+```
+
+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.

docs/index.rst

@@ -54,6 +54,8 @@ code ever again.
    howto/ddl.md
    howto/structs.md
 
+   howto/vet.md
+   howto/ci-cd.md
    howto/upload.md
 
 .. toctree::

docs/overview/install.md

@@ -48,10 +48,10 @@ docker run --rm -v "%cd%:/src" -w /src kjconroy/sqlc generate
 
 ## Downloads
 
-Get pre-built binaries for *v1.18.0*:
+Get pre-built binaries for *v1.19.0*:
 
-- [Linux](https://github.com/kyleconroy/sqlc/releases/download/v1.18.0/sqlc_1.18.0_linux_amd64.tar.gz)
-- [macOS](https://github.com/kyleconroy/sqlc/releases/download/v1.18.0/sqlc_1.18.0_darwin_amd64.zip)
-- [Windows (MySQL only)](https://github.com/kyleconroy/sqlc/releases/download/v1.18.0/sqlc_1.18.0_windows_amd64.zip)
+- [Linux](https://github.com/kyleconroy/sqlc/releases/download/v1.19.0/sqlc_1.19.0_linux_amd64.tar.gz)
+- [macOS](https://github.com/kyleconroy/sqlc/releases/download/v1.19.0/sqlc_1.19.0_darwin_amd64.zip)
+- [Windows (MySQL only)](https://github.com/kyleconroy/sqlc/releases/download/v1.19.0/sqlc_1.19.0_windows_amd64.zip)
 
 See [downloads.sqlc.dev](https://downloads.sqlc.dev/) for older versions.