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

Examples

use fraiseql_wire::FraiseClient;

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

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

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

Connect to Postgres with TLS encryption

Uses the PostgreSQL SSLRequest protocol to negotiate TLS. The connection starts as plain TCP, sends an SSLRequest message, and upgrades to TLS if the server responds with S.

Examples

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.

Examples

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 via the PostgreSQL SSLRequest protocol.

Examples

use fraiseql_wire::{FraiseClient, connection::{ConnectionConfig, TlsConfig, SslMode}};
use std::time::Duration;

// Configure connection with timeouts and TLS
let config = ConnectionConfig::builder("localhost", "mydb")
    .password("secret")
    .statement_timeout(Duration::from_secs(30))
    .sslmode(SslMode::VerifyFull)
    .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):

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

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);
}