SQLitePCLRaw Documentation

As of version 3.0, SQLitePCLRaw no longer distributes no-cost SQLite builds with encryption. The .bundle_e_sqlcipher package is deprecated.

Users requiring encryption have the following options:

1. SQLite Encryption Extension (SEE): The official implementation from the SQLite core team. Requires a paid license. SEE builds can be obtained via SourceGear's SQLite build service.
2. SQLCipher: Supported builds can be purchased from Zetetic.
3. SQLite3 Multiple Ciphers (sqlite3mc): An open-source option. Nuget packages for sqlite3mc are available through SourceGear's SQLite build service.

Note: SourceGear's e_sqlite3 base name is compatible with sqlite3mc builds.

SQLitePCLRaw is a "raw" low-level wrapper around the SQLite C API. It is intentionally designed to follow SQLite's C stylistic conventions rather than standard .NET patterns.

Key characteristics for developers:

• Naming: Methods follow C naming conventions (e.g., sqlite3_open() instead of Sqlite3Open()).
• Error Handling: Methods return integer error codes rather than throwing .NET exceptions.
• Purpose: It is designed as a portable foundation for higher-level wrappers (like Microsoft.Data.Sqlite or sqlite-net-pcl) rather than for direct use in application-level code.

SQLitePCLRaw does not provide free encryption-enabled builds. For encryption support, the recommended solution is the SQLite Encryption Extension (SEE), which is the official implementation from the SQLite team.

Note that SEE is not open source and requires a paid license. You can obtain SEE builds in the form of NuGet packages through SourceGear's SQLite build service.

Using SQLitePCLRaw requires a combination of three types of packages to function correctly:

1. Core Assembly: SQLitePCLRaw.core provides the main logic but contains no providers.
2. Provider Package: A package with an ID like SQLitePCLRaw.provider.* that implements the ISQLite3Provider interface. This tells the core assembly which native library to use.
3. Native Library Package: A package containing the actual native SQLite binaries (e.g., SourceGear.sqlite3).

In your platform-specific code, you must initialize the provider using SQLitePCL.raw.SetProvider().

// Example of manual initialization
SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_e_sqlite3());

To use an encryption-enabled SQLite build, the recommended approach is to name your shared library e_sqlite3 and use the SQLitePCLRaw.config.e_sqlite3 package. This allows you to swap in different crypto-enabled native libraries.

Supported encryption options include:

• SQLite Encryption Extension (SEE): The official implementation from the SQLite team (requires a paid license).
• SQLCipher: Builds are available for purchase from Zetetic.
• SQLite3 Multiple Ciphers: Maintained by @utelle; builds are available via SourceGear's SQLite build service.

For users requiring specific native SQLite builds, SourceGear provides a paid service at nuget.sourcegear.com. This service offers:

• Native SQLite builds updated immediately following each SQLite release.
• Regular SQLite builds.
• Builds with encryption support.
• Signed builds and supply chain information (e.g., SBOMs).
• Custom configurations.

If your project targets only iOS and you wish to use the SQLite library provided by the operating system instead of a bundled version, you can use the core and provider packages directly and manually initialize the provider.

<!-- Package references -->
<PackageReference Include="sqlitepclraw.core" Version="3.0.1" />
<PackageReference Include="sqlitepclraw.provider.sqlite3" Version="3.0.1" />

<!-- Initialization code -->
SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_sqlite3());

If you are currently using SQLitePCLRaw.bundle_e_sqlite3, the upgrade to 3.0 is a direct version bump and should 'Just Work'.

However, for better control over SQLite updates, it is recommended to switch from the bundle package to the new decoupled pattern. This allows you to update the native SQLite library independently of the SQLitePCLRaw configuration by updating only the SourceGear.sqlite3 package.

<!-- Option 1: Simple version bump -->
<PackageReference Include="sqlitepclraw.bundle_e_sqlite3" Version="3.0.1" />

<!-- Option 2: Recommended decoupled approach -->
<PackageReference Include="sqlitepclraw.config.e_sqlite3" Version="3.0.1" />
<PackageReference Include="sourcegear.sqlite3" Version="3.50.3" />

The SQLitePCLRaw.bundle_green package has been removed. This package was used to reference the system-provided SQLite on iOS while using e_sqlite3 on other platforms.

To achieve similar behavior with the new 3.0 structure, it is recommended to switch to the pairing of SQLitePCLRaw.config.e_sqlite3 and SourceGear.sqlite3 for all platforms.

<!-- Recommended replacement for bundle_green -->
<PackageReference Include="sqlitepclraw.config.e_sqlite3" Version="3.0.1" />
<PackageReference Include="sourcegear.sqlite3" Version="3.50.3" />

To generate provider code from the provider.tt template, use the t4 command. Note that running this via dotnet t4 may fail; use the direct t4 command instead.

Example command:

t4 -o tmp.cs -p:NAME=tmp -p:CONV=Cdecl -p:KIND=dynamic provider.tt