Crate rusqlite_gpkg

Source

Expand description

GeoPackage reader/writer built on top of rusqlite.

§Overview

The crate supports two GeoPackage content types:

Feature layers (spatial data with geometry):

Gpkg – the GeoPackage connection.
GpkgLayer – a single feature layer (table with geometry column).
GpkgFeature – a single feature (row with geometry + properties).

Attribute tables (non-spatial tabular data, no geometry):

GpkgAttributeTable – a single attribute table.
GpkgAttributeRow – a single row (properties only, no geometry).

Value represents a single property value in both cases.

Apache Arrow support is available behind the arrow feature flag.

Gpkg is the entry point and supports several open modes: Gpkg::open_read_only(path), Gpkg::open(path), and Gpkg::open_in_memory().

GpkgLayer::features() loads all features into memory. For large datasets, use features_batch(batch_size) to stream in chunks.

GpkgLayer::insert and GpkgLayer::update accept any geometry that implements geo_traits::GeometryTrait<T = f64> (for example geo_types::Point).

§Browser usage

On wasm targets, you can open with a custom writer (for example an OPFS-backed writer wrapper) via open_with_writer():

use rusqlite_gpkg::Gpkg;
let _gpkg = Gpkg::open_with_writer("demo.sqlite", opfs_writer)?;

If you prefer a storage-agnostic flow, use to_bytes() / from_bytes():

use rusqlite_gpkg::Gpkg;
let gpkg = Gpkg::open_in_memory()?;
let bytes = gpkg.to_bytes()?;
let _restored = Gpkg::from_bytes(&bytes)?;

§Gpkg

Gpkg represents the GeoPackage connection and is the entry point for opening databases, listing layers, and creating new layers.

list_layers() / get_layer(name) / create_layer(...) for feature layers.
list_attribute_tables() / get_attribute_table(name) / create_attribute_table(...) for attribute tables.

use rusqlite_gpkg::Gpkg;
let gpkg = Gpkg::open_read_only("data/example.gpkg")?;
let layer = gpkg.get_layer("points")?;

§GpkgLayer

GpkgLayer models a single feature table. It exposes schema information (geometry column, property columns) and provides read/write operations.

use geo_types::Point;
use rusqlite_gpkg::{Gpkg, params};
let layer = Gpkg::open("data.gpkg")?.get_layer("points")?;
layer.insert(Point::new(1.0, 2.0), params!["alpha", 7_i64])?;

§GpkgFeature

GpkgFeature represents one row. You can read the primary key, geometry, and property values from it.

use rusqlite_gpkg::Gpkg;
let features = Gpkg::open_read_only("data.gpkg")?
    .get_layer("points")?
    .features()?;
let feature = features.first().expect("feature");
let _geom = feature.geometry()?;

§Value

Value is the crate’s owned dynamic value for feature properties, mirroring SQLite’s dynamic typing. Convert with try_into() or match directly.

use rusqlite_gpkg::Gpkg;
let features = Gpkg::open_read_only("data.gpkg")?
    .get_layer("points")?
    .features()?;
let feature = features.first().expect("feature");
let name: String = feature
    .property("name")
    .ok_or_else(|| rusqlite_gpkg::GpkgError::MissingProperty {
        property: "name".to_string(),
    })?
    .try_into()?;

§Attribute tables

Attribute tables hold non-spatial data (no geometry column). They follow the GeoPackage spec Section 2.4 (data_type = 'attributes' in gpkg_contents).

use rusqlite_gpkg::{ColumnSpec, ColumnType, Gpkg, params};
let gpkg = Gpkg::open_in_memory()?;
let columns = vec![
    ColumnSpec { name: "name".to_string(), column_type: ColumnType::Varchar },
    ColumnSpec { name: "value".to_string(), column_type: ColumnType::Integer },
];
let table = gpkg.create_attribute_table("observations", &columns)?;
table.insert(params!["alpha", 7_i64])?;

let rows = table.rows()?;
let name: String = rows[0].property("name").unwrap().try_into()?;

§Arrow (feature = “arrow”)

The Arrow reader yields RecordBatches for a layer. It borrows the Gpkg because it holds a prepared statement internally.

use rusqlite_gpkg::{ArrowGpkgReader, Gpkg};
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let gpkg = Gpkg::open_read_only("data/example.gpkg")?;
    let mut reader = ArrowGpkgReader::new(&gpkg, "points", 256)?;
    let _batch = reader.next().transpose()?;
    Ok(())
}
fn main() {}

Macros§

params

Structs§

ArrowGpkgAttributeReader: Iterator that yields Arrow RecordBatches from a GeoPackage attribute table.
ArrowGpkgAttributeWriter: Writes Arrow RecordBatches into a GeoPackage attribute table (no geometry).
ArrowGpkgReader: Iterator that yields Arrow RecordBatches of features from a GeoPackage layer.
ArrowGpkgWriter: Writes Arrow RecordBatches into a GeoPackage layer.
ColumnSpec: Column definition used when creating or describing layer properties.
Gpkg: GeoPackage connection wrapper for reading (and later writing) layers.
GpkgAttributeRow: A single row from a GeoPackage attribute table (no geometry).
GpkgAttributeTable: A GeoPackage attribute table (non-spatial, no geometry column).
GpkgFeature: A single feature with geometry bytes and owned properties.
GpkgFeatureBatchIterator: Iterator that yields batches of features from a layer.
GpkgLayer: A GeoPackage layer with geometry metadata and column specs.
GpkgLayerMetadata: Layer-wide metadata and property column definitions.

Enums§

ColumnType: Logical column types used by GeoPackage layers and DDL helpers.
Dimension: Supported WKB dimensions
GeometryType: The geometry type of the WKB object.
GpkgError: Crate error type for GeoPackage operations.
Value: Owned dynamic value used for feature properties.

Functions§

register_spatial_functions: Register all spatial SQL helper functions in the provided connection.

Type Aliases§

Result