Auto-incrementing identifiers
A PostgreSQL table needs a database-generated numeric identifier.
Drizzle ORM · Function
serial
serial() declares a PostgreSQL auto-incrementing four-byte integer column. It is commonly used for generated identifier columns, often with .primaryKey().
How it works
serial() declares a PostgreSQL auto-incrementing four-byte integer column. Calling .primaryKey() makes it the table's primary key, while Drizzle generates the corresponding PostgreSQL serial column declaration.
Syntax
serial(name?)Parameters
| Name | Type | Description |
|---|---|---|
name/config | string or configuration object, optional | Optional column name and PostgreSQL serial-column configuration accepted by the Drizzle declaration. |
Returns
A PostgreSQL serial integer column builder used in a pgTable schema.
Key points
- In PostgreSQL,
serial()represents an auto-incrementing four-byte integer and is intended as a convenient identifier-column declaration. - Import
serialfromdrizzle-orm/pg-coreand use it within apgTableschema definition. - Chain
.primaryKey()ontoserial()when the generated identifier should be the table's primary key. - Drizzle maps the declaration to a PostgreSQL
serialcolumn in the generated table definition.
Example: PostgreSQL serial primary key
import { pgTable, serial, text } from "drizzle-orm/pg-core";
export const users = pgTable("users", {
id: serial().primaryKey(),
name: text().notNull(),
});Defines a PostgreSQL users table with an auto-incrementing serial primary key.
When to use it
Serial primary keys
A schema models a conventional relational primary key.
Typed PostgreSQL schema declarations
A Drizzle schema should express PostgreSQL serial semantics with type safety.
Interview questions
QWhat does Drizzle's PostgreSQL serial() declaration represent?
serial() is a convenience declaration for an auto-incrementing four-byte integer. It is commonly used for unique identifier columns and can be combined with .primaryKey().
Follow-up: How would you model an auto-incrementing eight-byte identifier? Use the PostgreSQL big integer identity or serial-related type documented for that database rather than serial(), which is four bytes.
QHow do you declare a serial primary key in a PostgreSQL table?
The declaration is imported from drizzle-orm/pg-core and used inside a pgTable definition. Drizzle emits a PostgreSQL serial column, and .primaryKey() adds the primary-key constraint.
Follow-up: What SQL shape should be expected for the example? A table containing an id serial PRIMARY KEY column, alongside the other declared columns.
QWhy use serial for identifiers?
serial is a notational convenience for creating unique identifier columns with automatic numbering. The generated database column is backed by PostgreSQL's serial behavior rather than an application-side counter.
Follow-up: Why prefer a database-generated identifier here? The database assigns values consistently during inserts and avoids requiring application code to coordinate the next identifier.
Related
serial4pgTableprimaryKeyinteger