data_drain 0.2.0 → 0.2.2

data/docs/glue_pyspark_example.py

@@ -0,0 +1,60 @@
+"""
+Script de AWS Glue (PySpark) compatible con DataDrain::GlueRunner.
+
+Crear el Job en la consola de AWS Glue (Spark 4.0+) y usar este script como base.
+Argumentos requeridos: JOB_NAME, start_date, end_date, s3_bucket, s3_folder,
+db_url, db_user, db_password, db_table, partition_by.
+
+Personalizar la sección de columnas derivadas según las partition_keys de cada tabla.
+"""
+
+import sys
+from awsglue.utils import getResolvedOptions
+from pyspark.context import SparkContext
+from awsglue.context import GlueContext
+from awsglue.job import Job
+from pyspark.sql.functions import col, year, month
+
+args = getResolvedOptions(sys.argv, [
+    'JOB_NAME', 'start_date', 'end_date', 's3_bucket', 's3_folder',
+    'db_url', 'db_user', 'db_password', 'db_table', 'partition_by'
+])
+
+sc = SparkContext()
+glueContext = GlueContext(sc)
+spark = glueContext.spark_session
+job = Job(glueContext)
+job.init(args['JOB_NAME'], args)
+
+options = {
+    "url": args['db_url'],
+    "dbtable": args['db_table'],
+    "user": args['db_user'],
+    "password": args['db_password'],
+    "sampleQuery": (
+        f"SELECT * FROM {args['db_table']} "
+        f"WHERE created_at >= '{args['start_date']}' "
+        f"AND created_at < '{args['end_date']}'"
+    )
+}
+
+df = spark.read.format("jdbc").options(**options).load()
+
+# Agregar columnas derivadas necesarias para las particiones.
+# isp_id ya existe en la tabla fuente — solo agregar las que se calculan.
+# Personalizar esta seccion segun las partition_keys de cada tabla.
+df_final = (
+    df.withColumn("year", year(col("created_at")))
+      .withColumn("month", month(col("created_at")))
+)
+
+output_path = f"s3://{args['s3_bucket']}/{args['s3_folder']}/"
+partitions = args['partition_by'].split(",")
+
+(df_final.write.mode("overwrite")
+    .partitionBy(*partitions)
+    .format("parquet")
+    .option("compression", "zstd")
+    .save(output_path))
+
+job.commit()

data/lib/data_drain/configuration.rb

@@ -6,10 +6,10 @@ module DataDrain
   # Contenedor para todas las opciones de configuración del motor DataDrain.
   class Configuration
     attr_accessor :storage_mode, :aws_region,
-      :aws_access_key_id, :aws_secret_access_key,
-      :db_host, :db_port, :db_user, :db_pass, :db_name,
-      :batch_size, :throttle_delay, :logger, :limit_ram, :tmp_directory,
-      :idle_in_transaction_session_timeout
+                  :aws_access_key_id, :aws_secret_access_key,
+                  :db_host, :db_port, :db_user, :db_pass, :db_name,
+                  :batch_size, :throttle_delay, :logger, :limit_ram, :tmp_directory,
+                  :idle_in_transaction_session_timeout
 
     def initialize
       @storage_mode   = :local
@@ -20,12 +20,56 @@ module DataDrain
       @limit_ram      = nil # eg 2GB
       @tmp_directory  = nil # eg /tmp/duckdb_work
       @idle_in_transaction_session_timeout = 0
-      @logger         = Logger.new($stdout)
+      @logger = Logger.new($stdout)
     end
 
     # @return [String] Cadena de conexión optimizada para DuckDB.
     def duckdb_connection_string
       "postgresql://#{@db_user}:#{@db_pass}@#{@db_host}:#{@db_port}/#{@db_name}?options=-c%20idle_in_transaction_session_timeout%3D#{@idle_in_transaction_session_timeout}"
     end
