By Oscar Franco

Twitter • YouTube • [Email](mailto:[email protected]?subject=I%20need%20a%20Freelancer)

Installing is easy

npm i -s @op-engineering/op-sqlite && npx pod-install

Configuration

SQLite is very customizable on compilation level. op-sqlite also allows you add extensions or even change the base implementation. You can do this by adding the following to your package.json:

{
	// your normal package.json
	// ...
	"op-sqlite": {
	  "sqlcipher": true,
	  "crsqlite": true,
	  "performanceMode": true,
	  "iosSqlite": false,
	  "sqliteFlags": "-DSQLITE_DQS=0",
	  "fts5": true,
	  "rtree": true,
	  "libsql": true,
	  "sqliteVec": true
	}
}

All keys are optional, only turn on the features you want:

sqlcipher allows to change the base sqlite implementation to sqlcipher, which encrypts all the database data with minimal overhead.
crsqlite is an extension that allows replication to a server backed sqlite database copy.
performanceMode turns on certain compilation flags that make sqlite speedier at the cost of disabling some features.
iosSqlite allows to use the iOS version from sqlite, which saves disk space but may use an older version and cannot load extensions as Apple disables it due to security concerns. On Android SQLite is always compiled from source as each vendor messes with sqlite or uses outdated versions.
sqliteFlags allows you to pass your own compilation flags to further disable/enable features and extensions. It follows the C flag format: -D[YOUR_FLAG]=[YOUR_VALUE]. If you are running large queries on large databases sometimes on Android devices you might get a IO exception. You can disable temporary files by using: "sqliteFlags": "-DSQLITE_TEMP_STORE=2"
fts5 enables the full text search extension
rtree enables the rtree extension
sqliteVec enables sqlite-vec, an extension for RAG embeddings

Some combination of features are not allowed. For example sqlcipher and iosSqlite since they are fundamentally different sources. In this cases you will get an error while doing a pod install or during the Android build.

🚨🚨🚨 IOS PODS USE_FRAMEWORKS BREAKS OP-SQLITE 🚨🚨🚨

In case you are using use_frameworks (for example because you are using react-native-firebase) this will break the compilation process and force the compilation to use the embedded sqlite on iOS. One possible workaround is putting this in your Podfile:

pre_install do |installer|
  installer.pod_targets.each do |pod|
    if pod.name.eql?('op-sqlite')
      def pod.build_type
        Pod::BuildType.static_library
      end
    end
  end
end

It forces static compilation on op-sqlite only. Since everything is compiled from sources this SHOULD work, however do it at your own risk since other compilation errors might arise. It is possible you will not get any error, but you will not be using the latest version of sqlite but rather the OS embedded one.

Runtime loadable extensions

You can load your own extensions on runtime.

db.loadExtension('/path/to/library.so', 'optional_entry_point_function_name');

You will need to compile your extension for both iOS and Android and all the respective architectures and make it available in a location the library can read (be careful about sandboxing).