Struct FraiseClient 

pub struct FraiseClient { /* private fields */ }

FraiseQL wire protocol client

Implementations

impl FraiseClient

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

Connect to Postgres using connection string

Errors

Returns WireError::Config if the connection string is invalid or missing required fields. Returns WireError if the TCP or Unix socket connection fails, or if startup/authentication is rejected by the server.

Examples

// Requires: live Postgres server.
use fraiseql_wire::FraiseClient;

// TCP connection
let client = FraiseClient::connect("postgres://localhost/mydb").await?;

// Unix socket
let client = FraiseClient::connect("postgres:///mydb").await?;

Errors

Returns WireError::Config if the connection string is malformed or missing required fields (host/port for TCP, path for Unix sockets). Returns WireError::Io if the underlying TCP or Unix socket connection fails.

pub async fn connect_tls( connection_string: &str, tls_config: TlsConfig, ) -> Result<Self>

Connect to Postgres with TLS encryption

TLS is configured independently from the connection string. The connection string should contain the hostname and credentials (user/password), while TLS configuration is provided separately via TlsConfig.

Errors

Returns WireError::Config if the connection string is invalid, TLS is requested over a Unix socket, or required fields are missing. Returns WireError::Io if the TLS handshake or TCP connection fails.

Examples

// Requires: live Postgres server with TLS.
use fraiseql_wire::{FraiseClient, connection::TlsConfig};

// Configure TLS with system root certificates
let tls = TlsConfig::builder()
    .verify_hostname(true)
    .build()?;

// Connect with TLS
let client = FraiseClient::connect_tls("postgres://secure.db.example.com/mydb", tls).await?;

pub async fn connect_with_config( connection_string: &str, config: ConnectionConfig, ) -> Result<Self>

Connect to Postgres with custom connection configuration

This method allows you to configure timeouts, keepalive intervals, and other connection options. The connection configuration is merged with parameters from the connection string.

Errors

Returns WireError::Config if the connection string is invalid or missing required fields. Returns WireError::Io if the TCP or Unix socket connection fails, or if startup/authentication is rejected by the server.

Examples

// Requires: live Postgres server.
use fraiseql_wire::{FraiseClient, connection::ConnectionConfig};
use std::time::Duration;

// Build connection configuration with timeouts
let config = ConnectionConfig::builder("localhost", "mydb")
    .password("secret")
    .statement_timeout(Duration::from_secs(30))
    .keepalive_idle(Duration::from_secs(300))
    .application_name("my_app")
    .build();

// Connect with configuration
let client = FraiseClient::connect_with_config("postgres://localhost:5432/mydb", config).await?;

pub async fn connect_with_config_and_tls( connection_string: &str, config: ConnectionConfig, tls_config: TlsConfig, ) -> Result<Self>

Connect to Postgres with both custom configuration and TLS encryption

This method combines connection configuration (timeouts, keepalive, etc.) with TLS encryption for secure connections with advanced options.

Errors

Returns WireError::Config if the connection string is invalid, TLS is requested over a Unix socket, or required fields are missing. Returns WireError::Io if the TLS handshake or TCP connection fails.

Examples

// Requires: live Postgres server with TLS.
use fraiseql_wire::{FraiseClient, connection::{ConnectionConfig, TlsConfig}};
use std::time::Duration;

// Configure connection with timeouts
let config = ConnectionConfig::builder("localhost", "mydb")
    .password("secret")
    .statement_timeout(Duration::from_secs(30))
    .build();

// Configure TLS
let tls = TlsConfig::builder()
    .verify_hostname(true)
    .build()?;

// Connect with both configuration and TLS
let client = FraiseClient::connect_with_config_and_tls(
    "postgres://secure.db.example.com/mydb",
    config,
    tls
).await?;

pub fn query<T: DeserializeOwned + Unpin + 'static>( self, entity: impl Into<String>, ) -> QueryBuilder<T>

Start building a query for an entity with automatic deserialization

The type parameter T controls consumer-side deserialization only. Type T does NOT affect SQL generation, filtering, ordering, or wire protocol.

Examples

Type-safe query (recommended):

// Requires: live Postgres server.
use serde::Deserialize;
use futures::stream::StreamExt;

#[derive(Deserialize)]
struct User {
    id: String,
    name: String,
}

let mut stream = client
    .query::<User>("user")
    .where_sql("data->>'type' = 'customer'")  // SQL predicate
    .where_rust(|json| {
        // Rust predicate (applied client-side, on JSON)
        json["estimated_value"].as_f64().unwrap_or(0.0) > 1000.0
    })
    .order_by("data->>'name' ASC")
    .execute()
    .await?;

while let Some(result) = stream.next().await {
    let user: User = result?;
    println!("User: {}", user.name);
}

Raw JSON query (debugging, forward compatibility):

// Requires: live Postgres server.
use futures::stream::StreamExt;

let mut stream = client
    .query::<serde_json::Value>("user")  // Escape hatch
    .execute()
    .await?;

while let Some(result) = stream.next().await {
    let json = result?;
    println!("JSON: {:?}", json);
}