Struct DbOptions 

pub struct DbOptions {

    pub path: PathBuf,
    pub busy_timeout: Duration,
    pub key: Option<Zeroizing<String>>,
    pub raw_key: Option<Zeroizing<[u8; 32]>>,
    pub profile: CacheProfile,
    pub durability: DurabilityProfile,
    pub foreign_keys: bool,
    pub integrity_check_on_open: bool,
    pub integrity: IntegrityCheck,
    pub journal: JournalSelect,
    pub owner_only: bool,
    pub init: Option<ConnInit>,
    pub journal_env: Option<String>,
    pub per_host_fallback: bool,
    pub secure_delete: Option<bool>,
    pub optimize_on_open: bool,
}

Fields

path: PathBuf

busy_timeout: Duration

SQLite busy wait, installed before key verification or any bootstrap statement. Default: five seconds.

key: Option<Zeroizing<String>>

SQLCipher passphrase-style key (base64-ish charset). See also DbOptions::raw_key.

raw_key: Option<Zeroizing<[u8; 32]>>

SQLCipher raw 256-bit key, applied as x'<hex>' (no KDF). Takes precedence over key.

profile: CacheProfile

durability: DurabilityProfile

foreign_keys: bool

integrity_check_on_open: bool

Legacy switch: true runs a full check on every open. Ignored when integrity is not Off.

integrity: IntegrityCheck

Open-time integrity check (default Off). A failed check is DbError::Integrity, which open_writer_recovering treats as unreadable.

journal: JournalSelect

owner_only: bool

Narrow the database and its sidecars to owner-only (0600) on unix. Default on. Set it to false when sibling processes must read the file (for example a helper running as another user); that is the intended switch, not a bug.

init: Option<ConnInit>

journal_env: Option<String>

The app’s own kill-switch variable (e.g. CODERIGHT_SQLITE_JOURNAL_MODE), checked before JOURNAL_ENV.

per_host_fallback: bool

When a rollback journal is in force (network mount, kill switch, or WAL refused), open the per-host sibling per_host_path instead of the requested file, so hosts sharing a network directory never share one rollback-journaled database. The requested file is not created. Default off.

secure_delete: Option<bool>

Sets PRAGMA secure_delete on every connection at open: Some(true) overwrites freed pages, Some(false) does not, None (default) leaves SQLite’s compile-time default.

optimize_on_open: bool

Run PRAGMA optimize on each writer connection at open (default true). Set it to false to leave planner statistics alone at open, for example when the file is opened only to inspect it. Readers never run it, whatever this is set to.

Implementations

impl DbOptions

pub fn restore_from(&self, backup_path: impl AsRef<Path>) -> Result<()>

Validate the backup first, then open the existing live database without bootstrap and restore it. Neither missing backup nor missing live DB is created. The backup must use the same SQLCipher key as these options.

impl DbOptions

pub fn open_writer_migrated( &self, migrations: &[Migration], options: &MigrateOptions, ) -> Result<(Connection, MigrationReport)>

Open the writer and bring the schema up to date (see migrate); the pre-migration backup is keyed like the database itself.

pub fn open_writer_migrated_or_degrade( &self, migrations: &[Migration], options: &MigrateOptions, policy: RecoveryPolicy, ) -> Result<OpenOrDegrade>

Open-or-degrade: Self::open_writer_migrated, with recovery for a stored database that is corrupt, not a database, or fails its integrity check, at open or during migration.

For such a failure, policy decides as in Self::open_writer_recovering: when it allows (quarantine_corrupt for a plain database, quarantine_keyed for a keyed one), the file and its sidecars move aside under the policy’s stamp and sidecar options (never deleted by default), and the database is created and migrated again. When it does not allow, the file is left untouched. Either way, if the store still cannot be opened, the connection is a private in-memory store that is migrated the same way only when policy.allow_in_memory_fallback explicitly acknowledges it (default refuse: the original error is returned). When acknowledged, OpenOrDegrade::degraded says so with in_memory: true, and the configured key remains applied.

