documentación-postgresql

Documentación de PostgreSQL

Reglas de la documentación de PostgreSQL 18 que es probable que un modelo acierte mal: valores predeterminados sorprendentes, trampas de bloqueo y concurrencia, cambios en PostgreSQL 18 y los patrones que recomienda la documentación. Cada regla termina con la URL de la documentación que la respalda.

Versión cubierta

Las referencias siguen la documentación de PostgreSQL 18 (versión menor 18.6). Los hechos que solo son válidos a partir de la versión 18 dicen "PostgreSQL 18". Verifique primero la versión del servidor. En un servidor más antiguo, trate cada regla de "PostgreSQL 18" como no disponible.

Cómo navegar

Lea solo la referencia que necesita la tarea, de la tabla a continuación. Fuentes: SOURCES.md.

Reglas rápidas

1. En PostgreSQL 18, una columna generada sin una palabra clave es VIRTUAL, calculada en la lectura. Escriba STORED para estadísticas o replicación lógica. https://www.postgresql.org/docs/18/ddl-generated-columns.html https://www.postgresql.org/docs/18/sql-altertable.html
2. Use columnas de identidad, no serial. Una columna de identidad es NOT NULL pero no única: agregue la PRIMARY KEY. https://www.postgresql.org/docs/18/ddl-identity-columns.html
3. Indexe usted mismo las columnas de referencia de cada clave externa. PostgreSQL solo indexa el lado referenciado. https://www.postgresql.org/docs/18/ddl-constraints.html
4. CREATE INDEX simple bloquea las escrituras durante toda la construcción. En tablas activas use CREATE INDEX CONCURRENTLY fuera de un bloque de transacción y elimine el índice INVALID que deja en caso de error. https://www.postgresql.org/docs/18/sql-createindex.html
5. Agregue restricciones a tablas grandes como NOT VALID, luego VALIDATE CONSTRAINT, que no bloquea las escrituras. PostgreSQL 18 acepta esto también para NOT NULL. https://www.postgresql.org/docs/18/sql-altertable.html
6. ADD COLUMN con un valor predeterminado volátil, una columna generada almacenada o una identidad reescribe toda la tabla bajo ACCESS EXCLUSIVE. Un valor predeterminado no volátil no lo hace. https://www.postgresql.org/docs/18/sql-altertable.html
7. Establezca lock_timeout en las sesiones de migración, y statement_timeout, lock_timeout y transaction_timeout por rol o sesión, nunca de forma global. https://www.postgresql.org/docs/18/runtime-config-client.html
8. Upsert con INSERT ... ON CONFLICT (cols) DO UPDATE, que en READ COMMITTED siempre inserta o actualiza bajo concurrencia. MERGE puede fallar con una violación de unicidad cuando otra sesión inserta la misma clave. https://www.postgresql.org/docs/18/transaction-iso.html
9. Reintente toda la transacción en SQLSTATE 40001 y 40P01. PostgreSQL nunca reintenta por sí mismo. Pruebe el SQLSTATE, no el mensaje. https://www.postgresql.org/docs/18/mvcc-serialization-failure-handling.html
10. El aislamiento predeterminado es READ COMMITTED: cada sentencia ve una nueva instantánea. Las reglas de negocio de varias filas necesitan SERIALIZABLE o bloqueos explícitos. https://www.postgresql.org/docs/18/transaction-iso.html https://www.postgresql.org/docs/18/applevel-consistency.html
11. Para colas de trabajos use SELECT ... FOR UPDATE SKIP LOCKED, y FOR NO KEY UPDATE cuando las claves permanezcan sin cambios. https://www.postgresql.org/docs/18/sql-select.html https://www.postgresql.org/docs/18/explicit-locking.html
12. NOT IN con un NULL en la lista o subconsulta nunca es verdadero. Las funciones de agregación distintas de count devuelven NULL sobre cero filas. https://www.postgresql.org/docs/18/functions-comparisons.html https://www.postgresql.org/docs/18/functions-aggregate.html
13. La paginación y LIMIT necesitan un ORDER BY en una clave única; de lo contrario, los resultados difieren entre ejecuciones. https://www.postgresql.org/docs/18/queries-limit.html
14. Almacene los instantes como timestamptz. TIMESTAMP '2004-10-19 10:23:54+02' es una marca de tiempo sin zona horaria y el desplazamiento se descarta. https://www.postgresql.org/docs/18/datatype-datetime.html
15. now() es la hora de inicio de la transacción. Use clock_timestamp() para la hora real. Nunca use el valor predeterminado de la cadena 'now'. https://www.postgresql.org/docs/18/functions-datetime.html
16. Use jsonb, indexado con GIN (col jsonb_path_ops) para consultas @>. El operador debe aplicarse a la expresión indexada para que se utilice el índice. https://www.postgresql.org/docs/18/datatype-json.html
17. PostgreSQL 18 agrega uuidv7(), un UUID ordenado por tiempo, junto a gen_random_uuid(). https://www.postgresql.org/docs/18/functions-uuid.html
18. PostgreSQL 18 RETURNING lee old.col y new.col en INSERT, UPDATE, DELETE y MERGE. https://www.postgresql.org/docs/18/dml-returning.html
19. EXPLAIN ANALYZE ejecuta la sentencia: envuelva las escrituras en BEGIN ... ROLLBACK. En PostgreSQL 18 incluye BUFFERS automáticamente. https://www.postgresql.org/docs/18/sql-explain.html https://www.postgresql.org/docs/18/using-explain.html
20. Un árbol B multicolumna puede servir una consulta sin su columna principal en PostgreSQL 18 (escaneo de salto), pero solo cuando esa columna tiene pocos valores distintos. https://www.postgresql.org/docs/18/indexes-multicolumn.html
21. Mantenga autovacuum activado y evite VACUUM FULL. Autovacuum nunca analiza tablas particionadas o tablas temporales: analícelas usted mismo. https://www.postgresql.org/docs/18/routine-vacuuming.html
22. La seguridad a nivel de fila no hace nada hasta ENABLE ROW LEVEL SECURITY, y los propietarios de tablas la omiten a menos que FORCE ROW LEVEL SECURITY. https://www.postgresql.org/docs/18/ddl-rowsecurity.html
23. Una función SECURITY DEFINER necesita SET search_path = trusted_schema, pg_temp y EXECUTE revocado de PUBLIC en la misma transacción. https://www.postgresql.org/docs/18/sql-createfunction.html
24. Conceder una tabla no se extiende a las secuencias que utiliza, incluidas las de las columnas serial. Establezca los privilegios de las secuencias por separado. https://www.postgresql.org/docs/18/sql-grant.html
25. Los clientes usan sslmode=prefer de forma predeterminada, que no verifica el servidor. Use sslmode=verify-full. https://www.postgresql.org/docs/18/libpq-ssl.html
26. Construya SQL dinámico con format('%I', ident) y EXECUTE ... USING para los valores, nunca por concatenación. https://www.postgresql.org/docs/18/plpgsql-statements.html
27. Los índices de expresión de búsqueda de texto completo deben usar to_tsvector('english', col) de 2 argumentos, y las consultas deben repetir esa forma exacta. https://www.postgresql.org/docs/18/textsearch-tables.html

