Scalars Overview
Scalar types for database columns with chainable modifiers
Scalar Types
| Scalar | TypeScript | Use for |
|---|---|---|
s.string() |
string |
Text, IDs, emails |
s.int() |
number |
Whole numbers, counts |
s.number() |
number |
Approximate decimals |
s.decimal({ precision, scale }) |
Decimal |
Exact fixed decimals, money |
s.bigInt() |
bigint |
Integers beyond 2^53 |
s.boolean() |
boolean |
Flags |
s.dateTime() |
Date |
Timestamps |
s.date() |
Date |
Calendar dates (no time) |
s.time() |
string |
Time of day (no date) |
s.json() |
unknown (or inferred via .schema()) |
Structured data |
s.blob() |
Uint8Array |
Binary data |
s.enum([...]) |
Union of the values | Fixed value sets |
s.point() |
{ longitude, latitude } |
Geographic points |
s.vector() |
number[] |
Embeddings (PostgreSQL pgvector) |
Database column types for each scalar — defaults and per-database overrides — live on Native Types. A factory that takes a native type accepts either one database’s constant or a map with one entry per database ({ pg, mysql, sqlite }); each migration reads only its own database’s entry.
Modifier Reference
Every modifier returns a new scalar instance, so they chain:
s.string()
.nullable() // string | null
.unique() // Unique constraint
.default("hello") // Static default; .default(() => ...) for runtime defaults
.map("column_name"); // Custom database column name
| Method | Effect | Type impact |
|---|---|---|
.nullable() |
Allow NULL | T | null |
.array() |
Array column (native on PG, JSON on MySQL/SQLite) | T[] |
.id() |
Primary key | — |
.unique() |
Unique constraint | — |
.default(v) / .default(() => v) |
Default value | Optional in create |
.schema(s) |
Extra Standard Schema validation | May narrow T |
.map(name) |
Custom column name | — |
Support Matrix
Not every modifier exists on every scalar:
| Scalar | .id() |
.unique() |
.array() |
.schema() |
Scalar-specific methods |
|---|---|---|---|---|---|
string |
✓ | ✓ | ✓ | ✓ | .uuid() .uuidv7() .ulid() .ksuid() .nanoid() .cuid() |
int |
✓ | ✓ | ✓ | ✓ | .increment() |
number |
✓ | ✓ | ✓ | ✓ | — |
decimal |
✓ scalar only | ✓ scalar only | ✓ | ✓ | required { precision, scale } |
bigInt |
✓ | ✓ | ✓ | ✓ | .increment() |
boolean |
— | — | ✓ | — | — |
dateTime |
✓ | ✓ | ✓ | ✓ | .now() .updatedAt() .withoutTimezone() |
date |
✓ | ✓ | ✓ | ✓ | .now() .updatedAt() |
time |
✓ | ✓ | ✓ | ✓ | .now() .updatedAt() .withoutTimezone() |
json |
— | — | — | ✓ | — |
blob |
— | — | — | — | — |
enum |
— | — | ✓ | — | .name() |
point |
— | — | — | — | bounds, polygon and distance query language |
vector |
— | — | — | — | .dimension() |
.nullable(), .default(), and .map() are available on every scalar. The scalar pages below only document their scalar-specific methods.
.nullable() preserves an existing literal or generated default; it supplies
null only when no default was declared. .schema() remains attached through
.nullable() and .array(). On lists, the custom schema validates each member,
including values supplied to push and unshift.
Custom schemas apply to writes. Filters validate the stored value domain and
do not repeat write transformations. Arithmetic updates on a field with
.schema() are refused because checking the delta cannot prove the resulting
stored value satisfies that schema. Use set with a validated value instead.
A fixed-decimal list cannot be an ID, unique field, index member, compound-key member, foreign-key member, or relation identity member. Its scalar form can use key positions normally.