ALTER COLUMN TYPE bloqueó la tabla o perdió precisión: qué hacer

VERICTO-018 Alta En CI (CLI offline): FLAGGED

ALTER TABLE orders ALTER COLUMN total TYPE integer; hace dos cosas que quizá no quieras. Si total era numeric, cada valor se redondea a un entero, así que los centavos desaparecen. Y PostgreSQL reescribe la tabla con un lock ACCESS EXCLUSIVE, que bloquea lecturas y escrituras hasta que termina. Si la sentencia todavía corre, cancelarla la deshace; si los valores ya se redondearon, los originales solo están en un backup.

Cómo recuperar los datos

  • Si el ALTER todavía corre y bloquea el tráfico, cancélalo (SELECT pg_cancel_backend(pid)); el cambio se deshace.
  • Si terminó y los valores se redondearon o truncaron, restaura una copia a un punto en el tiempo justo anterior en una instancia separada.
  • Copia los valores originales por clave primaria a una columna nueva del tipo correcto (por ejemplo total_cents bigint), en lugar de volver a convertir la columna dañada.

Por qué pasa

Un cambio de tipo parece una edición pequeña en una migración, pero la mayoría no son solo de metadatos: la base tiene que convertir y reescribir cada fila. Los casts que reducen (numeric a integer, bigint a integer, text a varchar(n)) redondean, fallan con valores fuera de rango o, en MySQL sin modo estricto, truncan con solo un warning.

Cómo corregirlo

Usa una migración aditiva: agrega una columna nueva con el tipo nuevo, complétala por lotes, mueve el código a ella y borra la columna vieja más adelante.

ALTER TABLE orders ADD COLUMN total_cents bigint;
UPDATE orders SET total_cents = round(total * 100) WHERE total_cents IS NULL;

En PostgreSQL, define un lock_timeout en las migraciones para que un ALTER bloqueado falle rápido en lugar de esperar detrás de transacciones largas.

Cómo evitar que vuelva a pasar

VERICTO-018 · ALTER TABLE ALTER COLUMN TYPE · Severidad: Alta · Nodo del AST: AlterTableStmt > AlterColumnType

La sentencia que la regla reporta

-- migrations/0048_total_type.sql
ALTER TABLE orders ALTER COLUMN total TYPE integer;

Salida real de la CLI

$ npx @vericto/vericto-cli@2.3.0 check --offline migrations/0048_total_type.sql
note: offline mode: 42 standard rules at default severities, engine 5.1.0. Custom rules, overrides, sensitive columns, allowlists and the audit trail apply online only.
! migrations/0048_total_type.sql  FLAGGED  VERICTO-018 high
    AlterTableStmt > AlterColumnType
    fix: Use an additive migration (new column + backfill + swap)
0 blocked · 0 allowed · 1 flagged · 0 monitored   (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))

En un archivo de migración la CLI la marca como FLAGGED y sale con 0: un cambio de esquema en una migración suele ser intencional, así que se señala para revisión en lugar de bloquearse. Con --fail-on flag (o fail_on = "flag" en .vericto.toml) sale con 1 y el job falla. Fuera de una migración (--sql, stdin u otro archivo) la bloquea, como el proxy y check_sql de MCP.

La versión corregida

-- migrations/0048_total_type.sql
ALTER TABLE orders ADD COLUMN total_cents bigint;
$ npx @vericto/vericto-cli@2.3.0 check --offline migrations/0048_total_type.sql
note: offline mode: 42 standard rules at default severities, engine 5.1.0. Custom rules, overrides, sensitive columns, allowlists and the audit trail apply online only.
0 blocked · 1 allowed · 0 flagged · 0 monitored   (ruleset standard@engine-5.1.0 · mode: offline (engine 5.1.0, 42 standard rules, no workspace policy))

Pruébalo gratis, sin cuenta

La CLI revisa tus archivos .sql en tu máquina con las 42 reglas estándar: sin registro, sin API key y sin que el SQL salga de tu equipo. Es open source (AGPL-3.0-only).

npx @vericto/vericto-cli@2.3.0 check --offline migrations/

En cada pull request

La GitHub Action vericto/check-sql (Apache-2.0) corre la misma revisión offline sobre los archivos .sql que cambia el PR y anota los hallazgos en el PR. Guárdala como .github/workflows/vericto.yml:

on: pull_request
jobs:
  vericto:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with: { fetch-depth: 0 }
      - uses: vericto/check-sql@v1
        with: { offline: true, upload-sarif: false }

En runtime, para agentes de IA

El SQL que escribe un agente de IA no pasa por un PR. El proxy TCP de Vericto revisa cada sentencia entre la aplicación o el agente y la base de datos, y la herramienta check_sql de MCP deja que el agente compruebe el SQL antes de ejecutarlo. Los dos usan el perfil de runtime, que también bloquea los cambios de esquema.

La condición AST en el engine

La regla es un predicado determinístico sobre el AST, en src/rules/evaluator.rs del engine open source (AGPL-3.0-only), en el commit de esta página:

"VERICTO-018" => find(stmts, |s| {
    s.kind == StatementKind::AlterTable
        && matches!(s.alter_table_kind, Some(AlterTableKind::AlterColumnType))
})
.map(|s| {
    let mut v = violation(
        rule,
        s,
        Some("Use an additive migration (new column + backfill + swap)".to_string()),
    );
    v.ast_node_path = "AlterTableStmt > AlterColumnType".to_string();
    v
}),

Preguntas frecuentes