@@ -8,50 +8,109 @@ Configure and establish connections to Microsoft SQL Server.
88
99## Configuration
1010
11+ ### Programmatic configuration
12+
1113``` swift
1214import MSSQLNio
1315
1416var config = MSSQLConnection.Configuration (
15- host : " sqlserver.example.com"
16- port : 1433 , // default
17- database : " AdventureWorks"
18- username : " sa"
19- password : " YourStrongPassword!"
17+ host : " sqlserver.example.com"
18+ port : 1433 , // default
19+ database : " AdventureWorks"
20+ username : " sa"
21+ password : " YourStrongPassword!"
22+ trustServerCertificate : false // true = skip cert verification
2023)
2124
2225// Optional settings
23- config.tls = .prefer // .require / .prefer / .disable
24- config.connectTimeout = 30 // seconds (default: 30)
25- config.queryTimeout = nil // per-query timeout in seconds (nil = no limit)
26- config.readOnly = false // mark connection as read-only hint
26+ config.tls = .prefer // .require / .prefer / .disable
27+ config.connectTimeout = 30 // seconds (default: 30)
28+ config.queryTimeout = nil // per-query timeout (nil = no limit)
29+ config.readOnly = false // read-only hint for AG replicas
2730
2831let conn = try await MSSQLConnection.connect (configuration : config)
2932defer { Task { try ? await conn.close () } }
3033```
3134
35+ ### Connection string
36+
37+ You can also initialise directly from a standard SQL Server connection string:
38+
39+ ``` swift
40+ let config = try MSSQLConnection.Configuration (connectionString :
41+ " Server=sqlserver.example.com,1433;Database=AdventureWorks;" +
42+ " User Id=sa;Password=YourStrongPassword!;" +
43+ " Encrypt=True;TrustServerCertificate=False;Connect Timeout=30;"
44+ )
45+ let conn = try await MSSQLConnection.connect (configuration : config)
46+ ```
47+
48+ Supported keys (case-insensitive):
49+
50+ | Key | Aliases | Values |
51+ | -----| ---------| --------|
52+ | ` Server ` | ` Data Source ` | ` host ` or ` host,port ` |
53+ | ` Database ` | ` Initial Catalog ` | database name |
54+ | ` User Id ` | ` UID ` | username |
55+ | ` Password ` | ` PWD ` | password |
56+ | ` Domain ` | — | enables NTLM/Windows auth |
57+ | ` Encrypt ` | — | ` True ` /` False ` /` Disable ` /` Strict ` /` Request ` |
58+ | ` TrustServerCertificate ` | — | ` True ` skips cert verification |
59+ | ` Connect Timeout ` | ` Connection Timeout ` | seconds |
60+ | ` Application Intent ` | — | ` ReadOnly ` |
61+
62+ ## TLS and TrustServerCertificate
63+
64+ Self-signed certificates (common in dev/test environments including Docker) require ` TrustServerCertificate=True ` :
65+
66+ ``` swift
67+ // Via init:
68+ let config = MSSQLConnection.Configuration (
69+ host : " 127.0.0.1" database : " MyDb"
70+ username : " sa" password : " pass"
71+ trustServerCertificate : true // skip cert verification for self-signed certs
72+ )
73+
74+ // Via connection string:
75+ let config = try MSSQLConnection.Configuration (connectionString :
76+ " Server=127.0.0.1;Database=MyDb;User Id=sa;Password=pass;" +
77+ " Encrypt=True;TrustServerCertificate=True;"
78+ )
79+ ```
80+
81+ ## Reachability Check
82+
83+ Perform a fast TCP-level pre-flight check before attempting a full TDS connection:
84+
85+ ``` swift
86+ // On Configuration (recommended):
87+ try await config.checkReachability () // throws SQLError.connectionError if unreachable
88+ let conn = try await MSSQLConnection.connect (configuration : config)
89+
90+ // Static version with explicit host/port:
91+ try await MSSQLConnection.checkReachability (host : " sqlserver.example.com" port : 1433 , timeout : 5 )
92+ ```
93+
3294## Azure SQL Database
3395
34- Azure SQL uses the same TDS protocol. Append the server suffix to the host name and ensure TLS is enabled :
96+ Azure SQL uses the same TDS protocol. Append the server suffix to the host and require TLS:
3597
3698``` swift
37- var config = MSSQLConnection.Configuration (
38- host : " myserver.database.windows.net"
39- database : " mydb"
40- username : " myuser@myserver"
41- password : " AzurePassword!"
99+ let config = try MSSQLConnection.Configuration (connectionString :
100+ " Server=myserver.database.windows.net;Database=mydb;" +
101+ " User Id=myuser@myserver;Password=AzurePassword!;" +
102+ " Encrypt=True;TrustServerCertificate=False;"
42103)
43- config.tls = .require // Azure requires TLS
44104```
45105
46106## Named Instances
47107
48108SQL Server named instances listen on a dynamic port. Resolve the port first (via SQL Server Browser on UDP 1434), then connect directly:
49109
50110``` swift
51- // After resolving the named instance port:
52111let config = MSSQLConnection.Configuration (
53- host : " sqlserver.example.com"
54- port : 52108 , // resolved instance port
112+ host : " sqlserver.example.com"
113+ port : 52108 , // resolved instance port
55114 database : " MyDb"
56115 username : " sa"
57116 password : " pass"
@@ -68,10 +127,10 @@ let conn = try await MSSQLConnection.connect(configuration: config)
68127// Using defer (recommended for scoped use):
69128defer { Task { try ? await conn.close () } }
70129
71- // Or explicit close at the end of a Task :
130+ // Or explicit close:
72131try await conn.close ()
73132
74- // Check if still open
133+ // Check if still open:
75134if conn.isOpen {
76135 let rows = try await conn.query (" SELECT GETDATE() AS now"
77136}
0 commit comments