Skip to content

Commit f5927df

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #36496 from dlevy-msft-sql/dlevy-oledb-major-version-restructure
Restructure OLE DB major version differences for readability
2 parents 21d7ed0 + beb6cc7 commit f5927df

1 file changed

Lines changed: 228 additions & 18 deletions

File tree

‎docs/connect/oledb/major-version-differences.md‎

Lines changed: 228 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
---
2-
title: "MSOLEDBSQL major version differences"
3-
description: A description of the differences between the OLE DB Driver 19 for SQL Server and the OLE DB Driver for SQL Server
2+
title: "MSOLEDBSQL Major Version Differences"
3+
description: Learn about breaking changes between OLE DB Driver 19 and version 18, including encryption defaults, property type changes, and migration steps.
44
author: David-Engel
55
ms.author: davidengel
6-
ms.date: 05/02/2025
6+
ms.reviewer: randolphwest
7+
ms.date: 01/30/2026
78
ms.service: sql
89
ms.subservice: connectivity
910
ms.topic: "reference"
@@ -15,26 +16,235 @@ helpviewer_keywords:
1516
---
1617
# Major version differences
1718

19+
This article describes breaking changes between Microsoft OLE DB Driver 19 for SQL Server and earlier versions.
20+
21+
> [!TIP]
22+
> **MSOLEDBSQL19** (Microsoft OLE DB Driver 19 for SQL Server) is the current recommended OLE DB driver. It supports TDS 8.0 and modern security features. Version 19.2.0+ also supports TLS 1.3. Use `Provider=MSOLEDBSQL19` in your connection strings.
23+
24+
## Summary of changes
25+
26+
| Area | Version 18 and earlier | Version 19+ |
27+
| --- | --- | --- |
28+
| Default encryption (`Encrypt`) setting | `no` (no encryption or the server can require encryption) | `Mandatory` (encryption required) |
29+
| `Encrypt` property type | `VT_BOOL` | `VT_BSTR` |
30+
| `Encrypt` valid values | `no`/`yes` | `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict` |
31+
| Certificate validation | Skipped when client sets `Encrypt=no` | Always evaluated when encryption occurs |
32+
| Driver name | `MSOLEDBSQL` | `MSOLEDBSQL19` |
33+
| CLSID | `MSOLEDBSQL_CLSID` (legacy) | `MSOLEDBSQL_CLSID` (updated in header) |
34+
35+
> [!WARNING]
36+
> **ActiveDirectoryPassword authentication is deprecated**. If you're migrating from version 18 to 19 and using `Authentication=ActiveDirectoryPassword`, plan to migrate to a more secure authentication method. See [Deprecated authentication methods](#deprecated-authentication-methods) for alternatives.
37+
1838
## Encryption property changes
1939

20-
In the Microsoft OLE DB Driver 19 for SQL Server, there are changes to the `Encrypt` property/connection string keyword and certificate validation behavior.
40+
### Encrypt property type change
41+
42+
The driver property `SSPROP_INIT_ENCRYPT` changes from `VT_BOOL` to `VT_BSTR`.
43+
44+
| Connection string | Version 18 values | Version 19 values |
45+
| --- | --- | --- |
46+
| Provider: `Encrypt` | `no`/`yes` | `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict` |
47+
| IDataInitialize: `Use Encryption for Data` | `true`/`false` | `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict` |
48+
49+
**Value mapping**:
50+
51+
| Mode | Equivalent values | Behavior |
52+
| --- | --- | --- |
53+
| `Optional` | `no`, `false` | Unencrypted unless server requires it |
54+
| `Mandatory` (default) | `yes`, `true` | Encrypted connection required |
55+
| `Strict` | *(no equivalent)* | TDS 8.0 encryption; requires SQL Server 2022+ |
56+
57+
> [!TIP]
58+
> Starting with version 19.2.0, TDS 8.0 connections can use TLS 1.3 when connecting to SQL Server 2022 or later. The `ServerCertificate` property was also added in this version. For more information, see [TLS 1.3 support](../../relational-databases/security/networking/tls-1-3.md).
59+
60+
For backward compatibility, version 19 accepts all version 18 values (`yes`/`no`) in addition to the new values (`Optional`/`Mandatory`/`Strict`).
61+
62+
### Default encryption behavior
63+
64+
| Version | Default | Result |
65+
| --- | --- | --- |
66+
| 18 and earlier | `no` | Connections unencrypted by default |
67+
| 19+ | `Mandatory` | Connections encrypted by default |
68+
69+
To restore version 18 behavior, add one of these options to your connection string:
70+
71+
- Provider: `Encrypt=Optional;`
72+
- IDataInitialize: `Use Encryption for Data=Optional;`
73+
74+
### Certificate validation behavior
75+
76+
| Scenario | Version 18 | Version 19+ |
77+
| --- | --- | --- |
78+
| Client sets `Encrypt=no`, server doesn't force encryption | No validation | No validation |
79+
| Client sets `Encrypt=no`, server forces encryption | `Trust Server Certificate` **ignored** | `Trust Server Certificate` **evaluated** |
80+
| Client sets `Encrypt=yes` | `Trust Server Certificate` evaluated | `Trust Server Certificate` evaluated |
81+
82+
#### Compatibility notes
83+
84+
Version 19 clients using default settings fail to connect when the server forces encryption and uses an untrusted certificate. Update your `Trust Server Certificate` setting or use a trusted certificate.
2185

