sparkling/repo

Types

Event

Events emitted by the repo for observability (logging, metrics, tracing)

pub type Event {
  QueryStart(sql: String)
  QueryEnd(sql: String, duration_ms: Int)
  QueryError(sql: String, error: String)
  RetryAttempt(sql: String, attempt: Int, error: String)
}

Constructors

```
QueryStart(sql: String)
```
```
QueryEnd(sql: String, duration_ms: Int)
```
```
QueryError(sql: String, error: String)
```

RetryAttempt(sql: String, attempt: Int, error: String)

Repo

</>

Repository configuration and state

pub type Repo {
  Repo(
    base_url: String,
    database: option.Option(String),
    user: option.Option(String),
    password: option.Option(String),
    on_event: fn(Event) -> Nil,
    retry_config: retry.RetryConfig,
    timeout_ms: Int,
  )
}

Constructors

Repo(
  base_url: String,
  database: option.Option(String),
  user: option.Option(String),
  password: option.Option(String),
  on_event: fn(Event) -> Nil,
  retry_config: retry.RetryConfig,
  timeout_ms: Int,
)

RepoError

</>

Error types for repository operations

pub type RepoError {
  HttpError(message: String)
  ParseError(message: String)
  ConnectionError(message: String)
  ClickHouseError(message: String, code: option.Option(Int))
}

Constructors

```
HttpError(message: String)
```
```
ParseError(message: String)
```
```
ConnectionError(message: String)
```

ClickHouseError(message: String, code: option.Option(Int))

Values

execute_sql

</>

pub fn execute_sql(
  repo: Repo,
  sql: String,
) -> Result(String, RepoError)

Execute a SQL query and return the response body as a string. This is the low-level interface; higher-level functions will parse the response.

new

</>

pub fn new(base_url: String) -> Repo

Create a new Repo with default configuration

query

</>

pub fn query(
  repo: Repo,
  sql: String,
  decoder: fn(String) -> Result(a, String),
) -> Result(a, RepoError)

Execute a query and parse the response using a decoder. This is a higher-level interface that combines execute_sql with decoding.

with_credentials

</>

pub fn with_credentials(
  repo: Repo,
  user: String,
  password: String,
) -> Repo

Set authentication credentials

with_database

</>

pub fn with_database(repo: Repo, database: String) -> Repo

Set the database name for queries

with_event_handler

</>

pub fn with_event_handler(
  repo: Repo,
  handler: fn(Event) -> Nil,
) -> Repo

Set event handler for observability

with_max_retries

</>

pub fn with_max_retries(repo: Repo, retries: Int) -> Repo

Set max retries for failed queries

with_retry_config

</>

pub fn with_retry_config(
  repo: Repo,
  config: retry.RetryConfig,
) -> Repo

Set retry configuration for advanced control

with_timeout

</>

pub fn with_timeout(repo: Repo, timeout_ms: Int) -> Repo

Set query timeout in milliseconds