SQL Server 连接字符串生成器
在一个表单里为 ADO.NET(Microsoft.Data.SqlClient)、ODBC Driver 18、JDBC、Go 和 SQLAlchemy 构建 SQL Server 或 Azure SQL 连接字符串;也可以粘贴一个,看看每个关键字的含义,以及哪里有风险。 所有操作都在你的浏览器中运行:你输入的内容不会被发送到任何地方。
在 SQLly 中打开此连接
从设计上保护隐私。 构建器和解码器是运行在此标签页中的纯 JavaScript。页面不会把你输入的内容发送给任何服务器,不存储任何内容(甚至不存入浏览器),一旦加载完毕即可离线继续工作。“在 SQLly 中打开”链接会直接从浏览器跳转到你电脑上的应用。
SQL Server 连接字符串格式
SQL Server 驱动程序共享关键字=值的格式,但关键字不同:ADO.NET 使用 User ID 和 Connect Timeout,ODBC 则说 Uid 和 ConnectTimeout,JDBC 则说 user 和 loginTimeout,而 Go 用的是 URL。它们还有一个共同的坑:端口写在逗号后面(host,1433),而不是冒号,这一点在除 JDBC 和 Go 之外的所有地方都成立。
另一个让人困惑的地方是加密。Microsoft.Data.SqlClient 4.0、ODBC Driver 18 和 JDBC Driver 10.2 默认都会加密并验证服务器证书,因此多年来可用的字符串在升级后开始失败。构建器明确指出 Encrypt 显式设置,并且解码器会告诉你未设置的 Encrypt 对每个驱动意味着什么。
ADO.NET Microsoft.Data.SqlClient、System.Data.SqlClient、Entity Framework、Dapper
Server=sql01.example.com;Database=Sales;User ID=app_user;Password=your_password;Encrypt=True;
ODBC ODBC Driver 18 for SQL Server、pyodbc
Driver={ODBC Driver 18 for SQL Server};Server=sql01.example.com;Database=Sales;Uid=app_user;Pwd=your_password;Encrypt=yes;
JDBC 适用于 SQL Server 的 Microsoft JDBC 驱动程序
jdbc:sqlserver://sql01.example.com;databaseName=Sales;user=app_user;password=your_password;encrypt=true;
Go URL github.com/microsoft/go-mssqldb
sqlserver://app_user:[email protected]?database=Sales&encrypt=true
SQLAlchemy URL 使用 pyodbc 的 Python SQLAlchemy
mssql+pyodbc://app_user:[email protected]/Sales?driver=ODBC+Driver+18+for+SQL+Server&Encrypt=yes
Windows 身份验证(ADO.NET) 集成安全性
Server=sql01.example.com;Database=Sales;Integrated Security=True;Encrypt=True;
搭配 Microsoft Entra ID 的 Azure SQL(ADO.NET) 托管标识、Azure CLI 或 Visual Studio 登录
Server=myserver.database.windows.net;Database=Sales;Authentication=Active Directory Default;Encrypt=True;
占位符,例如 your_password 就是这样:用上面的表单自己拼一个连接字符串即可。更多关于将 SQLly 连接到 SQL Server 的信息: SQLly 适用于 SQL Server.
Microsoft.Data.SqlClient (ADO.NET) 关键字
关键字不区分大小写,关键字周围的空格会被忽略;当同一个关键字(或其同义词之一)出现两次时,以最后一个值为准。遇到未知关键字会抛出 Keyword not supported。把值放进 " 或者 ' 当它包含 ;,或者以空格或引号开头、结尾;引号内的引号字符要双写。
| 关键字 | 同义词 | 默认 | 作用 |
|---|---|---|---|
Server |
Data Source, Address, Addr, Network Address | - | host, host\instance, host,port,或 tcp:host,port. . 和 (local) 表示这台机器; (localdb)\MSSQLLocalDB 是 LocalDB。命名实例通过 UDP 1434 端口上的 SQL Server Browser 来发现。 |
Database |
Initial Catalog | the login's default database | 连接后要使用的数据库。 |
User ID |
UID, User | - | SQL 登录,或 Entra 用户名,适用于 Active Directory Password / Interactive. |
Password |
PWD | - | 在以下情况下忽略 Integrated Security 处于开启状态。 |
Integrated Security |
Trusted_Connection | 假的 | true, yes 或者 sspi 以运行该进程的 Windows 账户身份登录(Kerberos 或 NTLM)。 |
Authentication |
- | 未设置 | Sql Password, Active Directory Integrated, Active Directory Interactive, Active Directory Default, Active Directory Managed Identity (别名 Active Directory MSI), Active Directory Service Principal, Active Directory Device Code Flow, Active Directory Workload Identity (5.2+), Active Directory Password (已弃用)。从 7.0 起,Entra 方式还需要提供 Microsoft.Data.SqlClient.Extensions.Azure 包。 |
Encrypt |
- | true (Mandatory),4.0 及以上; false 在 3.x 及更早版本中 |
true/yes/Mandatory, false/no/Optional,或 Strict (5.x 及以上版本,TDS 8.0:SQL Server 2022 及以上版本和 Azure SQL)。带有 Optional 登录数据包仍然是加密的,其余的不是。 |
TrustServerCertificate |
信任服务器证书 | 假的 | true 会跳过证书验证。与下列值同用会被忽略(视为 false) Encrypt=Strict. |
HostNameInCertificate |
证书中的主机名 | - | 5.0+。服务器证书中应预期的名称,当它不同于 Server,比如通过别名或 IP 地址连接时。 |
ServerCertificate |
服务器证书 | - | 5.1+。证书文件的路径,服务器证书必须与之完全匹配。 |
Connect Timeout |
连接超时、超时 | 15 | 等待连接的秒数,超过即失败。 |
Command Timeout |
- | 30 | 2.1+。默认 SqlCommand.CommandTimeout 以秒为单位;0 表示一直等待。 |
Application Name |
应用程序 | Core Microsoft SqlClient Data Provider (.NET) |
显示为 program_name in sys.dm_exec_sessions 也会出现在 Profiler / 扩展事件中。 |
ApplicationIntent |
应用程序意图 | 读写 | ReadOnly 路由到可读的可用性组副本或 Azure SQL 中的只读副本。 |
MultiSubnetFailover |
多子网故障转移 | 假的 | 设置为 true 连接到跨子网的可用性组侦听器时,以实现更快的故障转移。 |
MultipleActiveResultSets |
多个活动结果集 | 假的 | MARS:一个连接上同时打开多个读取器。 |
Pooling |
- | true | 连接池。 |
Max Pool Size |
- | 100 | 每个不同连接字符串的最大连接池连接数。 |
Min Pool Size |
- | 0 | 连接在池中保持打开。 |
ConnectRetryCount |
连接重试次数 | 1 | 空闲连接中断后重连尝试次数为 0 到 255 次。 |
ConnectRetryInterval |
连接重试间隔 | 10 | 两次尝试之间间隔 1 到 60 秒。 |
Persist Security Info |
保留安全信息 | 假的 | true 会把密码以可读形式留在 ConnectionString 打开之后。保持关闭即可。 |
ODBC Driver 18 for SQL Server 关键字
适用于 pyodbc、R、PHP、Excel 以及任何基于 ODBC 的工具。包含特殊字符的值需要包裹 ([]{}(),;?*=!@)括在大括号中。与 ADO.NET 不同,当关键字重复时,第一个出现的优先。
| 关键字 | 同义词 | 默认 | 作用 |
|---|---|---|---|
Driver |
- | - | {ODBC Driver 18 for SQL Server} (或 17)。必须与驱动程序管理器所列的名称一致。 |
Server |
地址、Addr | - | [tcp:]host[\instance][,port]. |
Database |
- | 默认登录名 | 数据库名称。 |
UID / PWD |
- | - | SQL 登录名和密码。 |
Trusted_Connection |
- | 否 | yes 使用 Windows 身份验证。 |
Authentication |
- | - | SqlPassword, ActiveDirectoryIntegrated, ActiveDirectoryInteractive (Windows), ActiveDirectoryMsi, ActiveDirectoryServicePrincipal, ActiveDirectoryPassword (已弃用)。没有 ActiveDirectoryDefault 在 ODBC 中。 |
Encrypt |
- | 是(驱动程序 18),否(17 及更早版本) | yes/mandatory, no/optional, strict (18.1.2.1+). |
TrustServerCertificate |
- | 否 | yes 会跳过证书验证;与下列值同用会被忽略 Encrypt=strict. |
HostnameInCertificate |
- | - | 18.0+。证书中应出现的主机名。 |
ServerCertificate |
- | - | 18.1+。服务器证书必须与之匹配的证书文件。 |
ConnectTimeout |
- | 15 | 18.7+。登录超时(秒);0 表示无限制。较旧的驱动只接受 SQL_ATTR_LOGIN_TIMEOUT 来自代码。 |
APP |
- | - | 应用程序名称。 |
ApplicationIntent |
- | 读写 | ReadOnly 用于可读副本。 |
MultiSubnetFailover |
- | 否 | Yes 用于多子网可用性组。 |
适用于 SQL Server 的 Microsoft JDBC 驱动程序属性
URL 形式: jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value...]。属性名称不区分大小写。包含 ; 要放在大括号里,而且从 8.4 版驱动开始,大括号里的右大括号要写成两个: password={pass;}}word}.
| 关键字 | 同义词 | 默认 | 作用 |
|---|---|---|---|
databaseName |
数据库 | - | 数据库名称。 |
user |
用户名 | - | 登录名。 |
password |
- | - | 密码。 |
integratedSecurity |
- | 假的 | Windows 身份验证。在 Windows 上需要 mssql-jdbc_auth-<version>.dll;在其他地方则添加 authenticationScheme=JavaKerberos. |
authentication |
- | 未指定 | SqlPassword, ActiveDirectoryPassword, ActiveDirectoryIntegrated, ActiveDirectoryInteractive (9.2+), ActiveDirectoryServicePrincipal (9.2+), ActiveDirectoryManagedIdentity (12.2+; ActiveDirectoryMSI 之前)。 |
encrypt |
- | true (10.2+); false (9.4 及更早版本) | true, false,或 strict (11.2+). |
trustServerCertificate |
- | 假的 | true 跳过证书验证。 |
hostNameInCertificate |
- | - | 预期的证书主机名。 |
serverCertificate |
- | - | 11.2+。配套的证书文件,配合严格模式使用。 |
loginTimeout |
- | 30(11.2+),15(旧版本) | 等待登录的秒数。 |
queryTimeout |
- | -1(无限制) | 默认查询超时(秒)。 |
applicationName |
- | 适用于 SQL Server 的 Microsoft JDBC 驱动程序 | 应用程序名称。 |
applicationIntent |
- | 读写 | ReadOnly 用于可读副本。 |
multiSubnetFailover |
- | 假的 | 多子网可用性组。 |
instanceName |
- | - | 命名实例,作为一种替代 host\instance 在 URL 中。 |
go-mssqldb URL 参数
URL 形式: sqlserver://user:password@host:port?database=... 或者 sqlserver://user:password@host/instance?...。路径是实例名,绝不是数据库名。用户名和密码中的特殊字符要做百分号编码。参数名不区分大小写。
| 关键字 | 同义词 | 默认 | 作用 |
|---|---|---|---|
database |
- | - | 数据库名称。 |
encrypt |
- | false(仅登录数据包) | strict, disable (完全没有 TLS), false, true。请注意,此默认值与 Microsoft 自家驱动程序有所不同。 |
TrustServerCertificate |
- | encrypt 已设置时为 false,未设置时为 true | true 跳过证书验证。 |
app name |
- | go-mssqldb | 应用程序名称(在 URL 中写作 app+name 或者 app%20name 在 URL 中)。 |
connection timeout |
- | 0(无) | 整个连接所需的秒数。 |
dial timeout |
- | 每个已注册协议 15 秒 | TCP 拨号所需的秒数。 |
fedauth |
- | - | Entra 方法 (ActiveDirectoryDefault, ActiveDirectoryManagedIdentity, ActiveDirectoryPassword, ...)连同 azuread 包和 azuresql 驱动程序名称。 |
常见的 SQL Server 连接错误
The certificate chain was issued by an authority that is not trusted.
原因: Microsoft.Data.SqlClient 4.0+、ODBC Driver 18 和 JDBC 10.2+ 默认加密并验证服务器证书。服务器正在使用它自动生成的自签名证书,或来自你的计算机不信任的私有 CA 的证书。
修复: 在服务器上安装来自受信任 CA 的证书(或在客户端信任你的内部 CA)。如果证书有效但签发给其他名称,请设置 HostNameInCertificate。仅对于本地开发服务器, TrustServerCertificate=True 就能让你上手。
Login failed for user 'app_user'. (Error 18456)
原因: 密码错误、在只允许 Windows 身份验证的服务器上使用了 SQL 登录、登录被禁用,或者登录打不开默认数据库。服务器日志会以状态编号记录真正的原因。
修复: 检查密码,如果使用 SQL 登录,请启用 SQL Server 和 Windows 身份验证模式,并设置 Database 为登录可以打开的数据库。服务器错误日志中的状态(例如状态 8 = 密码错误,状态 38 = 数据库不可用)能精确定位问题所在。
Keyword not supported: 'host'.
原因: Microsoft.Data.SqlClient 只接受它自己的关键字。 Host, Username 和 Port 是 Npgsql/MySQL 的关键字; Provider= 属于 OLE DB 连接字符串;像 Databse 也会以同样的方式失败。
修复: 使用 Server, User ID,以及 host,port。把字符串粘贴到上面的解码器:每个未知关键字都会被标出来。
Format of the initialization string does not conform to specification starting at index 42.
原因: 一个值包含 ; 或引号,而值没有加引号,于是解析器在错误的位置拆分了字符串。密码通常就是罪魁祸首。
修复: 用双引号把值括起来,值内部的双引号写成两个: Password="p;a""ss"。构建器会为你转义值。
The target principal name is incorrect. Cannot generate SSPI context.
原因: 集成安全性使用 Kerberos,而 SQL Server 服务的服务主体名称 (SPN) 缺失、重复或注册给了其他账户,或者你通过 IP 地址或别名进行连接。
修复: 使用服务器的完全限定名称连接,并让管理员注册 SPN(setspn -L <service account> 将其列出)。如果证书名称不匹配,还要检查 HostNameInCertificate.
SQL Server 连接字符串常见问题解答
SQL Server 的默认端口是多少?
默认实例为 1433。命名实例通常使用动态端口,SQL Server Browser(UDP 1434)会告知客户端,因此 host\instance 无需端口也能工作。在 ADO.NET 和 ODBC 中,端口在逗号后指定: Server=host,1433.
我应该使用 Encrypt=True 还是 TrustServerCertificate=True?
使用 Encrypt=True (或者 Strict 在 SQL Server 2022 和 Azure SQL 上) 使用客户端信任的证书。 TrustServerCertificate=True 仍会加密流量,但客户端不再校验对方是谁,因此任何能拦截连接的人都可能冒充服务器。本地开发时可以留着这个选项。
在 Microsoft.Data.SqlClient 4.0 中 Encrypt 有什么变化?
默认适用于 Encrypt 已从 false 到 true,而且驱动程序会默认验证服务器证书。ODBC Driver 18 和 JDBC Driver 10.2 也做了同样的改动。没有使用 Encrypt 关键字,过去不用 TLS 就能连接的字符串,现在需要服务器上有受信任的证书。
如何使用 Microsoft Entra ID 连接到 Azure SQL 数据库?
添加 Authentication=Active Directory Default (自动获取托管标识、环境凭据或你的 Azure CLI / Visual Studio 登录凭据)并省略密码。使用 Active Directory Managed Identity 在 Azure 托管的应用中,以及 Active Directory Interactive 用于浏览器登录。Azure SQL 不接受 Integrated Security=SSPI.
数据源(Data Source)和服务器(Server)、初始目录(Initial Catalog)和数据库(Database)有什么区别?
没有区别。它们在 Microsoft.Data.SqlClient 中是同义词, User ID / UID / User 和 Password / PWD也是如此。如果两种写法都出现,则以最后一个为准。
System.Data.SqlClient 使用相同的连接字符串吗?
大体支持。它接受经典关键字,但不支持较新的关键字,例如 Command Timeout, Encrypt=Strict, HostNameInCertificate 或大多数 Authentication 值,默认为 Encrypt=False。Microsoft 建议迁移到 Microsoft.Data.SqlClient。
连接一次。之后只管写 SQL。
SQLly 是适用于 macOS、Windows 和 Linux 的原生 SQL 工作台。在连接编辑器中粘贴连接字符串,把密码保存在系统钥匙串里,并在 SQL Server 等引擎上获得模式感知的 IntelliSense。