Skip to content

Commit 2ae2847

Browse files
committed
Changes
1 parent f6e6a93 commit 2ae2847

File tree

11 files changed

+129
-130
lines changed

11 files changed

+129
-130
lines changed

docs/guides/plugins.md

Lines changed: 1 addition & 1 deletion
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

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ catch both scenarios.
2222

2323
`sqlc vet` runs a set of lint checks against your SQL queries. These checks are
2424
helpful in catching anti-patterns before they make it into production. Please
25-
see the [vet](../reference/cli.html#vet) documentation for a complete guide on adding checks to your
25+
see the [vet](vet.md) documentation for a complete guide on adding checks to your
2626
project.
2727

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

6160
```yaml
6261
name: sqlc

docs/howto/vet.md

Lines changed: 112 additions & 0 deletions
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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ code ever again.
5454
howto/ddl.md
5555
howto/structs.md
5656

57+
howto/vet.md
5758
howto/ci-cd.md
5859
howto/upload.md
5960

docs/reference/changelog.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Released 2023-07-06
88

99
#### sqlc vet
1010

11-
[`vet`](cli.html#vet) runs queries through a set of lint rules.
11+
[`vet`](../howto/vet.md) runs queries through a set of lint rules.
1212

1313
Rules are defined in the `sqlc` [configuration](config.html#rules) file. They consist
1414
of a name, message, and an expression. If the expression evaluates to `true`, an
@@ -73,7 +73,7 @@ sql:
7373
package: "authors"
7474
out: "db"
7575
database:
76-
url: "postgresql://postgres:password@localhost:5432/postgres"
76+
uri: "postgresql://postgres:password@localhost:5432/postgres"
7777
rules:
7878
- sqlc/db-prepare
7979
```

docs/reference/cli.md

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

docs/reference/config.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ sql:
1616
package: "authors"
1717
out: "postgresql"
1818
database:
19-
url: "postgresql://postgres:postgres@localhost:5432/postgres"
19+
uri: "postgresql://postgres:postgres@localhost:5432/postgres"
2020
rules:
2121
- sqlc/db-prepare
2222
- schema: "mysql/schema.sql"
@@ -85,10 +85,10 @@ sql:
8585

8686
The `database` mapping supports the following keys:
8787

88-
- `url`:
88+
- `uri`:
8989
- Database connection URL
9090

91-
The URL can contain references to environment variables using the `${...}`
91+
The URI can contain references to environment variables using the `${...}`
9292
syntax. In the following example, the connection string will set the value of
9393
the password to the value set in the `PG_PASSWORD` environment variable.
9494

@@ -99,7 +99,7 @@ sql:
9999
queries: query.sql
100100
engine: postgresql
101101
database:
102-
url: postgresql://postgres:${PG_PASSWORD}@localhost:5432/authors
102+
uri: postgresql://postgres:${PG_PASSWORD}@localhost:5432/authors
103103
gen:
104104
go:
105105
package: authors
@@ -346,7 +346,7 @@ Each mapping in the `rules` collection has the following keys:
346346
- `message`:
347347
- An optional message shown when the rule returns true.
348348

349-
See the [vet](cli.html#vet) documentation for help writing custom rules.
349+
See the [vet](../howto/vet.md) documentation for help writing custom rules.
350350

351351
```yaml
352352
version: 2

docs/tutorials/getting-started-mysql.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Getting started with MySQL
22

33
This tutorial assumes that the latest version of sqlc is
4-
[installed](../overview/install.html) and ready to use.
4+
[installed](../overview/install.md) and ready to use.
55

66
Create a new directory called `sqlc-tutorial` and open it up.
77

docs/tutorials/getting-started-postgresql.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Getting started with PostgreSQL
22

33
This tutorial assumes that the latest version of sqlc is
4-
[installed](../overview/install.html) and ready to use.
4+
[installed](../overview/install.md) and ready to use.
55

66
Create a new directory called `sqlc-tutorial` and open it up.
77

docs/tutorials/getting-started-sqlite.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Getting started with SQLite
22

33
This tutorial assumes that the latest version of sqlc is
4-
[installed](../overview/install.html) and ready to use.
4+
[installed](../overview/install.md) and ready to use.
55

66
Create a new directory called `sqlc-tutorial` and open it up.
77

internal/cmd/vet.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -291,7 +291,7 @@ func (c *checker) checkSQL(ctx context.Context, s config.SQL) error {
291291
defer db.Close()
292292
prep = &dbPreparer{db}
293293
default:
294-
return fmt.Errorf("unsupported database url: %s", s.Engine)
294+
return fmt.Errorf("unsupported database uri: %s", s.Engine)
295295
}
296296
}
297297

0 commit comments

Comments
 (0)