Changes

Author: kyleconroy

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

@@ -22,7 +22,7 @@ catch both scenarios.
 
 `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](../reference/cli.html#vet) documentation for a complete guide on adding checks to your
+see the [vet](vet.md) documentation for a complete guide on adding checks to your
 project.
 
 ## General setup
@@ -54,9 +54,8 @@ jobs:
     - run: sqlc diff
 ```
 
-We also encourage running [`sqlc vet`](../reference/cli.html#vet). To get the most value out of `vet`,
-you'll want to set up a running database. See the [vet] documentation for a
-complete guide on adding checks to your project.
+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

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,7 @@ code ever again.
    howto/ddl.md
    howto/structs.md
 
+   howto/vet.md
    howto/ci-cd.md
    howto/upload.md
 

docs/reference/changelog.md

@@ -8,7 +8,7 @@ Released 2023-07-06
 
 #### sqlc vet
 
-[`vet`](cli.html#vet) runs queries through a set of lint rules.
+[`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
@@ -73,7 +73,7 @@ sql:
         package: "authors"
         out: "db"
     database:
-      url: "postgresql://postgres:password@localhost:5432/postgres"
+      uri: "postgresql://postgres:password@localhost:5432/postgres"
     rules:
       - sqlc/db-prepare
 ```

docs/reference/cli.md

@@ -22,117 +22,4 @@ Flags:
       --no-remote      disable remote execution (default: false)
 
 Use "sqlc [command] --help" for more information about a command.
-```
-
-## vet
-
-*Added in v1.19.0*
-
-`vet` runs queries through a set of lint rules.
-
-Rules are defined in the `sqlc` [configuration](config.html) 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](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:
-      url: "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/reference/config.md

@@ -16,7 +16,7 @@ sql:
       package: "authors"
       out: "postgresql"
   database:
-    url: "postgresql://postgres:postgres@localhost:5432/postgres"
+    uri: "postgresql://postgres:postgres@localhost:5432/postgres"
   rules:
     - sqlc/db-prepare
 - schema: "mysql/schema.sql"
@@ -85,10 +85,10 @@ sql:
 
 The `database` mapping supports the following keys:
 
-- `url`:
+- `uri`:
   - Database connection URL
 
-The URL can contain references to environment variables using the `${...}`
+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.
 
@@ -99,7 +99,7 @@ sql:
   queries: query.sql
   engine: postgresql
   database:
-    url: postgresql://postgres:${PG_PASSWORD}@localhost:5432/authors
+    uri: postgresql://postgres:${PG_PASSWORD}@localhost:5432/authors
   gen:
     go:
       package: authors
@@ -346,7 +346,7 @@ Each mapping in the `rules` collection has the following keys:
 - `message`:
   - An optional message shown when the rule returns true.
 
-See the [vet](cli.html#vet) documentation for help writing custom rules.
+See the [vet](../howto/vet.md) documentation for help writing custom rules.
 
 ```yaml
 version: 2

docs/tutorials/getting-started-mysql.md

@@ -1,7 +1,7 @@
 # Getting started with MySQL
 
 This tutorial assumes that the latest version of sqlc is
-[installed](../overview/install.html) and ready to use.
+[installed](../overview/install.md) and ready to use.
 
 Create a new directory called `sqlc-tutorial` and open it up.
 

docs/tutorials/getting-started-postgresql.md

@@ -1,7 +1,7 @@
 # Getting started with PostgreSQL 
 
 This tutorial assumes that the latest version of sqlc is
-[installed](../overview/install.html) and ready to use.
+[installed](../overview/install.md) and ready to use.
 
 Create a new directory called `sqlc-tutorial` and open it up.
 

docs/tutorials/getting-started-sqlite.md

@@ -1,7 +1,7 @@
 # Getting started with SQLite
 
 This tutorial assumes that the latest version of sqlc is
-[installed](../overview/install.html) and ready to use.
+[installed](../overview/install.md) and ready to use.
 
 Create a new directory called `sqlc-tutorial` and open it up.
 

internal/cmd/vet.go

@@ -291,7 +291,7 @@ func (c *checker) checkSQL(ctx context.Context, s config.SQL) error {
 			defer db.Close()
 			prep = &dbPreparer{db}
 		default:
-			return fmt.Errorf("unsupported database url: %s", s.Engine)
+			return fmt.Errorf("unsupported database uri: %s", s.Engine)
 		}
 	}