Crate tank_core

Expand description

Core primitives for the tank ORM / query toolkit.

This crate exposes a thin, async-first abstraction layer over SQL backends. The goal is portability – the same entity and query building code should compile and run against multiple SQL engines with minimal (ideally zero) changes.

§Design Highlights

“Bring your own runtime” – traits return impl Future / impl Stream. You can use Tokio, async-std, or any executor capable of driving futures streams. This varies from driver to driver.
Streaming results (Executor::run / fetch) to avoid buffering entire result sets.
A rich Value enum representing typed SQL values (including arrays, maps, structs, intervals, decimals) with conversion helpers via AsValue.
Declarative entity definition through the Entity trait + derive macro.
Dialect pluggability: the Driver supplies a SqlWriter that renders the appropriate SQL for its backend.
Composability: expressions / datasets build larger statements (SELECT, INSERT, DELETE) without stringly-typed concatenation.

§Quick Start

use tank::{Entity, Executor};
use uuid::Uuid;

#[derive(tank::Entity)]
#[tank(schema = "operations")]
struct Operator {
    #[tank(primary_key)]
    id: Uuid,
    callsign: String,
    #[tank(name = "rank")]
    service_rank: String,
}

async fn demo<E: Executor>(exec: &mut E, id: Uuid) -> anyhow::Result<Option<Operator>> {
    // Ensure table exists (idempotent when supported by driver)
    Operator::create_table(exec, true, true).await?;

    // Upsert an operator
    Operator { id, callsign: "Red-One".into(), service_rank: "LT".into() }
        .save(exec).await?;

    // Fetch it back
    let op = Operator::find_one(exec, &true).await?; // bool implements Expression
    Ok(op)
}

§Error Handling

All fallible operations use crate-level Result<T> (anyhow::Result<T>). For detailed context attachers prefer ErrorContext.

§Futures & Streams MUST be driven

Any method returning a future or stream performs no guaranteed side-effect until it is awaited / fully consumed. Never drop them silently.

§Feature Flags

Drivers may expose feature flags (e.g. disabling 128-bit integers). This crate itself is mostly feature-free; consult driver crates for details.

§Modules

The public surface re-exports most modules. Common entry points:

Entity – declare and persist typed rows.
Executor – run queries, fetch streams.
Query, QueryResult – represent prepared/raw statements & results.
Value, AsValue – value type system & conversions.
SqlWriter – backend SQL generation.
Interval – time span type usable as SQL INTERVAL.
Join, Expression – build complex predicates / SELECT trees.

For more elaborate examples inspect the tank-tests crate in the repository (src/simple.rs, src/transaction1.rs, etc.).

§Macros

Supporting macros like truncate_long!, possibly_parenthesized! and take_until! assist with SQL / token generation. They are re-exported at crate root for macro expansion within derives.

§Safety & Portability Notes

Do not rely on side-effects before awaiting returned futures.
Always exhaust streams if the driver might hold transactional or cursor resources.
When mapping Value conversions prefer AsValue::try_from_value for graceful errors.

§Contributing Docs

When adding new traits or types ensure they carry /// rustdoc including:

Purpose & invariants
Example snippet (consider pulling from tests)
Error semantics

Re-exports§

pub use ::indoc;

Modules§

future: Asynchronous values.
sink: Asynchronous sinks.
stream

Macros§

impl_executor_transaction
possibly_parenthesized
send_value: Sends the value through the channel and logs in case of error.
take_until: Accumulates tokens until one of the supplied parsers succeeds.
truncate_long

Structs§

BinaryOp
ColumnDef: Declarative specification of a table column.
ColumnRef: Fully-ì-qualified reference to a table column.
Context
ContextUpdater
DeclareTableRef: Wrapper used when declaring table references in generated macros.
FixedDecimal: Decimal wrapper enforcing compile-time width/scale.
GenericSqlWriter: Fallback generic SQL writer (closest to PostgreSQL / DuckDB conventions).
Interval
Join: Binary join of two datasets with optional ON predicate.
Ordered
References: Foreign key reference to another Entity’s columns.
RowLabeled: A result row with its corresponding column labels.
RowsAffected: Metadata about modify operations (INSERT/UPDATE/DELETE).
TableRef: Reference to a table (schema-qualified + optional alias).
TypeDecoded: Intermediate decoded type information used by derive macros.
UnaryOp

Enums§

Action: Referential action for foreign key updates / deletes.
BinaryOpType
EitherIterator: Polymorphic iterator adapter returning items from either variant.
Fragment
IntervalUnit
JoinType: Supported SQL join variants.
Operand
Order
Passive: Wrapper marking whether a column should be considered set or skipped (passive) on INSERT.
PrimaryKeyType: Indicates how (or if) a column participates in the primary key.
Query: A query ready to be executed by an Executor.
QueryResult: Heterogeneous items emitted by Executor::run combining rows and modify results.
UnaryOpType
Value: Strongly-typed, nullable SQL value representation used across Tank.

Traits§

AsValue
ColumnTrait: Helper trait for types that expose an underlying column definition and reference.
Connection: A live database handle capable of executing queries and spawning transactions.
DataSet: A selectable data source (table, join tree).
Driver: A backend implementation providing connection + SQL dialect services.
Entity: Represents a database-backed record with schema and persistence behavior.
ErrorContext: Provides the context method for Result.
Executor: Async query executor bound to a concrete Driver.
Expression: A renderable SQL expression node.
OpPrecedence: Provides numeric precedence for expressions allowing dialect writers to insert parentheses.
Prepared: A parameterized, backend-prepared query handle.
SqlWriter: Dialect printer converting semantic constructs into concrete SQL strings.
Transaction: A mutable transactional context implementing Executor.

Functions§

as_c_string: Convenience wrapper converting into a CString, panicking on interior NUL.
consume_while: Consume a prefix of input while the predicate returns true, returning that slice.
decode_type
matches_path: Determine if the trailing segments of a syn::Path match the expected identifiers.
quote_cow: Quote a Cow<T> preserving borrowed vs owned status for generated code.
quote_option: Quote an Option<T> into tokens.
separated_by: Write an iterator of items separated by a delimiter into a string.

Type Aliases§

CheckPassive
Error: Crate-wide error alias using anyhow.
Result: Crate-wide result alias using anyhow for flexible error context.
Row: Owned row value slice matching RowNames length.
RowNames: Shared reference-counted column name list.

Crate tank_core

Crate tank_core Copy item path

§Design Highlights

§Quick Start

§Error Handling

§Futures & Streams MUST be driven

§Feature Flags

§Modules

§Macros

§Safety & Portability Notes

§Contributing Docs

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate tank_core