Any other failure (busy, permission, I/O, a newer database, an invalid migration list) is returned as an error, because it does not show the stored data is damaged.

impl DbOptions

pub fn open_writer_with_key_candidates( &self, candidates: &[Zeroizing<String>], ) -> Result<(Connection, usize)>

Try each passphrase in order; the first that decrypts opens the writer.

pub fn open_writer_recovering( &self, policy: RecoveryPolicy, ) -> Result<OpenOutcome>

Open the writer; if the file is unreadable and the policy allows it, quarantine it and open a fresh database at the same path.

impl DbOptions

pub fn open_writer_recovering_unreadable( &self, policy: RecoveryPolicy, unreadable: UnreadablePolicy, ) -> Result<UnreadableRecovery>

DbOptions::open_writer_recovering plus a policy for a database that cannot be read.

• Opens normally: returns RecoveryAction::OpenedNormally and clears the failure count.
• Corrupt (not-a-database, corrupt, failed integrity check): as open_writer_recovering, decided by policy; quarantined gives RecoveryAction::QuarantinedCorrupt.
• Unreadable or storage unavailable (UnreadableCause): decided by unreadable; the default UnreadablePolicy::Fail returns DbError::Unreadable and touches nothing.
• Any other error is returned unchanged.

Errors

DbError::Unreadable as above; the original error otherwise; a quarantine or reopen failure after the file was set aside (the old file stays preserved).

pub fn open_writer_recovering_via( &self, policy: RecoveryPolicy, unreadable: UnreadablePolicy, open: impl FnMut() -> Result<Connection>, ) -> Result<UnreadableRecovery>

As DbOptions::open_writer_recovering_unreadable, with the open step supplied by the caller: it is called once for the first attempt and once more after a quarantine. This is the seam for tests that inject open errors and for apps with their own bootstrap.

impl DbOptions

pub fn new(path: impl Into<PathBuf>) -> Self

pub fn with_journal_env(self, name: impl Into<String>) -> Self

pub fn with_per_host_fallback(self, on: bool) -> Self

pub fn without_optimize_on_open(self) -> Self

Turn PRAGMA optimize off at writer open (see DbOptions::optimize_on_open).

pub fn effective_path(&self) -> PathBuf

The file connections actually open: the requested path, or its per-host sibling when Self::per_host_fallback applies (a rollback journal is in force, or a writer already fell back there).

pub fn with_passphrase(self, key: impl Into<String>) -> Self

pub fn with_raw_key(self, key: [u8; 32]) -> Self

pub fn is_keyed(&self) -> bool

pub fn open_writer(&self) -> Result<Connection>

pub fn open_reader(&self) -> Result<Connection>

pub fn open_read_only(&self) -> Result<Connection>

Open exactly path read-only, without creating it or running mutating bootstrap. URI parameters are passed to SQLite unchanged. Journal fallback, permissions, init, optimization, and migrations are skipped; key and timeout still apply.

pub fn open_existing_writer(&self) -> Result<Connection>

Open exactly path read-write without CREATE or mutating bootstrap. Uses the same minimal setup as Self::open_read_only.

pub fn open_in_memory(&self) -> Result<Connection>

Open a private, ephemeral database. path, filesystem permissions, journal selection/fallback, and mmap are ignored; other bootstrap options still apply.

pub fn open_read_pool(&self, cap: usize) -> Result<ReadPool>

A read pool with ReadPoolOptions::new: read-write file handles, with query_only set and verified on every reader. Same as open_read_pool_with(cap, ReadPoolOptions::new()).

pub fn open_read_pool_with( &self, cap: usize, pool: ReadPoolOptions, ) -> Result<ReadPool>

A read pool configured by ReadPoolOptions. A read-only pool needs the database to exist.

Trait Implementations

impl Clone for DbOptions

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.