Struct UriBuilder 

pub struct UriBuilder { /* private fields */ }

Builder for constructing sqlite-objs URIs with proper URL encoding.

SQLite URIs use query parameters to pass Azure credentials. SAS tokens contain special characters (&, =, %) that must be percent-encoded to avoid breaking the URI query string.

Example

use sqlite_objs::UriBuilder;

let uri = UriBuilder::new("mydb.db", "myaccount", "databases")
    .sas_token("sv=2024-08-04&ss=b&srt=sco&sp=rwdlacyx&se=2026-01-01T00:00:00Z&sig=abc123")
    .build();

// URI is properly encoded:
// file:mydb.db?azure_account=myaccount&azure_container=databases&azure_sas=sv%3D2024-08-04%26ss%3Db...

Authentication

Use either sas_token() or account_key(), not both. If both are set, sas_token takes precedence.

Implementations

impl UriBuilder

pub fn new(database: &str, account: &str, container: &str) -> Self

Create a new URI builder with required parameters.

Arguments

• database - Database filename (e.g., “mydb.db”)
• account - Azure Storage account name
• container - Blob container name

pub fn sas_token(self, token: &str) -> Self

Set the SAS token for authentication (preferred).

The token will be URL-encoded automatically. Do not encode it yourself.

pub fn account_key(self, key: &str) -> Self

Set the account key for Shared Key authentication (fallback).

The key will be URL-encoded automatically.

pub fn endpoint(self, endpoint: &str) -> Self

Set a custom endpoint (e.g., for Azurite: “http://127.0.0.1:10000”).

pub fn cache_dir(self, dir: &str) -> Self

Set the local cache directory for downloaded database files.

If not set, defaults to /tmp. The directory will be created if it doesn’t exist.

pub fn cache_reuse(self, enabled: bool) -> Self

Enable persistent cache reuse across database connections.

When enabled, the local cache file is kept after closing the database. On reopen, the VFS checks the blob’s ETag — if unchanged, the cached file is reused instead of re-downloading (saving ~20s for large databases).

Requires cache_dir to be set for predictable cache file locations. Default: false (cache files are deleted on close).

pub fn prefetch(self, mode: PrefetchMode) -> Self

Set the prefetch mode for blob data loading.

• PrefetchMode::All (default) — download the entire blob into the local cache when the database is opened.
• PrefetchMode::None — lazy mode; pages are fetched from Azure only when SQLite reads them.

Only emitted as a URI parameter when explicitly set to a non-default value, keeping URIs short in the common case.

Example

use sqlite_objs::{UriBuilder, PrefetchMode};

let uri = UriBuilder::new("big.db", "acct", "cont")
    .sas_token("tok")
    .prefetch(PrefetchMode::None)
    .build();
assert!(uri.contains("&prefetch=none"));

pub fn build(self) -> String

Build the URI string with proper URL encoding.

Returns a SQLite URI in the format: file:{database}?azure_account={account}&azure_container={container}&...