Crate arcature_data 

arcature-data — the Arcature high-level data layer over arcature-db.

AP2.1-6 (ADR-0006): a high-level model/query experience for ordinary CRUD over SeaORM, preserving the SeaORM and SQLx escape hatches. No new database engine, no ORM, no hidden global pool, no task-local connection, and no request-global DB. Every public API takes the Db handle (or the DatabaseConnection / PgPool it exposes) by reference — ownership is explicit on every call.

What this crate owns

• Explicit-ownership query ergonomics over SeaORM entities: a typed Query<E> bound to a &Db, reached on the golden path as Entity::query(&db) via the blanket QueryModel trait (no application trait implementation required — it works for any SeaORM Entity).
• Vertical slices: find by primary key, filter, order, paginate (Page<T>), eager-load typed relations, and CRUD — all carrying the &Db so the caller never re-passes db.orm() on every terminal call.
• Typed transactions (Transaction) over the SeaORM and SQLx paths, with explicit ownership and no hidden nesting/savepoint magic.
• Development/CI N+1 detection behind the n1 Cargo feature: a request-scoped tracker (n1::Tracker) that records query events with source attribution and reports likely relation N+1 patterns. Zero production hot-path overhead when the feature is off — the tracker, the recording calls, and the analyzer are cfg-gated out of the default build.
• Migration lint (classify / classify_statements) — a deterministic, database-free classifier of real PostgreSQL migration risks (destructive drops, unsafe NOT NULL, type narrowing, dangerous renames, blocking indexes).

What this crate does not own

It does not open a connection pool (it borrows Db), it does not reimplement SeaORM’s query builder or relation engine, it does not add a second transaction abstraction with hidden savepoints, and it does not introduce any global, thread-local, or task-local state. Raw SeaORM and SQLx remain first-class escape hatches via db.orm() / db.sqlx().

This crate is an internal workspace member (publish = false); its public surface is re-exported through the arcature facade behind the existing db feature. ADR-0006 authorizes no new public crate for AP2.1-6 — arcature-data is not an independent crates.io release unit.

Raw Axum usage

Db is Clone + Send + Sync + 'static (from arcature-db); this crate adds no state of its own. Query<E> borrows &Db for the duration of the query, so it composes with normal Axum state without a runtime dependency:

use arcature_data::QueryModel;
let posts = post::Entity::query(db)
    .filter(post::Column::Active.eq(true))
    .order_by_desc(post::Column::CreatedAt)
    .all()
    .await?;

Security note

Every query carries an explicit &Db; there is no hidden pool the framework resolves on the caller’s behalf. Migration lint output is side-effect-free and never reads environment variables or connects to a database; the N+1 tracker is request-scoped and constructed explicitly.

Structs

Db

The certified arcature-db engine, re-exported so downstream code targets the Arcature-pinned types through this crate. Db is the explicit ownership handle every API in this crate borrows. The Arcature database handle: one PostgreSQL connection pool with two first-class data paths.

Finding

One migration lint finding: a classified risk in a single statement.

LintReport

The aggregated lint report for a set of SQL statements.

Page

A page of results from a paginated query.

Paginated

A paginated query awaiting a page number and a fetch.

Query

A typed query bound to an explicit &Db, over a SeaORM entity E.

Relation

A typed reference to a related entity R, for eager loading.

SqlStatement

A single SQL statement, normalized for classification.

Transaction

Typed transactions over the explicit &Db — SeaORM and SQLx paths.

Enums

DataError

The error returned by the high-level data layer.

LintCategory

A category of real PostgreSQL migration risk (PROGRAM.md AP2.1-6).

LintSeverity

The severity of a migration lint finding.

PaginationError

An invalid pagination argument (AGENTS.md §18: typed, not a string).

Traits

QueryModel

The golden-path entry point: every SeaORM Entity gains Entity::query(&db).

Functions

classify

Classify a single script string (split into statements first).

classify_statements

Classify a set of SqlStatements and return a LintReport.

delete

Delete an existing row from its ActiveModel. Returns a sea_orm::DeleteResult carrying the number of affected rows.

find_by_pk

Find a single row by its primary key.

insert

Insert a new row from an ActiveModel. Returns the inserted model with database-generated fields (auto-increment PKs, defaults) populated.

of

Reference the related entity R for eager loading. Generic over R so the caller can name it explicitly:

update

Update an existing row from an ActiveModel. Returns the updated model.