Loadable extensions

Loadable extensions, also known as modules, are libraries of code that can be loaded at runtime to add functionality to WiredTiger. To build a loadable extension, use gcc -shared ... or libtool -module ..., or the equivalent for your system.

Extensions can be loaded on an open connection by calling WT_CONNECTION::load_extension.

Extensions can be loaded during wiredtiger_open by passing the extensions configuration when the database is created. When used this way, the extensions will be loaded each time the database is opened, whether by your application or the WiredTiger command line utility.

Extensions configured with early_load=true are an exception: they must be passed in the extensions configuration on every wiredtiger_open call. Early-load extensions are loaded before WiredTiger reads its persisted base configuration file, so they cannot be replayed from it automatically. A common example is a custom file system extension, which must be available before WiredTiger can read any files in the home directory.

By default, when an early_load=true extension appears in the base configuration file but not in the open configuration, WiredTiger logs a warning and the extension is absent from the connection. Pass extensions_strict=true to wiredtiger_open to fail the open with EINVAL in that situation instead.

The extension entry point, which defaults to wiredtiger_extension_init, is called for each loadable module. Applications must supply this entry point, which in turn usually calls WT_CONNECTION::add_data_source, WT_CONNECTION::add_encryptor, WT_CONNECTION::add_collator and/or WT_CONNECTION::add_compressor to add functionality to WiredTiger.

Extensions and recovery

Some extensions, in particular WT_COLLATOR and WT_COMPRESSOR, are required in order to run recovery if logging is enabled. This means that they must be loaded using the extensions keyword to wiredtiger_open, because recovery runs before wiredtiger_open returns the WT_CONNECTION handle to the application.

Local extensions

If it is not feasible to separate application logic into a loadable extension separate from the executable, applications can use the reserved name local as a path in the extensions list. This will search for the entry point in the running application, and should usually override the entry symbol.

Here is an example of a local entry point:

wiredtiger_open(path, NULL, "create,extensions=[local=(entry=my_extension_init)]")

Note that databases created in this way can only be opened by applications that include the specified entry point. In particular, they cannot be accessed using the WiredTiger command line utility.