Struct SecureConn 

pub struct SecureConn { /* private fields */ }

Secure database connection wrapper.

This is the primary interface for module developers to access the database. All operations require a SecurityCtx parameter for per-request access control.

Usage

Module services receive a &SecureConn and provide SecurityCtx per-request:

pub struct MyService<'a> {
    db: &'a SecureConn,
}

impl<'a> MyService<'a> {
    pub async fn get_user(&self, scope: &AccessScope, id: Uuid) -> Result<Option<User>> {
        self.db.find_by_id::<user::Entity>(ctx, id)?
            .one(self.db)
            .await
    }
}

Security Guarantees

• All queries require SecurityCtx from the request
• Queries are scoped by tenant/resource from the context
• Empty scopes result in deny-all (no data returned)
• Type system prevents unscoped queries from compiling
• Modules cannot access raw database connections

Implementations

impl SecureConn

pub fn db_engine(&self) -> &'static str

Return database engine identifier for tracing / logging.

pub fn find<E>(&self, scope: &AccessScope) -> SecureSelect<E, Scoped>

where E: ScopableEntity + EntityTrait, E::Column: ColumnTrait + Copy,

Create a scoped select query for the given entity.

Returns a SecureSelect<E, Scoped> that automatically applies tenant/resource filtering based on the provided security context.

Example

let ctx = SecurityCtx::for_tenants(vec![tenant_id], user_id);
let users = db.find::<user::Entity>(&ctx)?
    .filter(user::Column::Status.eq("active"))
    .order_by_asc(user::Column::Email)
    .all(db)
    .await?;

Errors

pub fn find_by_id<E>( &self, scope: &AccessScope, id: Uuid, ) -> Result<SecureSelect<E, Scoped>, ScopeError>

where E: ScopableEntity + EntityTrait, E::Column: ColumnTrait + Copy,

Create a scoped select query filtered by a specific resource ID.

This is a convenience method that combines find() with .and_id().

Example

let ctx = SecurityCtx::for_tenants(vec![tenant_id], user_id);
let user = db.find_by_id::<user::Entity>(&ctx, user_id)?
    .one(db)
    .await?;

Errors

Returns ScopeError if the entity doesn’t have a resource column or scoping fails.

pub fn update_many<E>(&self, scope: &AccessScope) -> SecureUpdateMany<E, Scoped>

where E: ScopableEntity + EntityTrait, E::Column: ColumnTrait + Copy,

Create a scoped update query for the given entity.

Returns a SecureUpdateMany<E, Scoped> that automatically applies tenant/resource filtering. Use .col_expr() or other SeaORM methods to specify what to update.

Example

let ctx = SecurityCtx::for_tenants(vec![tenant_id], user_id);
let result = db.update_many::<user::Entity>(&ctx)?
    .col_expr(user::Column::Status, Expr::value("active"))
    .col_expr(user::Column::UpdatedAt, Expr::value(Utc::now()))
    .exec(db)
    .await?;
println!("Updated {} rows", result.rows_affected);

pub fn delete_many<E>(&self, scope: &AccessScope) -> SecureDeleteMany<E, Scoped>

where E: ScopableEntity + EntityTrait, E::Column: ColumnTrait + Copy,

Create a scoped delete query for the given entity.

Returns a SecureDeleteMany<E, Scoped> that automatically applies tenant/resource filtering.

Example

let ctx = SecurityCtx::for_tenants(vec![tenant_id], user_id);
let result = db.delete_many::<user::Entity>(&ctx)?
    .exec(db)
    .await?;
println!("Deleted {} rows", result.rows_affected);

pub fn insert_one<E>( &self, scope: &AccessScope, am: E::ActiveModel, ) -> Result<SecureInsertOne<E::ActiveModel, Scoped>, ScopeError>

where E: ScopableEntity + EntityTrait, E::Column: ColumnTrait + Copy, E::ActiveModel: ActiveModelTrait<Entity = E> + Send,

