pixeluvw_supabase

A high-performance Rust SDK for Supabase.

Designed for reliability and improved developer experience, this crate provides a strongly-typed, fluent interface for interacting with the entire Supabase stack (Database, Auth, Realtime, Storage, and Edge Functions).

Note: This SDK is currently in Beta. APIs are stable but may evolve.

✨ Features

• 🚀 Database: Full PostgREST support with a fluent query builder, 25+ filters, and strong typing.
• 🔮 Schema Introspection: Unique capability to fetch remote schema metadata at runtime and generate Rust structs.
• 🔐 Auth: Complete authentication suite including Email/Password, OAuth, OTP, MFA, and Admin API.
• ⚡ Realtime: Robust WebSocket client for listening to database changes (INSERT, UPDATE, DELETE), presence, and broadcast.
• 📦 Storage: Simple API for file uploads, downloads, and signed URL generation.
• serverless Functions: Invoke Edge Functions seamlessly.
• 🛡️ Enterprise Ready: Built-in middleware support, automatic retries with exponential backoff, and robust error handling.

📦 Installation

Add this to your Cargo.toml:

[dependencies]
pixeluvw_supabase = "0.1"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
dotenv = "0.15"

🚀 Quick Start

1. Setup Environment

Create a .env file in your project root (ensure it's in your .gitignore):

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key

2. Basic Usage

use pixeluvw_supabase::{supabase, SupabaseClient};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv::dotenv().ok();

    // Initialize the client (automatically loads from env)
    let client = supabase!()?;

    // Perform a query
    let users: Vec<serde_json::Value> = client
        .from("users")
        .select("*")
        .eq("status", "active")
        .limit(5)
        .execute()
        .await?;

    println!("Users: {:?}", users);

    Ok(())
}

📚 Guides

Database

The query builder allows you to construct complex queries with ease.

// Select with multiple filters and ordering
let items = client
    .from("todos")
    .select("id, title, is_complete")
    .eq("user_id", "123")
    .is_("deleted_at", "null")
    .order("created_at", false) // descending
    .execute()
    .await?;

// Insert new data
client
    .from("todos")
    .insert(json!({ "title": "Buy milk", "user_id": "123" }))
    .execute()
    .await?;

// Update existing data
client
    .from("todos")
    .update(json!({ "is_complete": true }))
    .eq("id", 1)
    .execute()
    .await?;

Supported Filters

eq, neq, gt, gte, lt, lte, like, ilike, is_, in_, contains, contained_by, range_gt, range_gte, range_lt, range_lte, range_adjacent, overlaps, text_search, match_, filter, not, or, and.

Authentication

Handle user sessions securely.

// Sign in with email and password
let session = client.auth().sign_in_with_password("user@example.com", "pass123").await?;

// The client automatically attaches the access token to subsequent requests!
// You can also access the user object:
println!("Logged in as: {}", session.user.id);

// Sign out
client.auth().sign_out().await?;

OAuth Login:

let url = client.auth().sign_in_with_oauth(
    pixeluvw_supabase::Provider::Github,
    Some("https://myapp.com/callback"), // redirect URL
    None, // scopes
)?;
// Redirect your user to `url`

Realtime

Subscribe to database changes instantly.

use pixeluvw_supabase::PostgresEvent;
use tokio_stream::StreamExt;

let mut channel = client
    .realtime()
    .channel("room-1")
    .on_postgres_changes(
        PostgresEvent::Insert, 
        "public", 
        Some("messages"), 
        None // No filter
    )
    .subscribe()
    .await?;

// Listen for messages
while let Some(msg) = channel.next().await {
    println!("New event: {:?}", msg);
}

Storage

Manage user files.

let bucket = client.storage().from("avatars");

// Upload a file
bucket.upload("user_123.png", "./local_path.png", None).await?;

// Get a public URL
let url = bucket.get_public_url("user_123.png")?;

⚙️ Configuration

You can customize the client behavior using ClientConfig.

use pixeluvw_supabase::{ClientConfig, SupabaseClient};

let config = ClientConfig {
    timeout_secs: 60,
    max_retries: 3,
    retry_base_delay_ms: 500,
};

let client = SupabaseClient::with_config("url", "key", config)?;

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.