Crate pg_worm

source ·
Expand description

pg-worm

PostgreSQL’s Worst ORM

pg-worm is an opiniated, straightforward, async ORM for PostgreSQL servers. Well, at least that’s the goal.

This library is based on tokio_postgres and is intended to be used with tokio.

Usage

Fortunately, using this library is very easy.

Just derive the Model trait for your type, connect to your database and you are ready to go!

Here’s a quick example:

use pg_worm::{register, connect, NoTls, Model, Filter};

#[derive(Model)]
// Postgres doesn't allow tables named `user`
#[table(table_name = "users")]
struct User {
    // A primary key which automatically increments
    #[column(primary_key, auto)]
    id: i64,
    // A column which requires unique values
    #[column(unique)]
    name: String,
    // You can rename columns too
    #[column(column_name = "pwd_hash")]
    password: String
}

#[tokio::main]
async fn main() -> Result<(), pg_worm::Error> {
    // Simply connect to your server...
    connect!("postgres://me:me@localhost:5432", NoTls).await?;

    // ...and then register your `Model`.
    // This creates a new table. Be aware
    // that any old table with the same name
    // will be dropped and you _will_ lose your data.
    register!(User).await?;

    // Now start doing what you actually care about.

    // First, we will create some new users.
    User::insert("Bob", "very_hashed_password").await?;
    User::insert("Kate", "another_hashed_password").await?;

    // Querying data is just as easy:

    // Retrieve all users there are...
    let all_users: Vec<User> = User::select(Filter::all()).await;     
    assert_eq!(all_users.len(), 2);
     
    // Or look for Bob...
    let bob: Option<User> = User::select_one(User::name.eq("Bob")).await;
    assert!(bob.is_some());
    assert_eq!(bob.unwrap().name, "Bob");
     
    // Or delete Bob, since he does not actually exists
    User::delete(User::name.eq("Bob")).await;

    // Graceful shutdown
    Ok(())
}

Filters

Filters can be used to easily include WHERE clauses in your queries.

They can be constructed by calling functions of the respective column. pg_worm automatically constructs a Column constant for each field of your Model.

A practical example would look like this:

ⓘ
MyModel::select(MyModel::my_field.eq(5))

Currently the following filter functions are supported:

  • Filter::all() - doesn’t check anything
  • eq(T) - checks whether the column value is equal to something
  • neq(T) - checks whether the column value is not equal to something
  • one_of(Vec<T>) - checks whether the vector contains the column value.
  • none_of(Vec<T>) - checks whether the vector does not contain the column value.

You can also do filter logic using & and |: MyModel::my_field.eq(5) & MyModel::other_field.neq("Foo"). This works as you expect logical OR and AND to work. Please notice that, at this point, custom priorization via parantheses is not possible.

Opiniatedness

As mentioned before, pg_worm is opiniated in a number of ways. These include:

  • panics. For the sake of convenience pg_worm only returns a Result when inserting data, since in that case Postgres might reject the data because of some constraint.

    This means that should something go wrong, like:

    • the connection to the database collapsed,
    • pg_worm is unable to parse Postgres’ response,
    • …

    the program will panic.

  • ease of use. The goal of pg_worm is not to become an enterprise solution. If adding an option means infringing the ease of use then it will likely not be added.

Re-exports

Macros

  • connect
    Convenience macro for connecting the pg-worm client to a database server. Essentially writes the boilerplate code needed. See the tokio_postgres documentation for more information on the config format.
  • register
    Registers a Model with the database by creating a corresponding table.

Structs

  • Column
  • Filter
    Struct for filtering your queries.
  • NoTls
    A MakeTlsConnect and TlsConnect implementation which simply returns an error.
  • Row
    A row of data returned from the database by a query.

Enums

Traits

  • Model
    This is the trait which you should derive for your model structs.

Functions

  • _get_client
    Get a reference to the client, if a connection has been made. Returns Err(Error::NotConnected) otherwise.
  • connect
    Connect the pg_worm client to a postgres database.
  • register_model
    Register your model with the database. This creates a table representing your model.

Attribute Macros

Derive Macros

  • Model
    Automatically implement Model for your struct.