Struct FraiseWireAdapter 

pub struct FraiseWireAdapter { /* private fields */ }

The wire backend, behind the same feature that gates it in fraiseql-db. FraiseQL-Wire database adapter.

Uses fraiseql-wire for streaming JSON queries with bounded memory usage. This adapter is optimized for read-heavy workloads with large result sets.

Streaming reads

This adapter inherits the trait’s buffering default for stream_with_projection, so its rows are correct but materialised — the same shape the collecting methods below already have. That is a deliberate non-implementation, not an oversight: the underlying QueryStream really does stream, and threading it through would be a small change, but no CI leg executes this adapter against a real database, so the result could not be proven — only compiled. See #1115.

Architecture

• Connection Factory: Creates fresh clients on demand
• Streaming: Results are streamed incrementally (O(chunk_size) memory)
• WHERE Translation: AST → SQL via WhereSqlGenerator

Example

use fraiseql_core::db::{FraiseWireAdapter, WhereClause, WhereOperator, DatabaseAdapter};
use serde_json::json;

// Create adapter
let adapter = FraiseWireAdapter::new("postgres://localhost/mydb");

// Build WHERE clause
let where_clause = WhereClause::Field {
    path: vec!["status".to_string()],
    operator: WhereOperator::Eq,
    value: json!("active"),
};

// Execute query
let results = adapter
    .execute_where_query("v_user", Some(&where_clause), Some(10), None, None)
    .await?;

println!("Found {} users", results.len());

Implementations

impl FraiseWireAdapter

pub fn new(connection_string: impl Into<String>) -> FraiseWireAdapter

Create a new FraiseWire adapter.

Arguments

• connection_string - PostgreSQL connection string

Example

use fraiseql_core::db::FraiseWireAdapter;

let adapter = FraiseWireAdapter::new("postgres://localhost/fraiseql");

pub const fn with_chunk_size(self, chunk_size: usize) -> FraiseWireAdapter

Set chunk size for streaming queries.

Larger chunk sizes increase throughput but use more memory. Smaller chunk sizes reduce memory usage but may decrease throughput.

Arguments

• chunk_size - Number of rows per chunk (default: 1024)

Example

use fraiseql_core::db::FraiseWireAdapter;

let adapter = FraiseWireAdapter::new("postgres://localhost/fraiseql")
    .with_chunk_size(512);

Trait Implementations

impl Clone for FraiseWireAdapter

fn clone(&self) -> FraiseWireAdapter

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl DatabaseAdapter for FraiseWireAdapter

fn execute_with_projection<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, view: &'life1 str, _projection: Option<&'life2 SqlProjectionHint>, where_clause: Option<&'life3 WhereClause>, limit: Option<u32>, offset: Option<u32>, order_by: Option<&'life4 [OrderByClause]>, ) -> Pin<Box<dyn Future<Output = Result<Vec<JsonbValue>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, FraiseWireAdapter: 'async_trait,

Errors

Returns FraiseQLError::Database if the wire connection or query execution fails.

fn execute_where_query<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, view: &'life1 str, where_clause: Option<&'life2 WhereClause>, limit: Option<u32>, offset: Option<u32>, order_by: Option<&'life3 [OrderByClause]>, ) -> Pin<Box<dyn Future<Output = Result<Vec<JsonbValue>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, FraiseWireAdapter: 'async_trait,

Errors

Returns FraiseQLError::Validation if SQL generation fails, or FraiseQLError::Database if the wire connection or query execution fails.

fn supports_composed_reads(&self) -> bool

Stated rather than inherited, with the reason: a composed read carries every embedded level’s RLS predicate in its WHERE, and this adapter binds no parameters — it escapes values into literal SQL. Composing here would run authorization predicates through string escaping; binding parameters comes first.

fn execute_raw_query<'life0, 'life1, 'async_trait>( &'life0 self, _sql: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<HashMap<String, Value>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, FraiseWireAdapter: 'async_trait,

Errors

Always returns FraiseQLError::Database — arbitrary SQL is not supported by fraiseql-wire; use Self::execute_where_query instead.

