use std::{fmt::Write as _, sync::Arc};
use async_trait::async_trait;
use bytes::BufMut as _;
use fraiseql_error::{FraiseQLError, Result};
use tokio_postgres::{
Row,
types::{FromSql, Kind, Type},
};
use super::{
PostgresAdapter, build_projection_select_sql, build_where_select_sql,
build_where_select_sql_ordered, composed::build_composed_select_sql, jsonb_cell,
numeric::PgNumericText,
};
use crate::{
identifier::quote_postgres_identifier,
postgres::pg_detail,
traits::{
ColumnRowStream, ComposedLevel, DatabaseAdapter, JsonbRowStream, ProjectionRequest, Writer,
},
types::{
DatabaseType, JsonbValue, PoolMetrics, ReadRouting,
sql_hints::{OrderByClause, SqlProjectionHint},
},
where_clause::WhereClause,
};
type RowMap = std::collections::HashMap<String, serde_json::Value>;
struct PreparedCall<'r> {
function_name: &'r str,
sql: String,
args: Vec<FlexParam>,
configuration: Vec<(&'r str, &'r str)>,
mechanism: &'static str,
derived: Option<&'r crate::traits::DerivedCascade<'r>>,
report_changes: Option<i32>,
}
impl<'r> PreparedCall<'r> {
fn new(adapter: &'r PostgresAdapter, request: &crate::traits::WriteRequest<'r>) -> Self {
let crate::traits::WriteRequest {
function: function_name,
args,
session_vars,
changelog,
derived_cascade,
report_changes,
..
} = *request;
let quoted_fn = quote_postgres_identifier(function_name);
let sql = if let Some(cl) = changelog {
build_changelog_cte_sql("ed_fn, args.len(), cl.pre_image)
} else {
let placeholders: Vec<String> = (1..=args.len()).map(|i| format!("${i}")).collect();
format!("SELECT * FROM {quoted_fn}({})", placeholders.join(", "))
};
let mut flex_args: Vec<FlexParam> = args
.iter()
.map(|v| match v {
serde_json::Value::Null => FlexParam::Null,
value => FlexParam::Value(value.clone()),
})
.collect();
if let Some(changelog) = changelog {
flex_args.push(FlexParam::Text(changelog.object_type.to_string()));
flex_args.push(FlexParam::Text(changelog.modification_type.to_string()));
flex_args.push(
changelog.tenant_id.map_or(FlexParam::Null, |t| FlexParam::Text(t.to_string())),
);
flex_args.push(
changelog.trace_id.map_or(FlexParam::Null, |t| FlexParam::Text(t.to_string())),
);
flex_args.push(
changelog
.schema_version
.map_or(FlexParam::Null, |s| FlexParam::Text(s.to_string())),
);
flex_args.push(
changelog
.trace_context
.map_or(FlexParam::Null, |s| FlexParam::Text(s.to_string())),
);
flex_args.push(
changelog.actor_type.map_or(FlexParam::Null, |s| FlexParam::Text(s.to_string())),
);
flex_args.push(
changelog.acting_for.map_or(FlexParam::Null, |u| FlexParam::Text(u.to_string())),
);
flex_args.push(
changelog.transport.map_or(FlexParam::Null, |s| FlexParam::Text(s.to_string())),
);
}
let mut configuration: Vec<(&str, &str)> = Vec::with_capacity(session_vars.len() + 3);
configuration.extend_from_slice(session_vars);
configuration.push((crate::changelog::CDC_MEDIATED_VAR, crate::changelog::CDC_MEDIATED_ON));
if adapter.mutation_timing_enabled {
configuration.push((
adapter.timing_variable_name.as_str(),
crate::changelog::CLOCK_TIMESTAMP_DIRECTIVE,
));
}
if changelog.is_some()
&& !configuration.iter().any(|(name, _)| *name == crate::changelog::STARTED_AT_VAR)
{
configuration.push((
crate::changelog::STARTED_AT_VAR,
crate::changelog::CLOCK_TIMESTAMP_DIRECTIVE,
));
}
Self {
function_name,
sql,
args: flex_args,
configuration,
mechanism: if changelog.is_some() {
" (with change-log outbox)"
} else {
""
},
derived: derived_cascade,
report_changes: report_changes.filter(|_| derived_cascade.is_none()),
}
}
fn params(&self) -> Vec<&(dyn tokio_postgres::types::ToSql + Sync)> {
self.args
.iter()
.map(|v| v as &(dyn tokio_postgres::types::ToSql + Sync))
.collect()
}
fn configuration_failed(&self, e: &tokio_postgres::Error) -> FraiseQLError {
let names: Vec<&str> = self.configuration.iter().map(|(name, _)| *name).collect();
crate::postgres::database_error(
format!("set_config({names:?}) failed: {}", pg_detail(e)),
e,
)
}
fn call_failed(&self, e: &tokio_postgres::Error) -> FraiseQLError {
crate::postgres::database_error(
format!(
"Function call {}{} failed: {}",
self.function_name,
self.mechanism,
pg_detail(e)
),
e,
)
}
}
async fn run_functions_in_txn(
adapter: &PostgresAdapter,
requests: &[crate::traits::WriteRequest<'_>],
gate: crate::traits::BatchRowGate<'_>,
numbered: bool,
) -> Result<Vec<Vec<RowMap>>> {
let Some(mode) = requests.first().map(|request| request.mode) else {
return Ok(Vec::new());
};
if requests.iter().any(|request| request.mode != mode) {
return Err(FraiseQLError::Validation {
message: "a batch of writes commits all of its calls or none: they must share one \
write mode"
.to_string(),
path: None,
});
}
let count = requests.len();
let at = |index: usize, error: FraiseQLError| {
if numbered {
error.in_batch_item(index, count)
} else {
error
}
};
let commit = matches!(mode, crate::traits::WriteMode::Commit);
if commit {
adapter.mark_write();
}
let calls: Vec<PreparedCall<'_>> =
requests.iter().map(|request| PreparedCall::new(adapter, request)).collect();
let configurations: Vec<_> =
calls.iter().map(|call| set_config_batch(&call.configuration)).collect();
let mut client = adapter.acquire_connection_with_retry().await?;
let mut statements = Vec::with_capacity(count);
for (index, (call, (configure_sql, _))) in calls.iter().zip(&configurations).enumerate() {
let stmt = prepare_cached_stmt(&client, call.sql.as_str())
.await
.map_err(|e| at(index, e))?;
let configure = client
.prepare_cached(configure_sql)
.await
.map_err(|e| at(index, call.configuration_failed(&e)))?;
let report = match call.report_changes {
Some(_) => Some(
client
.prepare_cached(CHANGED_ROWS_SQL)
.await
.map_err(|e| at(index, changes_report_failed(&e)))?,
),
None => None,
};
statements.push((stmt, configure, report));
}
let mechanism = calls
.iter()
.find(|call| !call.mechanism.is_empty())
.map_or("", |call| call.mechanism);
let txn = client.build_transaction().start().await.map_err(|e| {
crate::postgres::database_error(
format!("Failed to start mutation{mechanism} transaction: {}", pg_detail(&e)),
&e,
)
})?;
let flight = |index: usize| {
let (call, (stmt, configure, report)) = (&calls[index], &statements[index]);
let configure_params = &configurations[index].1;
let txn = &txn;
async move {
let params = call.params();
let max_entities = call.report_changes.unwrap_or_default();
futures::join!(
txn.execute(configure, configure_params),
txn.query(stmt, params.as_slice()),
async {
match report {
Some(report) => Some(txn.query_one(report, &[&max_entities]).await),
None => None,
}
}
)
}
};
let settle = |index: usize,
(configured, called, reported): (
std::result::Result<u64, tokio_postgres::Error>,
std::result::Result<Vec<Row>, tokio_postgres::Error>,
Option<std::result::Result<Row, tokio_postgres::Error>>,
)| {
let call = &calls[index];
let txn = &txn;
async move {
configured.map_err(|e| call.configuration_failed(&e))?;
let rows = called.map_err(|e| call.call_failed(&e))?;
let mut results: Vec<RowMap> = rows.iter().map(row_to_map).collect();
if let Some(reported) = reported {
let report: serde_json::Value =
reported.map_err(|e| changes_report_failed(&e))?.get("report");
if let Some(first) = results.first_mut() {
first.insert(crate::traits::CHANGED_ROWS_KEY.to_string(), report);
}
}
if let Some(derived) = call.derived {
if let Some(first) = results.first_mut() {
if first.get("succeeded").and_then(serde_json::Value::as_bool) == Some(true) {
let report = derived_cascade_report(txn, derived).await?;
first.insert(crate::traits::DERIVED_CASCADE_KEY.to_string(), report);
}
}
}
Ok::<_, FraiseQLError>(results)
}
};
let answers: Vec<Option<_>> = if calls.iter().all(|call| call.derived.is_none()) {
in_order((0..count).map(flight).collect()).await.into_iter().map(Some).collect()
} else {
std::iter::repeat_with(|| None).take(count).collect()
};
let mut results = Vec::with_capacity(count);
for (index, answer) in answers.into_iter().enumerate() {
let answer = match answer {
Some(answer) => answer,
None => flight(index).await,
};
let rows = settle(index, answer).await.map_err(|e| at(index, e))?;
if let Err(refusal) = gate(index, &rows) {
txn.rollback().await.map_err(|e| {
crate::postgres::database_error(
format!("Failed to roll back refused mutation transaction: {}", pg_detail(&e)),
&e,
)
})?;
return Err(refusal);
}
results.push(rows);
}
if !commit {
txn.rollback().await.map_err(|e| {
crate::postgres::database_error(
format!("Failed to roll back dry-run transaction: {}", pg_detail(&e)),
&e,
)
})?;
return Ok(results);
}
txn.commit().await.map_err(|e| {
crate::postgres::database_error(
format!("Failed to commit mutation{mechanism} transaction: {}", pg_detail(&e)),
&e,
)
})?;
adapter.mark_write();
Ok(results)
}
async fn in_order<F: std::future::Future>(futures: Vec<F>) -> Vec<F::Output> {
let mut pending: Vec<_> =
futures.into_iter().map(|f| Box::pin(futures::future::maybe_done(f))).collect();
std::future::poll_fn(|cx| {
let mut done = true;
for future in &mut pending {
done &= std::future::Future::poll(future.as_mut(), cx).is_ready();
}
if done {
std::task::Poll::Ready(())
} else {
std::task::Poll::Pending
}
})
.await;
pending.iter_mut().filter_map(|future| future.as_mut().take_output()).collect()
}
const CHANGED_ROWS_SQL: &str =
"SELECT tviews.pg_tviews_flush_and_report($1, false, true) AS report";
fn changes_report_failed(e: &tokio_postgres::Error) -> FraiseQLError {
crate::postgres::database_error(
format!(
"tviews.pg_tviews_flush_and_report() failed, asked for the rows this write changed \
to evict the cached reads of exactly those (is pg_tviews installed and \
preloaded?): {}",
pg_detail(e)
),
e,
)
}
async fn derived_cascade_report(
txn: &deadpool_postgres::Transaction<'_>,
derived: &crate::traits::DerivedCascade<'_>,
) -> Result<serde_json::Value> {
let report_failed = |e: &tokio_postgres::Error| {
crate::postgres::database_error(
format!(
"cascade_source = \"pg_tviews\": tviews.pg_tviews_flush_and_report() \
failed (is pg_tviews installed and preloaded?): {}",
pg_detail(e)
),
e,
)
};
let flush = txn
.prepare_cached(
"SELECT tviews.pg_tviews_flush_and_report($1, false, true) AS report, \
to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.US\"Z\"') AS at",
)
.await
.map_err(|e| report_failed(&e))?;
let row = txn
.query_one(&flush, &[&derived.max_entities])
.await
.map_err(|e| report_failed(&e))?;
let mut report: serde_json::Value = row.get("report");
let at: String = row.get("at");
let reported_id = |entry: &serde_json::Value| match &entry["id"] {
serde_json::Value::String(s) => s.clone(),
other => other.to_string(),
};
if let Some(updated) = report.get_mut("updated").and_then(serde_json::Value::as_array_mut) {
let mut ids_by_view: Vec<(&str, &str, Vec<FlexParam>)> = Vec::new();
for entry in updated.iter() {
let typename = entry["__typename"].as_str().unwrap_or_default();
let Some((name, view)) = derived.views.iter().find(|(name, _)| *name == typename)
else {
continue;
};
let id = FlexParam::Text(reported_id(entry));
match ids_by_view.iter_mut().find(|(n, ..)| n == name) {
Some((.., ids)) => ids.push(id),
None => ids_by_view.push((name, view, vec![id])),
}
}
let reads = ids_by_view.iter().map(|(typename, view, ids)| async move {
let read_failed = |e: &tokio_postgres::Error| {
crate::postgres::database_error(
format!(
"cascade_source = \"pg_tviews\": reading {typename} from {view} \
failed: {}",
pg_detail(e)
),
e,
)
};
let sql = format!(
"SELECT id::text AS id, data FROM {} WHERE id = ANY($1)",
quote_postgres_identifier(view)
);
let statement = txn.prepare_cached(&sql).await.map_err(|e| read_failed(&e))?;
let rows = txn.query(&statement, &[ids]).await.map_err(|e| read_failed(&e))?;
let by_id: std::collections::HashMap<String, serde_json::Value> =
rows.iter().map(|r| (r.get("id"), r.get("data"))).collect();
Ok::<_, FraiseQLError>((*typename, by_id))
});
let read: Vec<(&str, std::collections::HashMap<String, serde_json::Value>)> =
futures::future::try_join_all(reads).await?;
for entry in updated.iter_mut() {
let typename = entry["__typename"].as_str().unwrap_or_default();
let entity = read
.iter()
.find(|(name, _)| *name == typename)
.and_then(|(_, by_id)| by_id.get(&reported_id(entry)))
.cloned()
.unwrap_or(serde_json::Value::Null);
entry["entity"] = entity;
}
}
if let Some(deleted) = report.get_mut("deleted").and_then(serde_json::Value::as_array_mut) {
for entry in deleted.iter_mut() {
entry["deletedAt"] = serde_json::Value::String(at.clone());
}
}
Ok(report)
}
const PG_UNDEFINED_COLUMN: &str = "42703";
#[derive(Debug)]
enum FlexParam {
Null,
Text(String),
Value(serde_json::Value),
}
fn aggregate_params(params: &[serde_json::Value]) -> Vec<FlexParam> {
bound_values(params)
}
fn bound_values(values: &[serde_json::Value]) -> Vec<FlexParam> {
values
.iter()
.map(|v| match v {
serde_json::Value::Null => FlexParam::Null,
value => FlexParam::Value(value.clone()),
})
.collect()
}
fn write_text(
text: &str,
ty: &tokio_postgres::types::Type,
out: &mut bytes::BytesMut,
) -> std::result::Result<(), Box<dyn std::error::Error + Sync + Send>> {
use tokio_postgres::types::Type;
if *ty == Type::JSONB {
out.put_u8(1);
out.extend_from_slice(text.as_bytes());
} else if *ty == Type::UUID {
let uuid = uuid::Uuid::parse_str(text)?;
out.extend_from_slice(uuid.as_bytes());
} else if *ty == Type::INT4 {
let n: i32 = text.parse()?;
out.put_i32(n);
} else if *ty == Type::INT8 {
let n: i64 = text.parse()?;
out.put_i64(n);
} else if *ty == Type::BOOL {
let b: bool = text.parse()?;
out.put_u8(u8::from(b));
} else {
out.extend_from_slice(text.as_bytes());
}
Ok(())
}
fn write_array_literal(items: &[serde_json::Value], json_elements: bool, out: &mut String) {
out.push('{');
for (i, item) in items.iter().enumerate() {
if i > 0 {
out.push(',');
}
match item {
serde_json::Value::Null => out.push_str("NULL"),
serde_json::Value::Array(inner) if !json_elements => {
write_array_literal(inner, json_elements, out);
},
serde_json::Value::String(s) if !json_elements => quote_array_item(s, out),
other => quote_array_item(&other.to_string(), out),
}
}
out.push('}');
}
fn quote_array_item(item: &str, out: &mut String) {
out.push('"');
for c in item.chars() {
if c == '"' || c == '\\' {
out.push('\\');
}
out.push(c);
}
out.push('"');
}
fn array_element(ty: &tokio_postgres::types::Type) -> Option<&tokio_postgres::types::Type> {
use tokio_postgres::types::Kind;
match ty.kind() {
Kind::Array(element) => Some(element),
Kind::Domain(base) => array_element(base),
_ => None,
}
}
impl tokio_postgres::types::ToSql for FlexParam {
fn to_sql(
&self,
ty: &tokio_postgres::types::Type,
out: &mut bytes::BytesMut,
) -> std::result::Result<tokio_postgres::types::IsNull, Box<dyn std::error::Error + Sync + Send>>
{
use tokio_postgres::types::{IsNull, Type};
match self {
Self::Null => Ok(IsNull::Yes),
Self::Text(s) => {
write_text(s, ty, out)?;
Ok(IsNull::No)
},
Self::Value(value) => {
if *ty == Type::JSONB {
out.put_u8(1);
serde_json::to_writer((&mut *out).writer(), value)?;
} else if *ty == Type::JSON {
serde_json::to_writer((&mut *out).writer(), value)?;
} else if let (Some(element), serde_json::Value::Array(items)) =
(array_element(ty), value)
{
let json_elements = [Type::JSONB, Type::JSON].contains(element);
let mut literal = String::new();
write_array_literal(items, json_elements, &mut literal);
out.extend_from_slice(literal.as_bytes());
} else if let serde_json::Value::String(s) = value {
write_text(s, ty, out)?;
} else {
write_text(&value.to_string(), ty, out)?;
}
Ok(IsNull::No)
},
}
}
fn accepts(_ty: &tokio_postgres::types::Type) -> bool {
true
}
fn encode_format(&self, ty: &tokio_postgres::types::Type) -> tokio_postgres::types::Format {
use tokio_postgres::types::{Format, Type};
if [
Type::JSONB,
Type::JSON,
Type::UUID,
Type::INT4,
Type::INT8,
Type::BOOL,
]
.contains(ty)
{
Format::Binary
} else {
Format::Text
}
}
fn to_sql_checked(
&self,
ty: &tokio_postgres::types::Type,
out: &mut bytes::BytesMut,
) -> std::result::Result<tokio_postgres::types::IsNull, Box<dyn std::error::Error + Sync + Send>>
{
self.to_sql(ty, out)
}
}
fn enrich_undefined_column_error(
err: FraiseQLError,
view: &str,
where_clause: Option<&WhereClause>,
) -> FraiseQLError {
let FraiseQLError::Database { ref sql_state, .. } = err else {
return err;
};
if sql_state.as_deref() != Some(PG_UNDEFINED_COLUMN) {
return err;
}
let native_cols: Vec<&str> =
where_clause.map(|wc| wc.native_column_names()).unwrap_or_default();
if native_cols.is_empty() {
return err;
}
FraiseQLError::Database {
message: format!(
"Column(s) {:?} referenced as native column(s) on `{view}` do not exist. \
These columns were auto-inferred from ID/UUID-typed query arguments. \
Either add the column(s) to the table/view, or set \
`native_columns = {{}}` explicitly in your schema to disable inference.",
native_cols,
),
sql_state: Some(PG_UNDEFINED_COLUMN.to_string()),
constraint: None,
}
}
struct PgEnumLabel(String);
impl<'a> FromSql<'a> for PgEnumLabel {
fn from_sql(
_ty: &Type,
raw: &'a [u8],
) -> std::result::Result<Self, Box<dyn std::error::Error + Sync + Send>> {
Ok(Self(std::str::from_utf8(raw)?.to_owned()))
}
fn accepts(ty: &Type) -> bool {
matches!(ty.kind(), Kind::Enum(_))
}
}
struct AnyCell;
impl<'a> FromSql<'a> for AnyCell {
fn from_sql(
_ty: &Type,
_raw: &'a [u8],
) -> std::result::Result<Self, Box<dyn std::error::Error + Sync + Send>> {
Ok(Self)
}
fn accepts(_ty: &Type) -> bool {
true
}
}
fn row_to_map(row: &Row) -> std::collections::HashMap<String, serde_json::Value> {
let mut map = std::collections::HashMap::new();
for (idx, column) in row.columns().iter().enumerate() {
map.insert(column.name().to_string(), decode_cell(row, idx));
}
map
}
pub(super) fn decode_cell(row: &Row, idx: usize) -> serde_json::Value {
let column = &row.columns()[idx];
if matches!(row.try_get::<_, Option<AnyCell>>(idx), Ok(None)) {
serde_json::Value::Null
} else if let Ok(v) = row.try_get::<_, i16>(idx) {
serde_json::json!(v)
} else if let Ok(v) = row.try_get::<_, i32>(idx) {
serde_json::json!(v)
} else if let Ok(v) = row.try_get::<_, i64>(idx) {
serde_json::json!(v)
} else if let Ok(v) = row.try_get::<_, f64>(idx) {
serde_json::json!(v)
} else if let Ok(v) = row.try_get::<_, String>(idx) {
serde_json::json!(v)
} else if let Ok(v) = row.try_get::<_, bool>(idx) {
serde_json::json!(v)
} else if let Ok(v) = row.try_get::<_, PgNumericText>(idx) {
let s = v.0;
serde_json::from_str::<serde_json::Value>(&s).unwrap_or(serde_json::Value::String(s))
} else if let Ok(v) = row.try_get::<_, uuid::Uuid>(idx) {
serde_json::json!(v.to_string())
} else if let Ok(v) = row.try_get::<_, chrono::DateTime<chrono::Utc>>(idx) {
serde_json::json!(v.to_rfc3339())
} else if let Ok(v) = row.try_get::<_, chrono::NaiveDateTime>(idx) {
serde_json::json!(v.to_string())
} else if let Ok(v) = row.try_get::<_, chrono::NaiveDate>(idx) {
serde_json::json!(v.to_string())
} else if let Ok(v) = row.try_get::<_, Vec<String>>(idx) {
serde_json::json!(v)
} else if let Ok(v) = row.try_get::<_, PgEnumLabel>(idx) {
serde_json::json!(v.0)
} else if let Ok(v) = row.try_get::<_, serde_json::Value>(idx) {
v
} else {
tracing::warn!(
column = %column.name(),
pg_type = %column.type_(),
"decode_cell: column type not representable as JSON; returning null"
);
serde_json::Value::Null
}
}
pub(super) async fn apply_session_vars(
txn: &deadpool_postgres::Transaction<'_>,
session_vars: &[(&str, &str)],
) -> Result<()> {
if session_vars.is_empty() {
return Ok(());
}
let (sql, params) = set_config_batch(session_vars);
let applied = match txn.prepare_cached(&sql).await {
Ok(statement) => txn.execute(&statement, ¶ms).await,
Err(e) => Err(e),
};
applied.map_err(|e| {
let names: Vec<&str> = session_vars.iter().map(|(name, _)| *name).collect();
crate::postgres::database_error(
format!("set_config({names:?}) failed: {}", pg_detail(&e)),
&e,
)
})?;
Ok(())
}
fn set_config_batch<'a>(
session_vars: &'a [(&'a str, &'a str)],
) -> (String, Vec<&'a (dyn tokio_postgres::types::ToSql + Sync)>) {
let mut sql = String::from("SELECT ");
let mut params: Vec<&(dyn tokio_postgres::types::ToSql + Sync)> =
Vec::with_capacity(session_vars.len() * 2);
for (index, (name, value)) in session_vars.iter().enumerate() {
if index > 0 {
sql.push_str(", ");
}
params.push(name);
let name_param = params.len();
if *value == crate::changelog::CLOCK_TIMESTAMP_DIRECTIVE {
let _ = write!(sql, "set_config(${name_param}, clock_timestamp()::text, true)");
} else {
params.push(value);
let _ = write!(sql, "set_config(${name_param}, ${}, true)", name_param + 1);
}
}
(sql, params)
}
pub(super) fn build_changelog_cte_sql(quoted_fn: &str, n_args: usize, pre_image: bool) -> String {
let placeholders: Vec<String> = (1..=n_args).map(|i| format!("${i}")).collect();
let object_type_idx = n_args + 1;
let modification_type_idx = n_args + 2;
let tenant_id_idx = n_args + 3;
let trace_id_idx = n_args + 4;
let schema_version_idx = n_args + 5;
let trace_context_idx = n_args + 6;
let actor_type_idx = n_args + 7;
let acting_for_idx = n_args + 8;
let transport_idx = n_args + 9;
let started_var = crate::changelog::STARTED_AT_VAR;
let duration = crate::changelog::duration_ms_sql(started_var);
let calc_version = crate::changelog::DURATION_CALC_VERSION;
let after_before_cols = if pre_image {
"object_data, object_data_before"
} else {
"object_data"
};
let after_before_vals = if pre_image {
"r.entity, r.entity_before"
} else {
"r.entity"
};
format!(
"WITH r AS MATERIALIZED (SELECT * FROM {quoted_fn}({args})), \
_changelog AS ( \
INSERT INTO core.tb_entity_change_log \
(object_type, modification_type, object_id, {after_before_cols}, \
updated_fields, cascade, started_at, duration_ms, extra_metadata, \
tenant_id, trace_id, schema_version, trace_context, \
actor_type, acting_for, commit_time) \
SELECT \
COALESCE(r.entity_type, ${object_type_idx}), \
${modification_type_idx}, \
r.entity_id, {after_before_vals}, r.updated_fields, r.cascade, \
current_setting('{started_var}')::timestamptz, \
{duration}, \
jsonb_build_object('duration_calc_version', {calc_version}::int) \
|| CASE WHEN ${transport_idx}::text IS NULL THEN '{{}}'::jsonb \
ELSE jsonb_build_object('transport', ${transport_idx}::text) END, \
${tenant_id_idx}::uuid, \
${trace_id_idx}, \
${schema_version_idx}, \
${trace_context_idx}::jsonb, \
${actor_type_idx}, \
${acting_for_idx}::uuid, \
clock_timestamp() \
FROM r \
WHERE r.succeeded AND r.state_changed \
RETURNING 1 \
) \
SELECT * FROM r",
args = placeholders.join(", "),
)
}
async fn prepare_cached_stmt(
client: &deadpool_postgres::Client,
sql: &str,
) -> Result<tokio_postgres::Statement> {
client.prepare_cached(sql).await.map_err(|e| {
let detail = pg_detail(&e);
let hint = changelog_prepare_hint(&detail);
crate::postgres::database_error(format!("Failed to prepare statement: {detail}{hint}"), &e)
})
}
fn changelog_prepare_hint(detail: &str) -> &'static str {
if detail.contains("core.tb_entity_change_log") {
"\nhint: the mutation change-log outbox table is not installed in this database — \
run `fraiseql setup` (or apply the fraiseql-observers change-log contract \
migration) before executing mutations"
} else if detail.contains("column r.") {
"\nhint: the mutation function does not return the v2.2 mutation_response row \
(13 columns: succeeded, state_changed, …) that the change-log outbox reads. \
`RETURNS SETOF v_*` and bare scalar returns are not supported — build the row \
with fraiseql.mutation_ok()/fraiseql.mutation_err() (installed by `fraiseql \
setup`); see docs/architecture/mutation-response.md"
} else {
""
}
}
#[async_trait]
impl DatabaseAdapter for PostgresAdapter {
fn applies_session_variables(&self) -> bool {
true
}
fn serves_reads_from_standbys(&self) -> bool {
self.read_replicas.is_some()
}
async fn execute_with_projection(
&self,
view: &str,
projection: Option<&SqlProjectionHint>,
where_clause: Option<&WhereClause>,
limit: Option<u32>,
offset: Option<u32>,
order_by: Option<&[OrderByClause]>,
) -> Result<Vec<JsonbValue>> {
self.execute_with_projection_impl(view, projection, where_clause, limit, offset, order_by)
.await
}
async fn execute_where_query(
&self,
view: &str,
where_clause: Option<&WhereClause>,
limit: Option<u32>,
offset: Option<u32>,
order_by: Option<&[OrderByClause]>,
) -> Result<Vec<JsonbValue>> {
let (sql, typed_params) = build_where_select_sql_ordered(
super::ReadFrom::relation(view),
where_clause,
limit,
offset,
order_by,
)?;
let param_refs = crate::types::as_sql_param_refs(&typed_params);
self.execute_raw(&sql, ¶m_refs, ReadRouting::Any)
.await
.map_err(|e| enrich_undefined_column_error(e, view, where_clause))
}
async fn explain_where_query(
&self,
view: &str,
where_clause: Option<&WhereClause>,
limit: Option<u32>,
offset: Option<u32>,
) -> Result<serde_json::Value> {
let (select_sql, typed_params) = build_where_select_sql(view, where_clause, limit, offset)?;
if select_sql.contains(';') {
return Err(FraiseQLError::Validation {
message: "EXPLAIN SQL must be a single statement".into(),
path: None,
});
}
let explain_sql = format!("EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) {select_sql}");
let param_refs = crate::types::as_sql_param_refs(&typed_params);
let client = self.acquire_read_connection_with_retry(ReadRouting::Any).await?;
let rows = client.query(explain_sql.as_str(), ¶m_refs).await.map_err(|e| {
crate::postgres::database_error(
format!("EXPLAIN ANALYZE failed: {}", pg_detail(&e)),
&e,
)
})?;
if let Some(row) = rows.first() {
let plan: serde_json::Value = row.try_get(0).map_err(|e| FraiseQLError::Database {
message: format!("Failed to parse EXPLAIN output: {e}"),
sql_state: None,
constraint: None,
})?;
Ok(plan)
} else {
Ok(serde_json::Value::Null)
}
}
fn database_type(&self) -> DatabaseType {
DatabaseType::PostgreSQL
}
fn supports_composed_reads(&self) -> bool {
true
}
async fn tview_profiles(&self, sources: &[String]) -> Result<Vec<crate::traits::TviewProfile>> {
let client = self.acquire_connection_with_retry().await?;
crate::postgres::introspector::query_tview_profiles(&client, sources).await
}
async fn schema_storage_bytes(&self, schema: &str) -> Result<Option<u64>> {
let client = self.acquire_connection_with_retry().await?;
let row = client
.query_one(
"SELECT COALESCE(sum(pg_total_relation_size(c.oid)), 0)::bigint FROM pg_class c \
JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = $1 \
AND c.relkind IN ('r', 'm')",
&[&schema],
)
.await
.map_err(|e| {
crate::postgres::database_error(
format!("measuring schema {schema:?}: {}", pg_detail(&e)),
&e,
)
})?;
let bytes: i64 = row.get(0);
Ok(Some(u64::try_from(bytes).unwrap_or(0)))
}
async fn describe_constraint(
&self,
violation: &fraiseql_error::ConstraintViolation,
) -> Result<crate::traits::ConstraintDescription> {
let (Some(schema), Some(table)) = (&violation.schema, &violation.table) else {
return Ok(crate::traits::ConstraintDescription {
name: violation.name.clone(),
columns: None,
});
};
let client = self.acquire_connection_with_retry().await?;
let name = match (&violation.name, &violation.column) {
(Some(name), _) => Some(name.clone()),
(None, Some(column)) => client
.query_opt(
"SELECT c.conname::text FROM pg_constraint c JOIN pg_attribute a ON \
a.attrelid = c.conrelid WHERE c.conrelid = to_regclass(format('%I.%I', \
$1::text, $2::text)) AND c.contype = 'n' AND a.attname = $3 AND c.conkey = \
ARRAY[a.attnum]",
&[schema, table, column],
)
.await
.map_err(|e| {
crate::postgres::database_error(
format!("Failed to resolve a not-null constraint: {}", pg_detail(&e)),
&e,
)
})?
.map(|row| row.get(0)),
(None, None) => None,
};
let Some(name) = name else {
return Ok(crate::traits::ConstraintDescription::default());
};
let columns: Option<Vec<String>> = client
.query_one(
"WITH k AS ( \
SELECT u.attnum, u.ord FROM pg_constraint c, \
unnest(c.conkey) WITH ORDINALITY u(attnum, ord) \
WHERE c.conrelid = to_regclass(format('%I.%I', $1::text, $2::text)) \
AND c.conname = $3 \
UNION ALL \
SELECT u.attnum, u.ord FROM pg_index i, \
unnest(i.indkey) WITH ORDINALITY u(attnum, ord) \
WHERE i.indexrelid = to_regclass(format('%I.%I', $1::text, $3::text)) \
AND i.indrelid = to_regclass(format('%I.%I', $1::text, $2::text)) \
AND u.ord <= i.indnkeyatts \
AND NOT EXISTS (SELECT 1 FROM pg_constraint c2 \
WHERE c2.conrelid = i.indrelid AND c2.conname = $3)) \
SELECT CASE WHEN count(*) = 0 OR bool_or(k.attnum = 0) THEN NULL \
ELSE array_agg(a.attname::text ORDER BY k.ord) END \
FROM k LEFT JOIN pg_attribute a \
ON a.attrelid = to_regclass(format('%I.%I', $1::text, $2::text)) \
AND a.attnum = k.attnum",
&[schema, table, &name],
)
.await
.map_err(|e| {
crate::postgres::database_error(
format!("Failed to resolve a constraint's columns: {}", pg_detail(&e)),
&e,
)
})?
.get(0);
Ok(crate::traits::ConstraintDescription {
name: Some(name),
columns,
})
}
async fn health_check(&self) -> Result<()> {
let client = self.acquire_connection_with_retry().await?;
client.query("SELECT 1", &[]).await.map_err(|e| {
crate::postgres::database_error(format!("Health check failed: {}", pg_detail(&e)), &e)
})?;
Ok(())
}
#[allow(clippy::cast_possible_truncation)] fn pool_metrics(&self) -> PoolMetrics {
let status = self.pool.status();
PoolMetrics {
total_connections: status.size as u32,
idle_connections: status.available as u32,
active_connections: (status.size - status.available) as u32,
waiting_requests: status.waiting as u32,
}
}
async fn execute_raw_query(
&self,
sql: &str,
) -> Result<Vec<std::collections::HashMap<String, serde_json::Value>>> {
let client = self.acquire_connection_with_retry().await?;
let rows: Vec<Row> = client.query(sql, &[]).await.map_err(|e| {
crate::postgres::database_error(
format!("Query execution failed: {}", pg_detail(&e)),
&e,
)
})?;
let results: Vec<std::collections::HashMap<String, serde_json::Value>> =
rows.iter().map(row_to_map).collect();
Ok(results)
}
async fn execute_parameterized_aggregate(
&self,
sql: &str,
params: &[serde_json::Value],
) -> Result<Vec<std::collections::HashMap<String, serde_json::Value>>> {
let typed = aggregate_params(params);
let param_refs: Vec<&(dyn tokio_postgres::types::ToSql + Sync)> =
typed.iter().map(|v| v as &(dyn tokio_postgres::types::ToSql + Sync)).collect();
let client = self.acquire_read_connection_with_retry(ReadRouting::Any).await?;
let rows: Vec<Row> = client.query(sql, ¶m_refs).await.map_err(|e| {
crate::postgres::database_error(
format!("Parameterized aggregate query failed: {}", pg_detail(&e)),
&e,
)
})?;
let results: Vec<std::collections::HashMap<String, serde_json::Value>> =
rows.iter().map(row_to_map).collect();
Ok(results)
}
async fn execute_parameterized_aggregate_with_session(
&self,
sql: &str,
params: &[serde_json::Value],
session_vars: &[(&str, &str)],
routing: ReadRouting,
) -> Result<Vec<std::collections::HashMap<String, serde_json::Value>>> {
if session_vars.is_empty() {
return self.execute_parameterized_aggregate(sql, params).await;
}
let typed = aggregate_params(params);
let param_refs: Vec<&(dyn tokio_postgres::types::ToSql + Sync)> =
typed.iter().map(|v| v as &(dyn tokio_postgres::types::ToSql + Sync)).collect();
let mut client = self.acquire_read_connection_with_retry(routing).await?;
let txn = client.build_transaction().start().await.map_err(|e| {
crate::postgres::database_error(
format!("Failed to start session-var transaction: {}", pg_detail(&e)),
&e,
)
})?;
apply_session_vars(&txn, session_vars).await?;
let rows: Vec<Row> = txn.query(sql, ¶m_refs).await.map_err(|e| {
crate::postgres::database_error(
format!("Parameterized aggregate query failed: {}", pg_detail(&e)),
&e,
)
})?;
txn.commit().await.map_err(|e| {
crate::postgres::database_error(
format!("Failed to commit session-var transaction: {}", pg_detail(&e)),
&e,
)
})?;
Ok(rows.iter().map(row_to_map).collect())
}
async fn execute_where_query_arc_with_session(
&self,
view: &str,
where_clause: Option<&WhereClause>,
limit: Option<u32>,
offset: Option<u32>,
order_by: Option<&[OrderByClause]>,
session_vars: &[(&str, &str)],
routing: ReadRouting,
) -> Result<Arc<Vec<JsonbValue>>> {
let (sql, typed_params) = build_where_select_sql_ordered(
super::ReadFrom::relation(view),
where_clause,
limit,
offset,
order_by,
)?;
let param_refs = crate::types::as_sql_param_refs(&typed_params);
if session_vars.is_empty() {
return self
.execute_raw(&sql, ¶m_refs, routing)
.await
.map(Arc::new)
.map_err(|e| enrich_undefined_column_error(e, view, where_clause));
}
self.execute_raw_with_session(&sql, ¶m_refs, session_vars, routing)
.await
.map(Arc::new)
.map_err(|e| enrich_undefined_column_error(e, view, where_clause))
}
async fn count_where_query(
&self,
view: &str,
where_clause: Option<&WhereClause>,
session_vars: &[(&str, &str)],
routing: ReadRouting,
) -> Result<u64> {
let (sql, typed_params) = super::build_count_sql(view, where_clause)?;
let param_refs = crate::types::as_sql_param_refs(&typed_params);
let row = if session_vars.is_empty() {
let client = self.acquire_read_connection_with_retry(routing).await?;
client.query_one(&sql, ¶m_refs).await.map_err(|e| {
crate::postgres::database_error(
format!("Count query failed: {}", pg_detail(&e)),
&e,
)
})?
} else {
let mut client = self.acquire_read_connection_with_retry(routing).await?;
let txn = client.build_transaction().start().await.map_err(|e| {
crate::postgres::database_error(
format!("Failed to start count session-var transaction: {}", pg_detail(&e)),
&e,
)
})?;
super::database::apply_session_vars(&txn, session_vars).await?;
let row = txn.query_one(&sql, ¶m_refs).await.map_err(|e| {
crate::postgres::database_error(
format!("Count query failed: {}", pg_detail(&e)),
&e,
)
})?;
txn.commit().await.map_err(|e| {
crate::postgres::database_error(
format!("Failed to commit count session-var transaction: {}", pg_detail(&e)),
&e,
)
})?;
row
};
let total: i64 = row.get(0);
Ok(total.cast_unsigned())
}
async fn execute_with_projection_arc_with_session(
&self,
request: &ProjectionRequest<'_>,
session_vars: &[(&str, &str)],
routing: ReadRouting,
) -> Result<Arc<Vec<JsonbValue>>> {
if request.projection.is_none()
&& request.matched_up_to.is_none()
&& request.source_args.is_none()
{
return self
.execute_where_query_arc_with_session(
request.view,
request.where_clause,
request.limit,
request.offset,
request.order_by,
session_vars,
routing,
)
.await;
}
let from = super::ReadFrom::of(request);
let (page, params) = match request.projection {
Some(projection) => build_projection_select_sql(
projection,
from,
request.where_clause,
request.limit,
request.offset,
request.order_by,
)?,
None => super::build_where_select_sql_ordered(
from,
request.where_clause,
request.limit,
request.offset,
request.order_by,
)?,
};
let (sql, typed_params) = match request.matched_up_to {
Some(bound) => {
super::with_matched_count(&page, params, from, request.where_clause, bound)?
},
None => (page, params),
};
tracing::debug!("SQL with projection = {}", sql);
let source_params = request.source_args.map_or_else(Vec::new, bound_values);
let param_refs: Vec<&(dyn tokio_postgres::types::ToSql + Sync)> = source_params
.iter()
.map(|p| p as &(dyn tokio_postgres::types::ToSql + Sync))
.chain(typed_params.iter().map(|p| p as &(dyn tokio_postgres::types::ToSql + Sync)))
.collect();
if session_vars.is_empty() {
return self.execute_raw(&sql, ¶m_refs, routing).await.map(Arc::new);
}
self.execute_raw_with_session(&sql, ¶m_refs, session_vars, routing)
.await
.map(Arc::new)
}
async fn execute_composed_with_session(
&self,
read: &ComposedLevel,
session_vars: &[(&str, &str)],
routing: ReadRouting,
) -> Result<Arc<Vec<JsonbValue>>> {
let (sql, typed_params) = build_composed_select_sql(read)?;
let param_refs = crate::types::as_sql_param_refs(&typed_params);
if session_vars.is_empty() {
return self.execute_raw(&sql, ¶m_refs, routing).await.map(Arc::new);
}
self.execute_raw_with_session(&sql, ¶m_refs, session_vars, routing)
.await
.map(Arc::new)
}
async fn stream_with_projection(
&self,
request: &ProjectionRequest<'_>,
session_vars: &[(&str, &str)],
routing: ReadRouting,
) -> Result<JsonbRowStream> {
crate::traits::refuse_function_source(self, request)?;
let (sql, typed_params) = match request.projection {
Some(projection) => build_projection_select_sql(
projection,
super::ReadFrom::relation(request.view),
request.where_clause,
request.limit,
request.offset,
request.order_by,
)?,
None => build_where_select_sql_ordered(
super::ReadFrom::relation(request.view),
request.where_clause,
request.limit,
request.offset,
request.order_by,
)?,
};
super::streaming::stream_rows(self, sql, typed_params, session_vars, routing, |row, sql| {
jsonb_cell(row, 0, sql)
})
.await
.map_err(|e| enrich_undefined_column_error(e, request.view, request.where_clause))
}
async fn stream_row_query(
&self,
view_name: &str,
columns: &[crate::types::ColumnSpec],
where_sql: Option<&str>,
order_by: Option<&str>,
limit: Option<u32>,
offset: Option<u32>,
) -> Result<ColumnRowStream> {
let sql = crate::traits::build_row_query_sql(view_name, where_sql, order_by, limit, offset);
let columns = columns.to_vec();
super::streaming::stream_rows(
self,
sql,
Vec::new(),
&[],
ReadRouting::Primary,
move |row, _sql| Ok(crate::traits::row_to_column_values(&row_to_map(row), &columns)),
)
.await
}
async fn execute_row_query_with_session(
&self,
view_name: &str,
columns: &[crate::types::ColumnSpec],
where_sql: Option<&str>,
order_by: Option<&str>,
limit: Option<u32>,
offset: Option<u32>,
session_vars: &[(&str, &str)],
) -> Result<Vec<Vec<crate::types::ColumnValue>>> {
if session_vars.is_empty() {
return self
.execute_row_query(view_name, columns, where_sql, order_by, limit, offset)
.await;
}
let sql = crate::traits::build_row_query_sql(view_name, where_sql, order_by, limit, offset);
let mut client = self.acquire_connection_with_retry().await?;
let txn = client.build_transaction().start().await.map_err(|e| {
crate::postgres::database_error(
format!("Failed to start row-read session-var transaction: {}", pg_detail(&e)),
&e,
)
})?;
apply_session_vars(&txn, session_vars).await?;
let rows: Vec<Row> = txn.query(sql.as_str(), &[]).await.map_err(|e| {
crate::postgres::database_error(
format!("Row query execution failed: {}", pg_detail(&e)),
&e,
)
})?;
txn.commit().await.map_err(|e| {
crate::postgres::database_error(
format!("Failed to commit row-read session-var transaction: {}", pg_detail(&e)),
&e,
)
})?;
Ok(rows
.iter()
.map(|row| crate::traits::row_to_column_values(&row_to_map(row), columns))
.collect())
}
async fn stream_row_query_with_session(
&self,
view_name: &str,
columns: &[crate::types::ColumnSpec],
where_sql: Option<&str>,
order_by: Option<&str>,
limit: Option<u32>,
offset: Option<u32>,
session_vars: &[(&str, &str)],
) -> Result<ColumnRowStream> {
let sql = crate::traits::build_row_query_sql(view_name, where_sql, order_by, limit, offset);
let columns = columns.to_vec();
super::streaming::stream_rows(
self,
sql,
Vec::new(),
session_vars,
ReadRouting::Primary,
move |row, _sql| Ok(crate::traits::row_to_column_values(&row_to_map(row), &columns)),
)
.await
}
async fn explain_query(
&self,
sql: &str,
_params: &[serde_json::Value],
) -> Result<serde_json::Value> {
if sql.contains(';') {
return Err(FraiseQLError::Validation {
message: "EXPLAIN SQL must be a single statement".into(),
path: None,
});
}
let explain_sql = format!("EXPLAIN (ANALYZE false, FORMAT JSON) {sql}");
let client = self.acquire_read_connection_with_retry(ReadRouting::Any).await?;
let rows: Vec<Row> = client.query(explain_sql.as_str(), &[]).await.map_err(|e| {
crate::postgres::database_error(format!("EXPLAIN failed: {}", pg_detail(&e)), &e)
})?;
if let Some(row) = rows.first() {
let plan: serde_json::Value = row.try_get(0).map_err(|e| FraiseQLError::Database {
message: format!("Failed to parse EXPLAIN output: {e}"),
sql_state: None,
constraint: None,
})?;
Ok(plan)
} else {
Ok(serde_json::Value::Null)
}
}
async fn query_stats(&self, limit: u32) -> Result<Vec<crate::types::QueryStatEntry>> {
self.pg_query_stats(limit).await
}
async fn query_stats_by_id(&self, id: &str) -> Result<Option<crate::types::QueryStatEntry>> {
self.pg_query_stats_by_id(id).await
}
async fn reset_query_stats(&self) -> Result<()> {
self.pg_reset_query_stats().await
}
async fn execute_admin_sql(
&self,
request: &crate::traits::AdminSqlRequest,
) -> Result<crate::traits::AdminSqlOutcome> {
super::admin_sql::execute_admin_sql_impl(self, request).await
}
}
#[async_trait]
impl Writer for PostgresAdapter {
async fn execute_write(
&self,
request: &crate::traits::WriteRequest<'_>,
gate: crate::traits::MutationRowGate<'_>,
) -> Result<Vec<std::collections::HashMap<String, serde_json::Value>>> {
let mut rows =
run_functions_in_txn(self, std::slice::from_ref(request), &|_, rows| gate(rows), false)
.await?;
Ok(rows.pop().unwrap_or_default())
}
async fn execute_writes(
&self,
requests: &[crate::traits::WriteRequest<'_>],
gate: crate::traits::BatchRowGate<'_>,
) -> Result<Vec<Vec<std::collections::HashMap<String, serde_json::Value>>>> {
run_functions_in_txn(self, requests, gate, true).await
}
}