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 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 query_stream_cursor<'a>(
        &'a mut self,
        sql: &'a str,
        _batch_size: usize,
    ) -> 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 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() 获取全部行后，以 futures::stream::iter 逐行 yield，提供统一的流式消费接口。 适合中小结果集；对超大结果集，支持原生游标的适配器应覆盖此方法。

注意

此方法本身是同步的（返回 Stream），但内部通过 futures::stream::once 异步获取数据后展开为逐行流。若适配器支持 sqlx fetch() 游标， 覆盖此方法可获得真正的逐行拉取，避免大结果集内存峰值。

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

游标式流式查询（P1-2）：按 batch_size 分批拉取，避免大结果集内存峰值。

适用于无原生服务器端游标（或无法便捷暴露逐行拉取）的数据库：

• Oracle：ROWNUM 子查询包装（见 cursor_stream::build_paged_query）；
• SQL Server：OFFSET ... ROWS FETCH NEXT ... ROWS ONLY。

默认实现退化为 Connection::query_stream（全量拉取后逐行 yield）； Oracle/MSSQL 适配器应覆盖此方法，使用 cursor_stream::stream_cursor_paged(conn, sql, DbType::Oracle, batch) 获得真正的分页游标流。

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

impl Connection for MockConnection