Struct OpenOptions 

pub struct OpenOptions { /* private fields */ }

A builder for opening or creating a GeoPackage with an explicit journal mode and/or synchronous level.

Both settings are optional. An unspecified journal mode leaves the file’s existing mode untouched (a freshly created file is JournalMode::Delete); an unspecified synchronous level keeps SQLite’s default. Journal mode is ignored by Self::open_read_only, which cannot write the change.

Examples

use geopackage::{JournalMode, OpenOptions, Synchronous};
let gpkg = OpenOptions::new()
    .journal_mode(JournalMode::Wal)
    .synchronous(Synchronous::Normal)
    .create("service.gpkg")?;

Implementations

impl OpenOptions

pub fn new() -> Self

Creates a builder with no settings applied (the same defaults the plain GeoPackage::create / GeoPackage::open constructors use).

pub fn journal_mode(self, mode: JournalMode) -> Self

Sets the journal mode (JournalMode::Wal to opt into WAL).

pub fn lenient(self, lenient: bool) -> Self

Accepts legacy and lightly non-conforming files, recording what was accepted as crate::OpenWarnings rather than failing to open.

Composes with every other setting here: leniency was previously reachable only through GeoPackage::open_lenient and GeoPackage::open_read_only_lenient, which take no options at all, so WAL and leniency, or constraint enforcement and leniency, could not be combined.

Leniency covers presentation, not identity: a file that cannot be identified as a GeoPackage, or that is missing a required core table, is still an error. Retrieve what was accepted with GeoPackage::open_warnings.

pub fn synchronous(self, synchronous: Synchronous) -> Self

Sets the synchronous durability level.

pub fn busy_timeout(self, timeout: Duration) -> Self

Sets how long a statement waits for a lock another connection holds before giving up with SQLITE_BUSY. DEFAULT_BUSY_TIMEOUT when unset.

Duration::ZERO restores SQLite’s own default, which is to fail immediately. That is rarely the right choice: a GeoPackage is a single-writer database that readers and writers are expected to share, so a write that meets a concurrent writer should wait rather than fail on the first attempt.

This is the whole of the crate’s retry policy. Waiting is what SQLite does on a caller’s behalf here, and it is worth knowing that the wait is skipped in the two cases where it could not help: a read-to-write upgrade that would deadlock under a rollback journal, and a stale snapshot under WAL, both of which return SQLITE_BUSY at once however long the timeout is.

pub fn allow_unsupported_extension_writes(self, allow: bool) -> Self

Allows writes to tables covered by an extension this crate cannot identify, instead of failing with Error::UnsupportedExtension.

By default such a write fails, because an unidentifiable extension may constrain the rows, triggers or encodings of the table it covers, and Requirement 64 makes every extension one a writer has to understand. Set this when you know what the extension is and know that writing beside it is safe: the check is the crate’s, not the format’s, and a caller who knows more than the catalogue does should be able to say so.

Reads are unaffected either way, and extensions this crate can name never trigger the error. GDAL, for comparison, warns in this situation and proceeds.

pub fn enforce_column_constraints(self, enforce: bool) -> Self

Checks written values against the gpkg_schema constraints their columns declare, rejecting a row that violates one with Error::ColumnConstraintViolation.

Off by default, because the format makes these constraints advisory: “These restrictions MAY be enforced by SQL triggers or by code in applications that update GeoPackage data values”. A file can therefore contain values its own constraints forbid, and rejecting writes beside them by default would impose a rule the format does not.

What is checked, for a constrained column: a range against integers and floats, an enum against text and against the decimal form of a number, since the spec’s own sample enumerates numbers as text, and a glob by asking SQLite. NULL satisfies every constraint, a constraint saying what a value may be rather than that there has to be one; use NOT NULL for that. Blob, date and datetime values are not checked.

The glob form goes to SQLite (SELECT ?1 GLOB ?2, prepared once per writer) rather than being matched here. Its pattern language has no definition beyond what SQLite does with it, and this crate bundles SQLite, so the engine that stores the file is the authority on what its own constraints mean. That also gives a number SQLite’s own text coercion, which is what a trigger enforcing the same constraint would apply.

Applies to every write path, the columnar one included. Measured at about 31% on a 200,000-row write with two constrained columns, and nothing at all for a layer with no constraints.

pub fn create<P: AsRef<Path>>(self, path: P) -> Result<GeoPackage>

Creates a new GeoPackage 1.4 file at path with these options.

As GeoPackage::create, but applying the configured journal mode and synchronous level to the new connection.

pub fn open<P: AsRef<Path>>(self, path: P) -> Result<GeoPackage>

Opens an existing GeoPackage read-write with these options.

pub fn open_read_only<P: AsRef<Path>>(self, path: P) -> Result<GeoPackage>

Opens an existing GeoPackage read-only with these options.

The journal mode is ignored (a read-only connection cannot change it); the synchronous level is still applied.

pub fn from_connection(self, conn: Connection) -> Result<GeoPackage>

Wraps an already-open connection with these options.

As GeoPackage::from_connection, but applying the configured journal mode and synchronous level. The caller is responsible for the connection being writable if a journal mode is set.

Trait Implementations

impl Clone for OpenOptions

fn clone(&self) -> OpenOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for OpenOptions

impl Debug for OpenOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for OpenOptions

fn default() -> OpenOptions

Returns the “default value” for a type.

impl Eq for OpenOptions

impl PartialEq for OpenOptions

fn eq(&self, other: &OpenOptions) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for OpenOptions