Trait Connection 

pub trait Connection: Send {
    // Required methods
    fn execute(&mut self, sql: &str) -> Result<ExecutionSummary, SqlError>;
    fn query(&mut self, sql: &str) -> Result<QueryResult, SqlError>;
    fn query_cursor(&mut self, sql: &str) -> Result<RowCursor<'_>, SqlError>;
    fn execute_multi(
        &mut self,
        sql: &str,
    ) -> Result<Vec<StatementResult>, SqlError>;
    fn ping(&mut self) -> Result<(), SqlError>;
    fn list_tables(
        &mut self,
        schema: Option<&str>,
    ) -> Result<Vec<String>, SqlError>;
    fn list_schemas(&mut self) -> Result<Vec<SchemaInfo>, SqlError>;
    fn describe_table(
        &mut self,
        schema: Option<&str>,
        table: &str,
    ) -> Result<QueryResult, SqlError>;
    fn primary_key(
        &mut self,
        schema: Option<&str>,
        table: &str,
    ) -> Result<Vec<String>, SqlError>;
    fn list_foreign_keys(
        &mut self,
        schema: Option<&str>,
    ) -> Result<Vec<ForeignKey>, SqlError>;
    fn bulk_insert_rows(
        &mut self,
        target: BulkInsert<'_>,
    ) -> Result<usize, SqlError>;

    // Provided methods
    fn size_guards(&self) -> SizeGuards { ... }
    fn set_size_guards(&mut self, guards: SizeGuards) { ... }
}

A synchronous, blocking database connection — ferrule-sql’s public connection API.

Every method blocks the calling thread until the database responds; there is no async fn / Future anywhere on this trait. Embedders that have no async runtime of their own (the motivating case: a single-threaded synchronous host) call these directly.

Runtime model. The async drivers (tokio-postgres, mysql_async, tiberius) are still used underneath, driven by a private current-thread tokio runtime that the concrete handle (crate::sync::SyncConnection) owns. That runtime is an implementation detail — it never surfaces in the public API. SQLite and Oracle are natively synchronous and call straight through.

Memory model. query buffers the full result set in memory (the Vec<Row> inside QueryResult) but is bounded by the connection’s SizeGuards: an oversized cell/row or a result past the total cap fails fast with a structured error instead of OOMing. For an unbounded result use query_cursor, which streams from a native database cursor at O(batch) memory and never buffers the whole result.

Reentrancy. Because the private runtime is current-thread, do not call these methods from inside another block_on on the same thread — that nests runtimes and panics. Async embedders must hop to a blocking thread (tokio::task::spawn_blocking or a dedicated OS thread) before using a Connection.

Required Methods

fn execute(&mut self, sql: &str) -> Result<ExecutionSummary, SqlError>

Execute a statement that may not return rows (INSERT, UPDATE, CREATE, etc.). Blocks until the statement completes.

fn query(&mut self, sql: &str) -> Result<QueryResult, SqlError>

Execute a SELECT-like query and return all rows. Blocks until the full result set is buffered in memory.

fn query_cursor(&mut self, sql: &str) -> Result<RowCursor<'_>, SqlError>

Open a streaming read cursor for sql, returning a RowCursor that pulls rows from a native database cursor at bounded memory.

Use this — not query — to ingest a large result under a fixed memory budget: the cursor never materializes the whole result, and it applies the connection’s per-cell / per-row SizeGuards as each row is decoded. The returned cursor borrows the connection for its lifetime (the async drivers’ row stream is tied to the connection handle), so the connection cannot be used for another statement until the cursor is dropped. Blocks on each batch; see RowCursor for the bounded-memory and reentrancy contract.

fn execute_multi(&mut self, sql: &str) -> Result<Vec<StatementResult>, SqlError>

Execute one or more statements, one result per statement. Backends that natively support multi-resultsets (Postgres, MSSQL) split the batch; others fall back to single-statement behavior. Blocks until the batch completes.

fn ping(&mut self) -> Result<(), SqlError>

Test connectivity (ping / SELECT 1). Blocks on a round-trip.

fn list_tables(&mut self, schema: Option<&str>) -> Result<Vec<String>, SqlError>

List tables in the given schema (or default schema if None).

fn list_schemas(&mut self) -> Result<Vec<SchemaInfo>, SqlError>

List the schemas / databases / owners visible on this connection, ordered by name. The entry whose is_default is set is the schema unqualified objects resolve against (PG current_schema(), MySQL DATABASE(), MSSQL SCHEMA_NAME(), Oracle USER, SQLite main). Blocks on a round-trip.

fn describe_table( &mut self, schema: Option<&str>, table: &str, ) -> Result<QueryResult, SqlError>

Describe the columns of a single table.

fn primary_key( &mut self, schema: Option<&str>, table: &str, ) -> Result<Vec<String>, SqlError>

Return the column names of table’s primary key, in key position order. Returns an empty Vec when the table has no declared PK. Must not infer a PK from unique indexes — only declared primary-key constraints.

fn list_foreign_keys( &mut self, schema: Option<&str>, ) -> Result<Vec<ForeignKey>, SqlError>

Return every foreign-key edge in schema (or the default schema if None). Used by schema-level copy to order tables — parents before children.