Referencias

Referencia	Léala cuando
schema-design.md	Crear tablas: identidad y secuencias, columnas generadas, restricciones, claves temporales, dominios, esquemas y search_path, diseño de particiones
migrations-and-locks.md	Escribir una migración: niveles de bloqueo y reescrituras de ALTER TABLE, NOT VALID, construcciones de índices concurrentes, REINDEX, adjuntar y desadjuntar particiones
data-types.md	Elegir tipos numéricos, texto, bytea, enum, UUID, array o rango, restricciones de exclusión en rangos
datetime.md	Cualquier cosa con marcas de tiempo, zonas horarias, intervalos, extract, date_trunc, to_char, to_timestamp
json.md	Almacenar, consultar, indexar o actualizar JSONB, jsonpath, JSON_VALUE, JSON_TABLE, agregados JSON
queries.md	Lógica SELECT: semántica NULL, uniones, LATERAL, agrupación, agregados, funciones de ventana, paginación, UNION, CTEs
writes.md	INSERT ON CONFLICT, uniones UPDATE y DELETE, agrupación de cambios grandes, RETURNING, MERGE, COPY, carga masiva
indexes.md	Elegir o revisar un índice: tipos, orden de columnas, escaneo de salto, parcial, expresión, INCLUDE, pattern_ops, GIN, BRIN
concurrency.md	Niveles de aislamiento, reintentos, bloqueos de filas y tablas, interbloqueos, bloqueos de asesoramiento, tiempos de espera, LISTEN y NOTIFY
performance.md	Leer EXPLAIN, estadísticas y estadísticas extendidas, vaciado, configuración de memoria y planificador, consultas paralelas, pg_stat_statements
security.md	GRANT y privilegios predeterminados, roles, seguridad a nivel de fila, SECURITY DEFINER, contraseñas, TLS y parámetros de conexión libpq
plpgsql-triggers.md	Escribir funciones, PL/pgSQL, SQL dinámico, excepciones, disparadores, procedimientos
text-search.md	Funciones de cadena, LIKE y expresiones regulares, comillas, búsqueda de texto completo con tsvector, clasificación, ts_headline

Cambios en PostgreSQL 18 a tener en cuenta al actualizar

• initdb habilita las sumas de comprobación de datos de forma predeterminada, y pg_upgrade necesita configuraciones coincidentes. https://www.postgresql.org/docs/18/release-18.html
• VACUUM y ANALYZE en una tabla particionada también procesan sus particiones. Escriba ONLY para la tabla principal sola. https://www.postgresql.org/docs/18/release-18.html
• pg_upgrade conserva las estadísticas del planificador pero no las estadísticas extendidas. https://www.postgresql.org/docs/18/release-18.html
• Los disparadores AFTER se ejecutan como el rol activo cuando se puso en cola el evento. https://www.postgresql.org/docs/18/release-18.html
• E/S asíncrona (io_method, predeterminado worker), y effective_io_concurrency predeterminado a 16. https://www.postgresql.org/docs/18/runtime-config-resource.html

Patrones antiguos

Antiguo	Actual
Literales 'now' o 'today' en valores predeterminados	now(), CURRENT_DATE (https://www.postgresql.org/docs/18/datatype-datetime.html)
Contraseñas MD5, método de autenticación password	scram-sha-256 (https://www.postgresql.org/docs/18/auth-password.html)