+
+    # Valida invariantes generales (storage_mode + AWS si aplica).
+    # Llamado por FileIngestor#initialize y GlueRunner.run_and_wait.
+    #
+    # @raise [DataDrain::ConfigurationError]
+    def validate!
+      validate_storage_mode!
+      validate_aws_config! if storage_mode.to_sym == :s3
+    end
+
+    # Valida además las credenciales PostgreSQL.
+    # Llamado por Engine#initialize.
+    #
+    # @raise [DataDrain::ConfigurationError]
+    def validate_for_engine!
+      validate!
+      validate_db_config!
+    end
+
+    private
+
+    def validate_storage_mode!
+      return if %i[local s3].include?(storage_mode.to_sym)
+
+      raise DataDrain::ConfigurationError,
+            "storage_mode debe ser :local o :s3, recibido #{storage_mode.inspect}"
+    end
+
+    def validate_aws_config!
+      return unless aws_region.nil? || aws_region.to_s.empty?
+
+      raise DataDrain::ConfigurationError,
+            "aws_region es obligatorio con storage_mode = :s3"
+    end
+
+    def validate_db_config!
+      %i[db_host db_user db_name].each do |attr|
+        val = public_send(attr)
+        next unless val.nil? || val.to_s.empty?
+
+        raise DataDrain::ConfigurationError,
+              "config.#{attr} es obligatorio para Engine (storage_mode=#{storage_mode})"
+      end
+    end
   end
 end

data/lib/data_drain/engine.rb

@@ -42,6 +42,7 @@ module DataDrain
       @skip_export = options.fetch(:skip_export, false)
 
       @config = DataDrain.configuration
+      @config.validate_for_engine!
       @logger = @config.logger
       @adapter = DataDrain::Storage.adapter
 

data/lib/data_drain/file_ingestor.rb

@@ -25,6 +25,7 @@ module DataDrain
       @bucket = options[:bucket]
 
       @config = DataDrain.configuration
+      @config.validate!
       @logger = @config.logger
       @adapter = DataDrain::Storage.adapter
 

data/lib/data_drain/glue_runner.rb

@@ -14,22 +14,35 @@ module DataDrain
     # @param job_name [String] Nombre del Job en la consola de AWS.
     # @param arguments [Hash] Argumentos de ejecución (deben empezar con --).
     # @param polling_interval [Integer] Segundos de espera entre cada chequeo de estado.
+    # @param max_wait_seconds [Integer, nil] Timeout máximo en segundos.
+    #   nil = sin límite (comportamiento anterior).
     # @return [Boolean] true si el Job terminó exitosamente (SUCCEEDED).
-    # @raise [RuntimeError] Si el Job falla o se detiene.
-    def self.run_and_wait(job_name, arguments = {}, polling_interval: 30)
+    # @raise [DataDrain::Error] si max_wait_seconds excede antes de SUCCEEDED.
+    # @raise [RuntimeError] si el Job falla o se detiene.
+    def self.run_and_wait(job_name, arguments = {}, polling_interval: 30, max_wait_seconds: nil)
       config = DataDrain.configuration
+      config.validate!
       client = Aws::Glue::Client.new(region: config.aws_region)
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-      # Usamos el logger de la configuración directamente para el primer log antes de instanciar safe_log si fuera necesario
-      # Pero como extendemos Observability, usamos safe_log directamente.
-      @logger = config.logger 
+      @logger = config.logger
 
       safe_log(:info, "glue_runner.start", { job: job_name })
       resp = client.start_job_run(job_name: job_name, arguments: arguments)
       run_id = resp.job_run_id
 
       loop do
+        if max_wait_seconds &&
+           (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) > max_wait_seconds
+          safe_log(:error, "glue_runner.timeout", {
+                     job: job_name,
+                     run_id: run_id,
+                     max_wait_seconds: max_wait_seconds
+                   })
+          raise DataDrain::Error,
+                "Glue Job #{job_name} (Run ID: #{run_id}) excedió max_wait_seconds=#{max_wait_seconds}"
+        end
+
         run_info = client.get_job_run(job_name: job_name, run_id: run_id).job_run
         status = run_info.job_run_state
 
