glimr - v0.6.2

glimr/db/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

</>

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

ColumnDef

</>

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

ColumnType

</>

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

</>

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

</>

Represents a database table definition with its name and column definitions. Used as the source of truth for code generation, migrations, and type inference.

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

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

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

Creates a boolean column.

Maps to:

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

columns

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

Returns the table’s columns in definition order. Useful for iterating over columns when generating code or performing schema introspection.

date

</> 
pub fn date(name: String) -> ColumnDef

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

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

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

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

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

Sets the default value to NULL. Use with nullable columns to explicitly set NULL as the default rather than having no default value specified.

default_string

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

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

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

Creates a floating-point number column.

Maps to:

  • PostgreSQL: name DOUBLE PRECISION
  • SQLite: name REAL

foreign

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

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

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

Creates a standard integer column.

Maps to:

  • PostgreSQL: name INTEGER
  • SQLite: name INTEGER

json

</> 
pub fn json(name: String) -> ColumnDef

Creates a JSON column for structured data.

Maps to:

  • PostgreSQL: name JSONB
  • SQLite: name TEXT

nullable

</> 
pub fn nullable(def: ColumnDef) -> ColumnDef

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

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

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

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

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

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

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

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

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

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

Creates a UUID column for universally unique identifiers.

Maps to:

  • PostgreSQL: name UUID
  • SQLite: name TEXT
✨ Search Document