Lifecycle Hooks

Quick Start

#[derive(Entity)]
#[entity(table = "users", hooks)]
pub struct User {
 #[id]
 pub id: Uuid,
 #[field(create, update, response)]
 pub email: String,
 #[field(create, response)]
 pub name: String,
 #[field(skip)]
 pub password_hash: String,
 #[field(response)]
 #[auto]
 pub created_at: DateTime<Utc>,
}

Generated Code

/// Generated by entity-derive
#[async_trait]
pub trait UserHooks: Send + Sync {
 type Error: std::error::Error + Send + Sync;
 /// Called before creating a new entity.
 /// Modify the DTO or return an error to abort.
 async fn before_create(&self, dto: &mut CreateUserRequest) -> Result<(), Self::Error>;
 /// Called after entity creation.
 async fn after_create(&self, entity: &User) -> Result<(), Self::Error>;
 /// Called before updating an entity.
 /// Modify the DTO or return an error to abort.
 async fn before_update(&self, id: &Uuid, dto: &mut UpdateUserRequest) -> Result<(), Self::Error>;
 /// Called after entity update.
 async fn after_update(&self, entity: &User) -> Result<(), Self::Error>;
 /// Called before deleting an entity.
 /// Return an error to abort.
 async fn before_delete(&self, id: &Uuid) -> Result<(), Self::Error>;
 /// Called after entity deletion.
 async fn after_delete(&self, id: &Uuid) -> Result<(), Self::Error>;
}

Invoking the Hooks

let repo = UserRepo::new(pool, MyUserHooks);
let user = repo.create(dto).await?; // before_create → INSERT → after_create
let user = repo.update(id, patch).await?; // before_update → UPDATE → after_update
let gone = repo.delete(id).await?; // after_delete only when a row was affected
let found = repo.find_by_id(id).await?; // reads carry no hooks

impl From<HookError> for sqlx::Error { /* ... */ }

Implementation Example

use async_trait::async_trait;
struct UserService {
 pool: PgPool,
 cache: RedisPool,
 email_sender: EmailService,
}
#[async_trait]
impl UserHooks for UserService {
 type Error = AppError;
 async fn before_create(&self, dto: &mut CreateUserRequest) -> Result<(), Self::Error> {
 // Normalize email
 dto.email = dto.email.trim().to_lowercase();
 // Validate email format
 if !dto.email.contains('@') {
 return Err(AppError::Validation("Invalid email format".into()));
 }
 // Check for duplicate email
 let exists = sqlx::query_scalar::<_, bool>(
 "SELECT EXISTS(SELECT 1 FROM users WHERE email = 1ドル)"
 )
 .bind(&dto.email)
 .fetch_one(&self.pool)
 .await?;
 if exists {
 return Err(AppError::Conflict("Email already registered".into()));
 }
 Ok(())
 }
 async fn after_create(&self, entity: &User) -> Result<(), Self::Error> {
 // Send welcome email
 self.email_sender
 .send_welcome(&entity.email, &entity.name)
 .await?;
 // Cache the new user
 self.cache.set(&format!("user:{}", entity.id), entity).await?;
 Ok(())
 }
 async fn before_update(&self, id: &Uuid, dto: &mut UpdateUserRequest) -> Result<(), Self::Error> {
 // Normalize email if provided
 if let Some(ref mut email) = dto.email {
 *email = email.trim().to_lowercase();
 // Check for duplicate (excluding current user)
 let exists = sqlx::query_scalar::<_, bool>(
 "SELECT EXISTS(SELECT 1 FROM users WHERE email = 1ドル AND id != 2ドル)"
 )
 .bind(&*email)
 .bind(id)
 .fetch_one(&self.pool)
 .await?;
 if exists {
 return Err(AppError::Conflict("Email already in use".into()));
 }
 }
 Ok(())
 }
 async fn after_update(&self, entity: &User) -> Result<(), Self::Error> {
 // Invalidate cache
 self.cache.del(&format!("user:{}", entity.id)).await?;
 Ok(())
 }
 async fn before_delete(&self, id: &Uuid) -> Result<(), Self::Error> {
 // Check if user can be deleted
 let has_orders = sqlx::query_scalar::<_, bool>(
 "SELECT EXISTS(SELECT 1 FROM orders WHERE user_id = 1ドル AND status = 'pending')"
 )
 .bind(id)
 .fetch_one(&self.pool)
 .await?;
 if has_orders {
 return Err(AppError::Forbidden("Cannot delete user with pending orders".into()));
 }
 Ok(())
 }
 async fn after_delete(&self, id: &Uuid) -> Result<(), Self::Error> {
 // Invalidate cache
 self.cache.del(&format!("user:{}", id)).await?;
 // Clean up related data
 sqlx::query("DELETE FROM user_sessions WHERE user_id = 1ドル")
 .bind(id)
 .execute(&self.pool)
 .await?;
 Ok(())
 }
}

Use Cases

Validation

async fn before_create(&self, dto: &mut CreateProductRequest) -> Result<(), Self::Error> {
 // Price validation
 if dto.price_cents <= 0 {
 return Err(AppError::Validation("Price must be positive".into()));
 }
 // SKU format validation
 if !dto.sku.chars().all(|c| c.is_alphanumeric() || c == '-') {
 return Err(AppError::Validation("Invalid SKU format".into()));
 }
 Ok(())
}

Normalization

async fn before_create(&self, dto: &mut CreateUserRequest) -> Result<(), Self::Error> {
 // Normalize email
 dto.email = dto.email.trim().to_lowercase();
 // Normalize name
 dto.name = dto.name.trim().to_string();
 // Capitalize first letter of each word
 dto.name = dto.name
 .split_whitespace()
 .map(|word| {
 let mut chars = word.chars();
 match chars.next() {
 None => String::new(),
 Some(first) => first.to_uppercase().chain(chars).collect(),
 }
 })
 .collect::<Vec<_>>()
 .join(" ");
 Ok(())
}

Authorization

async fn before_update(&self, id: &Uuid, _dto: &mut UpdatePostRequest) -> Result<(), Self::Error> {
 // Get current user from context (e.g., thread-local or passed via self)
 let current_user = self.current_user()?;
 // Check ownership
 let post = sqlx::query_as::<_, Post>(
 "SELECT * FROM posts WHERE id = 1ドル"
 )
 .bind(id)
 .fetch_optional(&self.pool)
 .await?
 .ok_or(AppError::NotFound)?;
 if post.author_id != current_user.id && !current_user.is_admin {
 return Err(AppError::Forbidden("Cannot edit other user's posts".into()));
 }
 Ok(())
}

Side Effects

async fn after_create(&self, entity: &Order) -> Result<(), Self::Error> {
 // Update inventory
 for item in &entity.items {
 sqlx::query(
 "UPDATE products SET stock = stock - 1ドル WHERE id = 2ドル"
 )
 .bind(item.quantity)
 .bind(item.product_id)
 .execute(&self.pool)
 .await?;
 }
 // Send notification
 self.notifications.send_order_confirmation(entity).await?;
 // Schedule fulfillment job
 self.job_queue.enqueue(FulfillOrderJob { order_id: entity.id }).await?;
 Ok(())
}

Audit Logging

async fn after_update(&self, entity: &User) -> Result<(), Self::Error> {
 sqlx::query(
 "INSERT INTO audit_log (entity_type, entity_id, action, performed_by, performed_at)
 VALUES ('user', 1,ドル 'update', 2,ドル NOW())"
 )
 .bind(entity.id)
 .bind(self.current_user_id())
 .execute(&self.pool)
 .await?;
 Ok(())
}

With Soft Delete

#[derive(Entity)]
#[entity(table = "documents", hooks, soft_delete)]
pub struct Document { /* ... */ }

#[async_trait]
pub trait DocumentHooks: Send + Sync {
 type Error: std::error::Error + Send + Sync;
 // Standard CRUD hooks...
 async fn before_create(&self, dto: &mut CreateDocumentRequest) -> Result<(), Self::Error>;
 async fn after_create(&self, entity: &Document) -> Result<(), Self::Error>;
 async fn before_update(&self, id: &Uuid, dto: &mut UpdateDocumentRequest) -> Result<(), Self::Error>;
 async fn after_update(&self, entity: &Document) -> Result<(), Self::Error>;
 async fn before_delete(&self, id: &Uuid) -> Result<(), Self::Error>; // Soft delete
 async fn after_delete(&self, id: &Uuid) -> Result<(), Self::Error>;
 // Soft delete specific hooks
 async fn before_restore(&self, id: &Uuid) -> Result<(), Self::Error>;
 async fn after_restore(&self, entity: &Document) -> Result<(), Self::Error>;
 async fn before_hard_delete(&self, id: &Uuid) -> Result<(), Self::Error>;
 async fn after_hard_delete(&self, id: &Uuid) -> Result<(), Self::Error>;
}

With Commands

#[derive(Entity)]
#[entity(table = "orders", hooks, commands)]
#[command(Place)]
#[command(Cancel, requires_id)]
pub struct Order { /* ... */ }

#[async_trait]
pub trait OrderHooks: Send + Sync {
 type Error: std::error::Error + Send + Sync;
 // Standard CRUD hooks...
 // Command hooks
 async fn before_command(&self, cmd: &OrderCommand) -> Result<(), Self::Error>;
 async fn after_command(&self, cmd: &OrderCommand, result: &OrderCommandResult) -> Result<(), Self::Error>;
}

async fn before_command(&self, cmd: &OrderCommand) -> Result<(), Self::Error> {
 match cmd {
 OrderCommand::Place(place) => {
 // Validate order can be placed
 if place.items.is_empty() {
 return Err(AppError::Validation("Order must have items".into()));
 }
 }
 OrderCommand::Cancel(cancel) => {
 // Check if order can be cancelled
 let order = self.find_order(cancel.id).await?;
 if order.status == "shipped" {
 return Err(AppError::Forbidden("Cannot cancel shipped order".into()));
 }
 }
 }
 Ok(())
}
async fn after_command(&self, cmd: &OrderCommand, result: &OrderCommandResult) -> Result<(), Self::Error> {
 match (cmd, result) {
 (OrderCommand::Place(_), OrderCommandResult::Place(order)) => {
 self.send_order_confirmation(order).await?;
 }
 (OrderCommand::Cancel(_), OrderCommandResult::Cancel) => {
 // Refund logic
 }
 }
 Ok(())
}

Best Practices

Error Handling Pattern

#[derive(Debug)]
pub enum HookError {
 Validation(String),
 Authorization(String),
 Conflict(String),
 Database(sqlx::Error),
}
impl std::error::Error for HookError {}
impl std::fmt::Display for HookError { /* ... */ }
impl From<sqlx::Error> for HookError {
 fn from(err: sqlx::Error) -> Self {
 HookError::Database(err)
 }
}
#[async_trait]
impl UserHooks for UserService {
 type Error = HookError;
 async fn before_create(&self, dto: &mut CreateUserRequest) -> Result<(), Self::Error> {
 if dto.email.is_empty() {
 return Err(HookError::Validation("Email required".into()));
 }
 Ok(())
 }
}

See Also