cquill - v0.1.0

cquill/adapter

Types

Adapter

opaque </>

The core adapter interface.

This uses a record of functions pattern rather than behaviours because:

  1. Gleam doesn’t have Elixir-style behaviours
  2. Records are first-class and composable
  3. Easier to test with mock adapters
  4. Type-safe at compile time

Type parameters:

  • conn: The connection/pool type specific to this adapter
  • row: The raw row type returned by the adapter (usually List(Dynamic))
pub opaque type Adapter(conn, row)

AdapterCapabilities

</>

Declares what optional features an adapter supports. This allows compile-time checking of feature availability.

pub type AdapterCapabilities {
  AdapterCapabilities(
    transactions: Bool,
    returning: Bool,
    batch_insert: Bool,
    upsert: Bool,
    max_params: option.Option(Int),
    json_operations: Bool,
    array_types: Bool,
  )
}

Constructors 

  • AdapterCapabilities(
  transactions: Bool,
  returning: Bool,
  batch_insert: Bool,
  upsert: Bool,
  max_params: option.Option(Int),
  json_operations: Bool,
  array_types: Bool,
)

    Arguments

    transactions

    Does the adapter support multi-statement transactions?

    returning

    Does the adapter support RETURNING clauses (get inserted ID)?

    batch_insert

    Does the adapter support batch insert operations?

    upsert

    Does the adapter support upsert (INSERT ON CONFLICT)?

    max_params

    Maximum number of parameters in a single query (None = unlimited)

    json_operations

    Does the adapter support JSON operations?

    array_types

    Does the adapter support array types?

AdapterError

</> 
pub type AdapterError =
  error.AdapterError

CompiledQuery

</>

Represents a compiled query ready for adapter execution. The full Query AST is defined in cquill/query, but adapters receive this simplified representation.

pub type CompiledQuery {
  CompiledQuery(
    sql: String,
    params: List(QueryParam),
    expected_columns: Int,
  )
}

Constructors 

  • CompiledQuery(
  sql: String,
  params: List(QueryParam),
  expected_columns: Int,
)

    Arguments

    sql

    The SQL or query string to execute

    params

    Bound parameters in order

    expected_columns

    Expected number of columns in result

QueryParam

</>

Query parameters with type information for proper encoding

pub type QueryParam {
  ParamInt(Int)
  ParamFloat(Float)
  ParamString(String)
  ParamBool(Bool)
  ParamNull
  ParamBytes(BitArray)
  ParamCustom(type_name: String, value: String)
}

Constructors 

  • ParamInt(Int)
  • ParamFloat(Float)
  • ParamString(String)
  • ParamBool(Bool)
  • ParamNull
  • ParamBytes(BitArray)
  • ParamCustom(type_name: String, value: String)

    For adapter-specific parameter types

TransactionError

</> 
pub type TransactionError(e) =
  error.TransactionError(e)

Values

capabilities

</> 
pub fn capabilities(
  adapter: Adapter(conn, row),
) -> AdapterCapabilities

Get the adapter’s declared capabilities

default_capabilities

</> 
pub fn default_capabilities() -> AdapterCapabilities

Default capabilities - minimal feature set all adapters support

format_error

</> 
pub fn format_error(err: error.AdapterError) -> String

from_mysql_error

</> 
pub fn from_mysql_error(
  code: Int,
  message: String,
) -> error.AdapterError

from_postgres_error

</> 
pub fn from_postgres_error(
  code: String,
  message: String,
  detail: String,
) -> error.AdapterError

from_sqlite_error

</> 
pub fn from_sqlite_error(
  code: Int,
  message: String,
) -> error.AdapterError

insert_returning

</> 
pub fn insert_returning(
  adapter: Adapter(conn, row),
  connection: conn,
  compiled: CompiledQuery,
) -> Result(option.Option(row), error.AdapterError)

Execute an INSERT with RETURNING (returns NotSupported if unavailable)

is_connection_error

</> 
pub fn is_connection_error(err: error.AdapterError) -> Bool

is_constraint_violation

</> 
pub fn is_constraint_violation(err: error.AdapterError) -> Bool

is_foreign_key_violation

</> 
pub fn is_foreign_key_violation(err: error.AdapterError) -> Bool

is_not_found

</> 
pub fn is_not_found(err: error.AdapterError) -> Bool

is_query_error

</> 
pub fn is_query_error(err: error.AdapterError) -> Bool

is_recoverable

</> 
pub fn is_recoverable(err: error.AdapterError) -> Bool

is_unique_violation

</> 
pub fn is_unique_violation(err: error.AdapterError) -> Bool

mutate

</> 
pub fn mutate(
  adapter: Adapter(conn, row),
  connection: conn,
  compiled: CompiledQuery,
) -> Result(Int, error.AdapterError)

