Trait DatabaseAdapter 

pub trait DatabaseAdapter: Send + Sync {
    // Required methods
    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;
    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;
    fn database_type(&self) -> DatabaseType;
    fn health_check<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn pool_metrics(&self) -> PoolMetrics;
    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;
    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;

    // Provided methods
    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>>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait { ... }
    fn execute_with_projection_arc<'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<Arc<Vec<JsonbValue>>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait,
             'life3: 'async_trait,
             'life4: 'async_trait { ... }
    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 { ... }
    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 { ... }
    fn supports_mutations(&self) -> bool { ... }
    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 { ... }
    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 { ... }
    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 { ... }
    fn invalidate_list_queries<'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 { ... }
    fn capabilities(&self) -> DatabaseCapabilities { ... }
    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 { ... }
    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 { ... }
    fn mutation_strategy(&self) -> MutationStrategy { ... }
    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 { ... }
}

Database adapter for executing queries against views.

This trait abstracts over different database backends (PostgreSQL, MySQL, SQLite, SQL Server). All implementations must support:

• Executing parameterized WHERE queries against views
• Returning JSONB data from the data column
• Connection pooling and health checks
• Row-level security (RLS) WHERE clauses

Architecture

The adapter is the runtime interface to the database. It receives:

• View/table name (e.g., “v_user”, “tf_sales”)
• Parameterized WHERE clauses (AST form, not strings)
• Projection hints (for performance optimization)
• Pagination parameters (LIMIT/OFFSET)

And returns:

• JSONB rows from the data column (most operations)
• Arbitrary rows as HashMap (for aggregation queries)
• Mutation results from stored procedures

Implementing a New Adapter

To add support for a new database (e.g., Oracle, Snowflake):

1. Create a new module in src/db/your_database/

2. Implement the trait:

   pub struct YourDatabaseAdapter { /* fields */ }
   
   #[async_trait]
   impl DatabaseAdapter for YourDatabaseAdapter {
       async fn execute_where_query(&self, ...) -> Result<Vec<JsonbValue>> {
           // 1. Build parameterized SQL from WhereClause AST
           // 2. Execute with bound parameters (NO string concatenation)
           // 3. Return JSONB from data column
       }
       // Implement other required methods...
   }

3. Add feature flag to Cargo.toml (e.g., feature = "your-database")

4. Copy structure from PostgreSQL adapter — see src/db/postgres/adapter.rs

5. Add tests in tests/integration/your_database_test.rs

Security Requirements

All implementations MUST:

• Never concatenate user input into SQL strings
• Always use parameterized queries with bind parameters
• Validate parameter types before binding
• Preserve RLS WHERE clauses (never filter them out)
• Return errors, not silently fail (e.g., connection loss)

Connection Management

• Use a connection pool (recommended: 20 connections default)
• Implement health_check() for ping-based monitoring
• Provide pool_metrics() for observability
• Handle stale connections gracefully

Performance Characteristics

Expected throughput when properly implemented:

• Simple queries (single table, no WHERE): 250+ Kelem/s
• Complex queries (JOINs, multiple conditions): 50+ Kelem/s
• Mutations (stored procedures): 1-10 RPS (depends on procedure)
• Relay pagination (keyset cursors): 15-30ms latency

Example: PostgreSQL Implementation

use sqlx::postgres::PgPool;
use async_trait::async_trait;

pub struct PostgresAdapter {
    pool: PgPool,
}

