Skip to content

Commit f5bd9ab

Browse files
rwestMSFTrwestMSFT
committed
Edit pass, remove info box stacking
1 parent d7cfb9a commit f5bd9ab

1 file changed

Lines changed: 48 additions & 49 deletions

File tree

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

Lines changed: 48 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
---
2-
title: "MSOLEDBSQL major version differences"
2+
title: "MSOLEDBSQL Major Version Differences"
33
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: 01/29/2026
6+
ms.reviewer: randolphwest
7+
ms.date: 01/30/2026
78
ms.service: sql
89
ms.subservice: connectivity
910
ms.topic: "reference"
@@ -17,90 +18,88 @@ helpviewer_keywords:
1718

1819
This article describes breaking changes between Microsoft OLE DB Driver 19 for SQL Server and earlier versions.
1920

20-
> [!TIP]
21+
> [!TIP]
2122
> **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.
2223
2324
## Summary of changes
2425

2526
| Area | Version 18 and earlier | Version 19+ |
26-
| ---- | ---------------------- | ----------- |
27+
| --- | --- | --- |
2728
| Default encryption | `Optional` (unencrypted) | `Mandatory` (encrypted) |
2829
| `Encrypt` property type | `VT_BOOL` | `VT_BSTR` |
2930
| `Encrypt` valid values | `no`/`yes` | `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict` |
3031
| Certificate validation | Skipped when client sets `Encrypt=no` | Always evaluated when encryption occurs |
3132
| Driver name | `MSOLEDBSQL` | `MSOLEDBSQL19` |
3233
| CLSID | `MSOLEDBSQL_CLSID` (legacy) | `MSOLEDBSQL_CLSID` (updated in header) |
3334

34-
> [!WARNING]
35-
> **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.
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.
3637
3738
## Encryption property changes
3839

3940
### Encrypt property type change
4041

4142
The driver property `SSPROP_INIT_ENCRYPT` changes from `VT_BOOL` to `VT_BSTR`.
4243

43-
| Connection string | Version 18 values | Version 19 values |
44-
| ------------------------------------------ | ----------------- | --------------------------------------------------------- |
45-
| Provider: `Encrypt` | `no`/`yes` | `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict` |
46-
| IDataInitialize: `Use Encryption for Data` | `true`/`false` | `no`/`yes`/`true`/`false`/`Optional`/`Mandatory`/`Strict` |
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` |
4748

48-
**Value mapping:**
49+
**Value mapping**:
4950

5051
| Mode | Equivalent values | Behavior |
51-
| ---- | ----------------- | -------- |
52+
| --- | --- | --- |
5253
| `Optional` | `no`, `false` | Unencrypted unless server requires it |
5354
| `Mandatory` (default) | `yes`, `true` | Encrypted connection required |
5455
| `Strict` | *(no equivalent)* | TDS 8.0 encryption; requires SQL Server 2022+ |
5556

56-
> [!TIP]
57+
> [!TIP]
5758
> 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).
5859
59-
> [!NOTE]
60-
> For backward compatibility, version 19 accepts all version 18 values (`yes`/`no`) in addition to the new values (`Optional`/`Mandatory`/`Strict`).
60+
For backward compatibility, version 19 accepts all version 18 values (`yes`/`no`) in addition to the new values (`Optional`/`Mandatory`/`Strict`).
6161

6262
### Default encryption behavior
6363

6464
| Version | Default | Result |
65-
| ------- | ------- | ------ |
65+
| --- | --- | --- |
6666
| 18 and earlier | `no` | Connections unencrypted by default |
6767
| 19+ | `Mandatory` | Connections encrypted by default |
6868

69-
To restore version 18 behavior, add one of these to your connection string:
69+
To restore version 18 behavior, add one of these options to your connection string:
7070

7171
- Provider: `Encrypt=Optional;`
7272
- IDataInitialize: `Use Encryption for Data=Optional;`
7373

7474
### Certificate validation behavior
7575

7676
| Scenario | Version 18 | Version 19+ |
77-
| -------- | ---------- | ----------- |
77+
| --- | --- | --- |
7878
| Client sets `Encrypt=no`, server doesn't force encryption | No validation | No validation |
7979
| Client sets `Encrypt=no`, server forces encryption | `Trust Server Certificate` **ignored** | `Trust Server Certificate` **evaluated** |
8080
| Client sets `Encrypt=yes` | `Trust Server Certificate` evaluated | `Trust Server Certificate` evaluated |
8181

82-
> [!IMPORTANT]
83-
> 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.
82+
#### Compatibility notes
8483

85-
> [!NOTE]
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.
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.
8785

88-
> [!NOTE]
89-
> 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 occurred, the driver would use the more secure registry setting, which could make connection string options appear to have no effect. This 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).
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.
9087

91-
> [!TIP]
92-
> Keyword format differs by interface:
93-
> - Provider connection strings use no spaces: `TrustServerCertificate=yes;`
94-
> - IDataInitialize connection strings use spaces: `Trust Server Certificate=yes;`
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).
9589

96-
For more information, see [Encryption and certificate validation](features/encryption-and-certificate-validation.md).
90+
Keyword format differs by interface:
9791

98-
### Registry Force Protocol Encryption
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
9998

10099
The **Force Protocol Encryption** registry setting uses numeric values that map to encryption modes:
101100

102101
| Registry value | Encryption mode | Description |
103-
| -------------- | --------------- | ----------- |
102+
| --- | --- | --- |
104103
| `0` | `Optional` | Encryption only if server requires it |
105104
| `1` | `Mandatory` | Encryption required |
106105
| `2` | `Strict` | TDS 8.0 encryption |
@@ -112,19 +111,19 @@ The driver uses the most secure option between the registry setting and the conn
112111
Version 19 supports side-by-side installation with version 18. The driver name includes the major version number for differentiation.
113112

114113
| Interface | Version 18 | Version 19 |
115-
| --------- | ---------- | ---------- |
114+
| --- | --- | --- |
116115
| Provider keyword | `MSOLEDBSQL` | `MSOLEDBSQL19` |
117116
| CLSID constant | `MSOLEDBSQL_CLSID` | `MSOLEDBSQL_CLSID` (updated in `msoledbsql.h`) |
118117
| UI display name | Microsoft OLE DB Driver for SQL Server | Microsoft OLE DB Driver 19 for SQL Server |
119118

120-
**Migration steps:**
119+
### Migration steps
121120

122121
1. Include the updated `msoledbsql.h` header in your project.
123122
1. For `IDBInitialize`: No changes needed (CLSID updated in header).
124123
1. For `IDataInitialize`: Change `Provider=MSOLEDBSQL` to `Provider=MSOLEDBSQL19`.
125124
1. For UI tools (SSMS, data link properties): Select **Microsoft OLE DB Driver 19 for SQL Server**.
126125

127-
**Connection string examples:**
126+
### Connection string examples
128127

129128
Version 18 (before):
130129

@@ -159,25 +158,25 @@ Version 19 introduces properties for enhanced certificate validation with `Stric
159158
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).
160159

161160
| Interface | Property |
162-
| --------- | -------- |
161+
| --- | --- |
163162
| Provider keyword | `HostNameInCertificate` |
164163
| IDataInitialize keyword | `Host Name In Certificate` |
165164
| OLE DB property | `SSPROP_INIT_HOST_NAME_CERTIFICATE` |
166165

167-
> [!NOTE]
166+
> [!NOTE]
168167
> This property is ignored when `Trust Server Certificate` is enabled. When `Encrypt=Strict`, the certificate is always validated.
169168
170169
### ServerCertificate (v19.2.0+)
171170

172171
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.
173172

174173
| Interface | Property |
175-
| --------- | -------- |
174+
| --- | --- |
176175
| Provider keyword | `ServerCertificate` |
177176
| IDataInitialize keyword | `Server Certificate` |
178177
| OLE DB property | `SSPROP_INIT_SERVER_CERTIFICATE` |
179178

180-
> [!IMPORTANT]
179+
> [!IMPORTANT]
181180
> `ServerCertificate` can only be used when `Encrypt=Strict`. Attempting to use it with `Mandatory` or `Optional` encryption results in a connection error.
182181
183182
## Deprecated authentication methods
@@ -186,18 +185,18 @@ Specifies the path to a certificate file (PEM, DER, or CER format) for exact cer
186185

187186
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.
188187

189-
> [!WARNING]
188+
> [!WARNING]
190189
> 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).
191190
192-
**Recommended alternatives:**
191+
#### Recommended alternatives
193192

194193
| Scenario | Recommended authentication | Connection string keyword |
195-
| -------- | -------------------------- | ------------------------- |
194+
| --- | --- | --- |
196195
| Interactive user context | Multifactor authentication | `Authentication=ActiveDirectoryInteractive` |
197196
| App running on Azure | Managed Identity | `Authentication=ActiveDirectoryMSI` |
198197
| Service/daemon without user | Service Principal | `Authentication=ActiveDirectoryServicePrincipal` |
199198

200-
For more information, see [Using Microsoft Entra ID](features/using-azure-active-directory.md).
199+
For more information, see [Use Microsoft Entra ID](features/using-azure-active-directory.md).
201200

202201
## Troubleshooting
203202

@@ -240,12 +239,12 @@ For more information, see [Using Microsoft Entra ID](features/using-azure-active
240239
- Update your connection string from `Provider=MSOLEDBSQL` to `Provider=MSOLEDBSQL19`.
241240
- Include the updated `msoledbsql.h` header if using `IDBInitialize` with the CLSID.
242241

243-
## See also
242+
## Related content
244243

245-
- [OLE DB Driver for SQL Server](oledb-driver-for-sql-server.md)
246-
- [Using Connection String Keywords with OLE DB Driver](applications/using-connection-string-keywords-with-oledb-driver-for-sql-server.md)
247-
- [Encryption and certificate validation](features/encryption-and-certificate-validation.md)
248-
- [Universal Data Link (UDL) Configuration](help-topics/data-link-pages.md)
249-
- [SQL Server Login Dialog Box (OLE DB)](help-topics/sql-server-login-dialog.md)
250-
- [Initialization and authorization properties (OLE DB driver)](ole-db-data-source-objects/initialization-and-authorization-properties.md)
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)
251250
- [Registry settings](features/registry-settings.md)

0 commit comments

Comments
 (0)