fn bulk_insert_rows( &mut self, target: BulkInsert<'_>, ) -> Result<usize, SqlError>

Insert target.rows into target.table using the backend’s native bulk loader. Returns the number of rows accepted, or SqlError::BulkUnavailable when the backend has no native loader so the caller can fall back to the generic INSERT path. Blocks until the whole batch has streamed to the server.

Provided Methods

fn size_guards(&self) -> SizeGuards

The size guards currently applied to this connection’s reads (per-cell, per-row, per-result byte caps). The default implementation reports SizeGuards::default; the concrete SyncConnection tracks the real configured value.

fn set_size_guards(&mut self, guards: SizeGuards)

Install new size guards for subsequent reads. Lets a host raise or lower the per-cell / per-row / per-result caps (e.g. the CLI wiring its [limits] config). The default implementation is a no-op for wrappers that hold no guard state; the concrete SyncConnection stores it.

Trait Implementations

impl Connection for Box<dyn Connection>

Forwarding impl so a boxed connection is itself a Connection.

Lets call sites pass &mut Box<dyn Connection> where a &mut dyn Connection is expected (the cross-backend copy path and the test helpers both hold owned Box<dyn Connection> handles). Each method simply delegates to the boxed value.

fn execute(&mut self, sql: &str) -> Result<ExecutionSummary, SqlError>

Execute a statement that may not return rows (INSERT, UPDATE, CREATE, etc.). Blocks until the statement completes.

fn query(&mut self, sql: &str) -> Result<QueryResult, SqlError>

Execute a SELECT-like query and return all rows. Blocks until the full result set is buffered in memory.

fn query_cursor(&mut self, sql: &str) -> Result<RowCursor<'_>, SqlError>

Open a streaming read cursor for sql, returning a RowCursor that pulls rows from a native database cursor at bounded memory.

fn size_guards(&self) -> SizeGuards

The size guards currently applied to this connection’s reads (per-cell, per-row, per-result byte caps). The default implementation reports SizeGuards::default; the concrete SyncConnection tracks the real configured value.

fn set_size_guards(&mut self, guards: SizeGuards)

Install new size guards for subsequent reads. Lets a host raise or lower the per-cell / per-row / per-result caps (e.g. the CLI wiring its [limits] config). The default implementation is a no-op for wrappers that hold no guard state; the concrete SyncConnection stores it.

fn execute_multi(&mut self, sql: &str) -> Result<Vec<StatementResult>, SqlError>

Execute one or more statements, one result per statement. Backends that natively support multi-resultsets (Postgres, MSSQL) split the batch; others fall back to single-statement behavior. Blocks until the batch completes.

fn ping(&mut self) -> Result<(), SqlError>

Test connectivity (ping / SELECT 1). Blocks on a round-trip.

fn list_tables(&mut self, schema: Option<&str>) -> Result<Vec<String>, SqlError>

List tables in the given schema (or default schema if None).

fn list_schemas(&mut self) -> Result<Vec<SchemaInfo>, SqlError>

List the schemas / databases / owners visible on this connection, ordered by name. The entry whose is_default is set is the schema unqualified objects resolve against (PG current_schema(), MySQL DATABASE(), MSSQL SCHEMA_NAME(), Oracle USER, SQLite main). Blocks on a round-trip.

fn describe_table( &mut self, schema: Option<&str>, table: &str, ) -> Result<QueryResult, SqlError>

Describe the columns of a single table.

fn primary_key( &mut self, schema: Option<&str>, table: &str, ) -> Result<Vec<String>, SqlError>

Return the column names of table’s primary key, in key position order. Returns an empty Vec when the table has no declared PK. Must not infer a PK from unique indexes — only declared primary-key constraints.

fn list_foreign_keys( &mut self, schema: Option<&str>, ) -> Result<Vec<ForeignKey>, SqlError>

Return every foreign-key edge in schema (or the default schema if None). Used by schema-level copy to order tables — parents before children.

fn bulk_insert_rows( &mut self, target: BulkInsert<'_>, ) -> Result<usize, SqlError>

Insert target.rows into target.table using the backend’s native bulk loader. Returns the number of rows accepted, or SqlError::BulkUnavailable when the backend has no native loader so the caller can fall back to the generic INSERT path. Blocks until the whole batch has streamed to the server.

Dyn Compatibility

This trait is dyn compatible.

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

Implementations on Foreign Types

impl Connection for Box<dyn Connection>

Forwarding impl so a boxed connection is itself a Connection.

Lets call sites pass &mut Box<dyn Connection> where a &mut dyn Connection is expected (the cross-backend copy path and the test helpers both hold owned Box<dyn Connection> handles). Each method simply delegates to the boxed value.

fn execute(&mut self, sql: &str) -> Result<ExecutionSummary, SqlError>

fn query(&mut self, sql: &str) -> Result<QueryResult, SqlError>

fn query_cursor(&mut self, sql: &str) -> Result<RowCursor<'_>, SqlError>

fn size_guards(&self) -> SizeGuards

fn set_size_guards(&mut self, guards: SizeGuards)

fn execute_multi(&mut self, sql: &str) -> Result<Vec<StatementResult>, SqlError>

fn ping(&mut self) -> Result<(), SqlError>

fn list_tables(&mut self, schema: Option<&str>) -> Result<Vec<String>, SqlError>

fn list_schemas(&mut self) -> Result<Vec<SchemaInfo>, SqlError>

fn describe_table( &mut self, schema: Option<&str>, table: &str, ) -> Result<QueryResult, SqlError>

fn primary_key( &mut self, schema: Option<&str>, table: &str, ) -> Result<Vec<String>, SqlError>

fn list_foreign_keys( &mut self, schema: Option<&str>, ) -> Result<Vec<ForeignKey>, SqlError>

fn bulk_insert_rows( &mut self, target: BulkInsert<'_>, ) -> Result<usize, SqlError>

Implementors

impl Connection for SyncConnection