@@ -41,15 +54,14 @@ module DataDrain
         when "FAILED", "STOPPED", "TIMEOUT"
           duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
           error_metadata = { job: job_name, run_id: run_id, status: status, duration_s: duration.round(2) }
-          
-          if run_info.error_message
-            error_metadata[:error_message] = run_info.error_message.gsub("\"", "'")[0, 200]
-          end
+
+          error_metadata[:error_message] = run_info.error_message.gsub("\"", "'")[0, 200] if run_info.error_message
 
           safe_log(:error, "glue_runner.failed", error_metadata)
           raise "Glue Job #{job_name} (Run ID: #{run_id}) falló con estado #{status}."
         else
-          safe_log(:info, "glue_runner.polling", { job: job_name, run_id: run_id, status: status, next_check_in_s: polling_interval })
+          safe_log(:info, "glue_runner.polling",
+                   { job: job_name, run_id: run_id, status: status, next_check_in_s: polling_interval })
           sleep polling_interval
         end
       end

data/lib/data_drain/observability.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 module DataDrain
-  # Módulo interno para garantizar que la telemetría cumpla con los 
+  # Módulo interno para garantizar que la telemetría cumpla con los
   # Global-Observability-Standards: resiliencia, KV-structured y precisión.
   #
   # Este módulo es genérico y puede ser utilizado en otras gemas.
   # @api private
   module Observability
+    SENSITIVE_KEY_PATTERN = /password|passwd|pass|secret|token|api_key|apikey|auth|credential|private_key/i
+
     private
 
     # Emite un log estructurado de forma segura.
@@ -19,7 +21,7 @@ module DataDrain
 
       # Enmascaramiento preventivo de secretos (Security)
       log_line = fields.map do |k, v|
-        val = %i[password token secret api_key auth].include?(k.to_sym) ? "[FILTERED]" : v
+        val = SENSITIVE_KEY_PATTERN.match?(k.to_s) ? "[FILTERED]" : v
         "#{k}=#{val}"
       end.join(" ")
 

data/lib/data_drain/record.rb

@@ -38,7 +38,8 @@ module DataDrain
 
       entry[:conn]&.close
       entry[:db]&.close
-    rescue StandardError # rubocop:disable Lint/SuppressedException
+    rescue StandardError
+      nil
     end
 
     # Retorna la conexión persistente a DuckDB en memoria para el hilo (Thread) actual.

data/lib/data_drain/storage/s3.rb

@@ -2,9 +2,9 @@
 
 module DataDrain
   module Storage
-    # Implementación del adaptador de almacenamiento para Amazon S3.
     class S3 < Base
       # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+
       # Carga la extensión httpfs en DuckDB e inyecta las credenciales de AWS.
       # Si aws_access_key_id y aws_secret_access_key están seteados, usa
       # credenciales explícitas. Si no, usa credential_chain (IAM role, env vars,
@@ -16,42 +16,6 @@ module DataDrain
         create_s3_secret(connection)
       end
 
-      private
-
-      # @param connection [DuckDB::Connection]
-      # @raise [DataDrain::ConfigurationError]
-      def create_s3_secret(connection)
-        region = @config.aws_region
-        raise DataDrain::ConfigurationError, "aws_region es obligatorio para storage_mode=:s3" if region.nil?
-
-        if @config.aws_access_key_id && @config.aws_secret_access_key
-          connection.query(<<~SQL)
-            CREATE OR REPLACE SECRET data_drain_s3 (
-              TYPE S3,
-              KEY_ID '#{escape_sql(@config.aws_access_key_id)}',
-              SECRET '#{escape_sql(@config.aws_secret_access_key)}',
-              REGION '#{escape_sql(region)}'
-            );
-          SQL
-        else
-          connection.query(<<~SQL)
-            CREATE OR REPLACE SECRET data_drain_s3 (
-              TYPE S3,
-              PROVIDER credential_chain,
-              REGION '#{escape_sql(region)}'
-            );
-          SQL
-        end
-      end
-
-      # @param value [String]
-      # @return [String]
-      def escape_sql(value)
-        value.to_s.gsub("'", "''")
-      end
-
-      public
-
       # @param bucket [String]
       # @param folder_name [String]
       # @param partition_path [String, nil]
