WowSQL Rust SDK

Official Rust client for WowSQL — PostgreSQL backend-as-a-service with project auth, object storage, and schema management.

Crate: wowsql · Edition: 2021 · Rust: 1.70+ recommended

Table of contents

1. Installation
2. Quick start
3. Concepts & API keys
4. Database: WOWSQLClient
5. Table & QueryBuilder
6. Authentication: AuthClient
7. Storage: StorageClient
8. Schema: SchemaClient
9. Models & enums
10. Errors
11. Features
12. Examples
13. Links

Installation

Cargo.toml:

[dependencies]

wowsql = "1.3"

tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

serde_json = "1"

Async methods are async and return Result<_, wowsql::WOWSQLError> (or specialized storage/schema errors where noted).

Quick start

use serde_json::{json, Value};
use wowsql::WOWSQLClient;

#[tokio::main]
async fn main() -> Result<(), wowsql::WOWSQLError> {
    let client = WOWSQLClient::new(
        "https://your-project.wowsql.com",
        std::env::var("WOWSQL_SERVICE_KEY").unwrap().as_str(),
    )?;

    let res = client
        .table("posts")
        .select(&["id", "title"])
        .eq("published", json!(true))
        .limit(10)
        .execute::<Value>()
        .await?;

    println!("rows: {}", res.count);
    Ok(())
}

Concepts & API keys

• SchemaClient must use a service role key.
• End-user JWTs from AuthClient are for your app session — use API keys for WOWSQLClient / StorageClient from backends (same model as other official SDKs).

Database: WOWSQLClient

Construction

use wowsql::WOWSQLClient;

// Simple
let client = WOWSQLClient::new(project_url, api_key)?;

// Builder
let client = WOWSQLClient::builder(project_url, api_key)
    .base_domain("wowsql.com")
    .secure(true)
    .timeout(30)
    .verify_ssl(true)
    .build()?;

Methods

Table & QueryBuilder

Table

QueryBuilder (owned / consuming)

Chain: select, filter, eq, …, group_by, having, order_by / order, order_by_multiple, limit, offset.

Terminal (consume self):

• execute::<T>(), get::<T>()
• first::<T>(), single::<T>()
• count()
• paginate::<T>(page, per_page)

Mutations on builder: create, insert, update, delete (when supported by implementation).

FilterOperator & SortDirection

FilterOperator: Eq, Neq, Gt, Gte, Lt, Lte, Like, IsNull, In, NotIn, Between, NotBetween, IsNot.

SortDirection: Asc, Desc.

Authentication: AuthClient

use wowsql::{AuthClient, AuthClientBuilder, MemoryTokenStorage, TokenStorage};
use std::sync::Arc;

let auth = AuthClient::builder(project_url, anon_key)
    .base_domain("wowsql.com")
    .timeout(30)
    .token_storage(Arc::new(MemoryTokenStorage::new()))
    .build()?;

TokenStorage trait

Send + Sync: get_access_token, get_refresh_token, set_tokens, clear.

Methods (async unless noted)

Storage: StorageClient

use wowsql::StorageClient;

let storage = StorageClient::builder(project_url, api_key)
    .base_domain("wowsql.com")
    .timeout(60)
    .build()?;

Schema: SchemaClient

Requires service role key.

use wowsql::{SchemaClient, ColumnDefinition};

let schema = SchemaClient::builder(project_url, service_key)
    .base_domain("wowsql.com")
    .build()?;

schema
    .create_table(
        "items",
        vec![
            ColumnDefinition::new("id", "SERIAL").auto_increment(true),
            ColumnDefinition::new("name", "TEXT").not_null(true),
        ],
        Some("id"),
        None,
    )
    .await?;

Helpers: ColumnDefinition, CreateTableRequest, AlterTableRequest, IndexDefinition, RenameColumn, SchemaResponse.

Models & enums

Exported from wowsql::models: QueryResponse, CreateResponse, UpdateResponse, DeleteResponse, PaginatedResponse, TableSchema, ColumnInfo, FilterExpression, HavingFilter, OrderByItem, AuthUser, AuthSession, AuthResponse, OAuthAuthorizationResponse, StorageBucket, StorageFile, StorageQuota, StorageStats, FileUploadResult, etc.

Errors

• WOWSQLError — main error type; new, from_response, is_authentication, is_not_found, is_rate_limit.
• StorageError, StorageLimitExceededError
• SchemaPermissionError

From conversions exist for reqwest::Error and storage/schema errors where implemented.

Use ? in async functions or match on e for status / body.

Features (Cargo)

Default features match Cargo.toml. Add serde types in your app for typed rows; SDK uses serde_json::Value in many places.

Examples

Paginated list

let page = client
    .table("orders")
    .select(&["id", "total"])
    .gte("total", json!(10))
    .order_by("id", wowsql::SortDirection::Desc)
    .paginate::<Value>(1, 20)
    .await?;

Auth sign-in

let session = auth.sign_in("a@b.com", "secret").await?.session.unwrap();
auth.set_session(&session.access_token, &session.refresh_token);

Links

• Documentation
• Website

License: MIT