Enhance cache stats, add DB helpers & benches

Several improvements across the codebase:

- Query/Prepared-statement cache: add atomic counters and fast-path flags (hits, misses, entries, size_bytes, evictions, invalidations), track approximate serialized size per entry, update eviction/invalidation accounting, optimize common read paths, and expose snapshot/reset semantics. Add tests covering replacements, reset semantics and clearing behavior.
- Benchmarks: add end-to-end query-cache and uncached-concurrency benchmarks (BenchCacheUser model + new benchmark functions), register them in the criterion group, and minor bench formatting fixes.
- Database API: add convenience async helpers (raw_with_params, execute_with_params, raw_json_with_params) and internal __* variants that operate on a given Database instance to run raw SQL with typed params.
- Error context: box ErrorContext in Error variants, add rendered conditions and operator_chain fields and helper builders, and improve formatting and tests.
- Docs/manifest: clarify that attachments/translations/fulltext are compile-time feature gates (do not add deps) in Cargo.toml and README; add a sqlite CI smoke test to Cargo.toml.
- Misc: small fixes and formatting in attachments, fulltext query formatting and parameter pushes, CRUD benchmark formatting, and move config tests to an external testing module.

These changes improve cache observability, concurrency behavior in benchmarks, and convenience for raw SQL usage while keeping feature flags and docs clearer.

Author: mohamadzoh

Cargo.toml

@@ -22,6 +22,8 @@ mysql = ["sea-orm/sqlx-mysql"]
 sqlite = ["sea-orm/sqlx-sqlite"]
 runtime-tokio = ["sea-orm/runtime-tokio-rustls", "dep:tokio"]
 runtime-async-std = ["sea-orm/runtime-async-std-rustls"]
+# These module flags intentionally gate TideORM's public API surface via #[cfg(feature = ...)]
+# and feature-specific tests/benches only. They do not enable extra dependencies.
 attachments = []
 translations = []
 fulltext = []
@@ -103,3 +105,8 @@ harness = false
 [[bench]]
 name = "tokenization_benchmarks"
 harness = false
+
+[[test]]
+name = "sqlite_ci_smoke_test"
+path = "tests/sqlite_ci_smoke_test.rs"
+required-features = ["sqlite", "runtime-tokio"]

README.md

@@ -192,15 +192,15 @@ tideorm = { version = "0.8.0", features = ["postgres", "fulltext"] }
 | `sqlite` | SQLite support |
 | `runtime-tokio` | Tokio runtime (default) |
 | `runtime-async-std` | async-std runtime |
-| `attachments` | Enables the attachments API and attachment-specific benchmarks/tests |
-| `translations` | Enables the translations API and translation-specific benchmarks/tests |
-| `fulltext` | Enables the full-text search API and fulltext-specific benchmarks/tests |
+| `attachments` | Compile-time-only feature gate for the attachments API and attachment-specific benchmarks/tests; adds no extra dependencies |
+| `translations` | Compile-time-only feature gate for the translations API and translation-specific benchmarks/tests; adds no extra dependencies |
+| `fulltext` | Compile-time-only feature gate for the full-text search API and fulltext-specific benchmarks/tests; adds no extra dependencies |
 
-Attachments are opt-in. Enable the `attachments` feature when you want to use `tideorm::attachments`, `HasAttachments`, or attachment URL generation helpers.
+Attachments are opt-in. Enable the `attachments` feature when you want to use `tideorm::attachments`, `HasAttachments`, or attachment URL generation helpers. This is a compile-time API gate only; it does not pull in additional crates.
 
-Translations are opt-in. Enable the `translations` feature when you want to use `tideorm::translations`, `HasTranslations`, or `ApplyTranslations`.
+Translations are opt-in. Enable the `translations` feature when you want to use `tideorm::translations`, `HasTranslations`, or `ApplyTranslations`. This is a compile-time API gate only; it does not pull in additional crates.
 
-Full-text search is opt-in. Enable the `fulltext` feature when you want to use `tideorm::fulltext`, `FullTextSearch`, or the highlighting helpers.
+Full-text search is opt-in. Enable the `fulltext` feature when you want to use `tideorm::fulltext`, `FullTextSearch`, or the highlighting helpers. This is a compile-time API gate only; it does not pull in additional crates.
 
 ## Relation Types
 
@@ -241,7 +241,7 @@ For runnable applications and broader demos, see **[tideorm-examples](https://gi
 
 ## Testing
 
-TideORM ships with unit, integration, and feature-specific test coverage. The repository CI runs `cargo check` plus `cargo test --lib` across PostgreSQL, MySQL, and SQLite feature sets.
+TideORM ships with unit, integration, and feature-specific test coverage. The repository CI runs cargo fmt, cargo clippy, cargo check, cargo test --lib across PostgreSQL, MySQL, and SQLite feature sets, plus a SQLite end-to-end smoke test.
 
 Common local commands:
 

benches/attachments_translations_benchmarks.rs

@@ -301,7 +301,7 @@ fn bench_files_data_serialization(c: &mut Criterion) {
                 {"key": "img3.jpg", "filename": "img3.jpg", "created_at": "2024-01-01T00:00:00Z"},
             ]
         });