fn execute_parameterized_aggregate<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _sql: &'life1 str, _params: &'life2 [Value], ) -> Pin<Box<dyn Future<Output = Result<Vec<HashMap<String, Value>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, FraiseWireAdapter: 'async_trait,

Errors

Always returns FraiseQLError::Database — aggregate SQL is not supported by fraiseql-wire.

fn database_type(&self) -> DatabaseType

Get database type (for logging/metrics).

fn health_check<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, FraiseWireAdapter: 'async_trait,

Health check - verify database connectivity.

fn pool_metrics(&self) -> PoolMetrics

Get connection pool metrics.

fn query_stats<'life0, 'async_trait>( &'life0 self, _limit: u32, ) -> Pin<Box<dyn Future<Output = Result<Vec<QueryStatEntry>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, FraiseWireAdapter: 'async_trait,

Retrieve query performance statistics from the database.

fn query_stats_by_id<'life0, 'life1, 'async_trait>( &'life0 self, _id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<QueryStatEntry>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, FraiseWireAdapter: 'async_trait,

Retrieve statistics for a single query by its ID.

fn execute_where_query_arc<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, view: &'life1 str, where_clause: Option<&'life2 WhereClause>, limit: Option<u32>, offset: Option<u32>, order_by: Option<&'life3 [OrderByClause]>, ) -> Pin<Box<dyn Future<Output = Result<Arc<Vec<JsonbValue>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self: 'async_trait,

Like execute_where_query but returns the result wrapped in an Arc.

fn execute_with_projection_arc<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, request: &'life1 ProjectionRequest<'life2>, ) -> Pin<Box<dyn Future<Output = Result<Arc<Vec<JsonbValue>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Like execute_with_projection but returns the result wrapped in an Arc.

fn serves_reads_from_standbys(&self) -> bool

Whether reads may be served by a hot standby — read replicas are configured (#1390).

fn execute_row_query<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, view_name: &'life1 str, columns: &'life2 [ColumnSpec], where_sql: Option<&'life3 str>, order_by: Option<&'life4 str>, limit: Option<u32>, offset: Option<u32>, ) -> Pin<Box<dyn Future<Output = Result<Vec<Vec<ColumnValue>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, Self: 'async_trait,

Execute a row-shaped query against a view, returning typed column values.

fn execute_row_query_with_session<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'life6, 'life7, 'async_trait>( &'life0 self, view_name: &'life1 str, columns: &'life2 [ColumnSpec], where_sql: Option<&'life3 str>, order_by: Option<&'life4 str>, limit: Option<u32>, offset: Option<u32>, _session_vars: &'life5 [(&'life6 str, &'life7 str)], ) -> Pin<Box<dyn Future<Output = Result<Vec<Vec<ColumnValue>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, 'life6: 'async_trait, 'life7: 'async_trait, Self: 'async_trait,

Connection-affine variant of execute_row_query.

fn execute_parameterized_aggregate_with_session<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>( &'life0 self, sql: &'life1 str, params: &'life2 [Value], _session_vars: &'life3 [(&'life4 str, &'life5 str)], _routing: ReadRouting, ) -> Pin<Box<dyn Future<Output = Result<Vec<HashMap<String, Value>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, Self: 'async_trait,

Connection-affine variant of execute_parameterized_aggregate.

fn invalidate_views<'life0, 'life1, 'async_trait>( &'life0 self, _views: &'life1 [ViewName], ) -> Pin<Box<dyn Future<Output = Result<u64, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Invalidate cached query results for the specified views.

fn invalidate_by_entity<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _entity_type: &'life1 str, _entity_id: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<u64, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Evict cache entries that contain the given entity UUID.

fn result_cache_stats(&self) -> Option<ResultCacheStats>

A snapshot of this adapter’s query-result cache, or None if it has none.

fn clear_result_cache<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Option<usize>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Drop every entry in this adapter’s query-result cache.

fn explain_query<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _sql: &'life1 str, _params: &'life2 [Value], ) -> Pin<Box<dyn Future<Output = Result<Value, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Run the database’s EXPLAIN on a SQL statement without executing it.

