schema

Schema DSL

A fluent builder for defining database table schemas in Gleam. Schemas serve as the source of truth for code generation, migration generation, and type inference.

Types

Column Type

Represents a column definition within a table. Each column has a name, type, nullability flag, and optional default value.

pub type Column {
  Column(
    name: String,
    column_type: ColumnType,
    nullable: Bool,
    default: option.Option(Default),
    renamed_from: option.Option(String),
  )
}

Constructors

Column(
  name: String,
  column_type: ColumnType,
  nullable: Bool,
  default: option.Option(Default),
  renamed_from: option.Option(String),
)

ColumnDef Type

Wrapper for column definitions that allows single columns or multiple columns (like timestamps) to be used in the same list.

pub type ColumnDef {
  Single(Column)
  Multiple(List(Column))
}

Constructors

```
Single(Column)
```
```
Multiple(List(Column))
```

ColumnType Type

Defines the available column types that map to both PostgreSQL and SQLite data types. The codegen tool uses these to generate appropriate Gleam types and SQL DDL statements.

pub type ColumnType {
  Id
  String(max: option.Option(Int))
  Text
  Int
  BigInt
  Float
  Boolean
  Timestamp
  UnixTimestamp
  Date
  Json
  Uuid
  Foreign(table: String)
}

Constructors

```
Id
```
Auto-incrementing integer primary key
```
String(max: option.Option(Int))
```
Variable-length string with optional max length (VARCHAR)
```
Text
```
Unlimited text (TEXT)
```
Int
```
Standard integer (INT/INTEGER)
```
BigInt
```
Large integer (BIGINT)
```
Float
```
Floating point number (REAL/DOUBLE PRECISION)
```
Boolean
```
Boolean value (BOOLEAN/INTEGER for SQLite)
```
Timestamp
```
Timestamp with timezone (TIMESTAMP/TEXT for SQLite)
```
UnixTimestamp
```
Unix timestamp as integer seconds (INTEGER)
```
Date
```
Date without time (DATE/TEXT for SQLite)
```
Json
```
JSON data (JSONB for Postgres, TEXT for SQLite)
```
Uuid
```
UUID (UUID for Postgres, TEXT for SQLite)
```
Foreign(table: String)
```
Foreign key reference to another table

Default Type

Defines default values that can be assigned to columns. Used in migration generation to produce appropriate SQL DEFAULT clauses.

pub type Default {
  DefaultString(String)
  DefaultInt(Int)
  DefaultFloat(Float)
  DefaultBool(Bool)
  DefaultNow
  DefaultUnixNow
  DefaultAutoUuid
  DefaultNull
}

Constructors

```
DefaultString(String)
```
```
DefaultInt(Int)
```
```
DefaultFloat(Float)
```
```
DefaultBool(Bool)
```
```
DefaultNow
```
```
DefaultUnixNow
```
```
DefaultAutoUuid
```
```
DefaultNull
```

Table Type

Represents a database table definition with its name and column definitions.

pub type Table {
  Table(name: String, columns: List(Column))
}

Constructors

Table(name: String, columns: List(Column))

Values

auto_uuid

</>

pub fn auto_uuid(def: ColumnDef) -> ColumnDef

Set Default to Auto-Generated UUID

Sets the default value to an auto-generated UUID. Use with uuid columns for automatic unique identifier generation.

Maps to:

PostgreSQL: gen_random_uuid()
SQLite: Custom expression generating UUID v4 format

Example:

table("users", [
  uuid("external_id")
    |> auto_uuid(),
])

bigint

</>

pub fn bigint(name: String) -> ColumnDef

Add Big Integer Column

Creates a large integer column for values exceeding standard integer range.

Maps to:

PostgreSQL: name BIGINT
SQLite: name INTEGER

boolean

</>

pub fn boolean(name: String) -> ColumnDef

Add Boolean Column

Creates a boolean column.

Maps to:

PostgreSQL: name BOOLEAN
SQLite: name INTEGER (0 = false, 1 = true)

columns

</>

pub fn columns(t: Table) -> List(Column)

Get Columns

Returns the table’s columns in definition order.

date

</>

pub fn date(name: String) -> ColumnDef

Add Date Column

Creates a date column (without time component).

Maps to:

PostgreSQL: name DATE
SQLite: name TEXT (YYYY-MM-DD format)

default_bool

</>

pub fn default_bool(def: ColumnDef, value: Bool) -> ColumnDef

Set Boolean Default

Sets a boolean default value for the column.

Example:

table("users", [
  boolean("is_active")
    |> default_bool(True),
])

default_float

</>

pub fn default_float(def: ColumnDef, value: Float) -> ColumnDef

Set Float Default

Sets a float default value for the column.

Example:

table("products", [
  float("price")
    |> default_float(0.0),
])

default_int

</>

pub fn default_int(def: ColumnDef, value: Int) -> ColumnDef

Set Integer Default

Sets an integer default value for the column.

Example:

table("posts", [
  int("view_count")
    |> default_int(0),
])

default_now

</>

pub fn default_now(def: ColumnDef) -> ColumnDef

Set Default to Current Timestamp

Sets the default value to the current timestamp.

