Trait Entity 

pub trait Entity {
    type PrimaryKey<'a>;

    // Required methods
    fn table() -> &'static TableRef;
    fn columns() -> &'static [ColumnDef];
    fn primary_key_def() -> impl ExactSizeIterator<Item = &'static ColumnDef>;
    fn primary_key(&self) -> Self::PrimaryKey<'_>;
    fn unique_defs(    ) -> impl ExactSizeIterator<Item = impl ExactSizeIterator<Item = &'static ColumnDef>>;
    fn row_filtered(&self) -> Box<[(&'static str, Value)]>;
    fn row_full(&self) -> Row;
    fn from_row(row: RowLabeled) -> Result<Self>
       where Self: Sized;
    fn create_table<Exec: Executor>(
        executor: &mut Exec,
        if_not_exists: bool,
        create_schema: bool,
    ) -> impl Future<Output = Result<()>> + Send;
    fn drop_table<Exec: Executor>(
        executor: &mut Exec,
        if_exists: bool,
        drop_schema: bool,
    ) -> impl Future<Output = Result<()>> + Send;
    fn insert_one<Exec: Executor, E: Entity>(
        executor: &mut Exec,
        entity: &E,
    ) -> impl Future<Output = Result<RowsAffected>> + Send;
    fn insert_many<'a, Exec, It>(
        executor: &mut Exec,
        items: It,
    ) -> impl Future<Output = Result<RowsAffected>> + Send
       where Self: 'a,
             Exec: Executor,
             It: IntoIterator<Item = &'a Self> + Send;
    fn find_pk<Exec: Executor>(
        executor: &mut Exec,
        primary_key: &Self::PrimaryKey<'_>,
    ) -> impl Future<Output = Result<Option<Self>>> + Send
       where Self: Sized;
    fn find_many<Exec: Executor, Expr: Expression>(
        executor: &mut Exec,
        condition: &Expr,
        limit: Option<u32>,
    ) -> impl Stream<Item = Result<Self>> + Send
       where Self: Sized;
    fn delete_one<Exec: Executor>(
        executor: &mut Exec,
        primary_key: Self::PrimaryKey<'_>,
    ) -> impl Future<Output = Result<RowsAffected>> + Send
       where Self: Sized;
    fn delete_many<Exec: Executor, Expr: Expression>(
        executor: &mut Exec,
        condition: &Expr,
    ) -> impl Future<Output = Result<RowsAffected>> + Send
       where Self: Sized;

    // Provided methods
    fn prepare_find<Exec: Executor, Expr: Expression>(
        executor: &mut Exec,
        condition: &Expr,
        limit: Option<u32>,
    ) -> impl Future<Output = Result<Query<Exec::Driver>>> { ... }
    fn find_one<Exec: Executor, Expr: Expression>(
        executor: &mut Exec,
        condition: &Expr,
    ) -> impl Future<Output = Result<Option<Self>>> + Send
       where Self: Sized { ... }
    fn save<Exec: Executor>(
        &self,
        executor: &mut Exec,
    ) -> impl Future<Output = Result<()>> + Send
       where Self: Sized { ... }
    fn delete<Exec: Executor>(
        &self,
        executor: &mut Exec,
    ) -> impl Future<Output = Result<()>> + Send
       where Self: Sized { ... }
}

Represents a database-backed record with schema and persistence behavior.

An Entity defines:

• Static table/column metadata
• Conversion to/from raw Row / RowLabeled
• Helper CRUD operations using an Executor

Lifetimes:

• Associated PrimaryKey<'a> may borrow from &self when composed.

Error Handling:

• Methods return Result<...> using crate-level Error.
• save / delete early-return an error when a primary key is not defined.

Streaming:

• find_many returns a Stream of row conversions.
• find_one and find_pk internally consume a single element from that stream.

Idempotency:

• save performs an UPSERT-style insert when supported (based on sql_writer().write_insert(..., true)), falling back to insert-only on unsupported drivers.

Required Associated Types

type PrimaryKey<'a>

Associated primary key type. May be a single value or a tuple.

Required Methods

fn table() -> &'static TableRef

Returns the table reference backing this entity.

fn columns() -> &'static [ColumnDef]

Returns all declared column definitions in declaration order.

fn primary_key_def() -> impl ExactSizeIterator<Item = &'static ColumnDef>

Iterator over columns forming the primary key. Empty iterator means no PK.

fn primary_key(&self) -> Self::PrimaryKey<'_>

Extracts the primary key value(s) from self.

Should mirror the order and shape returned by primary_key_def().

fn unique_defs() -> impl ExactSizeIterator<Item = impl ExactSizeIterator<Item = &'static ColumnDef>>

Returns an iterator over unique constraint definitions.

Each inner iterator represents one unique composite constraint.

fn row_filtered(&self) -> Box<[(&'static str, Value)]>

Returns a filtered mapping of column name to value, typically excluding auto-generated or default-only columns.

fn row_full(&self) -> Row

Returns a full Row representation including all persisted columns.

fn from_row(row: RowLabeled) -> Result<Self>

where Self: Sized,

Constructs Self from a labeled database row.

Errors if mandatory columns are missing or type conversion fails.

fn create_table<Exec: Executor>( executor: &mut Exec, if_not_exists: bool, create_schema: bool, ) -> impl Future<Output = Result<()>> + Send

Creates the underlying table (and optionally schema) if requested.

Parameters:

• if_not_exists: guards against existing table (if drivers support it, otherwise just create table).
• create_schema: attempt to create schema prior to table creation (if drivers support it).

fn drop_table<Exec: Executor>( executor: &mut Exec, if_exists: bool, drop_schema: bool, ) -> impl Future<Output = Result<()>> + Send

Drops the underlying table (and optionally schema) if requested.

Parameters:

• if_exists: guards against missing table (if drivers support it, otherwise just drop table).
• drop_schema: attempt to drop schema after table removal (if drivers support it).

fn insert_one<Exec: Executor, E: Entity>( executor: &mut Exec, entity: &E, ) -> impl Future<Output = Result<RowsAffected>> + Send

Inserts a single entity row.

Returns rows affected (expected: 1 on success).

fn insert_many<'a, Exec, It>( executor: &mut Exec, items: It, ) -> impl Future<Output = Result<RowsAffected>> + Send

where Self: 'a, Exec: Executor, It: IntoIterator<Item = &'a Self> + Send,

Multiple insert for a homogeneous iterator of entities.

Returns the number of rows inserted.

fn find_pk<Exec: Executor>( executor: &mut Exec, primary_key: &Self::PrimaryKey<'_>, ) -> impl Future<Output = Result<Option<Self>>> + Send

where Self: Sized,

Finds an entity by primary key.

Returns Ok(None) if no row matches.

fn find_many<Exec: Executor, Expr: Expression>( executor: &mut Exec, condition: &Expr, limit: Option<u32>, ) -> impl Stream<Item = Result<Self>> + Send

where Self: Sized,

Streams entities matching a condition.

limit restricts the maximum number of rows returned at a database level if Some (if supported, otherwise unlimited).

fn delete_one<Exec: Executor>( executor: &mut Exec, primary_key: Self::PrimaryKey<'_>, ) -> impl Future<Output = Result<RowsAffected>> + Send

where Self: Sized,

Deletes exactly one entity by primary key.

Returns rows affected (0 if not found).

fn delete_many<Exec: Executor, Expr: Expression>( executor: &mut Exec, condition: &Expr, ) -> impl Future<Output = Result<RowsAffected>> + Send

where Self: Sized,

Deletes all entities matching a condition.

Returns the number of rows deleted.

Provided Methods

fn prepare_find<Exec: Executor, Expr: Expression>( executor: &mut Exec, condition: &Expr, limit: Option<u32>, ) -> impl Future<Output = Result<Query<Exec::Driver>>>

Prepare (but do not yet run) a SQL select query.

Returns the prepared statement.

fn find_one<Exec: Executor, Expr: Expression>( executor: &mut Exec, condition: &Expr, ) -> impl Future<Output = Result<Option<Self>>> + Send

where Self: Sized,

Finds the first entity matching a condition expression.

Returns Ok(None) if no row matches.

fn save<Exec: Executor>( &self, executor: &mut Exec, ) -> impl Future<Output = Result<()>> + Send

where Self: Sized,

Saves the entity (insert or update) based on primary key presence.

Behavior:

• Errors if no primary key is defined in the table.
• Uses driver-specific UPSERT semantics when available (write_insert(..., true)).

Errors:

• Missing PK in the table.
• Execution failures from underlying driver.

fn delete<Exec: Executor>( &self, executor: &mut Exec, ) -> impl Future<Output = Result<()>> + Send

where Self: Sized,

Deletes this entity instance via its primary key.

Errors:

• Missing PK in the table.
• If not exactly one row was deleted.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors