Struct OrmItemReader 

pub struct OrmItemReader<'a, I>
where
    I: EntityTrait,
{ /* private fields */ }

Available on crate feature orm only.

A reader for reading entities from a database using SeaORM.

This reader provides an implementation of the ItemReader trait for SeaORM-based database operations. It supports reading entities from any SeaORM-compatible database with optional pagination for efficient memory usage when dealing with large datasets.

Generic Parameters

• I: The SeaORM entity type that implements EntityTrait

Design Philosophy

This reader follows SeaORM’s conventions and leverages its built-in pagination mechanisms for optimal performance. It provides a bridge between SeaORM’s async API and the batch framework’s synchronous ItemReader trait.

Memory Management

The reader uses an internal buffer to store entity models from the current page, which helps balance memory usage with query performance. When pagination is enabled, only one page of data is kept in memory at any time.

Query Flexibility

Accepts any SeaORM Select query, allowing for complex filtering, joins, and ordering. The query is executed as-is, with pagination parameters added when configured.

State Management

• offset: Tracks the absolute position across all pages
• current_page: Tracks which page is currently loaded in the buffer
• buffer: Holds the current page’s entity models

Implementations

impl<'a, I> OrmItemReader<'a, I>

where I: EntityTrait, I::Model: FromQueryResult + Send + Sync + Clone,

pub fn new() -> Self

Creates a new OrmItemReader with default configuration.

All parameters must be set using the builder methods before use. Use the builder pattern for a more convenient API.

Returns

A new OrmItemReader instance with default settings.

Examples

use spring_batch_rs::item::orm::OrmItemReader;
use sea_orm::{Database, EntityTrait};

let db = Database::connect("sqlite::memory:").await?;

// Using direct instantiation (less recommended)
// let reader = OrmItemReader::<MyEntity>::new()
//     .connection(&db)
//     .query(MyEntity::find())
//     .page_size(100);

// Using builder (recommended)
// let reader = OrmItemReaderBuilder::new()
//     .connection(&db)
//     .query(MyEntity::find())
//     .page_size(100)
//     .build();

pub fn connection(self, connection: &'a DatabaseConnection) -> Self

Sets the database connection for the reader.

This is a required parameter that must be set before using the reader.

Arguments

• connection - Reference to the SeaORM database connection

Returns

The updated OrmItemReader instance.

Examples

use spring_batch_rs::item::orm::OrmItemReader;
use sea_orm::Database;

let db = Database::connect("sqlite::memory:").await?;
let reader = OrmItemReader::<String>::new()
    .connection(&db);

pub fn query(self, query: Select<I>) -> Self

Sets the SeaORM select query for the reader.

This is a required parameter that must be set before using the reader. The query can include filtering, ordering, joins, and other SeaORM operations.

Arguments

• query - The SeaORM select query to execute

Returns

The updated OrmItemReader instance.

Examples

use spring_batch_rs::item::orm::OrmItemReader;
use sea_orm::EntityTrait;

// Basic query
// let reader = OrmItemReader::<MyEntity>::new()
//     .query(MyEntity::find());

// Filtered query
// let reader = OrmItemReader::<MyEntity>::new()
//     .query(MyEntity::find().filter(my_entity::Column::Active.eq(true)));

// Ordered query
// let reader = OrmItemReader::<MyEntity>::new()
//     .query(MyEntity::find().order_by_asc(my_entity::Column::Id));

pub fn page_size(self, page_size: u64) -> Self

Sets the page size for the reader.

When set, the reader will use pagination to limit memory usage. When not set, all data will be loaded at once.

Arguments

• page_size - The number of items to read per page

Returns

The updated OrmItemReader instance.

Performance Considerations

• Larger page sizes reduce the number of database round trips but use more memory
• Smaller page sizes use less memory but may result in more database queries
• Consider your dataset size and available memory when choosing a page size
• Recommended range: 50-1000 items per page for most use cases

Examples

use spring_batch_rs::item::orm::OrmItemReader;

// Small page size for memory-constrained environments
let reader = OrmItemReader::<String>::new()
    .page_size(50);

// Larger page size for better performance with ample memory
let reader = OrmItemReader::<String>::new()
    .page_size(1000);

Trait Implementations

impl<'a, I> Default for OrmItemReader<'a, I>

where I: EntityTrait, I::Model: FromQueryResult + Send + Sync + Clone,

fn default() -> Self

Returns the “default value” for a type.

impl<I> ItemReader<<I as EntityTrait>::Model> for OrmItemReader<'_, I>

where I: EntityTrait, I::Model: FromQueryResult + Send + Sync + Clone,

Implementation of ItemReader trait for OrmItemReader.

This implementation provides a way to read items from a database using SeaORM with support for pagination. It uses an internal buffer to store the results of database queries and keeps track of the current offset to determine when a new page of data needs to be fetched.

Reading Strategy

The reader implements a lazy-loading strategy:

1. First read: Loads the first page of data
2. Subsequent reads: Returns items from the buffer
3. Page boundary: When the buffer is exhausted, loads the next page
4. End of data: Returns None when no more data is available

State Management

• offset: Tracks the absolute position across all pages
• current_page: Tracks which page we’re currently reading from
• buffer: Holds the current page’s data

The reader maintains these invariants:

• offset always represents the next item to be read
• current_page represents the page currently loaded in the buffer
• The buffer contains items for the current page only

fn read(&self) -> ItemReaderResult<I::Model>

Reads the next item from the reader.

This method manages pagination internally and provides a simple interface for sequential reading. The complexity of pagination is hidden from the caller.

Reading Algorithm

1. Calculate buffer index: Determine where we are within the current page
2. Check if new page needed: If at the start of a page, load new data
3. Fetch from buffer: Get the item at the current index
4. Update counters: Increment offset and page number as needed
5. Return result: Clone the item or return None if exhausted

Pagination Logic

• With pagination: index = offset % page_size
• Without pagination: index = offset (all data in one “page”)
• New page trigger: When index == 0, we need to load a new page
• Page advancement: When we reach the end of a page, increment current_page

Memory Management

Items are cloned when returned to ensure the caller owns the data. This prevents borrowing issues and allows the buffer to be modified for the next page load.

Returns

• Ok(Some(item)) if an item was successfully read
• Ok(None) if there are no more items to read
• Err(BatchError) if an error occurred during reading (e.g., database error)

Examples

use spring_batch_rs::item::orm::OrmItemReaderBuilder;
use spring_batch_rs::core::item::ItemReader;
use sea_orm::FromQueryResult;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, FromQueryResult, Deserialize, Serialize)]
struct Product {
    id: i32,
    name: String,
    price: f64,
}

// Assuming you have a database connection and query set up
// let reader = OrmItemReaderBuilder::new()
//     .connection(&db)
//     .query(products::Entity::find())
//     .page_size(50)
//     .build();

// Read all products
// let mut products = Vec::new();
// while let Some(product) = reader.read()? {
//     products.push(product);
// }