Struct PostgresAdapter 

pub struct PostgresAdapter { /* private fields */ }

PostgreSQL database adapter with connection pooling.

Uses deadpool-postgres for connection pooling and tokio-postgres for async queries.

Example

use fraiseql_db::postgres::PostgresAdapter;
use fraiseql_db::{DatabaseAdapter, WhereClause, WhereOperator};
use serde_json::json;

// Create adapter with connection string
let adapter = PostgresAdapter::new("postgresql://localhost/mydb").await?;

// Execute query
let where_clause = WhereClause::Field {
    path: vec!["email".to_string()],
    operator: WhereOperator::Icontains,
    value: json!("example.com"),
};

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

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

Implementations

impl PostgresAdapter

pub async fn new(connection_string: &str) -> Result<Self>

Create new PostgreSQL adapter with default pool configuration.

Arguments

• connection_string - PostgreSQL connection string (e.g., “postgresql://localhost/mydb”)

Errors

Returns FraiseQLError::ConnectionPool if pool creation fails.

Example

let adapter = PostgresAdapter::new("postgresql://localhost/mydb").await?;

pub async fn with_pool_config( connection_string: &str, _min_size: usize, max_size: usize, ) -> Result<Self>

Create new PostgreSQL adapter with custom pool configuration.

Arguments

• connection_string - PostgreSQL connection string
• min_size - Minimum size hint (not enforced by deadpool-postgres)
• max_size - Maximum number of connections in pool

Errors

Returns FraiseQLError::ConnectionPool if pool creation fails.

Note

min_size is accepted for API compatibility but deadpool-postgres uses lazy initialization with dynamic pool sizing up to max_size.

pub async fn with_pool_size( connection_string: &str, max_size: usize, ) -> Result<Self>

Create new PostgreSQL adapter with custom pool size.

Arguments

• connection_string - PostgreSQL connection string
• max_size - Maximum number of connections in pool

Errors

Returns FraiseQLError::ConnectionPool if pool creation fails.

pub const fn pool(&self) -> &Pool

Get a reference to the internal connection pool.

This allows sharing the pool with other components like PostgresIntrospector.

pub fn with_mutation_timing(self, variable_name: &str) -> Self

Enable mutation timing injection.

When enabled, execute_function_call wraps each mutation in a transaction and sets a session variable to clock_timestamp()::text before execution, allowing SQL functions to compute their own duration.

Arguments

• variable_name - The PostgreSQL session variable name (e.g., "fraiseql.started_at")

pub const fn mutation_timing_enabled(&self) -> bool

Returns whether mutation timing injection is enabled.

pub async fn execute_with_projection( &self, view: &str, projection: Option<&SqlProjectionHint>, where_clause: Option<&WhereClause>, limit: Option<u32>, offset: Option<u32>, ) -> Result<Vec<JsonbValue>>

Execute query with SQL field projection optimization.

Uses the provided SqlProjectionHint to generate optimized SQL that projects only the requested fields from the JSONB column, reducing network payload and JSON deserialization overhead.

Arguments

• view - View/table name to query
• projection - Optional SQL projection hint with field list
• where_clause - Optional WHERE clause for filtering
• limit - Optional row limit

Returns

Vector of projected JSONB rows with only the requested fields

Errors

Returns FraiseQLError::Database on query execution failure.

Panics

Cannot panic in practice: the inner expect is guarded by an is_none() check immediately above it.

Example

// Requires: running PostgreSQL database.
use fraiseql_db::postgres::PostgresAdapter;
use fraiseql_db::types::SqlProjectionHint;
use fraiseql_db::DatabaseType;

let projection = SqlProjectionHint {
    database: DatabaseType::PostgreSQL,
    projection_template: "jsonb_build_object('id', data->>'id')".to_string(),
    estimated_reduction_percent: 75,
};

let results = adapter
    .execute_with_projection("v_user", Some(&projection), None, Some(10), None)
    .await?;

Trait Implementations

impl Clone for PostgresAdapter

fn clone(&self) -> PostgresAdapter

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl DatabaseAdapter for PostgresAdapter

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

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

Security

sql must be compiler-generated. Never pass user-supplied strings directly — doing so would open SQL-injection vulnerabilities.

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>>> + Send + 'async_trait>>

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

Execute a WHERE query with SQL field projection optimization.

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>>> + Send + 'async_trait>>

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

Execute a WHERE query against a view and return JSONB rows.

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>> + Send + 'async_trait>>

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

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

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<()>> + Send + 'async_trait>>

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

Health check - verify database connectivity.

fn pool_metrics(&self) -> PoolMetrics

Get connection pool metrics.

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>>>> + Send + 'async_trait>>

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

Execute a parameterized aggregate SQL query (GROUP BY / HAVING / window).

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

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

Execute a database function call and return all columns as rows.

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

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

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

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>>>> + Send + 'async_trait>>

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

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

fn supports_mutations(&self) -> bool

Returns true if this adapter supports GraphQL mutation operations.

fn bump_fact_table_versions<'life0, 'life1, 'async_trait>( &'life0 self, _tables: &'life1 [String], ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Bump fact table version counters after a successful mutation.

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

where Self: 'async_trait, 'life0: 'async_trait, 'life1: '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>> + Send + 'async_trait>>

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

Evict cache entries that contain the given entity UUID.

fn capabilities(&self) -> DatabaseCapabilities

Get database capabilities.

fn mutation_strategy(&self) -> MutationStrategy

Returns the mutation strategy used by this adapter.

fn execute_direct_mutation<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _ctx: &'life1 DirectMutationContext<'life2>, ) -> Pin<Box<dyn Future<Output = Result<Vec<Value>>> + Send + 'async_trait>>

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

Execute a direct SQL mutation (INSERT/UPDATE/DELETE) and return the mutation response rows as JSON objects.

impl Debug for PostgresAdapter

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

Formats the value using the given formatter.

impl RelayDatabaseAdapter for PostgresAdapter

async fn execute_relay_page( &self, view: &str, cursor_column: &str, after: Option<CursorValue>, before: Option<CursorValue>, limit: u32, forward: bool, where_clause: Option<&WhereClause>, order_by: Option<&[OrderByClause]>, include_total_count: bool, ) -> Result<RelayPageResult>

Execute keyset (cursor-based) pagination against a JSONB view.

totalCount semantics

When include_total_count is true, two queries are issued on the same connection:

1. A count query — SELECT COUNT(*) FROM {view} WHERE {user_filter} — that reflects the full connection size, ignoring cursor position. This is required by the Relay Cursor Connections spec, which defines totalCount as the count of all objects in the connection, regardless of after/before.

2. A page query — the cursor-filtered, limited result set.

The two-query approach fixes a previous bug where COUNT(*) OVER() ran inside the cursor-filtered subquery, causing totalCount to shrink as the cursor advanced. It also handles the edge case where the current page is empty but the total count is non-zero (e.g., cursor past the last row).

When include_total_count is false, only the page query is issued.

Performance note

The count query scans all rows matching the user filter without LIMIT. On large unfiltered tables this may be slow. Mitigations:

• Only enable totalCount when the client explicitly requests it (enforced by the executor via include_total_count).
• Add a statement_timeout on the connection for relay queries on very large datasets.
• Maintain a denormalised count table or materialised view for hot paths.

impl SupportsMutations for PostgresAdapter