Reglas de Nomenclatura y Estilo

Una nomenclatura SQL consistente reduce la carga cognitiva en migraciones, ORMs, herramientas de BI y sesiones de grep de guardia. Elige convenciones una vez, documéntalas en un ADR y aplícalas en la revisión.

Receta

-- Convenciones preferidas (ejemplo de ADR de equipo)
CREATE SCHEMA app;
 
CREATE TABLE app.order (          -- elección de ADR de tabla singular
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  customer_id bigint NOT NULL REFERENCES app.customer (id),
  placed_at timestamptz NOT NULL DEFAULT now(),
  status text NOT NULL CHECK (status IN ('open', 'shipped', 'cancelled'))
);
 
CREATE INDEX idx_order_customer_placed
  ON app.order (customer_id, placed_at DESC);

Cuándo usar esto: Arranque de un nuevo servicio, configuración de linter (SQLFluff) o refactorización de esquemas legacy en camelCase.

Ejemplo de Trabajo

-- Nomenclatura de restricciones
ALTER TABLE app.order
  ADD CONSTRAINT fk_order_customer
  FOREIGN KEY (customer_id) REFERENCES app.customer (id);
 
ALTER TABLE app.order
  ADD CONSTRAINT ck_order_status
  CHECK (status IN ('open', 'shipped', 'cancelled'));
 
-- Nomenclatura de vistas
CREATE VIEW app.v_order_summary AS
SELECT customer_id, count(*) AS order_count
FROM app.order
GROUP BY customer_id;

Extracto de la guía de estilo:

Profundización

Tablas Singulares vs. Plurales

Singular (order, customer):

• Se alinea con la clase de entidad ORM Order
• La FK se lee de forma natural: order.customer_id

Plural (orders, customers):

• Coincide con el SQL hablado ("select from orders")
• Popular en ecosistemas Rails

Regla: Cualquiera de las dos es válida - nunca mezcles en una misma base de datos. El legacy existente elige el ADR; los equipos nuevos eligen y documentan.

snake_case en Todas Partes

-- Evitar
CREATE TABLE app.OrderItems (orderItemId bigint);
 
-- Preferir
CREATE TABLE app.order_item (order_item_id bigint);  -- si el ADR es singular

• PostgreSQL convierte los identificadores sin comillas a minúsculas; usar comillas para "camelCase" es una trampa permanente.
• snake_case funciona sin identificadores entre comillas en todos los clientes.

Columnas de Marca de Tiempo y Dinero

placed_at timestamptz NOT NULL   -- instantes
amount_cents bigint NOT NULL     -- dinero como unidades menores enteras
currency_code char(3) NOT NULL   -- ISO 4217

• Nunca timestamp without time zone para eventos del mundo real.
• amount_cents es mejor que float para el dinero.

Documentación con Comentarios

COMMENT ON TABLE app.order IS 'Cabecera de compra del cliente; ámbito de inquilino a través de RLS';
COMMENT ON COLUMN app.order.status IS 'open|shipped|cancelled; expandir mediante migración';

• Los comentarios aparecen en pgAdmin/DBeaver y \d+.
• Documenta los valores CHECK similares a enum cuando no se usa el tipo ENUM de PostgreSQL.

Trampas

• Identificadores de mayúsculas/minúsculas entre comillas - Requieren comillas para siempre en cada consulta. Solución: Renombrar en una migración de expansión/contracción a snake_case.
• Palabras reservadas como nombres - user, order necesitan comillas o renombrarse (app_user, sales_order). Solución: Prefijar o sufijar nombres reservados.
• Sopa de abreviaturas - cust_ord_ln ahorra escritura, pierde legibilidad. Solución: Preferir palabras completas de menos de 30 caracteres.
• Nombres de índices inconsistentes - orders_customer_id_idx vs idx_order_customer. Solución: Una plantilla en la configuración de SQLFluff.
• Esquema public para todo - Riesgo de colisión y seguridad. Solución: Esquema de aplicación app con search_path explícito.

Alternativas

Preguntas Frecuentes

Relacionado

• Checklist de Reglas del Proyecto Postgres - reglas 1-5
• Conceptos Básicos de Migraciones - SQL en git
• Codificación y Localización del Cliente - opciones de intercalación

Versiones de Stack: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, y PostGIS 3.5+.