iet-db

core contracts official

Defines database lifecycle and reviewed-migration contracts without driver SQL types.

CoreFeaturesIntegrationsStacksTooling

Used byiet-db-timescale

iet-dbcontractsDatabase contracts

Depends oniet-corecontract

How to use it

iet-db defines the database lifecycle — Database: SessionFactory with close() — and the reviewed-migration contract MigrationRunner with status, apply, and rollback_to. Drivers implement it; only trusted, reviewed SQL files are executed through this port.

rust

// tools/iet-db-cli/src/main.rs
use iet_db::{Database, MigrationRunner};

let migrations =
    iet_db_timescale::migration::Migrations::load(database.clone(), &cli.directory).await?;
match cli.command {
    Command::Apply { .. } => migrations.apply().await?,
    Command::Rollback { target, .. } => migrations.rollback_to(target).await?,
    Command::Status | Command::Verify => {
        let status = migrations.status().await?;   // MigrationStatus
        for entry in status.entries {              // MigrationEntry
            println!(
                "{} {} {}",
                if entry.applied { "applied" } else { "pending" },
                entry.version,
                entry.description,
            );
        }
    }
    Command::New { .. } => unreachable!("handled offline"),
}
database.close().await;

MigrationStatus::pending() counts entries where applied == false without iterating yourself.
rollback_to(0) removes all history; a nonzero target must be an already-applied version.

How it works

MigrationRunner::status returns a MigrationStatus of MigrationEntry rows, while apply and rollback_to advance the reviewed schema; Database::close releases the driver after the command finishes.

sequenceDiagram
  participant C as "CLI caller"
  participant R as "MigrationRunner"
  participant S as "MigrationStatus"
  C->>R: "status"
  R-->>S: "entries"
  S-->>C: "MigrationEntry list"
  C->>R: "apply"
  C->>R: "rollback_to target"
  participant D as "Database"
  C->>D: "close"

Core contract

This page is the crate reference. For the framework-wide runtime and trait model, read Architecture.

What it implements

Defines the traits other crates implement: Database, MigrationRunner.

What's inside

Modules

src/lib.rs

Public API

(root)

trait Database

rust

pub trait Database: SessionFactory {
    fn resource_id(&self) -> &ResourceId;
    fn close(&self) -> impl Future<Output = ()> + Send;
}

struct MigrationEntry
struct MigrationStatus
pub fn pending(&self) -> usize
trait MigrationRunner — Trusted, reviewed SQL files; never execute request-supplied SQL here.

rust

pub trait MigrationRunner: Send + Sync {
    fn status(&self) -> impl Future<Output = AppResult<MigrationStatus>> + Send;
    fn apply(&self) -> impl Future<Output = AppResult<()>> + Send;
    /// Target zero removes all history; nonzero must be an applied version.
    fn rollback_to(&self, target: i64) -> impl Future<Output = AppResult<()>> + Send;
}

Depends on

iet-core

Used by

iet-db-timescale

In this repository

examples/htmx-starter
examples/skills-only-app-task-tracker

Source: crates/core/iet-db