Use shared DB handles; fix model serialization

Refactor database handling to use a shared internal DatabaseHandle in thread-local scope and resolve the active connection/backend directly from the current scope. Harden transaction semantics (consistent failure on leaked handles) and rename init helper usage in docs/examples (Database::init). Replace previous no-op serialization stubs for translations and file attachments with real implementations that operate on the model state and return explicit errors for unsupported operations (e.g. loading all translations into scalar fields). Update call sites (queries, fulltext, eager loading, nested upserts, generated macro code) to use the shared internal connection and conn.connection() where appropriate. Add tests for translation and file attachment round-trips and refresh docs/README and macros crate version to 0.8.4.

Author: mohamadzoh

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to TideORM will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.4] - 2026-03-20
+
+### Fixed
+
+- Replaced silent translation and file-attachment serialization stubs so `Model::load_language_translations()`, `Model::get_files_attribute()`, and `Model::set_files_attribute()` now operate on the model state instead of succeeding without effect.
+- Made `Model::load_all_translations()` fail loudly with a clear unsupported error instead of silently pretending to load all translations into scalar model fields.
+- Hardened `Database::transaction()` so leaked transaction handles now fail consistently on both commit and rollback paths instead of silently relying on drop-based rollback in the error path.
+- Ensured `NestedSaveBuilder::save()` persists related models with the parent foreign key instead of returning only FK-patched JSON payloads.
+
+### Changed
+
+- Reduced database-access overhead on model hot paths by resolving the current connection/backend directly from the active scope instead of repeatedly cloning the outer `Database` wrapper.
+- Changed transaction-scoped thread-local overrides to store `DatabaseHandle` directly and updated `ConnectionRef::Database` to carry the shared internal connection handle instead of cloning `DatabaseConnection` per lookup.
+- Refreshed public docs and examples to use the current global-database initialization API and the 0.8.4 crate version.
+
+### Internal
+
+- Kept the workspace warning-free after the connection-handle refactor by updating generated macro code, full-text execution paths, eager loading, nested bulk upserts, and query helpers to use shared internal connections correctly.
+- Verified the release with `cargo test --lib` and `cargo clippy --workspace --all-targets -- -D warnings`.
+
 ## [0.8.1] - 2026-03-18
 
 ### Fixed