22-
First, the driver property `SSPROP_INIT_ENCRYPT` changes from a `VT_BOOL` to a `VT_BSTR`. The valid values of this property are `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict`. The valid values for the provider connection string keyword `Encrypt` change from `no`/`yes` to `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict`. Similarly, for the `IDataInitialize` connection string keyword `Use Encryption for Data`, the valid values change from `true`/`false` to `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict`. The `Optional` value is synonymous with the old `no`/`false` values and the `Mandatory` value is synonymous with the old `yes`/`true` values. `Strict` is a new value added in version 19.0.0 of the OLE DB Driver for SQL Server and encrypts `PRELOGIN` packets in addition to all other communication with the server. `Strict` encryption is only supported on SQL Server endpoints that support TDS 8.0, otherwise the driver fails to connect. The OLE DB Driver 19 for SQL Server continues to support all legacy keyword values for backwards compatibility.
86+
`TrustServerCertificate` was **not removed** in version 19. The option still works. Version 18 ignored this setting when `Encrypt` was set to `no`, even when the server forced encryption. Version 19 now evaluates `TrustServerCertificate` in all encrypted scenarios.
2387

24-
Second, the default value changes from `no`/`false` to `Mandatory`. This change means that connections are encrypted by default. Previously, the driver would encrypt connections if explicitly set by the user and/or mandated by the SQL Server when the server side property `Force Encryption` was set to `yes`. To use old default behavior, include `Encrypt=Optional;` in the provider connection string, or `Use Encryption for Data=Optional;` in the `IDataInitialize` connection string.
88+
The version 19 driver, before 19.4.1, had an installer issue that could set the `TrustServerCertificate` registry option to `no` on systems that previously had v18 installed. When this problem occurred, the driver would use the more secure registry setting, which could make connection string options appear to have no effect. This issue was resolved in version 19.4.1. A fresh installation of v19 (without v18 present) always correctly defaulted the registry option to `yes`. For more information, see [Registry settings](features/registry-settings.md).
2589

26-
Third, the `Trust Server Certificate` option is disconnected from the `Encrypt`/`Use Encryption for Data` option. In previous versions, when `Encrypt` was `false` on the client, the `Trust Server Certificate` setting was always ignored, even if the server required encryption (the server-side `Force Encryption` setting). Starting with version 19, if either the client or the server negotiates encryption on the connection, the `Trust Server Certificate` setting is evaluated to determine whether the client validates the certificate. This behavior change causes version 19 clients that use default settings to fail to connect when the server forces encryption and uses an untrusted certificate (an insecure server configuration). Clients must change their `Trust Server Certificate` registry setting and connection option to connect to servers configured that way. For more information, see [Registry settings](features/registry-settings.md) and [Encryption and certificate validation](features/encryption-and-certificate-validation.md)
90+
Keyword format differs by interface:
91+
92+
- Provider connection strings use no spaces: `TrustServerCertificate=yes;`
93+
- IDataInitialize connection strings use spaces: `Trust Server Certificate=yes;`
94+
95+
For more information, see [Encryption and certificate validation in OLE DB](features/encryption-and-certificate-validation.md).
96+
97+
### Registry settings for Force Protocol Encryption
98+
99+
The **Force Protocol Encryption** registry setting uses numeric values that map to encryption modes:
100+
101+
| Registry value | Encryption mode | Description |
102+
| --- | --- | --- |
103+
| `0` | `Optional` | Encryption only if server requires it |
104+
| `1` | `Mandatory` | Encryption required |
105+
| `2` | `Strict` | TDS 8.0 encryption |
106+
107+
The driver uses the most secure option between the registry setting and the connection property. For registry key locations, see [Registry settings](features/registry-settings.md).
27108

28109
## Driver name changes
29110