@@ -96,6 +60,38 @@ module DataDrain
 
       private
 
+      # @param connection [DuckDB::Connection]
+      # @raise [DataDrain::ConfigurationError]
+      def create_s3_secret(connection)
+        region = @config.aws_region
+        raise DataDrain::ConfigurationError, "aws_region es obligatorio para storage_mode=:s3" if region.nil?
+
+        if @config.aws_access_key_id && @config.aws_secret_access_key
+          connection.query(<<~SQL)
+            CREATE OR REPLACE SECRET data_drain_s3 (
+              TYPE S3,
+              KEY_ID '#{escape_sql(@config.aws_access_key_id)}',
+              SECRET '#{escape_sql(@config.aws_secret_access_key)}',
+              REGION '#{escape_sql(region)}'
+            );
+          SQL
+        else
+          connection.query(<<~SQL)
+            CREATE OR REPLACE SECRET data_drain_s3 (
+              TYPE S3,
+              PROVIDER credential_chain,
+              REGION '#{escape_sql(region)}'
+            );
+          SQL
+        end
+      end
+
+      # @param value [String]
+      # @return [String]
+      def escape_sql(value)
+        value.to_s.gsub("'", "''")
+      end
+
       # @param client [Aws::S3::Client]
       # @param bucket [String]
       # @param objects_to_delete [Array<Hash>]

data/lib/data_drain/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DataDrain
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/skill/SKILL.md

@@ -213,3 +213,4 @@ Catálogo completo en [Antipatrones](references/antipatrones.md). Resumen de los
 - [API Detallada](references/api-detallada.md) — Firmas completas, parámetros, retornos y comportamientos de cada clase pública.
 - [Eventos y Telemetría](references/eventos-telemetria.md) — Catálogo completo de eventos KV emitidos por la gema.
 - [Antipatrones](references/antipatrones.md) — Qué NO hacer y alternativas correctas.
+- [Postgres Tuning](references/postgres-tuning.md) — Índices, VACUUM, particionamiento y diagnóstico por tamaño de tabla.

data/skill/references/antipatrones.md

