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

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.

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 for secure connections with advanced options.

Examples

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

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