---
title: Scalars Overview
description: Scalar types for database columns with chainable modifiers
icon: columns
---

## 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](/docs/schema/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:

```ts
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](https://standardschema.dev/) 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.

## Pages

**[String](/docs/schema/scalars/string)**

**[Number](/docs/schema/scalars/number)**

**[Decimal](/docs/schema/scalars/decimal)**

**[Boolean](/docs/schema/scalars/boolean)**

**[DateTime](/docs/schema/scalars/datetime)**

**[BigInt](/docs/schema/scalars/bigint)**

**[JSON](/docs/schema/scalars/json)**

**[Blob](/docs/schema/scalars/blob)**

**[Enum](/docs/schema/scalars/enum)**

**[GeoPoint](/docs/schema/scalars/point)**

**[Vector](/docs/schema/scalars/vector)**