Execute a mutation and return affected row count

mutation_query

</> 
pub fn mutation_query(
  sql: String,
  params: List(QueryParam),
) -> CompiledQuery

Create a mutation query (INSERT/UPDATE/DELETE)

name

</> 
pub fn name(adapter: Adapter(conn, row)) -> String

Get the adapter’s name

new

</> 
pub fn new(
  name name: String,
  capabilities capabilities: AdapterCapabilities,
  execute_query execute_query: fn(conn, CompiledQuery) -> Result(
    List(row),
    error.AdapterError,
  ),
  execute_mutation execute_mutation: fn(conn, CompiledQuery) -> Result(
    Int,
    error.AdapterError,
  ),
  execute_returning execute_returning: fn(conn, CompiledQuery) -> Result(
    option.Option(row),
    error.AdapterError,
  ),
  begin_transaction begin_transaction: fn(conn) -> Result(
    conn,
    error.AdapterError,
  ),
  commit_transaction commit_transaction: fn(conn) -> Result(
    Nil,
    error.AdapterError,
  ),
  rollback_transaction rollback_transaction: fn(conn) -> Result(
    Nil,
    error.AdapterError,
  ),
) -> Adapter(conn, row)

Create a new adapter with the given operations.

param_bool

</> 
pub fn param_bool(value: Bool) -> QueryParam

Create a boolean parameter

param_bytes

</> 
pub fn param_bytes(value: BitArray) -> QueryParam

Create a bytes parameter

param_custom

</> 
pub fn param_custom(
  type_name: String,
  value: String,
) -> QueryParam

Create a custom type parameter

param_float

</> 
pub fn param_float(value: Float) -> QueryParam

Create a float parameter

param_int

</> 
pub fn param_int(value: Int) -> QueryParam

Create an integer parameter

param_null

</> 
pub fn param_null() -> QueryParam

Create a null parameter

param_string

</> 
pub fn param_string(value: String) -> QueryParam

Create a string parameter

query

</> 
pub fn query(
  adapter: Adapter(conn, row),
  connection: conn,
  compiled: CompiledQuery,
) -> Result(List(row), error.AdapterError)

Execute a query and return all rows

query_one

</> 
pub fn query_one(
  adapter: Adapter(conn, row),
  connection: conn,
  compiled: CompiledQuery,
) -> Result(row, error.AdapterError)

Execute a query and return exactly one row, or error

query_optional

</> 
pub fn query_optional(
  adapter: Adapter(conn, row),
  connection: conn,
  compiled: CompiledQuery,
) -> Result(option.Option(row), error.AdapterError)

Execute a query and return an optional row (None if not found)

query_with_columns

</> 
pub fn query_with_columns(
  sql: String,
  params: List(QueryParam),
  expected_columns: Int,
) -> CompiledQuery

Create a query with expected column count

select_query

</> 
pub fn select_query(
  sql: String,
  params: List(QueryParam),
) -> CompiledQuery

Create a simple SELECT query

sql_capabilities

</> 
pub fn sql_capabilities() -> AdapterCapabilities

Full SQL database capabilities (Postgres, MySQL, etc.)

supports_arrays

</> 
pub fn supports_arrays(adapter: Adapter(conn, row)) -> Bool

Check if adapter supports array types

supports_batch_insert

</> 
pub fn supports_batch_insert(adapter: Adapter(conn, row)) -> Bool

Check if adapter supports batch inserts

supports_json

</> 
pub fn supports_json(adapter: Adapter(conn, row)) -> Bool

Check if adapter supports JSON operations

supports_returning

</> 
pub fn supports_returning(adapter: Adapter(conn, row)) -> Bool

Check if adapter supports RETURNING clause

supports_transactions

</> 
pub fn supports_transactions(adapter: Adapter(conn, row)) -> Bool

Check if adapter supports transactions

supports_upsert

</> 
pub fn supports_upsert(adapter: Adapter(conn, row)) -> Bool

Check if adapter supports upsert operations

transaction

</> 
pub fn transaction(
  adapter: Adapter(conn, row),
  connection: conn,
  operation: fn(conn) -> Result(a, e),
) -> Result(a, error.TransactionError(e))

Execute a function within a transaction. Returns UserError if the user’s operation function fails. Returns AdapterTransactionError if the adapter/database fails during the transaction.

transaction_with_adapter_errors

</> 
pub fn transaction_with_adapter_errors(
  adapter: Adapter(conn, row),
  connection: conn,
  operation: fn(conn) -> Result(a, error.AdapterError),
) -> Result(a, error.TransactionError(Nil))

Execute a function within a transaction with adapter error handling. This version allows the operation to return AdapterError, which is wrapped in AdapterTransactionError on failure instead of UserError.

✨ Search Document