fn explain_where_query<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _view: &'life1 str, _where_clause: Option<&'life2 WhereClause>, _limit: Option<u32>, _offset: Option<u32>, ) -> Pin<Box<dyn Future<Output = Result<Value, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Run EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) against a view with the same parameterized WHERE clause that execute_where_query would use.

fn execute_where_query_arc_with_session<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'life6, 'async_trait>( &'life0 self, view: &'life1 str, where_clause: Option<&'life2 WhereClause>, limit: Option<u32>, offset: Option<u32>, order_by: Option<&'life3 [OrderByClause]>, _session_vars: &'life4 [(&'life5 str, &'life6 str)], _routing: ReadRouting, ) -> Pin<Box<dyn Future<Output = Result<Arc<Vec<JsonbValue>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, 'life6: 'async_trait, Self: 'async_trait,

Connection-affine variant of execute_where_query_arc.

fn count_where_query<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>( &'life0 self, view: &'life1 str, where_clause: Option<&'life2 WhereClause>, session_vars: &'life3 [(&'life4 str, &'life5 str)], routing: ReadRouting, ) -> Pin<Box<dyn Future<Output = Result<u64, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, Self: 'async_trait,

Count the rows of view matching where_clause, without materialising them.

fn execute_with_projection_arc_with_session<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>( &'life0 self, request: &'life1 ProjectionRequest<'life2>, _session_vars: &'life3 [(&'life4 str, &'life5 str)], _routing: ReadRouting, ) -> Pin<Box<dyn Future<Output = Result<Arc<Vec<JsonbValue>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, Self: 'async_trait,

Connection-affine variant of execute_with_projection_arc.

fn stream_with_projection<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>( &'life0 self, request: &'life1 ProjectionRequest<'life2>, session_vars: &'life3 [(&'life4 str, &'life5 str)], routing: ReadRouting, ) -> Pin<Box<dyn Future<Output = Result<Pin<Box<dyn Stream<Item = Result<JsonbValue, FraiseQLError>> + Send>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, Self: 'async_trait,

The same read as execute_with_projection_arc_with_session, delivered row by row instead of as a materialised Vec (#958).

fn execute_composed_with_session<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, read: &'life1 ComposedLevel, _session_vars: &'life2 [(&'life3 str, &'life4 str)], _routing: ReadRouting, ) -> Pin<Box<dyn Future<Output = Result<Arc<Vec<JsonbValue>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, Self: 'async_trait,

Execute a read that composes its embedded levels into one statement.

fn stream_row_query<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, view_name: &'life1 str, columns: &'life2 [ColumnSpec], where_sql: Option<&'life3 str>, order_by: Option<&'life4 str>, limit: Option<u32>, offset: Option<u32>, ) -> Pin<Box<dyn Future<Output = Result<Pin<Box<dyn Stream<Item = Result<Vec<ColumnValue>, FraiseQLError>> + Send>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, Self: 'async_trait,

The same read as execute_row_query, delivered row by row (#958).

fn stream_row_query_with_session<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'life6, 'life7, 'async_trait>( &'life0 self, view_name: &'life1 str, columns: &'life2 [ColumnSpec], where_sql: Option<&'life3 str>, order_by: Option<&'life4 str>, limit: Option<u32>, offset: Option<u32>, _session_vars: &'life5 [(&'life6 str, &'life7 str)], ) -> Pin<Box<dyn Future<Output = Result<Pin<Box<dyn Stream<Item = Result<Vec<ColumnValue>, FraiseQLError>> + Send>>, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait, 'life6: 'async_trait, 'life7: 'async_trait, Self: 'async_trait,

Connection-affine variant of stream_row_query.

fn reset_query_stats<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Reset query performance statistics.

fn on_schema_reload(&self)

Notify the adapter that the schema has changed.

fn execute_admin_sql<'life0, 'life1, 'async_trait>( &'life0 self, _request: &'life1 AdminSqlRequest, ) -> Pin<Box<dyn Future<Output = Result<AdminSqlOutcome, FraiseQLError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Run one operator-supplied statement under the bounds in request (#962).

impl Debug for FraiseWireAdapter

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.