Struct Builder

pub struct Builder<T = ()> { /* private fields */ }

A builder for Database. This struct can be used to build all variants of Database. These variants include:

• new_local/Local which means a Database that is just a local libsql database it does no networking and does not connect to any remote database.
• new_remote_replica/RemoteReplica creates an embedded replica database that will be able to sync from the remote url and delegate writes to the remote primary.
• new_synced_database/SyncedDatabase creates a database that can be written offline and synced to a remote server.
• new_local_replica/LocalReplica creates an embedded replica similar to the remote version except you must use Database::sync_frames to sync with the remote. This version also includes the ability to delegate writes to a remote primary.
• new_remote/Remote creates a database that does not create anything locally but will instead run all queries on the remote database. This is essentially the pure HTTP api.

Note

Embedded replicas require a clean database (no database file) or a previously synced database or else it will throw an error to prevent any misuse. To work around this error a user can delete the database and let it resync and create the wal_index metadata file.

Implementations

impl Builder<()>

pub fn new_local(path: impl AsRef<Path>) -> Builder<Local>

Available on crate feature core only.

Create a new local database.

pub fn new_remote_replica( path: impl AsRef<Path>, url: String, auth_token: String, ) -> Builder<RemoteReplica>

Available on crate feature replication only.

Create a new remote embedded replica.

pub fn new_local_replica(path: impl AsRef<Path>) -> Builder<LocalReplica>

Available on crate feature replication only.

Create a new local replica.

pub fn new_synced_database( path: impl AsRef<Path>, url: String, auth_token: String, ) -> Builder<SyncedDatabase>

Available on crate feature sync only.

Create a database that can be written offline and synced to a remote server.

pub fn new_remote(url: String, auth_token: String) -> Builder<Remote>

Available on crate feature remote only.

Create a new remote database.

impl Builder<Local>

pub fn flags(self, flags: OpenFlags) -> Builder<Local>

Available on crate feature core only.

Set [OpenFlags] for this database.

pub fn encryption_config( self, encryption_config: EncryptionConfig, ) -> Builder<Local>

Available on crate feature core only.

Set an encryption config that will encrypt the local database.

pub unsafe fn skip_safety_assert(self, skip: bool) -> Builder<Local>

Available on crate feature core only.

Skip the saftey assert used to ensure that sqlite3 is configured correctly for the way that libsql uses the ffi code. By default, libsql will try to use the SERIALIZED threadsafe mode for sqlite3. This allows us to implement Send/Sync for all the types to allow them to move between threads safely. Due to the fact that sqlite3 has a global config this may conflict with other sqlite3 connections in the same process.

Using this setting is very UNSAFE and you are expected to use the libsql in adherence with the sqlite3 threadsafe rules or else you WILL create undefined behavior. Use at your own risk.

pub async fn build(self) -> Result<Database>

Available on crate feature core only.

Build the local database.

impl Builder<RemoteReplica>

pub fn connector<C>(self, connector: C) -> Builder<RemoteReplica>

where C: Service<Uri> + Send + Clone + Sync + 'static, C::Response: Socket, C::Future: Send + 'static, C::Error: Into<Box<dyn Error + Send + Sync>>,

Available on crate feature replication only.

Provide a custom http connector that will be used to create http connections.

pub fn encryption_config( self, encryption_config: EncryptionConfig, ) -> Builder<RemoteReplica>

Available on crate feature replication only.

Set an encryption key that will encrypt the local database.

pub fn read_your_writes(self, read_your_writes: bool) -> Builder<RemoteReplica>

Available on crate feature replication only.

Set whether you want writes to be visible locally before the write query returns. This means that you will be able to read your own writes if this is set to true.

Default

This defaults to true.

pub fn sync_interval(self, duration: Duration) -> Builder<RemoteReplica>

Available on crate feature replication only.

Set the duration at which the replicator will automatically call sync in the background. The sync will continue for the duration that the resulted Database type is alive for, once it is dropped the background task will get dropped and stop.

pub fn sync_protocol(self, protocol: SyncProtocol) -> Builder<RemoteReplica>

Available on crate feature replication only.

