sqlserver

package

v2.0.2 Latest Latest Go to latest Published: Aug 21, 2026 License: MIT Imports: 13 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/NeverStopDreamingWang/goi

Links

Open Source Insights

Documentation ¶

Index ¶

func Validate(attrs Model, partial bool) error
type Engine
- func Connect(UseDatabases string) *Engine
- func ConnectDatabase(UseDatabases string, database *goi.Database) *Engine
type MigrationsHandler
type Model
type Settings
type TransactionFunc

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Validate ¶

func Validate(attrs Model, partial bool) error

Validate SQL Server Engine Validate attrs 校验数据 partial 是否仅验证提供的非零值字段，零值字段跳过不验证必填项

Types ¶

type Engine ¶

type Engine struct {
	DB *sql.DB // 数据库连接对象
	// contains filtered or unexported fields
}

Engine 结构体用于管理 SQL Server 数据库连接和操作

func Connect ¶

func Connect(UseDatabases string) *Engine

Connect 连接 SQL Server 数据库

参数:

UseDatabases: string 数据库配置名称

返回:

*Engine: SQL Server 数据库操作实例

说明:

从全局配置中获取数据库连接信息
如果 Engine 不匹配则 panic
需要手动添加 _ "github.com/denisenkom/go-mssqldb" 包

func ConnectDatabase ¶

func ConnectDatabase(UseDatabases string, database *goi.Database) *Engine

ConnectDatabase 连接 SQL Server 数据库

参数:

UseDatabases: string 数据库配置名称
database: *goi.Database 数据库连接管理器

返回:

*Engine: SQL Server 数据库操作实例

说明:

如果 Engine 不匹配则 panic
需要手动添加 _ "github.com/denisenkom/go-mssqldb" 包

func (*Engine) Count ¶

func (engine *Engine) Count() (int64, error)

Count 统计符合当前条件的记记录数

返回:

int64: 满足当前 WHERE 条件的记录总数
error: 查询过程中的错误

说明:

必须先通过 SetModel 设置数据模型
会根据当前设置的 WHERE 条件生成 COUNT 语句
查询失败时返回0和错误信息

func (*Engine) Delete ¶

func (engine *Engine) Delete() (sql.Result, error)

Delete 删除符合条件的记录

返回:

sql.Result: 删除操作的结果
error: 删除过程中的错误

说明:

调用前必须先通过 SetModel 设置数据模型
会根据当前设置的 WHERE 条件生成 DELETE 语句
未设置 WHERE 条件时将删除整张表中的所有记录，使用时需谨慎

func (*Engine) Execute ¶

func (engine *Engine) Execute(query string, args ...any) (sql.Result, error)

Execute 执行 SQL 语句

参数:

query: string SQL语句，使用 ? 作为占位符，例如: "id = ? AND status IN (?)"
args: ...any SQL参数值列表

返回:

sql.Result: 执行操作的结果
error: 执行过程中的错误

说明:

使用 ? 作为统一占位符，最终会被转换为 SQL Server 的 @p1,@p2,... 格式
支持在事务中使用

func (*Engine) Exists ¶

func (engine *Engine) Exists() (bool, error)

Exists 判断是否存在符合条件的记录

返回:

bool: 是否存在至少一条满足条件的记录
error: 查询过程中的错误

说明:

必须先通过 SetModel 设置数据模型
会根据当前 WHERE 条件生成 SELECT 1 FROM "table" ...
使用 QueryRow 执行，若返回 sql.ErrNoRows 则视为不存在（false, nil）
其他错误会原样返回

func (Engine) Fields ¶

func (engine Engine) Fields(fields ...string) *Engine

Fields 指定查询要返回的字段

参数:

fields: ...string 要查询的字段名列表（模型结构体中的字段名）

返回:

*Engine: 当前实例的副本指针，支持链式调用

说明:

字段名必须是模型结构体中已定义的字段
只返回带有 field_type 标签的字段，未标记的字段会被忽略
字段名大小写不敏感，会自动转换为数据库字段名
数据库字段名默认使用字段名的小写形式，或由 field_name 标签显式指定
如果字段不存在则会 panic

func (*Engine) First ¶

func (engine *Engine) First(queryResult any) error

First 获取查询结果的第一条记录

参数:

queryResult: *struct{} 或 map[string]any / *map[string]any，用于接收结果的结构体指针或 map

返回:

error: 查询过程中的错误

说明:

必须传入结构体指针或 map/map 指针
自动映射数据库字段到结构体字段或 map 键
无记录时返回 sql.ErrNoRows
查询失败时返回错误信息

func (Engine) GetSQL ¶

func (engine Engine) GetSQL() string

GetSQL 获取最近一次执行的 SQL 语句

返回:

string: 最近一次执行的 SQL 语句

func (Engine) GroupBy ¶

func (engine Engine) GroupBy(groups ...string) *Engine

GroupBy 设置分组条件

参数:

groups: ...string 分组字段名列表

返回:

*Engine: 当前实例的副本指针，支持链式调用

说明:

字段名会被自动去除首尾空格和引号
字段名最终会使用 SQL Server 的方括号引用: [column]
空字段名会被忽略
多次调用会覆盖之前的分组设置

func (*Engine) Insert ¶

func (engine *Engine) Insert(model Model) (sql.Result, error)

Insert 向数据库插入一条记录

参数:

model: Model 要插入的数据模型实例

返回:

sql.Result: 插入操作的结果
error: 插入过程中的错误

说明:

调用前必须先通过 SetModel 设置数据模型
支持指针和非指针类型的字段值
只插入带有 field_type 标签的字段

Example ¶

package main

import (
	"fmt"
	"time"

	"github.com/NeverStopDreamingWang/goi/v2"
	"github.com/NeverStopDreamingWang/goi/v2/db"
	"github.com/NeverStopDreamingWang/goi/v2/db/sqlserver"
)

type UserModel struct {
	ID         *int64  `field_name:"id" field_type:"BIGINT IDENTITY(1,1) PRIMARY KEY" json:"id"`
	Username   *string `field_name:"username" field_type:"NVARCHAR(255) NOT NULL" json:"username"`
	Password   *string `field_name:"password" field_type:"NVARCHAR(255) NOT NULL" json:"-"`
	CreateTime *string `field_name:"create_time" field_type:"DATETIME2 DEFAULT SYSDATETIME()" json:"create_time"`
	UpdateTime *string `field_name:"update_time" field_type:"DATETIME2" json:"update_time"`
}

func (userModel UserModel) ModelSet() *sqlserver.Settings {
	encryptFields := []string{
		"username",
		"password",
	}

	modelSettings := &sqlserver.Settings{
		MigrationsHandler: sqlserver.MigrationsHandler{
			BeforeHandler: nil,
			AfterHandler:  nil,
		},
		TableName: "user_tb",
		Settings: goi.Params{
			"encrypt_fields": encryptFields,
		},
	}
	return modelSettings
}

func main() {
	mssqlDB := db.Connect[*sqlserver.Engine]("sqlserver_default")

	username := "test_user"
	password := "test123456"
	now := time.Now().Format(time.DateTime)

	user := UserModel{
		Username:   &username,
		Password:   &password,
		CreateTime: &now,
	}

	mssqlDB.SetModel(UserModel{})
	if _, err := mssqlDB.Insert(user); err != nil {
		fmt.Println("插入错误:", err)
		return
	}

	fmt.Println("插入成功")
}

Output:

func (*Engine) Migrate ¶

func (engine *Engine) Migrate(schema string, model Model)

Migrate 根据模型创建数据库表

参数:

schema: string 数据库名称，如果连接字符串中已指定数据库则可以传入空字符串
model: Model 数据模型

说明:

SQL Server 默认 schema 为 dbo
检查表是否已存在，存在则跳过创建
解析模型结构体的字段标签
支持自定义迁移前后处理函数
创建失败时会panic

Example ¶

package main

import (
	"github.com/NeverStopDreamingWang/goi/v2"
	"github.com/NeverStopDreamingWang/goi/v2/db"
	"github.com/NeverStopDreamingWang/goi/v2/db/sqlserver"
)

type UserModel struct {
	ID         *int64  `field_name:"id" field_type:"BIGINT IDENTITY(1,1) PRIMARY KEY" json:"id"`
	Username   *string `field_name:"username" field_type:"NVARCHAR(255) NOT NULL" json:"username"`
	Password   *string `field_name:"password" field_type:"NVARCHAR(255) NOT NULL" json:"-"`
	CreateTime *string `field_name:"create_time" field_type:"DATETIME2 DEFAULT SYSDATETIME()" json:"create_time"`
	UpdateTime *string `field_name:"update_time" field_type:"DATETIME2" json:"update_time"`
}

func (userModel UserModel) ModelSet() *sqlserver.Settings {
	encryptFields := []string{
		"username",
		"password",
	}

	modelSettings := &sqlserver.Settings{
		MigrationsHandler: sqlserver.MigrationsHandler{
			BeforeHandler: nil,
			AfterHandler:  nil,
		},
		TableName: "user_tb",
		Settings: goi.Params{
			"encrypt_fields": encryptFields,
		},
	}
	return modelSettings
}

func main() {
	mssqlDB := db.Connect[*sqlserver.Engine]("sqlserver_default")
	mssqlDB.Migrate("dbo", UserModel{})
}

Output:

func (Engine) Name ¶

func (engine Engine) Name() string

Name 获取数据库连接名称

返回:

string: 当前数据库连接名称

func (Engine) OrderBy ¶

func (engine Engine) OrderBy(orders ...string) *Engine

OrderBy 设置排序条件

参数:

orders: ...string 排序字段列表，支持前缀 "-" 表示倒序，例如: "name", "-created_at"

返回:

*Engine: 当前实例的副本指针，支持链式调用

说明:

字段名会被自动去除首尾空格和引号
不带前缀时使用 ASC 升序，带 "-" 前缀时使用 DESC 降序
字段名最终会使用 SQL Server 的方括号引用: [column] ASC/DESC
多次调用会覆盖之前的排序设置

func (*Engine) Page ¶

func (engine *Engine) Page(page int64, pageSize int64) (int64, int64, error)

Page 设置分页参数

参数:

page: int64 页码，从 1 开始
pageSize: int64 每页记录数

返回:

int64: 总记录数
int64: 总页数
error: 查询过程中的错误

说明:

页码小于等于 0 时自动设为 1
每页记录数小于等于 0 时设为默认值 10
总页数根据总记录数和每页记录数计算
会自动执行一次 Count 查询获取总记录数
SQL Server 使用 OFFSET ... ROWS FETCH NEXT ... ROWS ONLY 实现分页
注意：SQL Server 的 OFFSET/FETCH 语法必须配合 ORDER BY 使用，请确保调用 OrderBy 方法

func (*Engine) Query ¶

func (engine *Engine) Query(query string, args ...any) (*sql.Rows, error)

Query 执行查询 SQL 语句

参数:

query: string SQL查询语句，使用 ? 作为占位符，例如: "id = ? AND status IN (?)"
args: ...any SQL参数值列表

返回:

*sql.Rows: 查询结果集
error: 查询过程中的错误

说明: - 使用 ? 作为统一占位符，最终会被转换为 SQL Server 的 @p1,@p2,... 格式 - 返回的结果集需要调用方手动关闭 - 查询失败时返回nil和错误信息 - 支持在事务中使用

func (*Engine) QueryRow ¶

func (engine *Engine) QueryRow(query string, args ...any) *sql.Row

QueryRow 执行查询 SQL 语句

参数:

query: string SQL查询语句，使用 ? 作为占位符，例如: "id = ? AND status IN (?)"
args: ...any SQL参数值列表

返回:

*sql.Row: 查询结果行

说明:

使用 ? 作为统一占位符，最终会被转换为 SQL Server 的 @p1,@p2,... 格式
查询失败时返回nil
支持在事务中使用

func (*Engine) Select ¶

func (engine *Engine) Select(queryResult any) error

Select 执行查询并将结果扫描到切片中

参数:

queryResult: *[]T 或 []*T，用于接收结果的切片指针，其中 T 可以是 struct 或 map 类型

返回:

error: 查询过程中的错误

说明:

必须传入切片指针，且元素类型为结构体或 map
支持指针和非指针类型的结构体元素（[]T / []*T）
会根据 SetModel/Fields 解析的字段集合，自动将数据库字段映射到结构体字段或 map 键上
查询结束后会检查 rows.Err()，不会静默吞掉迭代过程中的错误

func (*Engine) SetModel ¶

func (engine *Engine) SetModel(model Model) *Engine

SetModel 设置当前操作的数据模型

参数:

model: Model 要设置的数据模型实例

返回:

*Engine: 当前 Engine 指针，支持链式调用

说明:

会重置内部的字段缓存、条件、排序、分组、分页等状态
只解析带有 field_type 标签的结构体字段
数据库字段名默认使用字段名的小写形式，或由 field_name 标签显式指定

func (*Engine) Update ¶

func (engine *Engine) Update(model Model) (sql.Result, error)

Update 更新符合条件的记录

参数:

model: Model 要更新的数据模型实例

返回:

sql.Result: 更新操作的结果
error: 更新过程中的错误

说明:

调用前必须先通过 SetModel 设置数据模型
只更新非空字段
支持指针和非指针类型的字段值
会根据当前设置的 WHERE 条件生成 UPDATE 语句

func (Engine) Where ¶

func (engine Engine) Where(query string, args ...any) *Engine

Where 构造 WHERE 条件

参数:

query: string 条件语句，使用 ? 作为占位符，例如: "id = ? AND status IN (?)"
args: ...any 对应占位符的参数列表，支持基本类型和切片/数组

返回:

*Engine: 当前实例的副本指针，支持链式调用

说明:

支持多次调用，条件之间使用 AND 连接
使用 ? 作为统一占位符，最终会在 Execute/Query 中被转换为 SQL Server 的 @p1,@p2,... 格式
对切片/数组参数会自动展开为 IN (...) 形式，占位符数量与元素个数一致
空切片/数组会被当作普通参数处理，此时生成的 SQL 可能不是预期的 IN () 语义，应在业务层避免传入空集合

func (Engine) WithTransaction ¶

func (engine Engine) WithTransaction(transactionFunc TransactionFunc, args ...any) (err error)

WithTransaction 使用事务执行函数

参数:

transactionFunc: TransactionFunc func(engine *Engine, args ...any) error 事务执行函数
args: ...any 传递给事务函数的参数列表

返回:

error: 事务执行的错误，发生错误时会自动回滚

说明:

使用值接收者，在事务内部会基于当前 Engine 复制一个副本，避免事务内外状态互相干扰
不支持嵌套事务，如果当前已在事务中则返回错误
事务函数执行失败时自动回滚，支持内部 panic

type MigrationsHandler ¶

type MigrationsHandler struct {
	BeforeHandler func() error // 迁移之前处理函数
	AfterHandler  func() error // 迁移之后处理函数
}

迁移处理函数

type Model ¶

type Model interface {
	ModelSet() *Settings
}

模型接口

type Settings ¶

type Settings struct {
	MigrationsHandler // 迁移处理函数

	TableName string // 表名

	// 自定义配置
	Settings goi.Params
}

SQL Server 模型设置

type TransactionFunc ¶

type TransactionFunc func(engine *Engine, args ...any) error

事务执行函数

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL