Skip to content

Commit 5c9376a

Browse files
CopilotAndriySvyryd
Copilot
and
AndriySvyryd
authored
Document SQLitePCLRaw 3.x breaking changes for Microsoft.Data.Sqlite 11.0 (#5300)
Fixes #5108 Co-authored-by: AndriySvyryd <6539701+AndriySvyryd@users.noreply.github.com>
1 parent efc9dc2 commit 5c9376a

1 file changed

Lines changed: 126 additions & 0 deletions

File tree

‎entity-framework/core/what-is-new/ef-core-11.0/breaking-changes.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@ This page documents API and behavior changes that have the potential to break ex
1616

1717
## Summary
1818

19+
> [!NOTE]
20+
> If you are using Microsoft.Data.Sqlite, please see the [separate section below on Microsoft.Data.Sqlite breaking changes](#MDS-breaking-changes).
21+
1922
| **Breaking change** | **Impact** |
2023
|:--------------------------------------------------------------------------------------------------------------- | -----------|
2124
| [Sync I/O via the Azure Cosmos DB provider has been fully removed](#cosmos-nosync) | Medium |
@@ -43,3 +46,126 @@ Synchronous blocking on asynchronous methods ("sync-over-async") is highly disco
4346
##### Mitigations
4447

4548
Convert your code to use async I/O APIs instead of sync I/O ones. For example, replace calls to `SaveChanges()` with `await SaveChangesAsync()`.
49+
50+
<a name="MDS-breaking-changes"></a>
51+
52+
## Microsoft.Data.Sqlite breaking changes
53+
54+
> [!NOTE]
55+
> [SQLitePCLRaw](https://github.com/ericsink/SQLitePCL.raw) is an external, community-maintained library that is not owned or maintained by Microsoft. Microsoft.Data.Sqlite depends on it for its SQLite connectivity.
56+
57+
### Summary
58+
59+
| **Breaking change** | **Impact** |
60+
|:----------------------------------------------------------------------------------------------------------|------------|
61+
| [Encryption-enabled SQLite packages have been removed](#sqlite-encryption-removed) | Medium |
62+
| [Some SQLitePCLRaw bundle packages have been removed](#sqlite-bundles-removed) | Medium |
63+
64+
### Medium-impact changes
65+
66+
<a name="sqlite-encryption-removed"></a>
67+
68+
#### Encryption-enabled SQLite packages have been removed
69+
70+
[Tracking Issue #5108](https://github.com/dotnet/EntityFramework.Docs/issues/5108)
71+
72+
##### Old behavior
73+
74+
Previously, the `SQLitePCLRaw.bundle_e_sqlcipher` NuGet package provided encryption-enabled SQLite builds at no cost.
75+
76+
##### New behavior
77+
78+
Starting with SQLitePCLRaw 3.0 (used by Microsoft.Data.Sqlite 11.0), the `SQLitePCLRaw.bundle_e_sqlcipher` package has been deprecated and removed from NuGet. No-cost encryption-enabled SQLite builds are no longer distributed.
79+
80+
##### Why
81+
82+
The previous no-cost `SQLitePCLRaw.bundle_e_sqlcipher` package was barely maintained, which is a significant concern for encryption software where security vulnerabilities may go unpatched. The SQLitePCLRaw maintainer removed these builds in version 3.0 in favor of professionally maintained, paid alternatives that provide ongoing security updates.
83+
84+
##### Mitigations
85+
86+
If you need SQLite encryption, you have the following options:
87+
88+
- **SQLite Encryption Extension (SEE)**: This is the official encryption implementation from the SQLite team. A paid license is required. See [https://sqlite.org/com/see.html](https://sqlite.org/com/see.html) for details. NuGet packages are available through [SourceGear's SQLite build service](https://github.com/ericsink/SQLitePCL.raw/wiki/SQLite-encryption-options-for-use-with-SQLitePCLRaw).
89+
- **SQLCipher**: Purchase supported builds from [Zetetic](https://www.zetetic.net/sqlcipher/), or build the [open source code](https://github.com/sqlcipher/sqlcipher) yourself.
90+
- **SQLite3 Multiple Ciphers**: NuGet packages are available to customers of [SourceGear's SQLite build service](https://github.com/ericsink/SQLitePCL.raw/wiki/SQLite-encryption-options-for-use-with-SQLitePCLRaw).
91+
92+
For more details, see [SQLite encryption options for use with SQLitePCLRaw](https://github.com/ericsink/SQLitePCL.raw/wiki/SQLite-encryption-options-for-use-with-SQLitePCLRaw) and [SQLitePCLRaw 3.0 Release Notes](https://github.com/ericsink/SQLitePCL.raw/blob/main/v3.md).
93+
94+
<a name="sqlite-bundles-removed"></a>
95+
96+
#### Some SQLitePCLRaw bundle packages have been removed
97+
98+
[Tracking Issue #5108](https://github.com/dotnet/EntityFramework.Docs/issues/5108)
99+
100+
##### Old behavior
101+
102+
Previously, the `SQLitePCLRaw.bundle_sqlite3`, `SQLitePCLRaw.bundle_winsqlite3`, `SQLitePCLRaw.bundle_green`, and `SQLitePCLRaw.bundle_e_sqlite3mc` packages provided a convenient way to configure SQLitePCLRaw with the corresponding SQLite provider.
103+
104+
##### New behavior
105+
106+
Starting with SQLitePCLRaw 3.0 (used by Microsoft.Data.Sqlite 11.0), these bundle packages have been removed. If your application depended on one of these bundles, you must now reference the corresponding provider package and explicitly initialize it.
107+
108+
##### Why
109+
110+
Each of these bundle packages contained only a single line of configuration code and added unnecessary packaging overhead. The corresponding provider packages are still supported.
111+
112+
##### Mitigations
113+
114+
Replace the removed bundle package with the corresponding provider package and add explicit initialization code.
115+
116+
**If using `bundle_sqlite3` or `bundle_winsqlite3`**, replace the package reference:
117+
118+
```xml
119+
<!-- Old -->
120+
<PackageReference Include="SQLitePCLRaw.bundle_sqlite3" Version="2.x.x" />
121+
<!-- or -->
122+
<PackageReference Include="SQLitePCLRaw.bundle_winsqlite3" Version="2.x.x" />
123+
124+
<!-- New -->
125+
<PackageReference Include="SQLitePCLRaw.core" Version="3.x.x" />
126+
<PackageReference Include="SQLitePCLRaw.provider.sqlite3" Version="3.x.x" />
127+
<!-- or -->
128+
<PackageReference Include="SQLitePCLRaw.core" Version="3.x.x" />
129+
<PackageReference Include="SQLitePCLRaw.provider.winsqlite3" Version="3.x.x" />
130+
```
131+
132+
Then add explicit initialization before using SQLite:
133+
134+
```csharp
135+
// For sqlite3
136+
static void Init()
137+
{
138+
SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_sqlite3());
139+
}
140+
141+
// For winsqlite3
142+
static void Init()
143+
{
144+
SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_winsqlite3());
145+
}
146+
```
147+
148+
**If using `bundle_green`**, the recommended migration path is to switch to `SQLitePCLRaw.bundle_e_sqlite3`. Alternatively, use `SQLitePCLRaw.config.e_sqlite3` paired with a separate native library package like `SourceGear.sqlite3`, which allows you to update the SQLite version independently:
149+
150+
```xml
151+
<PackageReference Include="SQLitePCLRaw.bundle_e_sqlite3" Version="3.x.x" />
152+
```
153+
154+
If you only target iOS and want to continue using the system SQLite library, reference the provider directly:
155+
156+
```xml
157+
<PackageReference Include="SQLitePCLRaw.core" Version="3.x.x" />
158+
<PackageReference Include="SQLitePCLRaw.provider.sqlite3" Version="3.x.x" />
159+
```
160+
161+
And initialize it explicitly:
162+
163+
```csharp
164+
static void Init()
165+
{
166+
SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_sqlite3());
167+
}
168+
```
169+
170+
> [!NOTE]
171+
> If you are using `SQLitePCLRaw.bundle_e_sqlite3`, no changes are required—just update the version number. See the [SQLitePCLRaw 3.0 Release Notes](https://github.com/ericsink/SQLitePCL.raw/blob/main/v3.md) for details.

0 commit comments

Comments
 (0)