<div align="center">
<img width="300" height="300" src="docs/public/logo.png" alt="Tank logo: a circular gold emblem with a military tank and a database symbol" />
</div>
# Tank
Tank (Table Abstraction & Navigation Kit) is the Rust data layer for teams that want one entity model, explicit queries, and the freedom to move across very different databases without rewriting their whole stack.
**One entity model. Any terrain.**
📘 **Docs:** https://tankhq.github.io/tank
🖥️ **Repo:** https://github.com/TankHQ/tank
📦 **Crate:** https://crates.io/crates/tank
> [!IMPORTANT]
> **Authenticity Notice**: This is **not** AI slop. It was meticulously crafted by me (human) [barsdeveloper](https://github.com/barsdeveloper).
## Mission Briefing
In plain terms, Tank is a thin layer over your database workflow, designed for the Rust operator who needs to deploy across multiple environments without changing the kit. It doesn't matter if you are digging into a local SQLite trench, coordinating a distributed ScyllaDB offensive, or managing a Postgres stronghold, Tank provides a unified interface. You define your entities, Tank handles the ballistics.
**Known battlefields**:
- Postgres
- SQLite
- MySQL/MariaDB
- DuckDB
- MongoDB
- ScyllaDB/Cassandra
- Valkey/Redis
## Mission Objectives
Tank exists to implement the **best possible** design for a ORM written in Rust. A clean-slate design focused on ergonomics, flexibility and broad database support.
- **Async operations** - Fire and forget.
- **Designed to be extensible** - Swap databases like changing magazines mid-battle.
- **SQL and NoSQL support** - One Tank, all terrains.
- **Transactions abstraction** - Commit on success or rollback and retreat.
- **Rich type arsenal** - Automatic conversions between Rust and database types.
- **Optional appender API** - High caliber bulk inserts.
- **TLS** - No open radios on this battlefield.
- **Joins** - Multi unit coordination.
- **Raw SQL** - You're never limited by the abstractions provided.
- **Zero setup** - Skip training. Go straight to live fire.
## No-Fly Zone
- No schema migrations (just table creation and destroy for fast setup).
- No implicit joins (no entities as fields, joins are explicit, every alliance is signed).
## Why Tank?
**Intelligence Report**: A quick recon of the battlefield revealed that while existing heavy weaponry is effective, there was a critical need for a more adaptable, cleaner design. Tank was designed from scratch to address these weaknesses.
**1. Modular Architecture**: Some systems rely on hardcoded enums for database support, which limits flexibility. If a backend isn't in the core list, it cannot be used. Tank is designed to be extensible: a driver can be implemented for any database (SQL or NoSQL) without touching the core library. If it can hold data, Tank can likely target it.
**2. Zero Boilerplate**: Field operations shouldn't require filling out forms in triplicate. Some tools force data definition twice: once in a complex DSL and again as a Rust struct. Tank keeps it simple: one struct, one definition. The macros handle table creation, selection, and insertion automatically. You can set up tables and get database communication running in just a few lines of code, all through a unified API that works the same regardless of the backend. Perfect for spinning up tests and prototypes rapidly while still scaling to production backends.
## Operational Guide
*For more examples check the [cheat sheet](https://tankhq.github.io/tank/00-cheat-sheet.html)*
1) Arm your cargo
```sh
cargo add tank
```
2) Choose your battlefield
```sh
cargo add tank-duckdb
```
3) Define unit schematics
```rust
use std::borrow::Cow;
use tank::{Entity, Executor, Result};
#[derive(Entity)]
#[tank(schema = "army")]
pub struct Tank {
#[tank(primary_key)]
pub name: String,
pub country: Cow<'static, str>,
#[tank(name = "caliber")]
pub caliber_mm: u16,
#[tank(name = "speed")]
pub speed_kmh: f32,
pub is_operational: bool,
pub units_produced: Option<u32>,
}
```
4) Fire for effect
```rust
use std::{borrow::Cow, collections::HashSet};
use tank::{ConnectionPool, Driver, Entity, PoolConfig, Result, expr, stream::TryStreamExt};
use tank_duckdb::DuckDBDriver;
async fn data() -> Result<()> {
let driver = DuckDBDriver::new();
let mut pool = driver
.connect_pool(
"duckdb://../target/debug/tests.duckdb?mode=rw".into(),
PoolConfig::new(),
)
.await?;
let mut connection = pool.get().await?;
let my_tank = Tank {
name: "Tiger I".into(),
country: "Germany".into(),
caliber_mm: 88,
speed_kmh: 45.4,
is_operational: false,
units_produced: Some(1_347),
};
/*
* CREATE SCHEMA IF NOT EXISTS "army";
* CREATE TABLE IF NOT EXISTS "army"."tank" (
* "name" VARCHAR PRIMARY KEY,
* "country" VARCHAR NOT NULL,
* "caliber" USMALLINT NOT NULL,
* "speed" FLOAT NOT NULL,
* "is_operational" BOOLEAN NOT NULL,
* "units_produced" UINTEGER);
*/
Tank::create_table(&mut connection, true, true).await?;
/*
* INSERT INTO "army"."tank" ("name", "country", "caliber", "speed", "is_operational", "units_produced") VALUES
* ('Tiger I', 'Germany', 88, 45.4, false, 1347)
* ON CONFLICT ("name") DO UPDATE SET
* "country" = EXCLUDED."country",
* "caliber" = EXCLUDED."caliber",
* "speed" = EXCLUDED."speed",
* "is_operational" = EXCLUDED."is_operational",
* "units_produced" = EXCLUDED."units_produced";
*/
my_tank.save(&mut connection).await?;
/*
* DuckDB uses the appender API. Other drivers generate an INSERT:
* INSERT INTO "army"."tank" ("name", "country", "caliber", "speed", "is_operational", "units_produced") VALUES
* ('T-34/85', 'Soviet Union', 85, 53.0, false, 49200),
* ('M1 Abrams', 'USA', 120, 72.0, true, NULL);
*/
Tank::insert_many(
&mut connection,
&[
Tank {
name: "T-34/85".into(),
country: "Soviet Union".into(),
caliber_mm: 85,
speed_kmh: 53.0,
is_operational: false,
units_produced: Some(49_200),
},
Tank {
name: "M1 Abrams".into(),
country: "USA".into(),
caliber_mm: 120,
speed_kmh: 72.0,
is_operational: true,
units_produced: None,
},
],
)
.await?;
/*
* SELECT "name", "country", "caliber", "speed", "is_operational", "units_produced"
* FROM "army"."tank"
* WHERE "is_operational" = false
* LIMIT 1000;
*/
let tanks = Tank::find_many(&mut connection, expr!(Tank::is_operational == false), Some(1000))
.try_collect::<Vec<_>>()
.await?;
assert_eq!(
tanks
.iter()
.map(|t| t.name.to_string())
.collect::<HashSet<_>>(),
HashSet::from_iter(["Tiger I".into(), "T-34/85".into()])
);
Ok(())
}
```
## Support the Mission
Building and maintaining drivers for half a dozen different databases is a massive effort. **If Tank saves your company time, infrastructure headaches, or boilerplate, please consider supporting its development.**
Donations ensure that Tank stays maintained, well-tested, and gets new capabilities (like more advanced driver features) faster.
🔗 **[Sponsor the Commander via GitHub Sponsors](https://github.com/sponsors/TankHQ)**
*Rustaceans don't hide behind ORMs, they drive Tanks.*