Create a scoped insert builder with on_conflict() support.

Unlike the simpler insert() method, this returns a builder that allows setting on_conflict() for upsert semantics while still enforcing tenant validation through the secure typestate pattern.

Example

use sea_orm::sea_query::OnConflict;

let scope = AccessScope::tenants_only(vec![tenant_id]);
let am = settings::ActiveModel {
    tenant_id: Set(tenant_id),
    user_id: Set(user_id),
    theme: Set(Some("dark".to_string())),
    ..Default::default()
};

db.insert_one(&scope, am)?
    .on_conflict(
        OnConflict::columns([Column::TenantId, Column::UserId])
            .update_columns([Column::Theme])
            .to_owned()
    )
    .exec(db)
    .await?;

Errors

• ScopeError::Invalid if tenant_id is not set for tenant-scoped entities
• ScopeError::TenantNotInScope if tenant_id is not in the provided scope

pub async fn insert<E>( &self, scope: &AccessScope, am: E::ActiveModel, ) -> Result<E::Model, ScopeError>

where E: ScopableEntity + EntityTrait, E::Column: ColumnTrait + Copy, E::ActiveModel: ActiveModelTrait<Entity = E> + Send, E::Model: IntoActiveModel<E::ActiveModel>,

Insert a new entity with automatic tenant validation.

This is a convenience wrapper around secure_insert() that uses the provided security context.

Example

let ctx = SecurityCtx::for_tenants(vec![tenant_id], user_id);
let am = user::ActiveModel {
    id: Set(Uuid::new_v4()),
    tenant_id: Set(tenant_id),
    owner_id: Set(ctx.subject_id),
    email: Set("user@example.com".to_string()),
    ..Default::default()
};

let user = db.insert::<user::Entity>(&ctx, am).await?;

Errors

• ScopeError::Invalid if entity requires tenant but scope has none
• ScopeError::Db if database insert fails

pub async fn update_with_ctx<E>( &self, scope: &AccessScope, id: Uuid, am: E::ActiveModel, ) -> Result<E::Model, ScopeError>

where E: ScopableEntity + EntityTrait, E::Column: ColumnTrait + Copy, E::ActiveModel: ActiveModelTrait<Entity = E> + Send, E::Model: IntoActiveModel<E::ActiveModel> + ModelTrait<Entity = E>,

Update a single entity with security scope validation.

This method ensures the entity being updated is within the security scope before performing the update. It validates that the record is accessible based on tenant/resource constraints.

Security

• Validates the entity exists and is accessible in the security scope
• Returns ScopeError::Denied if the entity is not in scope
• Ensures updates cannot affect entities outside the security boundary

Example

let ctx = SecurityCtx::for_tenant(tenant_id, user_id);

// Load and modify
let user_model = db.find_by_id::<user::Entity>(&ctx, id)?
    .one(db)
    .await?
    .ok_or(NotFound)?;

let mut user: user::ActiveModel = user_model.into();
user.email = Set("newemail@example.com".to_string());
user.updated_at = Set(Utc::now());

// Update with scope validation (pass ID separately)
let updated = db.update_with_ctx::<user::Entity>(&ctx, id, user).await?;

Errors

• ScopeError::Denied if the entity is not accessible in the current scope
• ScopeError::Db if the database operation fails

pub async fn delete_by_id<E>( &self, scope: &AccessScope, id: Uuid, ) -> Result<bool, ScopeError>

where E: ScopableEntity + EntityTrait, E::Column: ColumnTrait + Copy,

Delete a single entity by ID (scoped).

This validates the entity exists in scope before deleting.

Example

let ctx = SecurityCtx::for_tenants(vec![tenant_id], user_id);
db.delete_by_id::<user::Entity>(&ctx, user_id).await?;

Returns

• Ok(true) if entity was deleted
• Ok(false) if entity not found in scope

Errors