@@ -551,7 +571,8 @@ This is the first public release of TideORM, a developer-friendly ORM for Rust w
 - **Repository:** [https://github.com/mohamadzoh/tideorm](https://github.com/mohamadzoh/tideorm)
 - **Documentation:** See README.md and examples/
 
-[Unreleased]: https://github.com/mohamadzoh/tideorm/compare/v0.8.1...HEAD
+[Unreleased]: https://github.com/mohamadzoh/tideorm/compare/v0.8.4...HEAD
+[0.8.4]: https://github.com/mohamadzoh/tideorm/compare/v0.8.1...v0.8.4
 [0.8.1]: https://github.com/mohamadzoh/tideorm/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/mohamadzoh/tideorm/compare/v0.7.3...v0.8.0
 [0.7.3]: https://github.com/mohamadzoh/tideorm/compare/v0.7.2...v0.7.3

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "tideorm"
-version = "0.8.3"
+version = "0.8.4"
 edition = "2024"
 authors = ["Mohamad Al Zohbie <alzoubi528@gmail.com>"]
 description = "A developer-friendly ORM for Rust with clean, expressive syntax"
@@ -48,7 +48,7 @@ rust_decimal = { version = "1.40.0", features = ["serde"] }
 thiserror = "2.0.18"
 
 # Derive macros (our own crate)
-tideorm-macros = { version = "0.8.1", path = "tideorm-macros" }
+tideorm-macros = { version = "0.8.4", path = "tideorm-macros" }
 
 # Utils
 parking_lot = "0.12.5"

Cargo.toml

@@ -192,22 +192,22 @@ let recent_posts = user.posts.load_with(|q| {
 ```toml
 [dependencies]
 # PostgreSQL (default)
-tideorm = { version = "0.8.1", features = ["postgres"] }
+tideorm = { version = "0.8.4", features = ["postgres"] }
 
 # MySQL
-tideorm = { version = "0.8.1", features = ["mysql"] }
+tideorm = { version = "0.8.4", features = ["mysql"] }
 
 # SQLite
-tideorm = { version = "0.8.1", features = ["sqlite"] }
+tideorm = { version = "0.8.4", features = ["sqlite"] }
 
 # Enable attachments support explicitly
-tideorm = { version = "0.8.1", features = ["postgres", "attachments"] }
+tideorm = { version = "0.8.4", features = ["postgres", "attachments"] }
 
 # Enable translations support explicitly
-tideorm = { version = "0.8.1", features = ["postgres", "translations"] }
+tideorm = { version = "0.8.4", features = ["postgres", "translations"] }
 
 # Enable full-text search support explicitly
-tideorm = { version = "0.8.1", features = ["postgres", "fulltext"] }
+tideorm = { version = "0.8.4", features = ["postgres", "fulltext"] }
 ```
 
 ### Feature Flags

README.md

@@ -514,7 +514,7 @@ TideORM provides full-text search capabilities across PostgreSQL (tsvector/tsque
 Enable the feature explicitly when you need the full-text search API:
 
 ```toml
-tideorm = { version = "0.8.1", features = ["postgres", "fulltext"] }
+tideorm = { version = "0.8.4", features = ["postgres", "fulltext"] }
 ```
 
 ### Search Basics

docs/queries.md

@@ -210,7 +210,7 @@ Enable the feature first:
 
 ```toml
 [dependencies]
-tideorm = { version = "0.8.1", features = ["postgres", "attachments"] }
+tideorm = { version = "0.8.4", features = ["postgres", "attachments"] }
 ```
 
 ### Model Setup
@@ -545,7 +545,7 @@ Enable the feature first:
 
 ```toml
 [dependencies]
-tideorm = { version = "0.8.1", features = ["postgres", "translations"] }
+tideorm = { version = "0.8.4", features = ["postgres", "translations"] }
 ```
 
 ### Model Setup

docs/relations.md

@@ -35,7 +35,7 @@
 //!
 //! ```rust,ignore
 //! // Initialize global connection (call once at startup)
-//! Database::connect_global("postgres://localhost/myapp").await?;
+//! Database::init("postgres://localhost/myapp").await?;
 //!
 //! // Now models can use the global connection automatically
 //! let user = User {
@@ -66,7 +66,7 @@ use crate::tide_warn;
 static GLOBAL_DB: OnceLock<Database> = OnceLock::new();
 
 thread_local! {
-    static THREAD_DB_OVERRIDE: RefCell<Option<Database>> = const { RefCell::new(None) };
+    static THREAD_DB_OVERRIDE: RefCell<Option<DatabaseHandle>> = const { RefCell::new(None) };
 }
 
 #[derive(Clone)]
@@ -86,7 +86,7 @@ fn panic_missing_global_db(message: &str) -> ! {
 /// Get a reference to the global database connection
 ///
 /// This function returns the global database connection that was initialized
-/// with `Database::connect_global()` or `Database::set_global()`.
+/// with `Database::init()` or `Database::set_global()`.
 ///
 /// # Panics
 ///
@@ -96,7 +96,7 @@ fn panic_missing_global_db(message: &str) -> ! {
 /// # Example
 ///
 /// ```rust,ignore
-/// // After initializing with connect_global()
+/// // After initializing with Database::init()
 /// let users = User::all().await?;
 /// ```
 pub fn db() -> &'static Database {
@@ -159,13 +159,39 @@ pub fn has_global_db() -> bool {
 
 #[doc(hidden)]
 pub fn __current_db() -> Result<Database> {
-    if let Some(db) = THREAD_DB_OVERRIDE.with(|slot| slot.borrow().clone()) {
-        return Ok(db);
+    if let Some(handle) = THREAD_DB_OVERRIDE.with(|slot| slot.borrow().clone()) {
+        return Ok(Database::from_handle(handle));
     }
 
     require_db()
 }
 
+fn current_scope_handle() -> Result<DatabaseHandle> {
+    if let Some(handle) = THREAD_DB_OVERRIDE.with(|slot| slot.borrow().clone()) {
+        return Ok(handle);
+    }
+
+    global_db_handle().current_handle()
+}
+
+#[doc(hidden)]
+pub fn __current_connection() -> Result<ConnectionRef> {
+    Ok(match current_scope_handle()? {
+        DatabaseHandle::Connection(inner) => ConnectionRef::Database(inner),
+        DatabaseHandle::Transaction(tx) => ConnectionRef::Transaction(tx),
+    })
+}
+
+#[doc(hidden)]
+pub fn __current_backend() -> Result<crate::internal::DbBackend> {
+    use crate::internal::ConnectionTrait;
+
+    Ok(match current_scope_handle()? {
+        DatabaseHandle::Connection(inner) => inner.connection().get_database_backend(),
+        DatabaseHandle::Transaction(tx) => tx.as_ref().get_database_backend(),
+    })
+}
+
 /// Database connection handle
 ///
 /// This is the main entry point for all database operations in TideORM.
@@ -187,18 +213,14 @@ impl Database {
         }
     }
 
-    fn from_internal_connection(inner: InternalConnection) -> Self {
+    fn from_handle(handle: DatabaseHandle) -> Self {
         Self {
-            inner: Arc::new(RwLock::new(Some(DatabaseHandle::Connection(Arc::new(
-                inner,
-            ))))),
+            inner: Arc::new(RwLock::new(Some(handle))),
         }
     }
 
-    fn from_internal_transaction(inner: Arc<crate::internal::DatabaseTransaction>) -> Self {
-        Self {
-            inner: Arc::new(RwLock::new(Some(DatabaseHandle::Transaction(inner)))),
-        }
+    fn from_internal_connection(inner: InternalConnection) -> Self {
+        Self::from_handle(DatabaseHandle::Connection(Arc::new(inner)))
     }
 
     fn current_handle(&self) -> Result<DatabaseHandle> {
@@ -229,12 +251,12 @@ impl Database {
         self.inner.write().take();
     }
 
-    fn replace_thread_override(db: Option<Self>) -> Option<Self> {
-        THREAD_DB_OVERRIDE.with(|slot| slot.replace(db))
+    fn replace_thread_override(handle: Option<DatabaseHandle>) -> Option<DatabaseHandle> {
+        THREAD_DB_OVERRIDE.with(|slot| slot.replace(handle))
     }
 
-    fn set_thread_override(db: Option<Self>) {
-        THREAD_DB_OVERRIDE.with(|slot| *slot.borrow_mut() = db);
+    fn set_thread_override(handle: Option<DatabaseHandle>) {
+        THREAD_DB_OVERRIDE.with(|slot| *slot.borrow_mut() = handle);
     }
 
     fn is_connected(&self) -> bool {
@@ -308,8 +330,8 @@ impl Database {
     pub fn set_global(db: Self) -> Result<&'static Self> {
         let inner = db.current_inner()?;
         let global = global_db_handle();
-        global.replace_inner(inner);
-        Self::set_thread_override(Some(db));
+        global.replace_inner(inner.clone());
+        Self::set_thread_override(Some(DatabaseHandle::Connection(inner)));
         Ok(global)
     }
 
@@ -390,6 +412,7 @@ impl Database {
 
         let txn = match self.__get_connection()? {
             ConnectionRef::Database(conn) => conn
+                .connection()
                 .begin()
                 .await
                 .map_err(|e| Error::transaction(e.to_string()))?,
@@ -403,7 +426,7 @@ impl Database {
         let txn = Arc::new(txn);
         let tx = Transaction { inner: txn.clone() };
         let previous_override =
-            Self::replace_thread_override(Some(Self::from_internal_transaction(txn.clone())));
+            Self::replace_thread_override(Some(DatabaseHandle::Transaction(txn.clone())));
 
         let outcome = f(&tx).await;
 
@@ -505,13 +528,12 @@ impl Database {
     pub async fn raw<T: crate::model::Model>(sql: &str) -> Result<Vec<T>> {
         use crate::internal::{ConnectionTrait, FromQueryResult, Statement};
 
-        let db = crate::database::__current_db()?;
-        let backend = db.__internal_backend()?;
+        let backend = crate::database::__current_backend()?;
         let stmt = Statement::from_string(backend, sql.to_string());
 
-        let results = match db.__get_connection()? {
+        let results = match crate::database::__current_connection()? {
             ConnectionRef::Database(conn) => {
-                crate::profiling::__profile_future(conn.query_all_raw(stmt)).await
+                crate::profiling::__profile_future(conn.connection().query_all_raw(stmt)).await
             }
             ConnectionRef::Transaction(tx) => {
                 crate::profiling::__profile_future(tx.as_ref().query_all_raw(stmt)).await
@@ -563,8 +585,12 @@ impl Database {
 
         let results = match self.__get_connection()? {
             ConnectionRef::Database(conn) => {
-                let stmt = Statement::from_sql_and_values(conn.get_database_backend(), sql, params);
-                crate::profiling::__profile_future(conn.query_all_raw(stmt)).await
+                let stmt = Statement::from_sql_and_values(
+                    conn.connection().get_database_backend(),
+                    sql,
+                    params,
+                );
+                crate::profiling::__profile_future(conn.connection().query_all_raw(stmt)).await
             }
             ConnectionRef::Transaction(tx) => {
                 let stmt =
@@ -597,10 +623,9 @@ impl Database {
     pub async fn execute(sql: &str) -> Result<u64> {
         use crate::internal::ConnectionTrait;
 
-        let db = crate::database::__current_db()?;
-        let result = match db.__get_connection()? {
+        let result = match crate::database::__current_connection()? {
             ConnectionRef::Database(conn) => {
-                crate::profiling::__profile_future(conn.execute_unprepared(sql)).await
+                crate::profiling::__profile_future(conn.connection().execute_unprepared(sql)).await
             }
             ConnectionRef::Transaction(tx) => {
                 crate::profiling::__profile_future(tx.as_ref().execute_unprepared(sql)).await
@@ -640,8 +665,12 @@ impl Database {
 
         let result = match self.__get_connection()? {
             ConnectionRef::Database(conn) => {
-                let stmt = Statement::from_sql_and_values(conn.get_database_backend(), sql, params);
-                crate::profiling::__profile_future(conn.execute_raw(stmt)).await
+                let stmt = Statement::from_sql_and_values(
+                    conn.connection().get_database_backend(),
+                    sql,
+                    params,
+                );
+                crate::profiling::__profile_future(conn.connection().execute_raw(stmt)).await
             }
             ConnectionRef::Transaction(tx) => {
                 let stmt =
@@ -679,13 +708,12 @@ impl Database {
     pub async fn raw_json(sql: &str) -> Result<Vec<serde_json::Value>> {
         use crate::internal::{ConnectionTrait, Statement};
 
-        let db = crate::database::__current_db()?;
-        let backend = db.__internal_backend()?;
+        let backend = crate::database::__current_backend()?;
         let stmt = Statement::from_string(backend, sql.to_string());
 
-        let results = match db.__get_connection()? {
+        let results = match crate::database::__current_connection()? {
             ConnectionRef::Database(conn) => {
-                crate::profiling::__profile_future(conn.query_all_raw(stmt)).await
+                crate::profiling::__profile_future(conn.connection().query_all_raw(stmt)).await
             }
             ConnectionRef::Transaction(tx) => {
                 crate::profiling::__profile_future(tx.as_ref().query_all_raw(stmt)).await
@@ -716,8 +744,12 @@ impl Database {
 
         let results = match self.__get_connection()? {
             ConnectionRef::Database(conn) => {
-                let stmt = Statement::from_sql_and_values(conn.get_database_backend(), sql, params);
-                crate::profiling::__profile_future(conn.query_all_raw(stmt)).await
+                let stmt = Statement::from_sql_and_values(
+                    conn.connection().get_database_backend(),
+                    sql,
+                    params,
+                );
+                crate::profiling::__profile_future(conn.connection().query_all_raw(stmt)).await
             }
             ConnectionRef::Transaction(tx) => {
                 let stmt =
@@ -1011,16 +1043,14 @@ pub trait Connection: Send + Sync {
 /// Internal connection reference (hidden from users)
 #[doc(hidden)]
 pub enum ConnectionRef {
-    Database(crate::internal::DatabaseConnection),
+    Database(Arc<crate::internal::InternalConnection>),
     Transaction(Arc<crate::internal::DatabaseTransaction>),
 }
 
 impl Connection for Database {
     fn __get_connection(&self) -> Result<ConnectionRef> {
         Ok(match self.current_handle()? {
-            DatabaseHandle::Connection(inner) => {
-                ConnectionRef::Database(inner.connection().clone())
-            }
+            DatabaseHandle::Connection(inner) => ConnectionRef::Database(inner),
             DatabaseHandle::Transaction(tx) => ConnectionRef::Transaction(tx),
         })
     }