diesel_mysql_spatial/
lib.rs

1//! Diesel MySQL Spatial is an extension to [Diesel] that provides support for
2//! the MySQL flavour of OpenGIS spatial data types and the associated SQL functions.
3//!
4//! ## Declaring your schema
5//! The types in [`diesel_mysql_spatial::sql_types`] may be used in Diesel `table!` macros.
6//!
7//! If you use the `diesel.toml` file for automatic schema generation, you need to add the
8//! module to the `import_types` list:
9//! ```toml
10//! [print_schema]
11//! ## Add types from `diesel_mysql_spatial` like `LineString`
12//! import_types = ["diesel::sql_types::*", "diesel_mysql_spatial::sql_types::*"]
13//! ```
14//!
15//! ## Constructing a query
16//!
17//! This crate provides Diesel DSL functions for most spatial SQL functions.
18//! They live in [the `dsl` module](dsl).
19//!
20//! ```no_compile
21//! use diesel_mysql_spatial::dsl::ST_IsValid;
22//!
23//! let valid_districts = districts.select(area).filter(ST_IsValid(area));
24//! ```
25//!
26//! ## Serializing and Deserializing
27//!
28//! Diesel MySQL Spatial maps "Rust types" defined in [the `data_types` module] (e.g.
29//! [`diesel_mysql_spatial::data_types::Point`]) to and from "SQL types" (e.g.
30//! [`diesel_mysql_spatial::sql_types::Point`]). The latter types are only used to represent a
31//! SQL type. You should only put the structs in `data_types` into your `Queryable` structs.
32//!
33//! [Diesel]: `diesel`
34//! [`diesel_mysql_spatial::sql_types`]: `sql_types`
35//! [`diesel_mysql_spatial::sql_types::Point`]: `sql_types::Point`
36//! [`diesel_mysql_spatial::data_types::Point`]: `data_types::Point`
37//! [the `data_types` module]: `data_types`
38
39#[macro_use]
40extern crate diesel;
41
42use wkb::{WKBReadError, WKBWriteError};
43
44/// The error type for (de-)serialization and conversion errors of spatial datatypes.
45#[derive(thiserror::Error, Debug)]
46pub enum GeometryError {
47	/// Encountered WKB data in big endian byte order.
48	///
49	/// Should not occur as MySQL only uses little endian for the spatial datatypes.
50	#[error("big endian WKB currently unsupported")]
51	UnsupportedBigEndian,
52
53	/// Unexpected data type encountered (e.g. a `Polygon` instead of a `Point`).
54	#[error("Within in the format, there was an unexpected or wrong data type")]
55	WrongType,
56
57	/// A conversion could not be performed because a value precondition was not fulfilled
58	///
59	/// For example [`data_types::BoundingBox`] requires a `Polygon` in a specific shape.
60	#[error("Invalid value for this conversion")]
61	InvalidValue,
62
63	/// Deserialization failed because of a format mismatch or an I/O error happened in a underlying layer.
64	#[error("IO error: {0}")]
65	IOError(#[from] std::io::Error),
66
67	/// Encountered an unsupported geometry while serializing.
68	#[error("Unsupported geometry")]
69	UnsupportedGeoType,
70}
71
72impl From<WKBReadError> for GeometryError {
73	fn from(e: WKBReadError) -> Self {
74		match e {
75			WKBReadError::UnsupportedBigEndian => GeometryError::UnsupportedBigEndian,
76			WKBReadError::WrongType => GeometryError::WrongType,
77			WKBReadError::IOError(e) => GeometryError::IOError(e),
78		}
79	}
80}
81
82impl From<WKBWriteError> for GeometryError {
83	fn from(e: WKBWriteError) -> Self {
84		match e {
85			WKBWriteError::UnsupportedGeoTypeRect => GeometryError::UnsupportedGeoType,
86			WKBWriteError::UnsupportedGeoTypeTriangle => GeometryError::UnsupportedGeoType,
87			WKBWriteError::IOError(e) => GeometryError::IOError(e),
88		}
89	}
90}
91
92/// Spatial SQL types which may be used in table definitions
93pub mod sql_types;
94
95/// Structs that represent the Rust equivalent of spatial SQL types
96pub mod data_types;
97
98/// MySQL specific spatial functions for use in SQL expressions
99///
100/// All contained functions are also reexported in the `dsl` module.
101pub mod functions;
102
103/// Helper types that represent return types of spatial functions
104///
105/// See also: the [`functions`][`functions`] module.
106///
107/// All contained types are also reexported in the `dsl` module
108pub mod helper_types;
109
110/// Re-exports helper types and functions for SQL expressions
111pub mod dsl;
diesel_mysql_spatial/lib.rs

diesel_mysql_spatial/
lib.rs
