sqlite3_ext

Create SQLite loadable extensions in Rust. The design philosophy of the API is gradual enhancement: all use of SQLite features returns a Result, and an Err is returned when the host version of SQLite does not support the feature in question.

Early Version Warning

This crate is pre-1.0 and the API is allowed to change freely. In particular, if a safe API is found to be unsafe, it will be changed. Once the crate reaches version 1.0, the API will be subject to semantic versioning.

Being a pre-1.0, young crate, there may be bugs which have not yet been discovered. The crate comes with a modest test suite covering all of the features (over 100 tests currently).

Crate documentation is moderately covered, and there are example extensions in the repository that can serve as a guide. Also look at the integration test in the "test" folder at the root.

Features

• A querying interface similar to Rusqlite's.
• Application-defined scalar and aggregate functions, and collating sequences.
• A more comprehensive virtual table implementation than any other Rust crate currently published, supporting all SQLite virtual table methods.
• Rust support for the most modern features of SQLite, up to version 3.38.5.

Crate features

• static - The consumer of this crate is not an SQLite loadable extension. The SQLite API will be provided by the linker. To avoid link errors, sqlite3_ext disables all APIs that are added after 3.6.8.
• static_modern - Same as static, but sqlite3_ext does not disable any APIs. This will cause link errors if the linked version of SQLite is older than the version supported by sqlite3_ext.
• bundled - Same as static_modern, but use a bundled version of SQLite (from libsqlite3-sys) rather than the system one. This is the recommended way of building a static loadable extension for your Rust program.
• with_rusqlite - Adds support for registering your statically linked extension to a Rusqlite Connection object. See this test for an example.

Compilation Modes

There are three supported compilation modes for sqlite3_ext:

• As a loadable extension. Your crate is crate-type = [ "cdylib" ] and is loaded into another process as an SQLite loadable extension.
  • SQLite methods are provided by SQLite at run-time.
• As a statically linked extension. Your crate is crate-type = [ "staticlib" ] and is statically linked into another program.
  • Linker provides the SQLite methods.
• As a rust library. Your crate has any type and uses sqlite3_ext like any other crate.
  • You are responsible for providing SQLite (e.g. via Rusqlite).

Crate configurations

• By default, the crate is configured to be dynamically loaded by SQLite.
• Using feature static, the crate is able to be linked into a Rust or C program statically. This is highly compatible, but disables many features of SQLite.
• Using feature static_modern, the crate is able to be linked into a Rust or C program statically. This requires that the system's SQLite is at least the version supported by sqlite3_ext, or there will be link errors.

Test configurations

Tests run with modern SQLite:

• All tests from Cargo.toml with crate feature static.
• All tests from Cargo.toml with crate feature static_modern.

Todo:

• Run tests against SQLite 3.6.8.

Interfaces supported

Here is a compatibility chart showing which parts of the SQLite API are currently covered by sqlite3_ext. Iconography:

• :white_check_mark: - This API is fully exposed via an API in sqlite3_ext
• :grey_exclamation: - This API is available via unsafe ffi, but there are no plans to make an API for it in sqlite3_ext.