-        
+
         b.iter(|| {
             black_box(FilesData::from_json(&json))
         });
@@ -435,7 +435,7 @@ fn bench_translation_input(c: &mut Criterion) {
             "meta_title": {"en": "Title", "ar": "عنوان", "fr": "Titre", "es": "Título", "de": "Titel"},
             "meta_desc": {"en": "Meta", "ar": "ميتا", "fr": "Méta", "es": "Meta", "de": "Meta"}
         });
-        
+
         b.iter(|| {
             black_box(TranslationInput::from_json(&json).unwrap())
         });

benches/cache_benchmarks.rs

@@ -6,7 +6,23 @@
 
 use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_main};
 use std::hint::black_box;
+use std::sync::Arc;
+use std::thread;
+use std::time::Duration;
+use tideorm::Database;
 use tideorm::cache::{CacheKeyBuilder, CacheStrategy, PreparedStatementCache, QueryCache};
+use tideorm::internal::{ActiveModelTrait, ConnectionTrait, InternalModel};
+use tideorm::prelude::*;
+
+#[derive(Model, PartialEq)]
+#[tideorm(table = "bench_cache_users")]
+struct BenchCacheUser {
+    #[tideorm(primary_key, auto_increment)]
+    id: i64,
+    email: String,
+    name: String,
+    active: bool,
+}
 
 // =============================================================================
 // QUERY CACHE BENCHMARKS
@@ -448,6 +464,217 @@ fn benchmark_cache_with_serialization(c: &mut Criterion) {
     group.finish();
 }
 
+fn benchmark_end_to_end_query_cache_paths(c: &mut Criterion) {
+    let rt = tokio::runtime::Runtime::new().expect("failed to create tokio runtime");
+    let db = rt
+        .block_on(Database::connect("sqlite::memory:"))
+        .expect("failed to connect to benchmark sqlite database");
+
+    rt.block_on(async {
+        db.__internal_connection()
+            .execute_unprepared(
+                r#"
+                CREATE TABLE bench_cache_users (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    email TEXT NOT NULL,
+                    name TEXT NOT NULL,
+                    active INTEGER NOT NULL DEFAULT 1
+                )
+            "#,
+            )
+            .await
+            .expect("failed to create benchmark table");
+
+        for i in 0..100 {
+            BenchCacheUser {
+                id: 0,
+                email: format!("user_{i}@example.com"),
+                name: format!("User {i}"),
+                active: i % 2 == 0,
+            }
+            .into_active_model()
+            .insert(db.__internal_connection())
+            .await
+            .expect("failed to seed benchmark row");
+        }
+    });
+
+    let cache = QueryCache::global();
+    cache.disable();
+    cache.clear();
+    cache.reset_stats();
+
+    let mut group = c.benchmark_group("end_to_end_query_cache");
+
+    group.bench_function("uncached_cache_disabled", |b| {
+        b.to_async(&rt).iter(|| async {
+            let results = BenchCacheUser::query_with(&db)
+                .where_eq("email", "user_42@example.com")
+                .get()
+                .await
+                .expect("uncached query should succeed");
+            black_box(results)
+        });
+    });
+
+    cache.enable();
+    cache.clear();
+    cache.reset_stats();
+
+    group.bench_function("uncached_cache_enabled", |b| {
+        b.to_async(&rt).iter(|| async {
+            let results = BenchCacheUser::query_with(&db)
+                .where_eq("email", "user_42@example.com")
+                .get()
+                .await
+                .expect("uncached query should succeed");
+            black_box(results)
+        });
+    });
+
+    cache.clear();
+    cache.reset_stats();
+
+    group.bench_function("cached_query_enabled", |b| {
+        b.to_async(&rt).iter(|| async {
+            let results = BenchCacheUser::query_with(&db)
+                .where_eq("email", "user_42@example.com")
+                .cache(Duration::from_secs(60))
+                .get()
+                .await
+                .expect("cached query should succeed");
+            black_box(results)
+        });
+    });
+
+    cache.disable();
+    cache.clear();
+    cache.reset_stats();
+    group.finish();
+}
+
+fn benchmark_uncached_query_concurrency(c: &mut Criterion) {
+    let db_url = "sqlite://target/bench_cache_concurrency.db?mode=rwc";
+    let rt = tokio::runtime::Runtime::new().expect("failed to create tokio runtime");
+    let db = rt
+        .block_on(Database::connect(db_url))
+        .expect("failed to connect to concurrency benchmark sqlite database");
+
+    rt.block_on(async {
+        db.__internal_connection()
+            .execute_unprepared("DROP TABLE IF EXISTS bench_cache_users")
+            .await
+            .expect("failed to drop benchmark table");
+        db.__internal_connection()
+            .execute_unprepared(
+                r#"
+                CREATE TABLE bench_cache_users (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    email TEXT NOT NULL,
+                    name TEXT NOT NULL,
+                    active INTEGER NOT NULL DEFAULT 1
+                )
+            "#,
+            )
+            .await
+            .expect("failed to create benchmark table");
+
+        for i in 0..200 {
+            BenchCacheUser {
+                id: 0,
+                email: format!("concurrent_{i}@example.com"),
+                name: format!("Concurrent User {i}"),
+                active: i % 2 == 0,
+            }
+            .into_active_model()
+            .insert(db.__internal_connection())
+            .await
+            .expect("failed to seed concurrency benchmark row");
+        }
+    });
+
+    let db = Arc::new(db);
+    let cache = QueryCache::global();
+    let mut group = c.benchmark_group("uncached_query_concurrency");
+    let threads = 4;
+    let queries_per_thread = 50;
+    let total_queries = (threads * queries_per_thread) as u64;
+    group.throughput(Throughput::Elements(total_queries));
+
+    cache.disable();
+    cache.clear();
+    cache.reset_stats();
+
+    group.bench_function("cache_disabled", |b| {
+        b.iter(|| {
+            let handles: Vec<_> = (0..threads)
+                .map(|thread_id| {
+                    let db = Arc::clone(&db);
+                    thread::spawn(move || {
+                        let rt = tokio::runtime::Runtime::new()
+                            .expect("failed to create per-thread runtime");
+                        rt.block_on(async move {
+                            for query_id in 0..queries_per_thread {
+                                let user_index = (thread_id * queries_per_thread + query_id) % 200;
+                                let email = format!("concurrent_{user_index}@example.com");
+                                let results = BenchCacheUser::query_with(db.as_ref())
+                                    .where_eq("email", email)
+                                    .get()
+                                    .await
+                                    .expect("uncached concurrent query should succeed");
+                                black_box(results);
+                            }
+                        });
+                    })
+                })
+                .collect();
+
+            for handle in handles {
+                handle.join().expect("benchmark thread should join");
+            }
+        });
+    });
+
+    cache.enable();
+    cache.clear();
+    cache.reset_stats();
+
+    group.bench_function("cache_enabled_opt_out", |b| {
+        b.iter(|| {
+            let handles: Vec<_> = (0..threads)
+                .map(|thread_id| {
+                    let db = Arc::clone(&db);
+                    thread::spawn(move || {
+                        let rt = tokio::runtime::Runtime::new()
+                            .expect("failed to create per-thread runtime");
+                        rt.block_on(async move {
+                            for query_id in 0..queries_per_thread {
+                                let user_index = (thread_id * queries_per_thread + query_id) % 200;
+                                let email = format!("concurrent_{user_index}@example.com");
+                                let results = BenchCacheUser::query_with(db.as_ref())
+                                    .where_eq("email", email)
+                                    .get()
+                                    .await
+                                    .expect("uncached concurrent query should succeed");
+                                black_box(results);
+                            }
+                        });
+                    })
+                })
+                .collect();
+
+            for handle in handles {
+                handle.join().expect("benchmark thread should join");
+            }
+        });
+    });
+
+    cache.disable();
+    cache.clear();
+    cache.reset_stats();
+    group.finish();
+}
+
 // =============================================================================
 // CRITERION GROUPS
 // =============================================================================
