Crate diesel_geometry

Diesel Geometry

Diesel Geometry is an extension to Diesel that provides support for geometric types operators. If this is your first time with Diesel, we recommend starting with diesel’s getting started guide. They also have many other long form guides.

Where to find things

Declaring your schema

So Diesel is able to validate your queries at compile time, it requires you to specify your schema in your code, which you can do with the table! macro from Diesel.

If you can use Diesel >= 1.3, then you can use the diesel.toml file that allows configuring the schema generation process: http://diesel.rs/guides/configuring-diesel-cli/. It allows adding use statements:

[print_schema]
# Add types from `diesel_full_text_search` like `tsvector`
import_types = ["diesel::sql_types::*", "diesel_geometry::sql_types::*"]

Otherwise for Diesel <= 1.2 you must manually modify the generated code to export the diesel_geometry sql types inside each table! macro that uses diesel_geometry types. Because exporting any types inside the table macro overrides the default exports, you must also manually export the diesel sql types as well.

Before, as generated by diesel print-schema before 1.3

table! {
    items {
        id -> Integer,
        name -> VarChar,
        location -> Point,
    }
}

After manual modification

table! {
    use diesel::sql_types::*;
    use diesel_geometry::sql_types::*;
    items {
        id -> Integer,
        name -> VarChar,
        location -> Point,
    }
}

Getting started

Diesel Geometry provides a prelude module, which exports most of the typically used traits and types. We are conservative about what goes in this module, and avoid anything which has a generic name. Files which use Diesel Geometry are expected to have use diesel_geometry::prelude::*;.

Constructing a query

Diesel Geometry extends Diesel in two ways.

• “Expression methods” are things you would call on columns or other individual values. These methods live in the expression_methods module You can often find these by thinking “what would this be called” if it were a method and typing that into the search bar (e.g. ~= is called same_as in Diesel Geometry). Most operators are named based on the Rust function which maps to that operator in std::ops (For example == is called .eq, and != is called .ne).
• “Bare functions” are normal SQL functions such as isclosed. They live in the dsl module.

Serializing and Deserializing

Diesel Geometry maps “Rust types” (e.g. (f64, f64)) to and from “SQL types” (e.g. diesel_geometry::sql_types::Point). You can find all the types supported by Diesel Geometry in the sql_types module. These types are only used to represent a SQL type. You should never put them on your Queryable structs.

To find all the Rust types which can be used with a given SQL type, see the documentation for that SQL type.

Getting help

If you run into problems, email the developers. You can come ask for help at diesel_geometry devs mailing list

Modules

data_types

Structs to represent the primitive equivalent of SQL types where there is no existing Rust primitive, or where using it would be confusing (such as date and time types). This module will re-export all backend specific data structures when compiled against that backend.

dsl

Includes various helper types and bare functions which are named too generically to be included in prelude, but are often used when using Diesel Geometry.

expression

AST types representing various typed SQL expressions.

expression_methods

Adds various methods to construct new expressions. These traits are exported by default, and implemented automatically.

pg

Provides types and functions related to working with PostgreSQL

prelude

Re-exports important traits and types. Meant to be glob imported when using Diesel Geometry.

sql_types

Types which represent a SQL data type.