#[async_trait]
impl DatabaseAdapter for PostgresAdapter {
    async fn execute_where_query(
        &self,
        view: &str,
        where_clause: Option<&WhereClause>,
        limit: Option<u32>,
        offset: Option<u32>,
    ) -> Result<Vec<JsonbValue>> {
        // 1. Build SQL: SELECT data FROM {view} WHERE {where_clause} LIMIT {limit}
        let mut sql = format!(r#"SELECT data FROM "{}""#, view);

        // 2. Add WHERE clause (converts AST to parameterized SQL)
        let params = if let Some(where_clause) = where_clause {
            sql.push_str(" WHERE ");
            let (where_sql, params) = build_where_sql(where_clause)?;
            sql.push_str(&where_sql);
            params
        } else {
            vec![]
        };

        // 3. Add LIMIT and OFFSET
        if let Some(limit) = limit {
            sql.push_str(" LIMIT ");
            sql.push_str(&limit.to_string());
        }
        if let Some(offset) = offset {
            sql.push_str(" OFFSET ");
            sql.push_str(&offset.to_string());
        }

        // 4. Execute with bound parameters (NO string interpolation)
        let rows: Vec<(serde_json::Value,)> = sqlx::query_as(&sql)
            .bind(&params[0])
            .bind(&params[1])
            // ... bind all parameters
            .fetch_all(&self.pool)
            .await?;

        // 5. Extract JSONB and return
        Ok(rows.into_iter().map(|(data,)| data).collect())
    }

    // Implement other required methods...
}

Example: Basic Usage

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

// Build WHERE clause (AST, not string)
let where_clause = WhereClause::Field {
    path: vec!["email".to_string()],
    operator: WhereOperator::Icontains,
    value: json!("example.com"),
};

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

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

See Also

• WhereClause — AST for parameterized WHERE clauses
• RelayDatabaseAdapter — Optional trait for keyset pagination
• DatabaseCapabilities — Feature detection for the adapter
• Performance Guide

Required Methods

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.

Arguments

• view - View name (e.g., “v_user”, “v_post”)
• where_clause - Optional WHERE clause AST
• limit - Optional row limit (for pagination)
• offset - Optional row offset (for pagination)

Returns

Vec of JSONB values from the data column.

Errors

Returns FraiseQLError::Database on query execution failure. Returns FraiseQLError::ConnectionPool if connection pool is exhausted.

Example

// Simple query without WHERE clause
let all_users = adapter
    .execute_where_query("v_user", None, Some(10), Some(0), None)
    .await?;

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.

Projects only the requested fields at the database level, reducing network payload and JSON deserialization overhead by 40-55% based on production measurements.

This is the primary query execution method for optimized GraphQL queries. It automatically selects only the fields requested in the GraphQL query, avoiding unnecessary network transfer and deserialization of unused fields.

Automatic Projection

In most cases, you don’t call this directly. The Executor automatically:

1. Determines which fields the GraphQL query requests
2. Generates a SqlProjectionHint using database-specific SQL
3. Calls this method with the projection hint

Arguments

• view - View name (e.g., “v_user”, “v_post”)
• projection - Optional SQL projection hint with field list
  • Some(hint): Use projection to select only requested fields
  • None: Falls back to standard query (full JSONB column)
• where_clause - Optional WHERE clause AST for filtering
• limit - Optional row limit (for pagination)

Returns

Vec of JSONB values, either:

• Full objects (when projection is None)
• Projected objects with only requested fields (when projection is Some)

Errors

Returns FraiseQLError::Database on query execution failure, including:

• Connection pool exhaustion
• SQL execution errors
• Type mismatches

Performance Characteristics

When projection is provided (recommended):

• Latency: 40-55% reduction vs full object fetch
• Network: 40-55% smaller payload (proportional to unused fields)
• Throughput: Maintains 250+ Kelem/s (elements per second)
• Memory: Proportional to projected fields only

Improvement scales with:

• Percentage of unused fields (more unused = more improvement)
• Size of result set (larger sets benefit more)
• Network latency (network-bound queries benefit most)

When projection is None:

• Behavior identical to execute_where_query()
• Returns full JSONB column
• Used for compatibility/debugging

Database Support

Database	Status	Implementation
PostgreSQL	✅ Optimized	jsonb_build_object()
MySQL	⏳ Fallback	Server-side filtering (planned)
SQLite	⏳ Fallback	Server-side filtering (planned)
SQL Server	⏳ Fallback	Server-side filtering (planned)

Example: Direct Usage (Advanced)

// Requires: running PostgreSQL database and a DatabaseAdapter implementation.
use fraiseql_db::types::SqlProjectionHint;
use fraiseql_db::traits::DatabaseAdapter;
use fraiseql_db::DatabaseType;

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

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

// results only contain id, name, email fields
// 75% smaller than fetching all fields

Example: Fallback (No Projection)

// Requires: running PostgreSQL database and a DatabaseAdapter implementation.
// For debugging or when projection not available
let results = adapter
    .execute_with_projection("v_user", None, None, Some(100), None, None)
    .await?;

// Equivalent to execute_where_query() - returns full objects

See Also

• execute_where_query() - Standard query without projection
• SqlProjectionHint - Structure defining field projection
• Projection Optimization Guide

fn database_type(&self) -> DatabaseType

Get database type (for logging/metrics).

Used to identify which database backend is in use.

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.

Executes a simple query (e.g., SELECT 1) to verify the database is reachable.

Errors

Returns FraiseQLError::Database if health check fails.

fn pool_metrics(&self) -> PoolMetrics

Get connection pool metrics.

Returns current statistics about the connection pool:

• Total connections
• Idle connections
• Active connections
• Waiting requests

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,

Execute raw SQL query and return rows as JSON objects.

Used for aggregation queries where we need full row data, not just JSONB column.

Security Warning

This method executes arbitrary SQL. NEVER pass untrusted input directly to this method. Always:

• Use parameterized queries with bound parameters
• Validate and sanitize SQL templates before execution
• Only execute SQL generated by the FraiseQL compiler
• Log SQL execution for audit trails

Arguments

• sql - Raw SQL query to execute (must be safe/trusted)

Returns

Vec of rows, where each row is a HashMap of column name to JSON value.

Errors

Returns FraiseQLError::Database on query execution failure.

Example

// Safe: SQL generated by FraiseQL compiler
let sql = "SELECT category, SUM(revenue) as total FROM tf_sales GROUP BY category";
let rows = adapter.execute_raw_query(sql).await?;
for row in rows {
    println!("Category: {}, Total: {}", row["category"], row["total"]);
}

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).