Returns ScopeError::Invalid if the entity does not have a resource_col defined.

pub async fn transaction<F>(self, f: F) -> (Self, Result<()>)

where F: for<'a> FnOnce(&'a SecureTx<'a>) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'a>> + Send,

Execute a closure inside a database transaction.

This method starts a SeaORM transaction, provides the transaction handle to the closure as &SecureTx, and handles commit/rollback.

Return Type

Returns anyhow::Result<Result<T, E>> where:

• Outer Err: Database/infrastructure error (transaction rolls back)
• Inner Ok(T): Success (transaction commits)
• Inner Err(E): Domain/validation error (transaction still commits)

This design ensures domain validation errors don’t cause rollback.

Architecture Note

Transaction boundaries should be managed by application/domain services, not by REST handlers. REST handlers should call service methods that internally decide when to open transactions.

Example

use modkit_db::secure::SecureConn;

// In a domain service:
pub async fn create_user(
    db: &SecureConn,
    repo: &UsersRepo,
    user: User,
) -> Result<User, DomainError> {
    let result = db.transaction(|conn| async move {
        // Check email uniqueness
        if repo.email_exists(conn, &user.email).await? {
            return Ok(Err(DomainError::EmailExists));
        }
        // Create user
        let created = repo.create(conn, user).await?;
        Ok(Ok(created))
    }).await?;
    result
}

Security

This method consumes self and returns it after the transaction completes. This prevents accidental use of the outer connection inside the transaction, making transaction bypass impossible by construction.

Only &SecureTx is available inside the closure, ensuring all operations execute within the transaction scope.

Returns

Returns a tuple (Self, Result<()>) where:

• Self is the connection (always returned, even on error)
• Result<()> indicates transaction success or failure

Errors

The Result component is Err(anyhow::Error) if:

• The transaction cannot be started
• A database operation fails (transaction is rolled back)
• The commit fails

pub async fn transaction_with<T, F>(self, f: F) -> (Self, Result<T>)

where T: Send + 'static, F: for<'a> FnOnce(&'a SecureTx<'a>) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'a>> + Send,

Execute a transaction and return both the connection and a result value.

This method consumes self and returns both the connection and the result from the transaction closure. Use this when you need to return data from within the transaction.

Security

Like transaction, this method prevents transaction bypass by consuming self, making it impossible to access the outer connection inside the transaction closure.

Example

let (conn, result) = conn.transaction_with(|tx| {
    Box::pin(async move {
        let user = repo.create(tx, &scope, new_user).await?;
        Ok(user)
    })
}).await;
let user = result?;

Returns

Returns a tuple (Self, Result<T>) where:

• Self is the connection (always returned)
• Result<T> contains the transaction result or error

Errors

The Result component is Err(anyhow::Error) if:

• The transaction cannot be started
• A database operation fails (transaction is rolled back)
• The commit fails

pub async fn transaction_with_config<T, F>( self, cfg: TxConfig, f: F, ) -> (Self, Result<T>)

where T: Send + 'static, F: for<'a> FnOnce(&'a SecureTx<'a>) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'a>> + Send,

Execute a closure inside a database transaction with custom configuration.

This method is similar to transaction, but allows specifying the isolation level and access mode.

Configuration

Use TxConfig to specify transaction settings without importing SeaORM types:

use modkit_db::secure::{TxConfig, TxIsolationLevel, TxAccessMode};

let cfg = TxConfig {
    isolation: Some(TxIsolationLevel::Serializable),
    access_mode: Some(TxAccessMode::ReadWrite),
};

Example

use modkit_db::secure::{SecureConn, TxConfig, TxIsolationLevel};

