SQLC项目入门指南：PostgreSQL数据库操作代码生成

汤中岱Wonderful

于 2025-06-02 09:16:08 发布

阅读量391

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00656/article/details/148377538

SQLC项目入门指南：PostgreSQL数据库操作代码生成

sqlc sqlc-dev/sqlcsqlc-dev/sqlcli: 是一个用于 PostgreSQL 和 SQLite 数据库的跨平台命令行工具，它提供了一个简单易用的界面用于管理 PostgreSQL 和 SQLite 数据库。适合用于管理 PostgreSQL 和 SQLite 数据库，特别是对于需要轻量级、跨平台的数据库管理工具的场景。特点是轻量级、跨平台、支持 PostgreSQL 和 SQLite 数据库。项目地址: https://gitcode.com/gh_mirrors/sq/sqlc

前言

在现代应用开发中，数据库操作是不可或缺的一部分。传统的手写SQL查询和ORM框架各有优缺点，而SQLC项目提供了一种创新的解决方案。本文将详细介绍如何使用SQLC为PostgreSQL数据库生成类型安全的Go代码。

SQLC项目简介

SQLC是一个将SQL查询转换为类型安全代码的工具，它支持多种编程语言，本文以Go语言为例。与传统的ORM不同，SQLC不会隐藏SQL，而是基于你编写的SQL生成对应的类型安全代码，既保留了SQL的灵活性，又获得了编译时类型检查的好处。

环境准备

在开始之前，请确保已安装以下工具：

最新版本的SQLC工具
Go工具链（1.16或更高版本）
PostgreSQL数据库

项目初始化

首先创建一个新目录并初始化Go模块：

mkdir sqlc-tutorial && cd sqlc-tutorial
go mod init tutorial.sqlc.dev/app

配置SQLC

SQLC需要一个配置文件来指定生成参数。创建sqlc.yaml文件：

version: "2"
sql:
  - engine: "postgresql"
    queries: "query.sql"
    schema: "schema.sql"
    gen:
      go:
        package: "tutorial"
        out: "tutorial"
        sql_package: "pgx/v5"

关键配置说明：

engine: 指定数据库类型为PostgreSQL
queries: SQL查询文件路径
schema: 数据库模式文件路径
gen.go: Go代码生成配置
- package: 生成的包名
- out: 输出目录
- sql_package: 使用的数据库驱动

定义数据库模式

创建schema.sql文件定义数据库表结构：

CREATE TABLE authors (
  id   BIGSERIAL PRIMARY KEY,
  name text      NOT NULL,
  bio  text
);

这个简单的作者表包含ID、姓名和简介字段。

编写SQL查询

在query.sql中定义CRUD操作：

-- 获取单个作者
-- name: GetAuthor :one
SELECT * FROM authors
WHERE id = $1 LIMIT 1;

-- 列出所有作者
-- name: ListAuthors :many
SELECT * FROM authors
ORDER BY name;

-- 创建作者
-- name: CreateAuthor :one
INSERT INTO authors (name, bio) 
VALUES ($1, $2)
RETURNING *;

-- 更新作者
-- name: UpdateAuthor :exec
UPDATE authors
SET name = $2,
    bio = $3
WHERE id = $1;

-- 删除作者
-- name: DeleteAuthor :exec
DELETE FROM authors
WHERE id = $1;

SQLC通过特殊注释解析查询：

-- name: 指定生成的函数名
:one: 返回单条记录
:many: 返回多条记录
:exec: 执行但不返回记录

生成代码

运行以下命令生成Go代码：

sqlc generate

生成的文件结构如下：

tutorial/
├── db.go        # 数据库接口定义
├── models.go    # 数据结构定义
└── query.sql.go # 查询方法实现

使用生成的代码

创建main.go使用生成的代码：

package main

import (
	"context"
	"log"
	"reflect"

	"github.com/jackc/pgx/v5"
	"github.com/jackc/pgx/v5/pgtype"
	"tutorial.sqlc.dev/app/tutorial"
)

func main() {
	ctx := context.Background()

	// 连接数据库
	conn, err := pgx.Connect(ctx, "user=youruser dbname=yourdb sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close(ctx)

	queries := tutorial.New(conn)

	// 创建作者
	author, err := queries.CreateAuthor(ctx, tutorial.CreateAuthorParams{
		Name: "Brian Kernighan",
		Bio:  pgtype.Text{String: "C语言和Go语言联合作者", Valid: true},
	})
	if err != nil {
		log.Fatal(err)
	}

	// 查询作者
	fetched, err := queries.GetAuthor(ctx, author.ID)
	if err != nil {
		log.Fatal(err)
	}

	log.Println(reflect.DeepEqual(author, fetched)) // true
}