sql contains $N (PostgreSQL), ? (MySQL / SQLite), or @P1 (SQL Server) placeholders for string and array values; numeric and NULL values may be inlined. params are the corresponding values in placeholder order.

Unlike execute_raw_query, this method accepts bind parameters so that user-supplied filter values never appear as string literals in the SQL text, eliminating the injection risk that escape_sql_string mitigated previously.

Arguments

• sql - SQL with placeholders generated by AggregationSqlGenerator::generate_parameterized
• params - Bind parameters in placeholder order

Returns

Vec of rows, where each row is a HashMap of column name to JSON value.

Errors

Returns FraiseQLError::Database on execution failure. Returns FraiseQLError::Database on adapters that do not support raw SQL (e.g., FraiseWireAdapter).

Provided Methods

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

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

Like execute_where_query but returns the result wrapped in an Arc.

The default implementation wraps the result of execute_where_query in a fresh Arc. CachedDatabaseAdapter overrides this to return the cached Arc directly — eliminating the full Vec<JsonbValue> clone that the non-Arc path requires on every cache hit.

Callers on the hot query path should prefer this variant and borrow from the Arc via &**arc rather than taking ownership.

Errors

Same errors as execute_where_query.

fn execute_with_projection_arc<'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<Arc<Vec<JsonbValue>>>> + Send + 'async_trait>>

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

Like execute_with_projection but returns the result wrapped in an Arc.

The default implementation wraps the result of execute_with_projection in a fresh Arc. CachedDatabaseAdapter overrides this to return the cached Arc directly — eliminating the full Vec<JsonbValue> clone that the non-Arc path requires on every cache hit.

Errors

Same errors as execute_with_projection.

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.

Used by the gRPC transport for protobuf encoding of query results. The default implementation delegates to execute_raw_query and converts JSON results to ColumnValue vectors.

Errors

Returns FraiseQLError::Database if the adapter returns an error.

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.

Builds SELECT * FROM {function_name}($1, $2, ...) with one positional placeholder per argument, executes it with the provided JSON values, and returns each result row as a HashMap<column_name, json_value>.

Used by the mutation execution pathway to call stored procedures that return the app.mutation_response composite type (status, message, entity_id, entity_type, entity jsonb, updated_fields text[], cascade jsonb, metadata jsonb).

