Trait Connection 

pub trait Connection: Send + Sync {
    // Required methods
    fn execute<'a>(
        &'a mut self,
        sql: &'a str,
    ) -> Pin<Box<dyn Future<Output = Result<u64, DbError>> + Send + 'a>>;
    fn query<'a>(
        &'a mut self,
        sql: &'a str,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<HashMap<String, Value>>, DbError>> + Send + 'a>>;
    fn begin_transaction<'a>(
        &'a mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), DbError>> + Send + 'a>>;
    fn commit<'a>(
        &'a mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), DbError>> + Send + 'a>>;
    fn rollback<'a>(
        &'a mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), DbError>> + Send + 'a>>;
    fn is_connected(&self) -> bool;
    fn ping<'a>(&'a mut self) -> Pin<Box<dyn Future<Output = bool> + Send + 'a>>;
    fn close<'a>(
        &'a mut self,
    ) -> Pin<Box<dyn Future<Output = Result<(), DbError>> + Send + 'a>>;

    // Provided methods
    fn in_transaction(&self) -> bool { ... }
    fn execute_with_params<'a>(
        &'a mut self,
        sql: &'a str,
        params: &'a [Value],
    ) -> Pin<Box<dyn Future<Output = Result<u64, DbError>> + Send + 'a>> { ... }
    fn query_with_params<'a>(
        &'a mut self,
        sql: &'a str,
        params: &'a [Value],
    ) -> Pin<Box<dyn Future<Output = Result<Vec<HashMap<String, Value>>, DbError>> + Send + 'a>> { ... }
    fn query_values<'a>(
        &'a mut self,
        sql: &'a str,
    ) -> Pin<Box<dyn Future<Output = Result<(Vec<String>, Vec<Vec<Value>>), DbError>> + Send + 'a>> { ... }
    fn query_values_with_params<'a>(
        &'a mut self,
        sql: &'a str,
        params: &'a [Value],
    ) -> Pin<Box<dyn Future<Output = Result<(Vec<String>, Vec<Vec<Value>>), DbError>> + Send + 'a>> { ... }
    fn query_stream<'a>(
        &'a mut self,
        sql: &'a str,
    ) -> Pin<Box<dyn Stream<Item = Result<HashMap<String, Value>, DbError>> + Send + 'a>> { ... }
    fn execute_batch<'a>(
        &'a mut self,
        sqls: &'a [String],
    ) -> Pin<Box<dyn Future<Output = Result<u64, DbError>> + Send + 'a>> { ... }
    fn execute_batch_params<'a>(
        &'a mut self,
        sql: &'a str,
        params_batch: &'a [Vec<Value>],
    ) -> Pin<Box<dyn Future<Output = Result<u64, DbError>> + Send + 'a>> { ... }
}

数据库连接 trait

注意：此 trait 手动解糖 async 方法（不使用 #[async_trait]）， 以避免 &str 参数触发 HRTB 与 sqlx::Executor 冲突。 所有 async 方法使用单一生命周期 'a（绑定 &'a mut self 和 &'a str）， 而非 HRTB，从而允许 sqlx 适配器实现。

Required Methods

fn execute<'a>( &'a mut self, sql: &'a str, ) -> Pin<Box<dyn Future<Output = Result<u64, DbError>> + Send + 'a>>

fn query<'a>( &'a mut self, sql: &'a str, ) -> Pin<Box<dyn Future<Output = Result<Vec<HashMap<String, Value>>, DbError>> + Send + 'a>>

fn begin_transaction<'a>( &'a mut self, ) -> Pin<Box<dyn Future<Output = Result<(), DbError>> + Send + 'a>>

fn commit<'a>( &'a mut self, ) -> Pin<Box<dyn Future<Output = Result<(), DbError>> + Send + 'a>>

fn rollback<'a>( &'a mut self, ) -> Pin<Box<dyn Future<Output = Result<(), DbError>> + Send + 'a>>

fn is_connected(&self) -> bool

fn ping<'a>(&'a mut self) -> Pin<Box<dyn Future<Output = bool> + Send + 'a>>

fn close<'a>( &'a mut self, ) -> Pin<Box<dyn Future<Output = Result<(), DbError>> + Send + 'a>>

Provided Methods

fn in_transaction(&self) -> bool

查询连接当前是否处于未提交事务中。

默认返回 false；支持事务的适配器（sz-orm-sqlx）应返回内部 in_transaction 标志。连接池在归还连接时据此先回滚未完成事务， 避免脏连接持锁/污染复用连接（Critical fix：MySQL metadata lock 泄漏）。

fn execute_with_params<'a>( &'a mut self, sql: &'a str, params: &'a [Value], ) -> Pin<Box<dyn Future<Output = Result<u64, DbError>> + Send + 'a>>

参数绑定执行（INSERT/UPDATE/DELETE）

使用真实 prepared statement 绑定参数，避免 SQL 注入。 默认实现返回 NotImplemented 错误；支持参数绑定的适配器 （如 sz-orm-oracle）应覆盖此方法。

fn query_with_params<'a>( &'a mut self, sql: &'a str, params: &'a [Value], ) -> Pin<Box<dyn Future<Output = Result<Vec<HashMap<String, Value>>, DbError>> + Send + 'a>>

参数绑定查询（SELECT）

使用真实 prepared statement 绑定参数，避免 SQL 注入。 默认实现返回 NotImplemented 错误；支持参数绑定的适配器 （如 sz-orm-oracle）应覆盖此方法。

fn query_values<'a>( &'a mut self, sql: &'a str, ) -> Pin<Box<dyn Future<Output = Result<(Vec<String>, Vec<Vec<Value>>), DbError>> + Send + 'a>>

位置式查询（SELECT）：返回 (列名, 按列顺序的值矩阵)

绕过 HashMap<String, Value> 行映射，适用于 SELECT ALL 大结果集场景。 默认实现返回 NotImplemented 错误；适配器可覆盖此方法以获得 30%~50% 性能提升。

fn query_values_with_params<'a>( &'a mut self, sql: &'a str, params: &'a [Value], ) -> Pin<Box<dyn Future<Output = Result<(Vec<String>, Vec<Vec<Value>>), DbError>> + Send + 'a>>

参数绑定位置式查询（SELECT）：叠加 prepared statement + 位置式映射双重优化

默认实现返回 NotImplemented 错误；适配器可覆盖此方法以获得最佳性能。

fn query_stream<'a>( &'a mut self, sql: &'a str, ) -> Pin<Box<dyn Stream<Item = Result<HashMap<String, Value>, DbError>> + Send + 'a>>

流式查询：返回逐行结果流

默认实现返回空流；适配器可覆盖此方法以支持大结果集逐行消费， 避免 query 一次性 fetch_all 导致的内存峰值。

fn execute_batch<'a>( &'a mut self, sqls: &'a [String], ) -> Pin<Box<dyn Future<Output = Result<u64, DbError>> + Send + 'a>>

批量执行多条 SQL（按顺序执行，返回累计影响行数）

默认实现循环调用 execute；适配器可覆盖此方法以利用数据库原生 批量执行能力。

fn execute_batch_params<'a>( &'a mut self, sql: &'a str, params_batch: &'a [Vec<Value>], ) -> Pin<Box<dyn Future<Output = Result<u64, DbError>> + Send + 'a>>

批量插入（单条 SQL 多次参数绑定执行）

默认实现循环调用 execute_with_params；适配器可覆盖此方法 以利用数据库原生批量 DML 能力（如 Oracle Array DML）。

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors