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

// 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 Error::Config if the connection string is invalid or missing required fields. Returns Error::Io if the TCP/Unix connection fails. Returns Error::Authentication if startup authentication 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.

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?;

Errors

Returns Error::Config if the connection string is invalid, TLS is attempted over Unix socket, or the server rejects the SSL request or TLS handshake fails. Returns Error::Io if the TCP connection fails. Returns Error::Authentication if startup authentication fails.

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

// 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?;

Errors

Returns Error::Config if the connection string is invalid or missing required fields. Returns Error::Io if the TCP/Unix connection fails. Returns Error::Authentication if startup authentication fails.

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

// 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?;

Errors

Returns Error::Config if the connection string is invalid, TLS is attempted over Unix socket, or the server rejects the SSL request or TLS handshake fails. Returns Error::Io if the TCP connection fails. Returns Error::Authentication if startup authentication fails.

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