rusqlite_gpkg/
lib.rs

1//! GeoPackage reader/writer built on top of rusqlite.
2//!
3//! ## Overview
4//!
5//! - `Gpkg` represents the GeoPackage connection.
6//! - `GpkgLayer` represents a single layer (feature table).
7//! - `GpkgFeature` represents a single feature (row).
8//! - `Value` represents a single property value.
9//!
10//! Apache Arrow support is available behind the `arrow` feature flag.
11//!
12//! `Gpkg` is the entry point and supports several open modes:
13//! `Gpkg::open_read_only(path)`, `Gpkg::open(path)`, and `Gpkg::open_in_memory()`.
14//!
15//! `GpkgLayer::features()` loads all features into memory. For large datasets,
16//! use `features_batch(batch_size)` to stream in chunks.
17//!
18//! `GpkgLayer::insert` and `GpkgLayer::update` accept any geometry that implements
19//! `geo_traits::GeometryTrait<T = f64>` (for example `geo_types::Point`).
20//!
21//! ## Browser usage (to_bytes / from_bytes)
22//!
23//! In browser environments, file access is often unavailable. Use `to_bytes()` to
24//! serialize an in-memory GeoPackage and `from_bytes()` to restore it later.
25//!
26//! ```no_run
27//! use rusqlite_gpkg::Gpkg;
28//! let gpkg = Gpkg::open_in_memory()?;
29//! let bytes = gpkg.to_bytes()?;
30//! let _restored = Gpkg::from_bytes(&bytes)?;
31//! # Ok::<(), rusqlite_gpkg::GpkgError>(())
32//! ```
33//!
34//! ## Gpkg
35//!
36//! `Gpkg` represents the GeoPackage connection and is the entry point for
37//! opening databases, listing layers, and creating new layers.
38//!
39//! ```no_run
40//! use rusqlite_gpkg::Gpkg;
41//! let gpkg = Gpkg::open_read_only("data/example.gpkg")?;
42//! let layer = gpkg.get_layer("points")?;
43//! # Ok::<(), rusqlite_gpkg::GpkgError>(())
44//! ```
45//!
46//! ## GpkgLayer
47//!
48//! `GpkgLayer` models a single feature table. It exposes schema information
49//! (geometry column, property columns) and provides read/write operations.
50//!
51//! ```no_run
52//! use geo_types::Point;
53//! use rusqlite_gpkg::{Gpkg, params};
54//! let layer = Gpkg::open("data.gpkg")?.get_layer("points")?;
55//! layer.insert(Point::new(1.0, 2.0), params!["alpha", 7_i64])?;
56//! # Ok::<(), rusqlite_gpkg::GpkgError>(())
57//! ```
58//!
59//! ## GpkgFeature
60//!
61//! `GpkgFeature` represents one row. You can read the primary key, geometry, and
62//! property values from it.
63//!
64//! ```no_run
65//! use rusqlite_gpkg::Gpkg;
66//! let features = Gpkg::open_read_only("data.gpkg")?
67//!     .get_layer("points")?
68//!     .features()?;
69//! let feature = features.first().expect("feature");
70//! let _geom = feature.geometry()?;
71//! # Ok::<(), rusqlite_gpkg::GpkgError>(())
72//! ```
73//!
74//! ## Value
75//!
76//! `Value` is the crate's owned dynamic value for feature properties, mirroring
77//! SQLite's dynamic typing. Convert with `try_into()` or match directly.
78//!
79//! ```no_run
80//! use rusqlite_gpkg::Gpkg;
81//! let features = Gpkg::open_read_only("data.gpkg")?
82//!     .get_layer("points")?
83//!     .features()?;
84//! let feature = features.first().expect("feature");
85//! let name: String = feature.property("name").ok_or("missing name")?.try_into()?;
86//! # Ok::<(), rusqlite_gpkg::GpkgError>(())
87//! ```
88//!
89//! ## Arrow (feature = "arrow")
90//!
91//! The Arrow reader yields `RecordBatch`es for a layer. It borrows the `Gpkg`
92//! because it holds a prepared statement internally.
93//!
94//! ```no_run
95//! # #[cfg(feature = "arrow")]
96//! use rusqlite_gpkg::{ArrowGpkgReader, Gpkg};
97//! # #[cfg(feature = "arrow")]
98//! fn main() -> Result<(), Box<dyn std::error::Error>> {
99//!     let gpkg = Gpkg::open_read_only("data/example.gpkg")?;
100//!     let mut reader = ArrowGpkgReader::new(&gpkg, "points", 256)?;
101//!     let _batch = reader.next().transpose()?;
102//!     Ok(())
103//! }
104//! # #[cfg(not(feature = "arrow"))]
105//! fn main() {}
106//! ```
107mod error;
108mod gpkg;
109mod sql_functions;
110
111#[cfg(feature = "arrow")]
112mod arrow;
113
114mod conversions;
115mod ogc_sql;
116mod types;
117
118#[cfg(feature = "arrow")]
119pub use arrow::reader::ArrowGpkgReader;
120
121pub use error::{GpkgError, Result};
122pub use gpkg::{Gpkg, GpkgFeature, GpkgFeatureBatchIterator, GpkgLayer};
123pub use sql_functions::register_spatial_functions;
124pub use types::{ColumnSpec, ColumnType, GpkgLayerMetadata, Value};
125
126// Re-export types used in public fields to keep the public API stable.
127pub use wkb::reader::{Dimension, GeometryType};
rusqlite_gpkg/lib.rs

rusqlite_gpkg/
lib.rs