// In a domain service requiring serializable isolation:
pub async fn reconcile_accounts(
    db: &SecureConn,
    repo: &AccountsRepo,
) -> anyhow::Result<Result<ReconciliationResult, DomainError>> {
    let cfg = TxConfig::serializable();

    db.transaction_with_config(cfg, |conn| async move {
        let accounts = repo.find_all_pending(conn).await?;
        for account in accounts {
            repo.reconcile(conn, &account).await?;
        }
        Ok(Ok(ReconciliationResult { processed: accounts.len() }))
    }).await
}

Backend Notes

• PostgreSQL: Full support for all isolation levels and access modes.
• MySQL/InnoDB: Full support for all isolation levels and access modes.
• SQLite: Only supports Serializable isolation. Other levels are mapped to Serializable. Read-only mode is a hint only.

Security

This method consumes self and returns both the connection and result, preventing transaction bypass by making the outer connection unavailable inside the closure.

Returns

Returns a tuple (Self, Result<T>) where:

• Self is the connection (always returned)
• Result<T> contains the transaction result or error

Errors

The Result component is Err(anyhow::Error) if:

• The transaction cannot be started with the specified configuration
• A database operation fails (transaction is rolled back)
• The commit fails

pub async fn in_transaction<T, E, F>( self, f: F, ) -> (Self, Result<T, TxError<E>>)

where T: Send + 'static, E: Debug + Display + Send + 'static, F: for<'a> FnOnce(&'a SecureTx<'a>) -> Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'a>> + Send,

Execute a closure inside a typed domain transaction.

This method returns TxError<E> which distinguishes domain errors from infrastructure errors, allowing callers to handle them appropriately.

Error Handling

• Domain errors returned from the closure are wrapped in TxError::Domain(e)
• Database infrastructure errors are wrapped in TxError::Infra(InfraError)

Use TxError::into_domain to convert the result into your domain error type.

Example

use modkit_db::secure::SecureConn;

async fn create_user(db: &SecureConn, repo: &UsersRepo, user: User) -> Result<User, DomainError> {
    db.in_transaction(move |tx| Box::pin(async move {
        if repo.exists(tx, user.id).await? {
            return Err(DomainError::already_exists(user.id));
        }
        repo.create(tx, user).await
    }))
    .await
    .map_err(|e| e.into_domain(DomainError::database_infra))
}

Security

This method consumes self and returns both the connection and result, preventing transaction bypass by making the outer connection unavailable inside the closure.

Returns

Returns a tuple (Self, Result<T, TxError<E>>) where:

• Self is the connection (always returned)
• Result<T, TxError<E>> contains the transaction result or error

Errors

The Result component is Err(TxError<E>) if:

• The callback returns a domain error (TxError::Domain(E)).
• The transaction fails due to a database/infrastructure error (TxError::Infra(InfraError)).

pub async fn in_transaction_mapped<T, E, F, M>( self, map_infra: M, f: F, ) -> (Self, Result<T, E>)

where T: Send + 'static, E: Debug + Display + Send + 'static, M: FnOnce(InfraError) -> E + Send, F: for<'a> FnOnce(&'a SecureTx<'a>) -> Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'a>> + Send,

Execute a typed domain transaction with automatic infrastructure error mapping.

This is a convenience wrapper around in_transaction that automatically converts TxError into the domain error type using the provided mapping function for infrastructure errors.

Example

use modkit_db::secure::SecureConn;

async fn create_user(db: &SecureConn, repo: &UsersRepo, user: User) -> Result<User, DomainError> {
    db.in_transaction_mapped(DomainError::database_infra, move |tx| Box::pin(async move {
        if repo.exists(tx, user.id).await? {
            return Err(DomainError::already_exists(user.id));
        }
        repo.create(tx, user).await
    })).await
}

Security

This method consumes self and returns both the connection and result, preventing transaction bypass.

Returns

Returns a tuple (Self, Result<T, E>) where:

• Self is the connection (always returned)
• Result<T, E> contains the transaction result or mapped error

Errors

The Result component is Err(E) if:

• The callback returns a domain error (E).
• The transaction fails due to a database/infrastructure error, mapped via map_infra.