@@ -207,7 +207,7 @@ ArchivedX.connection.close  # Rompe la siguiente query del mismo thread
 
 **Razón:** `Record.connection` es thread-local y persistente — diseñada para amortizar el costo de cargar `httpfs` y credenciales. Cerrarla obliga a reconectar todo en la próxima query y puede dejar el `Thread.current` apuntando a una conexión muerta (`Database` GC'd).
 
-**Alternativa:** No cerrarla manualmente. Vive mientras vive el thread.
+**Alternativa:** No usar `Record.connection.close` directamente. Si necesitás cerrar (Sidekiq/Puma middleware), usar `Record.disconnect!` que cierra `db` + `conn` y limpia `Thread.current` atómicamente. En threads de larga vida, esto previene memory leak.
 
 ---
 
@@ -234,9 +234,26 @@ DataDrain::Engine.new(
 
 **Incorrecto:**
 ```ruby
-DataDrain::GlueRunner.run_and_wait("job", args)  # Asumir que retorna en X minutos
+DataDrain::GlueRunner.run_and_wait("job", args)  # Sin timeout, puede bloquearse
 ```
 
-**Razón:** El loop de polling no tiene timeout máximo. Si Glue queda colgado en `RUNNING` indefinidamente, `run_and_wait` bloquea para siempre.
+**Razón:** Si Glue queda colgado en `RUNNING`, bloquea indefinidamente.
 
-**Alternativa:** Envolver en `Timeout.timeout(N)` en el caller, o monitorear el job desde fuera (CloudWatch alarm). Mejor aún: futura mejora de la gema agregar `max_wait_seconds`.
+**Alternativa:** Usar `max_wait_seconds:` (desde v0.2.2):
+```ruby
+GlueRunner.run_and_wait("job", args, max_wait_seconds: 3600)  # 1h max
+```
+
+---
+
+## 15. Llamar `Engine.new` con configuración incompleta
+
+**Incorrecto:**
+```ruby
+DataDrain::Engine.new(table_name: "versions", start_date: ..., end_date: ...)
+# donde DataDrain.configuration no tiene db_name seteado
+```
+
+**Razón:** Desde v0.2.2, `Engine#initialize` llama `config.validate_for_engine!` que verifica `db_host`, `db_user`, `db_name`. Si alguno falta, levanta `DataDrain::ConfigurationError`.
+
+**Alternativa:** Asegurar que `db_name`, `db_user` y `db_host` estén seteados en `DataDrain.configure` antes de llamar `Engine.new`. Si se usa auth peer/trust, `db_pass` puede ser `nil`.

data/skill/references/api-detallada.md

@@ -40,7 +40,20 @@ Atributos (`attr_accessor`):
 ### `#duckdb_connection_string`
 Retorna URI: `postgresql://user:pass@host:port/db?options=-c%20idle_in_transaction_session_timeout%3D<val>`
 
-**No hay validaciones automáticas.** Caller debe garantizar consistencia (ej. credenciales AWS si `storage_mode = :s3`).
+### `#validate!`
+Valida invariantes generales. Llamada automáticamente por `FileIngestor#initialize` y `GlueRunner.run_and_wait`.
+
+Raises `DataDrain::ConfigurationError` si:
+- `storage_mode` no es `:local` ni `:s3`
+- `storage_mode == :s3` y `aws_region` es nil o vacío
+
+### `#validate_for_engine!`
+Valida invariantes de Engine. Además de `#validate!`, verifica `db_host`, `db_user`, `db_name` no nil ni vacíos.
+
+Llamada automáticamente por `Engine#initialize`.
+
+**No valida `db_pass`** — puede ser nil con auth peer/trust (sockets locales) o IAM (RDS).
+**No valida `db_port`** — tiene default `5432`, nunca nil tras `Configuration#initialize`.
 
 ---
 
@@ -164,24 +177,24 @@ Formato: `#<Class attr1: val1, attr2: val2, ...>`.
 
 ## `DataDrain::GlueRunner`
 
-### `.run_and_wait(job_name, arguments = {}, polling_interval: 30) → true`
+### `.run_and_wait(job_name, arguments = {}, polling_interval: 30, max_wait_seconds: nil) → true`
 
 | Parámetro | Tipo | Descripción |
 |-----------|------|-------------|
 | `job_name` | String | Nombre del Job en consola AWS |
 | `arguments` | Hash | Args con prefijo `--` (ej. `"--start_date" => "..."`) |
 | `polling_interval` | Integer | Segundos entre chequeos. Default `30` |
+| `max_wait_seconds` | Integer, nil | Timeout máximo. nil = sin límite. Default `nil` |
 
 Flujo:
 1. `Aws::Glue::Client.new(region: config.aws_region)`
 2. `start_job_run` → captura `run_id`
 3. Loop: `get_job_run`, evalúa `job_run_state`:
+   - Si `max_wait_seconds` excede → log `glue_runner.timeout`, `raise DataDrain::Error`
    - `SUCCEEDED` → log `glue_runner.complete`, retorna `true`
    - `FAILED|STOPPED|TIMEOUT` → log `glue_runner.failed` (incluye `error_message` truncado a 200 chars), `raise RuntimeError`
    - Otro → log `glue_runner.polling`, `sleep polling_interval`
 
-No tiene timeout máximo. Si Glue queda colgado en `RUNNING`, esto bloquea indefinidamente.
-
 ---
 
 ## `DataDrain::Storage`
@@ -220,7 +233,7 @@ Diseñado para `include` (instance methods, requiere `@logger`) o `extend` (clas
 ### `#safe_log(level, event, metadata = {})` (privado)
 - Si `@logger` es nil, no-op.
 - Construye `fields = { component: observability_name, event: event }.merge(metadata)`.
-- Filtra valores cuyas keys sean `:password|:token|:secret|:api_key|:auth` → `[FILTERED]`.
+- Filtra valores cuyas keys matcheen `SENSITIVE_KEY_PATTERN = /password|passwd|pass|secret|token|api_key|apikey|auth|credential|private_key/i` → `[FILTERED]`. Aplica a claves exactas (`password`) y variantes (`db_password`, `aws_secret_access_key`, `bearer_token`, etc.).
 - Emite `@logger.send(level) { "k1=v1 k2=v2 ..." }`.
 - `rescue StandardError` silencioso (resilience).
 

data/skill/references/eventos-telemetria.md

@@ -128,6 +128,11 @@ Catálogo completo de eventos KV emitidos por DataDrain. Formato Wispro-Observab
 **Campos:** `job`, `run_id`, `status`, `duration_s`, `error_message` (si Glue lo provee, truncado a 200 chars).
 **Consecuencia:** `raise RuntimeError`.
 
+### `glue_runner.timeout`
+**Nivel:** ERROR. Emite cuando `max_wait_seconds` excede antes de `SUCCEEDED`.
+**Campos:** `job`, `run_id`, `max_wait_seconds`.
+**Consecuencia:** `raise DataDrain::Error`.
+
 ---
 
 ## Ejemplos reales

data/skill/references/postgres-tuning.md

@@ -0,0 +1,129 @@
+# Postgres Tuning para DataDrain
+
+Guía operacional para tablas que DataDrain archiva y purga. Cubre índices,
+VACUUM, particionamiento y diagnóstico.
+
+## Tabla de decisión por tamaño
+
+| Tamaño | Estrategia |
+|--------|-----------|
+| <10GB | Índice composite `(created_at, pk)` con `CREATE INDEX CONCURRENTLY` |
+| 10-100GB | Mismo + `SET maintenance_work_mem='4GB'` + checklist |
+| 100GB-1TB | Particionamiento declarativo por mes |
+| >1TB | Particionamiento obligatorio + `DROP PARTITION` reemplaza DELETE |
+
+## Índice recomendado
+
+Para tablas <100GB, DataDrain se beneficia de un índice composite:
+
+    CREATE INDEX CONCURRENTLY idx_versions_created_at_id
+    ON versions (created_at, id);
+
+El DELETE en batches usa `WHERE created_at >= X AND created_at < Y` + `IN (SELECT id LIMIT N)`.
+El índice composite lo convierte en index scan por rango + acceso directo al id.
+
+### Checklist pre-`CREATE INDEX CONCURRENTLY`
+
+- [ ] Tamaño actual: `SELECT pg_size_pretty(pg_total_relation_size('versions'));`
+- [ ] Espacio libre disco (>2x tabla)
+- [ ] `SET maintenance_work_mem = '4GB';` (sesión)
+- [ ] `SET statement_timeout = 0;`
+- [ ] Ventana de baja carga
+- [ ] Plan rollback: `DROP INDEX CONCURRENTLY` si satura I/O
+
+### Riesgos de `CONCURRENTLY`
+
+1. **Dos pasadas** (puede tardar horas en 500GB)
+2. **I/O sostenido** (satura IOPS en EBS gp3 sin provisioned)
+3. **Puede fallar y dejar índice INVALID** → recuperar con `DROP INDEX CONCURRENTLY idx; CREATE INDEX CONCURRENTLY idx ...`
+4. **Espacio en disco alto** durante build (sort externo si `maintenance_work_mem` bajo)
+
+## VACUUM ANALYZE post-purga
+
+En tablas no particionadas, purgar millones de rows deja dead tuples.
+Sin VACUUM, el espacio no se libera y los seq scan recorren páginas vacías.
+
+    VACUUM ANALYZE versions;
+
+Item 5 del roadmap agrega `config.vacuum_after_purge` para automatizar esto.
+Hasta v0.3.0, correr manualmente después de cada `Engine#call` en tablas
+grandes no particionadas.
+
+**NO usar `VACUUM FULL`** — bloquea la tabla entera (ACCESS EXCLUSIVE lock).
+
+## Diagnóstico de purga lenta
+
+    -- Plan del DELETE en lotes
+    EXPLAIN (ANALYZE, BUFFERS)
+    DELETE FROM versions
+    WHERE id IN (
+      SELECT id FROM versions
+      WHERE created_at >= '2026-01-01' AND created_at < '2026-02-01'
+      LIMIT 5000
+    );
+
+    -- Sesiones activas sobre la tabla
+    SELECT pid, state, wait_event, query_start, query
+    FROM pg_stat_activity
+    WHERE query LIKE '%versions%'
+      AND state != 'idle';
+
+    -- Estadísticas de la tabla
+    SELECT relname, n_live_tup, n_dead_tup, last_vacuum, last_autovacuum
+    FROM pg_stat_user_tables
+    WHERE relname = 'versions';
+
+    -- Top queries lentas (requiere pg_stat_statements)
+    SELECT substring(query, 1, 100) AS query, calls, mean_exec_time, rows
+    FROM pg_stat_statements
+    WHERE query LIKE '%versions%'
+    ORDER BY mean_exec_time DESC
+    LIMIT 10;
+
+## Particionamiento declarativo (tablas > 100GB)
+
+Migrar a tabla particionada cambia DataDrain de "DELETE masivo throttled" a
+"DROP PARTITION instantáneo".
+
+### Setup
+
+    -- 1. Crear tabla particionada (vacía, misma estructura que versions)
+    CREATE TABLE versions_new (
+      id UUID PRIMARY KEY,
+      created_at TIMESTAMP NOT NULL,
+      ... -- resto de columnas
+    ) PARTITION BY RANGE (created_at);
+
+    -- 2. Crear partición por mes
+    CREATE TABLE versions_2026_03 PARTITION OF versions_new
+      FOR VALUES FROM ('2026-03-01') TO ('2026-04-01');
+
+    -- 3. Migrar datos (lotes, una partición por vez)
+    INSERT INTO versions_2026_03
+    SELECT * FROM versions
+    WHERE created_at >= '2026-03-01' AND created_at < '2026-04-01';
+
+    -- 4. Swap nombres (downtime mínimo)
+    BEGIN;
+      ALTER TABLE versions RENAME TO versions_old;
+      ALTER TABLE versions_new RENAME TO versions;
+    COMMIT;
+
+### Beneficio para DataDrain
+
+    -- v0.2.x: DELETE en lotes, VACUUM después, horas en TB
+    DataDrain::Engine.new(...).call
+
+    -- Con particiones: DataDrain sigue funcionando pero si el rango
+    -- coincide con una partición, el operador puede hacer:
+    DROP TABLE versions_2026_03;  -- instantáneo, sin bloat
+
+DataDrain no detecta particiones automáticamente (futuro item). Hoy el
+operador decide.
+
+## Referencias
+
+- Skill: `.agents/skills/postgresql-optimization/SKILL.md`
+- PG docs: https://www.postgresql.org/docs/current/ddl-partitioning.html
+- Item 5 roadmap (VACUUM automático): ../IMPROVEMENT_PLAN.md#item-5
+- Item 11b roadmap (warning runtime): ../IMPROVEMENT_PLAN.md#item-11b

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: data_drain
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Gabriel
@@ -97,6 +97,11 @@ files:
 - README.md
 - Rakefile
 - data_drain.gemspec
+- docs/IMPROVEMENT_PLAN.md
+- docs/execution/archive/v0.2.0.agente-review.md
+- docs/execution/archive/v0.2.0.md
+- docs/execution/v0.2.2.md
+- docs/glue_pyspark_example.py
 - lib/data_drain.rb
 - lib/data_drain/configuration.rb
 - lib/data_drain/engine.rb
@@ -117,6 +122,7 @@ files:
 - skill/references/antipatrones.md
 - skill/references/api-detallada.md
 - skill/references/eventos-telemetria.md
+- skill/references/postgres-tuning.md
 homepage: https://github.com/gedera/data_drain
 licenses: []
 metadata: {}