Arguments

• function_name - Fully-qualified function name (e.g. fn_create_machine)
• args - Positional JSON arguments passed as $1, $2, … bind parameters

Errors

Returns FraiseQLError::Database on query execution failure. Returns FraiseQLError::Unsupported on adapters that do not support mutations (default implementation — see SupportsMutations).

fn supports_mutations(&self) -> bool

Returns true if this adapter supports GraphQL mutation operations.

This is the authoritative mutation gate. The executor checks this method before dispatching any mutation. Adapters that return false will cause mutations to fail with a clear FraiseQLError::Validation diagnostic instead of silently calling the unsupported execute_function_call default.

Override to return false for read-only adapters (e.g., SqliteAdapter, FraiseWireAdapter). The compile-time SupportsMutations marker trait complements this runtime check — see its documentation for the distinction.

Default

Returns true. All adapters are assumed mutation-capable unless they override this method.

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.

Called by the executor when a mutation definition declares invalidates_fact_tables. For each listed table the version counter is incremented so that subsequent aggregation queries miss the cache and re-fetch fresh data.

The default implementation is a no-op: adapters that are not cache- aware (e.g. PostgresAdapter, SqliteAdapter) simply return Ok(()). CachedDatabaseAdapter overrides this to call bump_tf_version($1) for every FactTableVersionStrategy::VersionTable table and update the in-process version cache.

Arguments

• tables - Fact table names declared by the mutation (validated SQL identifiers; originate from MutationDefinition.invalidates_fact_tables)

Errors

Returns FraiseQLError::Database if the version-bump SQL function fails.

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.

Called by the executor after a mutation succeeds, so that stale cache entries reading from modified views are evicted. The default implementation is a no-op; CachedDatabaseAdapter overrides this.

Returns

The number of cache entries evicted.

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.

Called by the executor after a successful UPDATE or DELETE mutation when the mutation_response includes an entity_id. Only cache entries whose entity-ID index contains the given UUID are removed; unrelated entries remain warm.

The default implementation is a no-op. CachedDatabaseAdapter overrides this to perform the selective eviction.

Returns

The number of cache entries evicted.

fn invalidate_list_queries<'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,

Evict only list (multi-row) cache entries for the given views.

Called by the executor after a successful CREATE mutation. Unlike invalidate_views(), this preserves single-entity point-lookup entries that are unaffected by the newly created entity.

The default implementation delegates to invalidate_views() (safe fallback for adapters without a list_index). CachedDatabaseAdapter overrides this to use the dedicated list_index for precise eviction.

Returns

The number of cache entries evicted.

fn capabilities(&self) -> DatabaseCapabilities

Get database capabilities.

Returns information about what features this database supports, including collation strategies and limitations.

Returns

DatabaseCapabilities describing supported features.

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.

Returns a JSON representation of the query plan. The format is database-specific (e.g. PostgreSQL returns JSON, SQLite returns rows).

The default implementation returns Unsupported.

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.

Unlike explain_query, this method uses real bound parameters and actually executes the query (ANALYZE mode), so the plan reflects PostgreSQL’s runtime statistics for the given filter values.

Only PostgreSQL supports this; other adapters return FraiseQLError::Unsupported by default.

Arguments

• view - View name (e.g., “v_user”)
• where_clause - Optional filter (same as execute_where_query)
• limit - Optional row limit
• offset - Optional row offset

Errors

Returns FraiseQLError::Database on execution failure. Returns FraiseQLError::Unsupported for non-PostgreSQL adapters.

fn mutation_strategy(&self) -> MutationStrategy

Returns the mutation strategy used by this adapter.

The default is FunctionCall (stored procedures). Adapters that generate direct SQL (e.g., SQLite) override this to return DirectSql.

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.

Only adapters using MutationStrategy::DirectSql need to override this. The default implementation returns Unsupported.

Errors

Returns FraiseQLError::Unsupported by default. Returns FraiseQLError::Database on SQL execution failure. Returns FraiseQLError::Validation on invalid mutation parameters.

Implementors

impl DatabaseAdapter for PostgresAdapter