30-
The new Microsoft OLE DB Driver 19 for SQL Server supports side by side installation with the older Microsoft OLE DB Driver for SQL Server. To be able to differentiate the drivers, the name was changed to include the major version number. To use the new driver in an application, the user must specify the new driver name. The new driver name, along with the corresponding CLSID, is specified in the updated `msoledbsql.h` header that must be included in the project. Connections through the `IDBInitialize` interface require no further changes since `MSOLEDBSQL_CLSID` specifies the CLSID of the OLE DB Driver 19 for SQL Server. Connections through the `IDataInitialize` interface must replace the value of the `Provider` keyword with `MSOLEDBSQL19` to use the Microsoft OLE DB Driver 19 for SQL Server. In graphical user interfaces such as data link properties or linked server setup in SSMS, "Microsoft OLE DB Driver 19 for SQL Server" must be selected from the list of installed providers.
31-
32-
## See also
33-
[OLE DB Driver for SQL Server](oledb-driver-for-sql-server.md)
34-
[Using Connection String Keywords with OLE DB Driver](applications/using-connection-string-keywords-with-oledb-driver-for-sql-server.md)
35-
[Encryption and certificate validation](features/encryption-and-certificate-validation.md)
36-
[Universal Data Link (UDL) Configuration](help-topics/data-link-pages.md)
37-
[SQL Server Login Dialog Box (OLE DB)](help-topics/sql-server-login-dialog.md)
38-
[Initialization and authorization properties (OLE DB driver)](ole-db-data-source-objects/initialization-and-authorization-properties.md)
39-
[Registry settings](features/registry-settings.md)
40-
111+
Version 19 supports side-by-side installation with version 18. The driver name includes the major version number for differentiation.
112+
113+
| Interface | Version 18 | Version 19 |
114+
| --- | --- | --- |
115+
| Provider keyword | `MSOLEDBSQL` | `MSOLEDBSQL19` |
116+
| CLSID constant | `MSOLEDBSQL_CLSID` | `MSOLEDBSQL_CLSID` (updated in `msoledbsql.h`) |
117+
| UI display name | Microsoft OLE DB Driver for SQL Server | Microsoft OLE DB Driver 19 for SQL Server |
118+
119+
### Migration steps
120+
121+
1. Include the updated `msoledbsql.h` header in your project.
122+
1. For `IDBInitialize`: No changes needed (CLSID updated in header).
123+
1. For `IDataInitialize`: Change `Provider=MSOLEDBSQL` to `Provider=MSOLEDBSQL19`.
124+
1. For UI tools (SSMS, data link properties): Select **Microsoft OLE DB Driver 19 for SQL Server**.
125+
126+
### Connection string examples
127+
128+
Version 18 (before):
129+
130+
```text
131+
Provider=MSOLEDBSQL;Server=myserver;Database=mydb;Trusted_Connection=yes;
132+
```
133+
134+
Version 19 (after):
135+
136+
```text
137+
Provider=MSOLEDBSQL19;Server=myserver;Database=mydb;Trusted_Connection=yes;
138+
```
139+
140+
Version 19 with explicit encryption settings:
141+
142+
```text
143+
Provider=MSOLEDBSQL19;Server=myserver;Database=mydb;Encrypt=Mandatory;TrustServerCertificate=no;
144+
```
145+
146+
Version 19 with Strict encryption (TDS 8.0):
147+
148+
```text
149+
Provider=MSOLEDBSQL19;Server=myserver;Database=mydb;Encrypt=Strict;ServerCertificate=C:\certs\server.cer;
150+
```
151+
152+
## New version 19 properties
153+
154+
Version 19 introduces properties for enhanced certificate validation with `Strict` encryption mode.
155+
156+
### HostNameInCertificate (v19.0.0+)
157+
158+
Specifies the host name to validate against the server's TLS/SSL certificate. Use this property when the server name in the connection string differs from the certificate's Common Name (CN) or Subject Alternative Name (SAN).
159+
160+
| Interface | Property |
161+
| --- | --- |
162+
| Provider keyword | `HostNameInCertificate` |
163+
| IDataInitialize keyword | `Host Name In Certificate` |
164+
| OLE DB property | `SSPROP_INIT_HOST_NAME_CERTIFICATE` |
165+
166+
> [!NOTE]
167+
> This property is ignored when `Trust Server Certificate` is enabled. When `Encrypt=Strict`, the certificate is always validated.
168+
169+
### ServerCertificate (v19.2.0+)
170+
171+
Specifies the path to a certificate file (PEM, DER, or CER format) for exact certificate matching. The driver compares this certificate against the server's certificate during the TLS handshake.
172+
173+
| Interface | Property |
174+
| --- | --- |
175+
| Provider keyword | `ServerCertificate` |
176+
| IDataInitialize keyword | `Server Certificate` |
177+
| OLE DB property | `SSPROP_INIT_SERVER_CERTIFICATE` |
178+
179+
> [!IMPORTANT]
180+
> `ServerCertificate` can only be used when `Encrypt=Strict`. Attempting to use it with `Mandatory` or `Optional` encryption results in a connection error.
181+
182+
## Deprecated authentication methods
183+
184+
### ActiveDirectoryPassword
185+
186+
The `ActiveDirectoryPassword` authentication method (Microsoft Entra ID Password authentication) is deprecated. This authentication is based on the [OAuth 2.0 Resource Owner Password Credentials (ROPC) grant](/entra/identity-platform/v2-oauth-ropc), which is incompatible with multifactor authentication (MFA) and poses security risks.
187+
188+
> [!WARNING]
189+
> Microsoft is moving away from this high-risk authentication flow to protect users from malicious attacks. Plan to migrate to a more secure authentication method before this option is removed. For more information, see [Planning for mandatory multifactor authentication for Azure](/entra/identity/authentication/concept-mandatory-multifactor-authentication).
190+
191+
#### Recommended alternatives
192+
193+
| Scenario | Recommended authentication | Connection string keyword |
194+
| --- | --- | --- |
195+
| Interactive user context | Multifactor authentication | `Authentication=ActiveDirectoryInteractive` |
196+
| App running on Azure | Managed Identity | `Authentication=ActiveDirectoryMSI` |
197+
| Service/daemon without user | Service Principal | `Authentication=ActiveDirectoryServicePrincipal` |
198+
199+
For more information, see [Use Microsoft Entra ID](features/using-azure-active-directory.md).
200+
201+
## Troubleshooting
202+
203+
### Connection fails with certificate validation error
204+
205+
**Symptom**: Connection fails with a certificate validation error or untrusted certificate message.
206+
207+
**Cause**: Version 19 defaults to `Encrypt=Mandatory`, which requires a valid server certificate. Version 18 defaulted to `Encrypt=no` (unencrypted).
208+
209+
**Solutions**:
210+
211+
- **Recommended**: Install a trusted certificate on the server.
212+
- **Development only**: Add `TrustServerCertificate=yes;` to your connection string (not recommended for production).
213+
- **Fallback**: Add `Encrypt=Optional;` to restore version 18 behavior (reduces security).
214+
215+
### Connection fails with "Server Certificate can only be used with strict encryption"
216+
217+
**Symptom**: Connection fails when you use the `ServerCertificate` property.
218+
219+
**Cause**: The `ServerCertificate` property requires `Encrypt=Strict`.
220+
221+
**Solution**: Either remove `ServerCertificate` from your connection string, or change to `Encrypt=Strict;`.
222+
223+
### Application receives VT_BOOL error when setting Encrypt property
224+
225+
**Symptom**: Setting `SSPROP_INIT_ENCRYPT` with a boolean value fails.
226+
227+
**Cause**: Version 19 changed the property type from `VT_BOOL` to `VT_BSTR`.
228+
229+
**Solution**: Use string values (`"Mandatory"`, `"Optional"`, `"Strict"`, `"yes"`, `"no"`) instead of boolean values.
230+
231+
### Provider not found after upgrading
232+
233+
**Symptom**: Application fails with "Provider not found" or similar error.
234+
235+
**Cause**: Version 19 uses a different provider name (`MSOLEDBSQL19`).
236+
237+
**Solutions**:
238+
239+
- Update your connection string from `Provider=MSOLEDBSQL` to `Provider=MSOLEDBSQL19`.
240+
- Include the updated `msoledbsql.h` header if using `IDBInitialize` with the CLSID.
241+
242+
## Related content
243+
244+
- [Microsoft OLE DB Driver for SQL Server](oledb-driver-for-sql-server.md)
245+
- [Using connection string keywords with OLE DB Driver for SQL Server](applications/using-connection-string-keywords-with-oledb-driver-for-sql-server.md)
246+
- [Encryption and certificate validation in OLE DB](features/encryption-and-certificate-validation.md)
247+
- [Universal Data Link (UDL) configuration](help-topics/data-link-pages.md)
248+
- [SQL Server Login dialog box (OLE DB)](help-topics/sql-server-login-dialog.md)
249+
- [Initialization and authorization properties](ole-db-data-source-objects/initialization-and-authorization-properties.md)
250+
- [Registry settings](features/registry-settings.md)

0 commit comments

Comments
 (0)