based

A standardized interface for database operations. This module defines types for adapter packages to use in their public interfaces.

Types

BatchQueryHandler

</>

A function that executes a list of parameterized queries and returns a list of results.

pub type BatchQueryHandler(v, conn) =
  fn(List(sql.Query(v)), conn) -> Result(
    List(Queried),
    BasedError,
  )

DatabaseError

</>

pub type DatabaseError {
  DatabaseError(code: String, name: String, message: String)
  ConstraintError(code: String, name: String, message: String)
  SyntaxError(code: String, name: String, message: String)
  ConnectionError(message: String)
  ConnectionUnavailable
  ConnectionTimeout
}

Constructors

DatabaseError(code: String, name: String, message: String)

ConstraintError(code: String, name: String, message: String)

SyntaxError(code: String, name: String, message: String)

```
ConnectionError(message: String)
```
```
ConnectionUnavailable
```
```
ConnectionTimeout
```

Db

</>

A configured database connection bundling a connection value, a Driver with query handlers, and a sql.Adapter for query rendering.

pub type Db(v, conn) {
  Db(driver: Driver(v, conn), sql: sql.Adapter(v))
}

Constructors

Db(driver: Driver(v, conn), sql: sql.Adapter(v))

Driver

opaque </>

An opaque driver that holds the query, execute, and batch handler functions provided by an adapter package.

pub opaque type Driver(v, conn)

ExecuteHandler

</>

A function that executes a raw SQL string and returns a count of affected rows.

pub type ExecuteHandler(conn) =
  fn(String, conn) -> Result(Int, BasedError)

Holds a count of affected rows, a list of queried fields, and a list of Dynamic rows returned from the database. A Queried record can be passed to based.decode with a decoder, returning a Returning record containing the decoded rows.

pub type Queried {
  Queried(
    count: Int,
    fields: List(String),
    rows: List(dynamic.Dynamic),
  )
}

Constructors

Queried(
  count: Int,
  fields: List(String),
  rows: List(dynamic.Dynamic),
)

QueryHandler

</>

A function that executes a parameterized query and returns rows.

pub type QueryHandler(v, conn) =
  fn(sql.Query(v), conn) -> Result(Queried, BasedError)

Returning

</>

Holds a count of affected rows and a list of decoded rows returned from the database.

pub type Returning(a) {
  Returning(count: Int, rows: List(a))
}

Constructors

```
Returning(count: Int, rows: List(a))
```

TransactionError

</>

Error type for transaction operations including rollbacks and transaction failures.

pub type TransactionError(error) {
  Rollback(cause: error)
  NotInTransaction
  TransactionError(message: String)
}

Constructors

```
Rollback(cause: error)
```
```
NotInTransaction
```
```
TransactionError(message: String)
```

TxHandler

</>

A function provided by an adapter package that wraps a callback in a database transaction. The handler receives a connection and a callback; it is responsible for committing on Ok and rolling back on Error.

pub type TxHandler(conn, t, error) =
  fn(conn, fn(conn) -> Result(t, error)) -> Result(
    t,
    TransactionError(error),
  )

Values

all

</>

pub fn all(
  query: sql.Query(v),
  db: Db(v, conn),
  decoder: decode.Decoder(a),
) -> Result(List(a), BasedError)

A convenience function for callers performing a query that will return a list of rows, but don’t need the full Returning record.

batch

</>

pub fn batch(
  queries: List(sql.Query(v)),
  db: Db(v, conn),
) -> Result(List(Queried), BasedError)

Executes a list of queries as a batch.

database_error_to_string

</>

pub fn database_error_to_string(err: DatabaseError) -> String

Formats the provided DatabaseError as a string.

decode

</>

pub fn decode(
  queried: Queried,
  decoder: decode.Decoder(a),
) -> Result(Returning(a), BasedError)

Accepts a Queried record and applies a decoder to its rows. Returns a Returning record with the decoded rows.

driver

</>

pub fn driver(
  conn: conn,
  on_query handle_query: fn(sql.Query(v), conn) -> Result(
    Queried,
    BasedError,
  ),
  on_execute handle_execute: fn(String, conn) -> Result(
    Int,
    BasedError,
  ),
  on_batch handle_batch: fn(List(sql.Query(v)), conn) -> Result(
    List(Queried),
    BasedError,
  ),
) -> Driver(v, conn)

Returns a configured Driver record.

error_to_string

</>

pub fn error_to_string(err: BasedError) -> String

execute

</>

pub fn execute(
  sql: String,
  db: Db(v, conn),
) -> Result(Int, BasedError)

Executes a raw SQL string using the configured driver.

new

</>

pub fn new(
  driver: Driver(v, conn),
  sql: sql.Adapter(v),
) -> Db(v, conn)

Creates a new Db from a driver and adapter.

one

</>

pub fn one(
  query: sql.Query(v),
  db: Db(v, conn),
  decoder: decode.Decoder(a),
) -> Result(a, BasedError)

A convenience function for callers performing a query that will return only one row. It’s up to callers to ensure they’re providing the correct SQL query to avoid decoding n rows and then losing all but the first. Returns Error(NotFound) if the query returns zero rows.

query

</>

pub fn query(
  query: sql.Query(v),
  db: Db(v, conn),
) -> Result(Queried, BasedError)

Executes a query using the configured driver.

transaction

</>

pub fn transaction(
  db: Db(v, conn),
  handler: fn(conn, fn(conn) -> Result(t, error)) -> Result(
    t,
    TransactionError(error),
  ),
  next: fn(Db(v, conn)) -> Result(t, error),
) -> Result(t, TransactionError(error))

Runs next inside a database transaction using the provided handler.

The handler (supplied by an adapter package) is responsible for beginning the transaction, committing on success, and rolling back on failure.