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.

Multi-threading support is low-priority and untested. If your application-defined functions and virtual tables don't reference data outside of the database they are attached to, this will not cause issues because SQLite always does database operations in a single thread. However, the API needs to be evaluated through a multithreading lens to ensure that it is safe.

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 a statically linked run-time loadable extension. SQLite 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 also statically link a bundled version of SQLite from libsqlite3-sys. Please do not activate this feature from library crates, so that the consumer of your crate can decide for themselves to enable it.
• with_rusqlite - Adds support for registering your statically linked extension to a Rusqlite Connection object.

How to use

• I want to create a loadable extension that can be used by any SQLite client, or from the sqlite3 shell.
  • Your crate should be crate-type = [ "cdylib" ].
  • Use sqlite3_ext_main to register your enhancements.
  • SQLite methods are provided by SQLite at run-time, and methods will return Error::VersionNotSatisfied if they are not available in the host SQLite.
• I want to create a Rust binary that uses features not supported by rusqlite.
  • Your crate can be of any type. Enable the with_rusqlite and bundled features of this crate.
  • Use sqlite3_ext_init to create an initialization function. Call the function with the rusqlite Connection, as shown here.
  • SQLite methods will always be available, since the SQLite version is controlled by Rust.
• I want to create a statically linked extension that can be used by a (potentially non-Rust) program.
  • Your crate should be crate-type = [ "staticlib" ]. Enable the static feature of this crate. Use sqlite3_ext_main to register your enhancements.
  • Call sqlite3_mycrate_init directly (the method name is derived from the crate name) as documented here, or use sqlite3_auto_extension.
  • The host system provides SQLite. SQLite methods not available in version 3.6.8 will always return Error::VersionNotSatisfied.
• I want to create a statically linked extension with modern SQLite features that can be used by a (potentially non-Rust) program.
  • This is the same as above, but using the static_modern feature.
  • The version of SQLite being linked in must be the same or newer than the version supported by sqlite3_ext.
• I want to create a Rust program that does not use rusqlite.
  • Your crate can be of any type. Enable the with_rusqlite and bundled features of this crate.
  • Use sqlite3_ext_init to create an initialization function. Use Database to open a connection to a database. Pass the Database to the init function.
  • SQLite methods will always be available, since the SQLite version is controlled by Rust.
  • Note: if you are publishing a library crate, use static_modern instead of bundled, to avoid corrupting the database of your library's consumer.

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:

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