Crate gel_tokio 

Client for the Gel database, using async Tokio runtime

To get started, check out the Rust client tutorial.

The main way to use Gel bindings is to use the Client. It encompasses connection pool to the database that is transparent for user. Individual queries can be made via methods on the client. Correlated queries are done via transactions.

To create a client, use the create_client function (it gets a database connection configuration from environment). You can also use a Builder to build custom Config and create a client using that config.

Example

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let conn = gel_tokio::create_client().await?;
    let val = conn.query_required_single::<i64, _>(
        "SELECT 7*8",
        &(),
    ).await?;
    println!("7*8 is: {}", val);
    Ok(())
}

More examples on github

Nice Error Reporting

We use miette crate for including snippets in your error reporting code.

To make it work, first you need enable fancy feature in your top-level crate’s Cargo.toml:

[dependencies]
miette = { version="5.3.0", features=["fancy"] }
gel-tokio = { version="*", features=["miette-errors"] }

Then if you use miette all the way through your application, it just works:

#[tokio::main]
async fn main() -> miette::Result<()> {
    let conn = gel_tokio::create_client().await?;
    conn.query::<String, _>("SELECT 1+2)", &()).await?;
    Ok(())
}

However, if you use some boxed error container (e.g. anyhow), you might need to downcast error for printing:

async fn do_something() -> anyhow::Result<()> {
    let conn = gel_tokio::create_client().await?;
    conn.query::<String, _>("SELECT 1+2)", &()).await?;
    Ok(())
}

#[tokio::main]
async fn main() {
    match do_something().await {
        Ok(res) => res,
        Err(e) => {
            e.downcast::<gel_tokio::Error>()
                .map(|e| eprintln!("{:?}", miette::Report::new(e)))
                .unwrap_or_else(|e| eprintln!("{:#}", e));
            std::process::exit(1);
        }
    }
}

In some cases, where parts of your code use miette::Result or miette::Report before converting to the boxed (anyhow) container, you might want a little bit more complex downcasting:

#[tokio::main]
async fn main() {
    match do_something().await {
        Ok(res) => res,
        Err(e) => {
            e.downcast::<gel_tokio::Error>()
                .map(|e| eprintln!("{:?}", miette::Report::new(e)))
                .or_else(|e| e.downcast::<miette::Report>()
                    .map(|e| eprintln!("{:?}", e)))
                .unwrap_or_else(|e| eprintln!("{:#}", e));
            std::process::exit(1);
        }
    }
}

Note that last two examples do hide error contexts from anyhow and do not pretty print if source() of the error is gel_errors::Error but not the top-level one. We leave those more complex cases as an excersize to the reader.

Re-exports

pub use state::ConfigDelta;

pub use state::GlobalsDelta;

Modules

dsn

Gel data-source name (DSN) parser and builder.

state

Connection state modification utilities

tutorial

Gel Rust client tutorial

Structs

Builder

A builder for Config.

Client

Gel database client.

CloudName

The name of a Gel Cloud instance.

Config

The configuration for a connection.

Error

Error type returned from Gel database calls.

ResultVerbose

Query result with additional metadata.

RetryOptions

This structure contains options for retrying transactions and queries

RetryingTransaction

Transaction object passed to the closure via Client::within_transaction() method.

Transaction

A representation of a transaction.

TransactionOptions

Options for transaction()

Enums

InstanceName

Parsed an instance name. This may refer to a locally-linked instance, or a cloud-based instance if the instance name contains a / character.

RetryCondition

Specific condition for retrying queries

TlsSecurity

TLS Client Security Mode

Constants

DEFAULT_PROJECT_FILE

The default project filename.

PROJECT_FILES

The ordered list of project filenames supported.

Traits

QueryExecutor

Abstracts over different query executors In particular &Client and &mut Transaction

Functions

create_client

Create a connection to the database with default parameters

Derive Macros

ConfigDelta

GlobalsDelta

Queryable