@@ -473,6 +700,8 @@ criterion_group!(
     complex_benches,
     benchmark_realistic_workload,
     benchmark_cache_with_serialization,
+    benchmark_end_to_end_query_cache_paths,
+    benchmark_uncached_query_concurrency,
 );
 
 criterion_main!(

benches/crud_benchmarks.rs

@@ -135,7 +135,8 @@ fn bench_single_insert(c: &mut Criterion) {
         b.iter(|| {
             let unique_id = COUNTER.fetch_add(1, Ordering::SeqCst);
             rt.block_on(async {
-                let user = BenchUser::new(format!("bench_{unique_id}@example.com"), "Benchmark User");
+                let user =
+                    BenchUser::new(format!("bench_{unique_id}@example.com"), "Benchmark User");
                 user.save().await.expect("Insert failed")
             })
         });
@@ -191,11 +192,8 @@ fn bench_find_by_id(c: &mut Criterion) {
     let user_ids: Vec<i64> = rt.block_on(async {
         let mut ids = Vec::new();
         for i in 0..100 {
-            let user = BenchUser::new(
-                format!("find_{i}@example.com"),
-                format!("Find User {i}"),
-            )
-            .with_age(25 + (i % 30));
+            let user = BenchUser::new(format!("find_{i}@example.com"), format!("Find User {i}"))
+                .with_age(25 + (i % 30));
             let saved = user.save().await.expect("Insert failed");
             ids.push(saved.id);
         }

src/attachments.rs

@@ -434,8 +434,8 @@ pub trait HasAttachments {
         if Self::is_has_one_relation(relation) {
             if attachments.is_empty() {
                 files.remove_one(relation);
-                } else if let Some(first) = attachments.into_iter().next() {
-                    files.set_one(relation, first);
+            } else if let Some(first) = attachments.into_iter().next() {
+                files.set_one(relation, first);
             }
         } else {
             files.clear_many(relation);