Menu

Clave primaria en PostgreSQL: identity, SERIAL y UUID

Cómo definir una clave primaria en PostgreSQL y cómo generarla: columnas identity, el antiguo SERIAL y UUID con gen_random_uuid(). También claves compuestas y cómo reiniciar una secuencia.

Esta página incluye editores ejecutables: edita, ejecuta y ve el resultado al instante.

Una clave primaria es la columna, o el conjunto de columnas, que identifica cada fila. Sus valores tienen que ser únicos y no NULL, y una tabla solo puede tener una. En PostgreSQL lo normal es dejar que la base de datos la genere con una columna identity: id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY.

Los ids son 1 y 2. Definir la clave también crea un índice único sobre ella, llamado users_pkey.

Columnas identity: ALWAYS frente a BY DEFAULT

Las columnas identity son la forma estándar de SQL para numerar filas, disponible desde PostgreSQL 10. Hay dos variantes:

  • GENERATED ALWAYS AS IDENTITY rechaza un valor explícito en el INSERT, salvo que el insert indique OVERRIDING SYSTEM VALUE. Es la opción más segura.
  • GENERATED BY DEFAULT AS IDENTITY usa el valor generado solo cuando no das uno.

Con BY DEFAULT, insertar tus propios ids deja la secuencia atrás, y el siguiente id generado choca. Después de importar filas con ids explícitos, adelanta la secuencia más allá del mayor con setval:

Sin la línea de setval, el último insert recibiría el id 1 y fallaría con un error de clave duplicada. Con ella, la fila nueva recibe el 4.

SERIAL frente a identity

serial (4 bytes) y bigserial (8 bytes) no son tipos reales. Son una abreviatura que crea una secuencia y pone como valor por defecto de la columna su nextval():

La columna es un simple integer con el valor por defecto nextval('legacy_id_seq'::regclass). Nada impide que un insert escriba su propio id, y la secuencia necesita sus propios permisos. Las columnas identity resuelven las dos cosas, así que úsalas en las tablas nuevas. serial sigue funcionando, y lo verás en esquemas y tutoriales antiguos.

Usa bigint (o bigserial) en las tablas que pueden crecer. Una clave integer se agota tras unos 2100 millones de valores.

Claves primarias UUID

gen_random_uuid() devuelve un UUID aleatorio de versión 4. Viene integrado desde PostgreSQL 13, así que no hace falta ninguna extensión:

Cada ejecución muestra ids distintos, de 36 caracteres cada uno en forma de texto. El tipo uuid los guarda en 16 bytes, así que úsalo en lugar de text. PostgreSQL 18 añade uuidv7(), que genera UUID ordenados por tiempo que se insertan en el orden del índice. En PostgreSQL 17, genéralos en tu aplicación.

Claves primarias compuestas

Una clave puede abarcar varias columnas, escrita en su propia línea dentro de CREATE TABLE. Es la clave natural de una tabla de enlace, donde cada par puede aparecer una sola vez:

El par repetido (1, 10) se omite, así que el recuento es 3. Para añadir una clave a una tabla existente, usa ALTER TABLE t ADD PRIMARY KEY (col). La página de ALTER TABLE explica los demás cambios. Otras tablas apuntan a la clave con claves foráneas.

Preguntas frecuentes

¿PostgreSQL tiene AUTO_INCREMENT?

No con ese nombre. La forma estándar es una columna identity, id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, disponible desde PostgreSQL 10. Los tipos antiguos serial y bigserial hacen lo mismo con una secuencia y un valor por defecto.

¿Por qué la secuencia de ids de PostgreSQL tiene huecos?

Una secuencia entrega un valor aunque el insert falle después o su transacción haga rollback, y ese valor nunca se reutiliza. Los huecos son normales e inofensivos, así que no cuentes con que los ids sean consecutivos.

¿Una clave primaria crea un índice en PostgreSQL?

Sí. Una clave primaria (y toda restricción UNIQUE) crea automáticamente un índice B-tree único, llamado tablename_pkey en el caso de la clave primaria.

¿Uso UUID o bigint como clave primaria?

Las claves identity bigint son más pequeñas (8 bytes frente a 16) y se insertan en el orden del índice. Los UUID se pueden generar en cualquier sitio sin consultar la base de datos y no revelan cuántas filas hay. Los UUID aleatorios reparten las inserciones por todo el índice, lo que cuesta más en tablas grandes.

Ilustración de los lenguajes de programación de Coddy

Aprende a programar con Coddy

Comenzar