0f4df23290
Some checks failed
kotlin / test (push) Has been skipped
python / test (push) Has been skipped
typescript / test (push) Has been skipped
go / build darwin/amd64 (push) Has been cancelled
go / build linux/amd64 (push) Has been cancelled
go / build windows/amd64 (push) Has been cancelled
go / build darwin/arm64 (push) Has been cancelled
go / build linux/arm64 (push) Has been cancelled
go / build windows/arm64 (push) Has been cancelled
go / test (push) Has been cancelled
go / vuln_check (push) Has been cancelled
75 lines
2.5 KiB
Markdown
75 lines
2.5 KiB
Markdown
# `fmt` - Formatting queries
|
|
|
|
> [!NOTE]
|
|
> `fmt` is in beta. It rewrites your query files in place, so commit
|
|
> or back them up first. The formatting it produces may change in a
|
|
> future release.
|
|
|
|
`sqlc fmt` rewrites the query files referenced by your configuration file in a
|
|
canonical format. Each query is parsed with the engine's parser and printed
|
|
back from the syntax tree, so formatting never depends on how the query was
|
|
written — only on what it means. PostgreSQL, MySQL and SQLite are supported;
|
|
query files for other engines are left unchanged.
|
|
|
|
Like `gofmt`, the formatter does not impose a maximum line width. A statement
|
|
written on a single line stays on a single line, and a statement the author
|
|
broke across lines keeps its breaks: the printer notices which clause
|
|
boundaries (`FROM`, `WHERE`, `ORDER BY`, ...) and list boundaries the author
|
|
broke at and preserves them, normalizing indentation and spacing around them.
|
|
|
|
Comments inside a statement are formatted along with it: each comment is
|
|
anchored to the code around it by source position and printed back there —
|
|
a comment trailing a select-list item stays with that item, a comment above
|
|
a clause stays above its keyword — and a comment that runs to the end of its
|
|
line breaks the statement open around it. Any statement that cannot be
|
|
proven to survive formatting unchanged is left exactly as written.
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
sqlc fmt [--diff]
|
|
```
|
|
|
|
Without flags, the query files are rewritten in place. With `--diff`, the
|
|
changes are printed to standard output instead and no files are modified.
|
|
|
|
## Examples
|
|
|
|
Given this query file:
|
|
|
|
```sql
|
|
-- name: GetAuthor :one
|
|
select id,name , bio
|
|
from authors
|
|
where id = ? limit 1;
|
|
|
|
-- name: SearchAuthors :many
|
|
SELECT id, -- the primary key
|
|
name, bio, created_at FROM authors WHERE name LIKE ? AND bio IS NOT NULL AND id > ? AND created_at > ? AND name <> ? ORDER BY name;
|
|
```
|
|
|
|
running `sqlc fmt` rewrites it to:
|
|
|
|
```sql
|
|
-- name: GetAuthor :one
|
|
SELECT id, name, bio
|
|
FROM authors
|
|
WHERE id = ?
|
|
LIMIT 1;
|
|
|
|
-- name: SearchAuthors :many
|
|
SELECT
|
|
id, -- the primary key
|
|
name,
|
|
bio,
|
|
created_at
|
|
FROM authors
|
|
WHERE name LIKE ? AND bio IS NOT NULL AND id > ? AND created_at > ? AND name <> ?
|
|
ORDER BY name;
|
|
```
|
|
|
|
`GetAuthor` keeps the line breaks its author wrote; had it been written on
|
|
one line, it would stay on one line. In `SearchAuthors`, the line comment
|
|
cannot share a line with the code after it, so the statement breaks open
|
|
around it, while the `WHERE` chain — written on one line — stays on one.
|