fraiseql_db/traits/
relay.rs

1//! Relay cursor pagination trait.
2//!
3//! [`RelayDatabaseAdapter`] extends [`DatabaseAdapter`](super::DatabaseAdapter)
4//! with keyset-based pagination for Relay-style GraphQL connections.
5
6use std::future::Future;
7
8use fraiseql_error::Result;
9
10use super::{CursorValue, DatabaseAdapter, RelayPageResult};
11use crate::{types::sql_hints::OrderByClause, where_clause::WhereClause};
12
13/// Database adapter supertrait for adapters that implement Relay cursor pagination.
14///
15/// Only adapters that genuinely support keyset pagination need to implement this trait.
16/// Non-implementing adapters carry no relay code at all — no stubs, no flags.
17///
18/// # Implementors
19///
20/// - `PostgresAdapter` — full keyset pagination
21/// - `MySqlAdapter` — keyset pagination with `?` params
22/// - `CachedDatabaseAdapter<A>` — delegates to inner `A`
23///
24/// # Usage
25///
26/// Construct an `Executor` with `Executor::new_with_relay` to enable relay
27/// query execution. The bound `A: RelayDatabaseAdapter` is enforced at that call site.
28pub trait RelayDatabaseAdapter: DatabaseAdapter {
29    /// Execute keyset (cursor-based) pagination against a JSONB view.
30    ///
31    /// # Arguments
32    ///
33    /// * `view`                — SQL view name (will be quoted before use)
34    /// * `cursor_column`       — column used as the pagination key (e.g. `pk_user`, `id`)
35    /// * `after`               — forward cursor: return rows where `cursor_column > after`
36    /// * `before`              — backward cursor: return rows where `cursor_column < before`
37    /// * `limit`               — row fetch count (pass `page_size + 1` to detect `hasNextPage`)
38    /// * `forward`             — `true` → ASC order; `false` → DESC (re-sorted ASC via subquery)
39    /// * `where_clause`        — optional user-supplied filter applied after the cursor condition
40    /// * `order_by`            — optional custom sort; cursor column appended as tiebreaker
41    /// * `include_total_count` — when `true`, compute the matching row count before LIMIT
42    ///
43    /// # Errors
44    ///
45    /// Returns `FraiseQLError::Database` on SQL execution failure.
46    fn execute_relay_page<'a>(
47        &'a self,
48        view: &'a str,
49        cursor_column: &'a str,
50        after: Option<CursorValue>,
51        before: Option<CursorValue>,
52        limit: u32,
53        forward: bool,
54        where_clause: Option<&'a WhereClause>,
55        order_by: Option<&'a [OrderByClause]>,
56        include_total_count: bool,
57    ) -> impl Future<Output = Result<RelayPageResult>> + Send + 'a;
58
59    /// Connection-affine variant of [`execute_relay_page`](Self::execute_relay_page).
60    ///
61    /// Applies `session_vars` transaction-locally on the same connection that
62    /// runs the page (and total-count) queries, so RLS-protected relay
63    /// pagination over views reading `current_setting()` returns the correct
64    /// tenant's rows (fixes #329 for the cursor-pagination path).
65    ///
66    /// Adapters that do not support session variables inherit the default,
67    /// which drops `session_vars` and delegates to `execute_relay_page`.
68    ///
69    /// # Errors
70    ///
71    /// Same errors as [`execute_relay_page`](Self::execute_relay_page);
72    /// additionally returns `FraiseQLError::Database` if `set_config` fails.
73    #[allow(clippy::too_many_arguments)] // Reason: relay pagination requires all cursor/filter/sort/count arguments plus session vars; no natural grouping
74    fn execute_relay_page_with_session<'a>(
75        &'a self,
76        view: &'a str,
77        cursor_column: &'a str,
78        after: Option<CursorValue>,
79        before: Option<CursorValue>,
80        limit: u32,
81        forward: bool,
82        where_clause: Option<&'a WhereClause>,
83        order_by: Option<&'a [OrderByClause]>,
84        include_total_count: bool,
85        _session_vars: &'a [(&'a str, &'a str)],
86    ) -> impl Future<Output = Result<RelayPageResult>> + Send + 'a {
87        self.execute_relay_page(
88            view,
89            cursor_column,
90            after,
91            before,
92            limit,
93            forward,
94            where_clause,
95            order_by,
96            include_total_count,
97        )
98    }
99}
fraiseql_db/traits/relay.rs

fraiseql_db/traits/
relay.rs
