Metadata and document fields
Store structured, schemaless application data in a PostgreSQL table.
Drizzle ORM · Function
json
Drizzle's json() builder declares a PostgreSQL JSON column. $type<T>() adds compile-time inference and checking for JSON values across defaults, inserts, and selects.
How it works
The json() column builder maps a PostgreSQL JSON column into a Drizzle schema. Add $type<T>() to describe the TypeScript shape and receive compile-time checking for defaults, inserts, and selected values; this does not validate runtime data.
Syntax
json(); json().$type<T>(); json().default(value); json().default(sql`...`);Returns
A PostgreSQL JSON column builder used in a pgTable schema.
Key points
json()represents textual JSON data according to RFC 7159.- The underlying PostgreSQL JSON behavior is documented by PostgreSQL itself.
- Use
$type<T>()when you want a JSON column to infer a particular object, array, or primitive shape. - The declared JSON type is checked across defaults, inserts, and selected schema values.
Common mistakes
$type<T>()only affects compile-time inference; it does not validate values at runtime.- The type annotation protects default, insert, and select schemas, but it is not a database-side runtime validator.
Example: Typed JSON column
import { json, pgTable } from "drizzle-orm/pg-core";
export const table = pgTable("table", {
metadata: json().$type<{ foo: string }>().default({ foo: "bar" }),
});Defines a PostgreSQL table with a JSON column whose inferred TypeScript shape is checked for the default value.
When to use it
Typed JSON inference
Make JSON objects or arrays statically typed in TypeScript.
Database defaults
Provide an object literal or SQL expression as the column default.
Interview questions
QHow do you declare a PostgreSQL JSON column in Drizzle?
Use json() from drizzle-orm/pg-core as a field in a pgTable definition. It represents PostgreSQL's JSON data type in the Drizzle schema.
Follow-up: How can the JSON value's TypeScript shape be constrained? Add $type<T>() to the builder, such as json().$type<string[]>().
QWhat does $type<T>() do on a JSON column?
Call $type<T>() on the JSON builder, where T is the desired TypeScript shape. Drizzle then checks that shape in defaults, inserts, and selected results at compile time.
Follow-up: What limitation remains? $type<T>() cannot perform runtime validation of values.
QHow can you define a default value for a JSON column?
A JSON column can receive a JavaScript object directly as a default, or a SQL expression through sql, such as sql\'{"foo": "bar"}'\. The generated schema uses PostgreSQL's json type.
Follow-up: Why use a SQL expression for a default? It lets the database receive an explicit SQL default expression rather than relying on a TypeScript object literal.
Related
pgTablesql$type<T>()PostgreSQL json