cake/param

A Param is a value that can be used in a query.

Param is the boxed value type used in prepared statements. Every piece of user-supplied data that enters a query should be wrapped in a Param so the driver can safely encode and transmit it separately from the SQL string.

Aliases

import cake/param as p

Concept

A Param carries a single typed value. It is never executed directly — it is bound to a placeholder (?) at query time. This separation is what makes Cake queries safe from SQL injection.

flowchart LR
    A[Gleam value] --> B[p.string, p.int, ...]
    B --> C[Param]
    C --> D[prepared statement]
    D --> E[placeholder ?]
    E --> F[driver encodes & binds]
    F --> G[SQL + params sent to DB]

Param Constructors

Each constructor wraps a Gleam value into the corresponding Param variant.

string(value: String) -> Param

p.string("hello world")

int(value: Int) -> Param

p.int(42)

float(value: Float) -> Param

p.float(3.14)

bool(value: Bool) -> Param

p.bool(True)

true() -> Param

Convenience for p.bool(True).

false() -> Param

Convenience for p.bool(False).

null() -> Param

Represents an SQL NULL. Use when a column value is unknown or intentionally absent.

p.null()

date(value: calendar.Date) -> Param

Wraps a Gleam calendar.Date into a Param suitable for DATE columns.

import gleam/time/calendar

p.date(calendar.from_iso_date("2025-01-15"))

Param Variants

The Param type has the following constructors:

| Constructor | Description |

Using Params in Queries

Params are typically created inside builder functions (e.g. i.string(), w.col()) rather than imported directly, but you can use cake/param convenience functions anywhere a Param is needed.

In WHERE conditions

import cake/select as s
import cake/where as w

s.new()
|> s.from_table("users")
|> s.col("name")
|> s.where(w.and([
    w.eq(w.col("age"), w.int(p.int(18))),
    w.eq(w.col("role"), w.string(p.string("admin"))),
]))
|> s.to_query

In INSERT values

import cake/insert as i

i.from_values("users", ["name", "age"], [
  i.row([
    i.string(p.string("Alice")),
    i.int(p.int(30)),
  ]),
])

In fragments

Params created via cake/param can be passed to f.prepared() in the same way as the convenience constructors in cake/fragment.

Full Example

import cake/insert as i
import cake/param as p
import cake/where as w
import gleam/time/calendar

type User {
  User(name: String, age: Int, active: Bool, registered: calendar.Date)
}

let user = User("Alice", 30, True, calendar.from_iso_date("2025-01-15"))

i.from_values("users", ["name", "age", "active", "registered"], [
  i.row([
    i.string(p.string(user.name)),
    i.int(p.int(user.age)),
    i.bool(p.bool(user.active)),
    i.date(p.date(user.registered)),
  ]),
])
|> i.to_query
// INSERT INTO users (name, age, active, registered) VALUES ($1, $2, $3, $4)

pub type Param {
  StringParam(value: String)
  IntParam(value: Int)
  FloatParam(value: Float)
  NullParam
  BoolParam(value: Bool)
  DateParam(value: calendar.Date)
}

pub fn bool(value: Bool) -> Param

pub fn date(value: calendar.Date) -> Param

pub fn float(value: Float) -> Param

pub fn int(value: Int) -> Param

pub fn null() -> Param

pub fn string(value: String) -> Param