Example:

table("posts", [
  timestamp("published_at")
    |> default_now(),
])

default_null

</>

pub fn default_null(def: ColumnDef) -> ColumnDef

Set Default to NULL

Explicitly sets the default value to NULL.

Example:

table("users", [
  string("deleted_at")
    |> nullable()
    |> default_null(),
])

default_string

</>

pub fn default_string(def: ColumnDef, value: String) -> ColumnDef

Set String Default

Sets a string default value for the column.

Example:

table("users", [
  string("role")
    |> default_string("user"),
])

default_unix_now

</>

pub fn default_unix_now(def: ColumnDef) -> ColumnDef

Set Default to Current Unix Timestamp

Sets the default value to the current Unix timestamp (seconds since epoch). Use with unix_timestamp columns.

Example:

table("events", [
  unix_timestamp("created_at")
    |> default_unix_now(),
])

float

</>

pub fn float(name: String) -> ColumnDef

Add Float Column

Creates a floating-point number column.

Maps to:

PostgreSQL: name DOUBLE PRECISION
SQLite: name REAL

foreign

</>

pub fn foreign(name: String, references: String) -> ColumnDef

Add Foreign Key Column

Creates an integer column that references another table’s id. The column name should follow the convention {table}_id.

Maps to:

PostgreSQL: name INTEGER REFERENCES table(id)
SQLite: name INTEGER REFERENCES table(id)

Example:

table("posts", [
  id(),
  foreign("user_id", "users"),
  string("title"),
])

id

</>

pub fn id() -> ColumnDef

Add ID Column

Creates an auto-incrementing integer primary key column named “id”. This is typically the first column in a table.

Maps to:

PostgreSQL: id SERIAL PRIMARY KEY
SQLite: id INTEGER PRIMARY KEY AUTOINCREMENT

int

</>

pub fn int(name: String) -> ColumnDef

Add Integer Column

Creates a standard integer column.

Maps to:

PostgreSQL: name INTEGER
SQLite: name INTEGER

json

</>

pub fn json(name: String) -> ColumnDef

Add JSON Column

Creates a JSON column for structured data.

Maps to:

PostgreSQL: name JSONB
SQLite: name TEXT

nullable

</>

pub fn nullable(def: ColumnDef) -> ColumnDef

Make Column Nullable

Marks the column as nullable (allows NULL). By default, columns are NOT NULL.

Example:

table("users", [
  id(),
  string("name"),
  string("bio")
    |> nullable(),
])

rename_from

</>

pub fn rename_from(def: ColumnDef, old_name: String) -> ColumnDef

Rename Column

Indicates that this column was renamed from a previous name. The migration generator will use RENAME COLUMN instead of drop/add, preserving data. This modifier is automatically removed from the schema after the migration is generated.

Example:

table("users", [
  string("email_address")
    |> rename_from("email"),
])

string

</>

pub fn string(name: String) -> ColumnDef

Add String Column

Creates a VARCHAR(255) column with the given name.

Maps to:

PostgreSQL: name VARCHAR(255)
SQLite: name TEXT

string_sized

</>

pub fn string_sized(name: String, max: Int) -> ColumnDef

Add Sized String Column

Creates a VARCHAR column with a specific maximum length.

Maps to:

PostgreSQL: name VARCHAR(max)
SQLite: name TEXT

table

</>

pub fn table(name: String, column_defs: List(ColumnDef)) -> Table

Create Table

Creates a new table definition with the given name and column definitions.

Example:

import glimr/db/schema.{table, id, string, timestamps}

pub const name = "users"

pub fn definition() {
  table(name, [
    id(),
    string("name"),
    string("email"),
    timestamps(),
  ])
}

text

</>

pub fn text(name: String) -> ColumnDef

Add Text Column

Creates an unlimited text column. Use for large text content like blog posts, descriptions, etc.

Maps to:

PostgreSQL: name TEXT
SQLite: name TEXT

timestamp

</>

pub fn timestamp(name: String) -> ColumnDef

Add Timestamp Column

Creates a timestamp column for date/time values.

Maps to:

PostgreSQL: name TIMESTAMP WITH TIME ZONE
SQLite: name TEXT (ISO 8601 format)

timestamps

</>

pub fn timestamps() -> ColumnDef

Add Timestamp Columns

Creates both created_at and updated_at timestamp columns. This is a convenience function for the common pattern of tracking record creation and modification times.

unix_timestamp

</>

pub fn unix_timestamp(name: String) -> ColumnDef

Add Unix Timestamp Column

Creates an integer column for storing Unix timestamps (seconds since epoch).

Maps to:

PostgreSQL: name BIGINT
SQLite: name INTEGER

unix_timestamps

</>

pub fn unix_timestamps() -> ColumnDef

Add Unix Timestamp Columns

Creates both created_at and updated_at as unix timestamp columns (integer seconds since epoch). This is a convenience function for the common pattern of tracking record creation and modification times using integer timestamps.

uuid

</>

pub fn uuid(name: String) -> ColumnDef

Add UUID Column

Creates a UUID column for universally unique identifiers.

Maps to:

PostgreSQL: name UUID
SQLite: name TEXT