Set the duration at which the replicator will automatically call sync in the background. The sync will continue for the duration that the resulted Database type is alive for, once it is dropped the background task will get dropped and stop.

pub fn remote_encryption( self, encryption_context: EncryptionContext, ) -> Builder<RemoteReplica>

Available on crate feature replication only.

Set the encryption context if the database is encrypted in remote server.

pub fn http_request_callback<F>(self, f: F) -> Builder<RemoteReplica>

where F: Fn(&mut Request<()>) + Send + Sync + 'static,

Available on crate feature replication only.

pub fn namespace(self, namespace: impl Into<String>) -> Builder<RemoteReplica>

Available on crate feature replication only.

Set the namespace that will be communicated to remote replica in the http header.

pub unsafe fn skip_safety_assert(self, skip: bool) -> Builder<RemoteReplica>

Available on crate feature replication only.

Skip the safety assert used to ensure that sqlite3 is configured correctly for the way that libsql uses the ffi code. By default, libsql will try to use the SERIALIZED threadsafe mode for sqlite3. This allows us to implement Send/Sync for all the types to allow them to move between threads safely. Due to the fact that sqlite3 has a global config this may conflict with other sqlite3 connections in the same process.

Using this setting is very UNSAFE and you are expected to use the libsql in adherence with the sqlite3 threadsafe rules or else you WILL create undefined behavior. Use at your own risk.

pub async fn build(self) -> Result<Database>

Available on crate feature replication only.

Build the remote embedded replica database.

impl Builder<LocalReplica>

pub fn flags(self, flags: OpenFlags) -> Builder<LocalReplica>

Available on crate feature replication only.

Set [OpenFlags] for this database.

pub fn http_request_callback<F>(self, f: F) -> Builder<LocalReplica>

where F: Fn(&mut Request<()>) + Send + Sync + 'static,

Available on crate feature replication only.

pub async fn build(self) -> Result<Database>

Available on crate feature replication only.

Build the local embedded replica database.

impl Builder<SyncedDatabase>

pub fn read_your_writes(self, v: bool) -> Builder<SyncedDatabase>

Available on crate feature sync only.

pub fn remote_writes(self, v: bool) -> Builder<SyncedDatabase>

Available on crate feature sync only.

pub fn set_push_batch_size(self, v: u32) -> Builder<SyncedDatabase>

Available on crate feature sync only.

pub fn sync_interval(self, duration: Duration) -> Builder<SyncedDatabase>

Available on crate feature sync only.

Set the duration at which the replicator will automatically call sync in the background. The sync will continue for the duration that the resulted Database type is alive for, once it is dropped the background task will get dropped and stop.

pub fn remote_encryption( self, encryption_context: EncryptionContext, ) -> Builder<SyncedDatabase>

Available on crate feature sync only.

Set the encryption context if the database is encrypted in remote server.

pub fn connector<C>(self, connector: C) -> Builder<SyncedDatabase>

where C: Service<Uri> + Send + Clone + Sync + 'static, C::Response: Socket, C::Future: Send + 'static, C::Error: Into<Box<dyn Error + Send + Sync>>,

Available on crate feature sync only.

Provide a custom http connector that will be used to create http connections.

pub async fn build(self) -> Result<Database>

Available on crate feature sync only.

Build a connection to a local database that can be synced to remote server.

impl Builder<Remote>

pub fn connector<C>(self, connector: C) -> Builder<Remote>

where C: Service<Uri> + Send + Clone + Sync + 'static, C::Response: Socket, C::Future: Send + 'static, C::Error: Into<Box<dyn Error + Send + Sync>>,

Available on crate feature remote only.

Provide a custom http connector that will be used to create http connections.

pub fn namespace(self, namespace: impl Into<String>) -> Builder<Remote>

Available on crate feature remote only.

Set the namespace that will be communicated to the remote in the http header.

pub fn remote_encryption( self, encryption_context: EncryptionContext, ) -> Builder<Remote>

Available on crate feature remote only.

Set the encryption context if the database is encrypted in remote server.

pub async fn build(self) -> Result<Database>

Available on crate feature remote only.

Build the remote database client.