rusqlite-gpkg

GeoPackage reader/writer built on top of rusqlite.

Web Demo

A simple GitHub Pages demo is available with a button to generate and download a .gpkg file in the browser using a Web Worker + OPFS.

https://yutannihilation.github.io/rusqlite-gpkg/

See web/README.md for implementation details and design notes.

Overview

rusqlite-gpkg provides a small API around the main GeoPackage concepts:

Feature layers (spatial data with geometry):

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

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

• GpkgAttributeTable represents a single attribute table.
• GpkgAttributeRow represents a single row (properties only).

Value represents a single property value in both cases.

Apache Arrow support is available behind the arrow feature flag. You can find some example codes in the bottom of this README.

The library focuses on simple, explicit flows. You control how layers are created and which property columns are present.

Browser usage (to_bytes / from_bytes)

Web environments often cannot access files directly (OPFS can be used by rusqlite, but this crate does not currently expose a way to enable it). In those cases, the recommended workflow is to serialize a GeoPackage to bytes.

use rusqlite_gpkg::Gpkg;

let gpkg = Gpkg::open_in_memory()?;
// ... write layers/features ...
let bytes = gpkg.to_bytes()?; // store bytes in IndexedDB, send over network, etc.

let restored = Gpkg::from_bytes(&bytes)?;
# Ok::<(), rusqlite_gpkg::GpkgError>(())

Gpkg

Gpkg represents the GeoPackage connection and is the entry point for almost all operations. There are multiple ways to open it:

• Gpkg::open_read_only(path): open an existing file without write access.
• Gpkg::open(path): open a new or existing file for read/write.
• Gpkg::open_in_memory(): create a transient in-memory GeoPackage.

From a Gpkg, you can discover or create content:

Feature layers:

• list_layers() returns the feature layer names.
• get_layer(name) loads a GpkgLayer by name.
• create_layer(...) creates a new feature layer and returns a GpkgLayer.

Attribute tables:

• list_attribute_tables() returns the attribute table names.
• get_attribute_table(name) loads a GpkgAttributeTable by name.
• create_attribute_table(...) creates a new attribute table and returns a GpkgAttributeTable.

use rusqlite_gpkg::Gpkg;

let gpkg = Gpkg::open_read_only("data/example.gpkg")?;
let layers = gpkg.list_layers()?;
let layer = gpkg.get_layer(&layers[0])?;
# Ok::<(), rusqlite_gpkg::GpkgError>(())

GpkgLayer

GpkgLayer represents a single feature table. You typically get it from Gpkg::get_layer (for existing data) or Gpkg::create_layer (for new data). It exposes the layer schema (geometry column name, property columns) and methods to iterate, insert, or update features. Insertions and updates accept any geometry that implements geo_traits::GeometryTrait<T = f64>, including common types from geo_types and parsed wkt::Wkt.

GpkgLayer::features() always allocates a Vec<GpkgFeature> for the whole layer. For large datasets, use features_batch(batch_size) to stream features in chunks and limit peak memory.

use geo_types::Point;
use rusqlite_gpkg::{ColumnSpec, ColumnType, Gpkg, params};

let gpkg = Gpkg::new("data/new.gpkg")?;
let columns = vec![
    ColumnSpec { name: "name".to_string(), column_type: ColumnType::Varchar },
    ColumnSpec { name: "value".to_string(), column_type: ColumnType::Integer },
];
let layer = gpkg.create_layer(
    "points",
    "geom".to_string(),
    wkb::reader::GeometryType::Point,
    wkb::reader::Dimension::Xy,
    4326,
    &columns,
)?;

layer.insert(Point::new(1.0, 2.0), params!["alpha", 7_i64])?;
let count = layer.features()?.count();
# Ok::<(), rusqlite_gpkg::GpkgError>(())

Batch iteration example:

use rusqlite_gpkg::Gpkg;

let gpkg = Gpkg::open_read_only("data/example.gpkg")?;
let layer = gpkg.get_layer("points")?;
for batch in layer.features_batch(100)? {
    let features = batch?;
    for feature in features {
        let _id = feature.id();
        let _geom = feature.geometry()?;
    }
}
# Ok::<(), rusqlite_gpkg::GpkgError>(())

You might notice the params! macro in the example above. It is useful when you want to pass a fixed list of values.

params! accepts Option<T> and converts None to SQL NULL. Because None has no inherent type, you may need to annotate it:

layer.insert(
    Point::new(0.0, 0.0),
    params![Some(1.0_f64), Option::<i64>::None],
)?;

When programmatically constructing parameters, build an iterator of &Value from owned values:

use rusqlite_gpkg::Value;

fn convert_to_value(input: &str) -> Value {
    Value::from(input)
}

let raw = vec!["alpha", "beta"];
let values: Vec<Value> = raw.iter().map(|v| convert_to_value(v)).collect();
layer.insert(Point::new(1.0, 2.0), values.iter())?;

GpkgFeature

GpkgFeature represents one row in a layer. You usually obtain it by iterating GpkgLayer::features(). It provides the primary key (id()), geometry (geometry()), and property access via property(name) returning an owned Value. The geometry is returned as a wkb::reader::Wkb, which you can inspect or convert to WKT for display.

use rusqlite_gpkg::Gpkg;
use wkt::to_wkt::write_geometry;

let gpkg = Gpkg::open_read_only("data/example.gpkg")?;
let layer = gpkg.get_layer("points")?;
let features = layer.features()?;
let feature = features.first().expect("feature");
let id = feature.id();
let geom = feature.geometry()?;
let mut wkt = String::new();
write_geometry(&mut wkt, &geom)?;
let name: String = feature
    .property("name")
    .ok_or("missing name")?
    .try_into()?;
# Ok::<(), rusqlite_gpkg::GpkgError>(())

Value

Value is the crate's owned dynamic value used for feature properties. It mirrors SQLite's dynamic typing (null, integer, real, text, blob) and is returned by GpkgFeature::property as Option<Value>. Convert using try_into() or match directly.

use rusqlite_gpkg::Gpkg;

let gpkg = Gpkg::open_read_only("data/example.gpkg")?;
let layer = gpkg.get_layer("points")?;
let features = layer.features()?;
let feature = features.first().expect("feature");

let name: String = feature.property("name").ok_or("missing name")?.try_into()?;
let active: bool = feature.property("active").ok_or("missing active")?.try_into()?;
# Ok::<(), rusqlite_gpkg::GpkgError>(())

The conversion above returns an error if the value is NULL. If you want to handle NULL, convert to Option<T>; NULL becomes None and non-null values become Some(T):

use rusqlite_gpkg::Value;

let value = Value::Null;
let maybe_i64: Option<i64> = value.try_into()?;
assert_eq!(maybe_i64, None);
# Ok::<(), rusqlite_gpkg::GpkgError>(())

GpkgAttributeTable

GpkgAttributeTable represents a non-spatial table (no geometry column). It follows the GeoPackage spec Section 2.4 (data_type = 'attributes' in gpkg_contents). The API mirrors GpkgLayer but without geometry arguments.

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])?;
table.insert(params!["beta", 9_i64])?;

let rows = table.rows()?;
let name: String = rows[0].property("name").unwrap().try_into()?;
assert_eq!(name, "alpha");
# Ok::<(), rusqlite_gpkg::GpkgError>(())

Disclaimer

Most of the implementation is coded by Codex, while the primary idea is based on my own work in https://github.com/yutannihilation/duckdb-ext-st-read-multi/pulls. This probably requires more testing against real data; feedback is welcome!

Prior Work

• https://github.com/cjriley9/gpkg-rs

Example

Reader

use rusqlite_gpkg::{Gpkg, Value};
use wkt::to_wkt::write_geometry;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let gpkg = Gpkg::open("data.gpkg")?;
    for layer_name in gpkg.list_layers()? {
        let layer = gpkg.get_layer(&layer_name)?;
        for feature in layer.features()? {
            let geom = feature.geometry()?;

            // Convert geometry to WKT for display.
            let mut wkt = String::new();
            write_geometry(&mut wkt, &geom)?;
            println!("{layer_name}: {wkt}");

            for column in &layer.property_columns {
                // Property values are returned as `Value`.
                let value = feature.property(&column.name).unwrap_or(Value::Null);
                println!("  {} = {:?}", column.name, value);
            }
        }
    }
    Ok(())
}

Writer

use geo_types::Point;
use rusqlite_gpkg::{ColumnSpec, ColumnType, Gpkg, params};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let gpkg = Gpkg::new("data.gpkg")?;

    let columns = vec![
        ColumnSpec {
            name: "name".to_string(),
            column_type: ColumnType::Varchar,
        },
        ColumnSpec {
            name: "value".to_string(),
            column_type: ColumnType::Integer,
        },
    ];

    let layer = gpkg.create_layer(
        "points",
        "geom".to_string(),
        wkb::reader::GeometryType::Point,
        wkb::reader::Dimension::Xy,
        4326,
        &columns,
    )?;

    // Insert a feature with geometry and property values.
    layer.insert(
        Point::new(1.0, 2.0),    // geometry: You can pass whatever object that implements GeometryTrait
        params!["alpha", 7_i64], // other properties: pass references to Value
    )?;

    Ok(())
}

Arrow reader

use rusqlite_gpkg::{ArrowGpkgReader, Gpkg};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open an existing GeoPackage and stream Arrow batches.
    let gpkg = Gpkg::open_read_only("data/example.gpkg")?;
    let mut reader = ArrowGpkgReader::new(&gpkg, "points", 1024)?;
    while let Some(batch) = reader.next() {
        let batch = batch?;
        // Use the Arrow RecordBatch API.
        println!("rows = {}", batch.num_rows());
    }
    Ok(())
}

Arrow writer

[!WARNING] When the writer auto-registers a non-default SRS (anything other than the built-in EPSG:4326), the definition column in gpkg_spatial_ref_sys is set to "undefined" because we don't have a WKT1 source for arbitrary EPSG codes. Some GeoPackage consumers may expect a proper WKT1 definition there.

use arrow_array::{Int64Array, RecordBatch, StringArray};
use arrow_schema::{Field, Schema};
use rusqlite_gpkg::{ArrowGpkgWriter, Gpkg};
use std::sync::Arc;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let gpkg = Gpkg::open_in_memory()?;

    // Build a RecordBatch with a GeoArrow WKB geometry column and property columns.
    // (The geometry field must carry GeoArrow extension metadata with CRS information
    // so that the writer can derive the EPSG srs_id.)
    let schema = Arc::new(Schema::new(vec![
        Arc::new(geom_field),   // WKB geometry field with GeoArrow metadata
        Arc::new(Field::new("name", arrow_schema::DataType::Utf8, true)),
        Arc::new(Field::new("value", arrow_schema::DataType::Int64, true)),
    ]));
    let batch = RecordBatch::try_new(schema, vec![geom_array, name_array, value_array])?;

    // Write the batch into a new GeoPackage layer.
    let mut writer = ArrowGpkgWriter::new(&gpkg, "my_layer")?;
    writer.write(&batch)?;

    Ok(())
}

Arrow attribute table reader/writer

use arrow_array::{Int64Array, RecordBatch, StringArray};
use arrow_schema::{Field, Schema};
use rusqlite_gpkg::{ArrowGpkgAttributeReader, ArrowGpkgAttributeWriter, Gpkg};
use std::sync::Arc;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let gpkg = Gpkg::open_in_memory()?;

    // Build a RecordBatch without any geometry column.
    let schema = Arc::new(Schema::new(vec![
        Arc::new(Field::new("name", arrow_schema::DataType::Utf8, true)),
        Arc::new(Field::new("value", arrow_schema::DataType::Int64, true)),
    ]));
    let name_array = Arc::new(StringArray::from(vec!["alpha", "beta"]));
    let value_array = Arc::new(Int64Array::from(vec![10, 20]));
    let batch = RecordBatch::try_new(schema, vec![name_array, value_array])?;

    // Write into a new attribute table.
    let mut writer = ArrowGpkgAttributeWriter::new(&gpkg, "observations")?;
    writer.write(&batch)?;

    // Read back.
    let mut reader = ArrowGpkgAttributeReader::new(&gpkg, "observations", 1024)?;
    while let Some(batch) = reader.next() {
        let batch = batch?;
        println!("rows = {}", batch.num_rows());
    }

    Ok(())
}

Arrow geometry handling

use geoarrow_array::array::WkbArray;
use geoarrow_array::GeoArrowArrayAccessor;
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)?;
    if let Some(batch) = reader.next() {
        let batch = batch?;
        let geom_index = batch.num_columns() - 1;
        let schema = batch.schema();
        let geom_field = schema.field(geom_index).as_ref();
        let geom_array =
            WkbArray::try_from((batch.column(geom_index).as_ref(), geom_field))?;

        // Access raw WKB bytes from the geometry column.
        let wkb = geom_array.value(0)?;
        let _bytes: &[u8] = wkb.buf();
    }
    Ok(())
}