クエリアノテーション

sqlcは各クエリに名前とコマンドを示す小さなコメントが必要です。このコメントの形式は以下の通りです：

-- name: <n> <command>

`:exec`

生成されたメソッドは、ExecContextからのエラーを返します。

-- name: DeleteAuthor :exec
DELETE FROM authors
WHERE id = $1;

func (q *Queries) DeleteAuthor(ctx context.Context, id int64) error {
	_, err := q.db.ExecContext(ctx, deleteAuthor, id)
	return err
}

`:execresult`

生成されたメソッドは、ExecContextによって返されるsql.Resultを返します。

-- name: DeleteAllAuthors :execresult
DELETE FROM authors;

func (q *Queries) DeleteAllAuthors(ctx context.Context) (sql.Result, error) {
	return q.db.ExecContext(ctx, deleteAllAuthors)
}

`:execrows`

生成されたメソッドは、ExecContextによって返される結果から影響を受けた行数を返します。

-- name: DeleteAllAuthors :execrows
DELETE FROM authors;

func (q *Queries) DeleteAllAuthors(ctx context.Context) (int64, error) {
	_, err := q.db.ExecContext(ctx, deleteAllAuthors)
	// ...
}

`:execlastid`

生成されたメソッドは、ExecContextによって返される結果からデータベースによって生成された番号を返します。

-- name: InsertAuthor :execlastid
INSERT INTO authors (name) VALUES (?);

func (q *Queries) InsertAuthor(ctx context.Context, name string) (int64, error) {
	_, err := q.db.ExecContext(ctx, insertAuthor, name)
	// ...
}

`:many`

生成されたメソッドは、QueryContextを介してレコードのスライスを返します。

-- name: ListAuthors :many
SELECT * FROM authors
ORDER BY name;

func (q *Queries) ListAuthors(ctx context.Context) ([]Author, error) {
	rows, err := q.db.QueryContext(ctx, listAuthors)
	// ...
}

`:one`

生成されたメソッドは、QueryRowContextを介して単一のレコードを返します。

-- name: GetAuthor :one
SELECT * FROM authors
WHERE id = $1 LIMIT 1;

func (q *Queries) GetAuthor(ctx context.Context, id int64) (Author, error) {
	row := q.db.QueryRowContext(ctx, getAuthor, id)
	// ...
}

`:batchexec`

注意：このコマンドは、pgx/v4およびpgx/v5ドライバーを使用してGoコードを出力するPostgreSQLでのみ動作します。

生成されたメソッドは、バッチオブジェクトを返します。バッチオブジェクトには以下のメソッドがあります：

Exec：func(int, error)パラメーターを取る
Close：バッチ操作を早期に閉じる

-- name: DeleteBook :batchexec
DELETE FROM books
WHERE book_id = $1;

type DeleteBookBatchResults struct {
	br  pgx.BatchResults
	ind int
}

func (q *Queries) DeleteBook(ctx context.Context, bookID []int32) *DeleteBookBatchResults {
	//...
}
func (b *DeleteBookBatchResults) Exec(f func(int, error)) {
	//...
}
func (b *DeleteBookBatchResults) Close() error {
	//...
}

`:batchmany`

注意：このコマンドは、pgx/v4およびpgx/v5ドライバーを使用してGoコードを出力するPostgreSQLでのみ動作します。

生成されたメソッドは、バッチオブジェクトを返します。バッチオブジェクトには以下のメソッドがあります：

Query：func(int, []T, error)パラメーターを取る（Tはクエリの戻り値の型）
Close：バッチ操作を早期に閉じる

-- name: BooksByTitleYear :batchmany
SELECT * FROM books
WHERE title = $1 AND year = $2;

type BooksByTitleYearBatchResults struct {
	br  pgx.BatchResults
	ind int
}
type BooksByTitleYearParams struct {
	Title string `json:"title"`
	Year  int32  `json:"year"`
}

func (q *Queries) BooksByTitleYear(ctx context.Context, arg []BooksByTitleYearParams) *BooksByTitleYearBatchResults {
	//...
}
func (b *BooksByTitleYearBatchResults) Query(f func(int, []Book, error)) {
	//...
}
func (b *BooksByTitleYearBatchResults) Close() error {
	//...
}

`:batchone`

注意：このコマンドは、pgx/v4およびpgx/v5ドライバーを使用してGoコードを出力するPostgreSQLでのみ動作します。

生成されたメソッドは、バッチオブジェクトを返します。バッチオブジェクトには以下のメソッドがあります：

QueryRow：func(int, T, error)パラメーターを取る（Tはクエリの戻り値の型）
Close：バッチ操作を早期に閉じる

-- name: CreateBook :batchone
INSERT INTO books (
    author_id,
    isbn
) VALUES (
    $1,
    $2
)
RETURNING book_id, author_id, isbn

type CreateBookBatchResults struct {
	br  pgx.BatchResults
	ind int
}
type CreateBookParams struct {
	AuthorID int32  `json:"author_id"`
	Isbn     string `json:"isbn"`
}

func (q *Queries) CreateBook(ctx context.Context, arg []CreateBookParams) *CreateBookBatchResults {
	//...
}
func (b *CreateBookBatchResults) QueryRow(f func(int, Book, error)) {
	//...
}
func (b *CreateBookBatchResults) Close() error {
	//...
}

`:copyfrom`

注意：このコマンドはドライバーとパッケージ固有です。挿入方法を参照してください。

このコマンドは、順次挿入よりもはるかに高速に行を挿入するために使用されます。

原文：https://docs.sqlc.dev/en/latest/reference/query-annotations.html

マクロデータベースと言語サポート