Crate orma

orma

A PostgreSQL ORM written in Rust language

Introduction

When you feel the need to persist data as documents on PostgreSQL you often want a way to map these documents on structs.

If you have such needs and you are using PostgreSQL instead of other databases, it’s probably because you also want all other cool stuff present in PostgreSQL.

orma is a special ORM for PostgreSQL written in Rust language developed just for you!

orma takes advantage of PostgreSQL JSONB data representation and doesn’t give up the relational advantages of a RDBMS like PostgreSQL.

orma provides out of the box features for search and CRUD operation over your documents

orma is fast and easy to learn, with a very simple API.

Quick start

orma is thought to be mapped over tables that have at least the following columns:

- id: uuid NOT NULL
- version: integer NOT NULL
- data: jsonb

• id identifies a record.
• version is used for record versioning and prevents a record to be modified if version has changed in another session. orma takes care of record versioning OOTB.
• data is used to map the document and it’s mapped over structs that implement DbData trait.

All structs that implement DbData trait need to be serializable too, as they’ll be represented as jsonb data in your db records.

While DbData is mapped to data column, DbEntity is mapped over the three columns, and table, just described.

You can use DbEntity<DbData> to perform search and crud operations.

If you need to relate two different entities, DbJoin<DbData> is used to get entities related to the specified DbData.
You need to use JoinBuilder to create a DbJoin relation, and you can define both simple joins and table joins for M to N relations.

Example

Using an imaginary “pgactix” database.

use orma_derive::DbData;
use serde_derive::Serialize;
use orma::*;

async fn create_connection() -> Connection {
    let connection_string = format!(
        "host={host} port={port} dbname={dbname} user={user} password={password}",
        host = &env::var("INTRARED_DB_HOSTNAME").unwrap_or_else(|_| "localhost".to_string()),
        port = env::var("INTRARED_DB_PORT").unwrap_or_else(|_| "5433".to_string()),
        dbname = env::var("INTRARED_DB_NAME").unwrap_or_else(|_| "pgactix".to_string()),
        user = env::var("INTRARED_DB_USERNAME").unwrap_or_else(|_| "pgactix".to_string()),
        password = env::var("INTRARED_DB_PASSWORD").unwrap_or_else(|_| "pgactix".to_string()),
    );
    let (client, conn) = tokio_postgres::connect(&connection_string, tokio_postgres::NoTls)
        .await
        .unwrap();
    tokio::spawn(conn);
    client.into()
}

#[pk(field_1 = "field1", field_2 = "field2")]
#[table("schema.table_name")]
#[derive(Serialize, DbData)]
struct TestData {
    field_1: String,
    field_2: String,
    some_other_filed: Option<Vec<String>>,
}

Modules

tls

Macros

new_data

Structs

Client

An asynchronous PostgreSQL client.

Config

Connection configuration.

Connection

Wrapper over tokio_postgres::Client

DbEntity

This struct is used to create a mapping for a data table.

DbError

Errors are mapped to this structure

DbJoin

This struct is used to create a join between DbEntyty elements and JoinBuilder is used to create a DbJoin instance.

JoinBuilder

NoTls

A MakeTlsConnect and TlsConnect implementation which simply returns an error.

Row

wrapper for tokio_postgres::Row

RowStream

A stream of table rows.

SimpleQueryRow

wrapper for tokio_postgres::SimpleQueryRow

Socket

The standard stream type used by the crate.

Statement

Wrapper around tokio_postgres::Statement

Uuid

A Universally Unique Identifier (UUID).

Enums

SimpleQueryMessage

Traits

DbData

This trait is maps data in a data table and it’s used along with DbEntity structure

ToSql

A trait for types that can be converted into Postgres values.

ToStatement

Like tokio_postgres::ToStatement trait

Functions

select_part

Helper function to create a SQL SELECT statement for a DbEntity table. This method returns the (id, version, data) tuple