SQL Server DSN 必须以 sqlserver:// 开头,密码含@/:等特殊字符需 URL 编码或改用参数化连接串;gorm.Open() 不立即建连,首次查询才触发;Windows认证、加密、超时等参数需显式配置。

直接用 sqlserver.Open() 配合 URL 形式 DSN 就能连上,但密码含 @、/、: 等字符时会解析失败——这是最常卡住新手的地方。
SQL Server 的 DSN 必须用 sqlserver:// 协议头
不是 mssql://,也不是 sqlserver:(少斜杠)或 sqlserver:///(多斜杠)。GORM V2 的 SQL Server 驱动只认 sqlserver:// 开头的字符串。
- 正确:
sqlserver://sa:123@127.0.0.1:1433?database=master - 错误:
mssql://sa:123@127.0.0.1:1433?database=master(驱动未注册) - 错误:
sqlserver:sa:123@127.0.0.1:1433?database=master(Open()解析失败,返回 nil)
驱动内部依赖 github.com/microsoft/go-mssqldb,协议名硬编码为 sqlserver,拼错就 panic 或静默失败。
密码含特殊字符必须 URL 编码或改用参数化连接串
URL 中 @ 是分隔用户名和 host 的关键符号,如果密码里有 @(比如 Pass@2026),DSN 会被截断成 sqlserver://sa:Pass@2026@127.0.0.1:1433?...,中间多出一个 @,解析器直接报错 invalid port ":1433?database=..."。
- 方案一(推荐):用
url.QueryEscape()编码密码:password := url.QueryEscape("Pass@2026"),再拼进 DSN - 方案二(更稳):放弃 URL 形式,改用参数化连接字符串:
server=localhost;user id=sa;password=Pass@2026;database=master;,传给sqlserver.Open()—— 这种格式不走 URL 解析,完全绕过特殊字符问题 - 注意:
gorm.io/driver/sqlserver和已废弃的github.com/denisenkom/go-mssqldb(旧 mssql 驱动)不兼容,别混用
gorm.Open() 不立即建连,真正连接发生在第一次查询时
调用 gorm.Open(sqlserver.Open(dsn), &gorm.Config{}) 只是初始化一个 *gorm.DB 对象,不会发任何网络请求。DB 实例本身不持有活跃连接。
- 首次调用
db.First()、db.Find()或db.Exec()时,才从连接池取或新建物理连接 - 这意味着:即使 DSN 写错,
gorm.Open()也可能不报错;真正报错在第一次查询时,如dial tcp: lookup xxx: no such host - 验证是否真连上,得加一句
db.Exec("SELECT 1").Error或db.Raw("SELECT 1").Scan(&var).Error
Windows 认证、加密、超时等关键参数要显式控制
生产环境不能依赖默认行为。SQL Server 默认启用加密通信,但自签名证书下容易因证书校验失败而中断连接。
-
encrypt=false:禁用加密(仅开发/内网可信环境) -
encrypt=disable:彻底关闭 TLS(比false更激进,登录包也不加密) -
connection+timeout=30:连接建立超时秒数(单位是秒,不是毫秒) -
dial+timeout=5:DNS 解析 + TCP 握手阶段超时(建议设为 5~10 秒) - Windows 认证用户写法:
sqlserver://DOMAIN\user:password@host:1433?database=xxx,注意反斜杠要双写或用 raw string
最容易被忽略的是:SQL Server 默认监听 TCP 端口 1433,但命名实例(如 SQLExpress)必须用 instance=SQLExpress 参数,不能写端口;两者不可共存。


















