Adding `starberry_sql` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add starberry_sql

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

starberry_sql = "0.6.4"

The starberry_sql library will be automatically available globally. Read the starberry_sql library documentation.

Back to the crate overview.

Readme

starberry_sql

starberry_sql is an asynchronous SQL client and query builder designed for the Starberry ecosystem. It provides a simple, type-safe API to execute queries, map rows to structs, manage transactions, and handle connection pooling.

Features

Asynchronous connections via tokio
Secure TLS support using rustls
Safe parameter binding with the Encode trait
Flexible query builder via SqlQuery
Automatic row-to-struct mapping with the FromRow trait
Convenient result handling through QueryResult methods
Connection pooling with SqlPool
Transaction support: begin, commit, rollback
Batch execution and prepared statements
Customizable SQL context via SqlContext

Installation

Add starberry_sql to your Cargo.toml:

[dependencies]
starberry_sql = "0.6.0"

Then import in your code:

use starberry_sql::*;

Quick Start

Establish a Connection

use starberry_sql::{DbConnectionBuilder, DbError, SslMode};

#[tokio::main]
async fn main() -> Result<(), DbError> {
    let mut conn = DbConnectionBuilder::new("127.0.0.1", 5432)
        .ssl_mode(SslMode::Disable)
        .database("postgres")
        .username("postgres")
        .password("secret")
        .connect()
        .await?;
    Ok(())
}

Execute a Simple Query

let rows = SqlQuery::new("SELECT 1 AS a, 'foo' AS b")
    .fetch_all(&mut conn)
    .await?;
for row in rows {
    println!("a = {}", row.get("a").unwrap());
}

Insert Data with Parameter Binding

let count = SqlQuery::new("INSERT INTO users (name, age) VALUES ($1, $2)")
    .bind("Alice")
    .bind(30)
    .execute(&mut conn)
    .await?;
println!("Inserted {} rows", count);

Map Rows to Your Structs

use std::collections::HashMap;
use starberry_sql::{FromRow, DbError};

#[derive(Debug)]
struct User { id: i32, name: String }

impl FromRow for User {
    fn from_row(row: &HashMap<String, String>) -> Result<Self, DbError> {
        Ok(User {
            id: row.get("id").unwrap().parse().unwrap(),
            name: row.get("name").unwrap().to_string(),
        })
    }
}

let users: Vec<User> = SqlQuery::new("SELECT id, name FROM users")
    .fetch_all_as(&mut conn)
    .await?;

Connection Pooling

let builder = DbConnectionBuilder::new("127.0.0.1", 5432)
    .ssl_mode(SslMode::Disable)
    .database("postgres")
    .username("postgres")
    .password("secret");
let pool = SqlPool::new(builder, 5);

let row = SqlQuery::new("SELECT COUNT(*) AS count")
    .fetch_one_pool(&pool)
    .await?;

Transactions

conn.begin_transaction().await?;
// perform multiple statements
conn.commit_transaction().await?;

Batch Execution and Prepared Statements

let total = conn.batch_execute(vec![
    ("INSERT INTO tx_test (id, name) VALUES ($1, $2)", vec!["1".to_string(), "One".to_string()]),
    ("INSERT INTO tx_test (id, name) VALUES ($1, $2)", vec!["2".to_string(), "Two".to_string()]),
])
.await?
.row_count();

let stmt = conn.prepare_statement("INSERT INTO tx_test (id, name) VALUES ($1, $2)")
    .await?;
let result = conn.execute_prepared(&stmt, vec!["5".to_string(), "Five".to_string()])
    .await?;

Modules Overview

DbConnectionBuilder: Configure and establish database connections.
SqlQuery: Build and execute queries with parameter binding.
SqlPool: Manage a pool of connections for concurrent usage.
SqlContext: Customize SQL execution context and settings.
Encode trait: Convert Rust types into SQL-escaped literals.
FromRow trait: Map a row (as HashMap<String, String>) into a struct.
QueryResult: Handle query outcomes (Rows, Count, Empty, Error).
DbError: Unified error type for connection and query operations.

License

starberry_sql is released under the MIT License. See LICENSE for details.

Adding starberry_sql library as a dependency

Adding `starberry_sql` library as a dependency