data_drain 0.1.18 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09d58bbf9060fa6fb61ddeff5e43f020168280d9487726912c25deda6b1a2a45'
-  data.tar.gz: e8d13997382a5b9c69031406450ff579f01afe9593b1b9edee28546944b9faee
+  metadata.gz: e121779f19f63fc4209e8c8393155a96403f4516dc62c285e90cebf244b3548e
+  data.tar.gz: 8e48a3a12f6b901030ce570b97ebd71999daceaa2b562f94980f85c414f1eea6
 SHA512:
-  metadata.gz: de7135c83eb0d5cbdc018cf965d974ccc449ae9c74166868914b4f73e5c775ea9bc39c80bee0ada779b7cafeb313c4cdde7b20b454cfab7b415d9cb7e25ff815
-  data.tar.gz: de65115bbb65cfe1ef4ae035c2c7c644027109fb485e2b0e9e17b079b15595ad2ce015ffd4771432551e314ac7bd42cedb014f907cbd690d669d9a7166a79625
+  metadata.gz: e20f0cc6586c0a1bed1281eae429ed5747b09cd8bf008b5fc996c7e3690f6a56a14083debd41744440f190c3521a8135c6822bc19c9faca1c33b3dd1507b67c2
+  data.tar.gz: c2c3333e2b3938431c8732ea3662cbfae00bd2fcb78519a4a5e9ec5d953c00ec3235ed134cc480b9029ced947b232394b575c60bf24eacbfac301cb32668c6ee

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-13
+
+### Security
+- **BREAKING (preventivo):** `table_name` y `primary_key` se validan contra regex `\A[a-zA-Z_][a-zA-Z0-9_]*\z`. Identificadores con caracteres especiales (puntos, espacios, comillas) ahora levantan `DataDrain::ConfigurationError`. (item 2)
+- Storage::S3 migra a `CREATE SECRET (TYPE S3, PROVIDER credential_chain)`. Si `aws_access_key_id`/`aws_secret_access_key` están seteados, se mantiene comportamiento explícito; si no, usa AWS credential chain (IAM roles, env vars, ~/.aws/credentials). `aws_region` ahora se escapa con `''` en el SQL. (item 1)
+
+### Features
+- `Record.disconnect!` cierra y limpia la conexión DuckDB thread-local. Recomendado en middlewares Sidekiq/Puma para evitar memory leak. Idempotente. (item 3)
+
+### Tests
+- Cobertura: 112 specs, coverage líneas 97.37% (SimpleCov).
+- Specs nuevos: Record, Storage::Local, Storage::S3, Storage factory, GlueRunner, Observability, Configuration, JsonType, Validations, Engine (validación), FileIngestor (validación + ingestión CSV/JSON/Parquet).
+
+## [0.1.19] - 2026-03-30
+
+- Fix: `Record.build_query_path` ahora usa `partition_keys` como fuente de verdad del orden, ignorando el orden de los kwargs del caller. Antes, pasar `where(year: 2026, isp_id: 42)` en distinto orden generaba un path que no coincidía con la estructura Hive en disco.
+- Fix: `GlueRunner` reemplaza `.truncate(200)` de ActiveSupport por `[0, 200]` de Ruby puro, eliminando la dependencia implícita.
+- Convention: orden canónico de `partition_keys` es `[dimension_principal, year, month]` (ej. `isp_id` primero). Documentado en CLAUDE.md y actualizado en README, specs y ejemplos de PySpark.
+- Docs: README actualizado con ejemplos de producción correctos para Glue + Engine + Record.
+
 ## [0.1.18] - 2026-03-23
 
 - Feature: Módulo `Observability` centraliza el logging estructurado en toda la gema.

data/CLAUDE.md

@@ -19,9 +19,31 @@ created_at >= 'START' AND created_at < 'END_BOUNDARY'
 ```
 Donde `END_BOUNDARY` es el inicio del periodo siguiente (ej. `next_day.beginning_of_day`). Nunca usar `<= end_of_day` — los microsegundos en el límite pueden quedar fuera.
 
+### Partition Keys — Orden y Contrato
+
+El array `partition_keys` es **completamente dinámico** — cada tabla/modelo define el suyo. No existe un orden estándar en la librería.
+
+**Regla crítica:** el orden de `partition_keys` al **escribir** (Engine/FileIngestor) debe ser idéntico al declarado en el modelo **Record** que lee esos archivos. Un mismatch genera paths que no coinciden y DuckDB retorna vacío sin error.
+
+```ruby
+# Escritura
+Engine.new(partition_keys: %w[isp_id year month], ...)
+
+# Lectura — debe coincidir
+class ArchivedVersion < DataDrain::Record
+  self.partition_keys = [:isp_id, :year, :month]
+end
+```
+
+**Criterio de diseño del orden:** el primer key debe ser la dimensión de mayor cardinalidad o la que más se usa como filtro (ej. `isp_id` si las consultas son siempre por ISP). Esto determina la jerarquía de carpetas Hive y el rendimiento del prefix scan en S3.
+
 ### Idempotencia
 Las exportaciones usan `OVERWRITE_OR_IGNORE 1` de DuckDB. Los procesos son seguros de reintentar.
 
+### Validación de identificadores SQL
+
+`Engine#initialize` y `FileIngestor#initialize` validan `table_name`, `primary_key` y `folder_name` contra la regex `\A[a-zA-Z_][a-zA-Z0-9_]*\z`. Valores con caracteres especiales (`.`, `;`, espacios, comillas) levantan `DataDrain::ConfigurationError`. `select_sql` y `where_clause` siguen siendo trusted.
+
 ### `idle_in_transaction_session_timeout`
 El valor `0` **desactiva** el timeout (sin límite). Para purgas de gran volumen esto es mandatorio. Internamente, se debe validar con `!nil?` ya que `0.present?` es falso.
 

data/README.md

@@ -1,142 +1,107 @@
 # DataDrain
 
-DataDrain es un micro-framework de nivel empresarial diseñado para extraer, archivar y purgar datos históricos desde bases de datos PostgreSQL transaccionales, así como para **ingerir archivos crudos (CSV, JSON, Parquet)**, hacia un Data Lake analítico.
+Micro-framework Ruby para extraer, archivar y purgar datos históricos de PostgreSQL hacia un Data Lake (S3 o disco local) en formato Parquet, usando DuckDB en memoria.
 
-Utiliza **DuckDB** en memoria para lograr velocidades de procesamiento y compresión extremas. Garantiza la retención segura de datos mediante chequeos de integridad estrictos antes de purgar las bases de datos de origen, y automatiza la conversión y subida de archivos pesados a la nube.
+## Características
 
-## Características Principales
-
-* **ETL de Alto Rendimiento:** Transfiere millones de registros desde Postgres a Parquet utilizando DuckDB sin cargar los objetos en la memoria RAM de Ruby.
-* **File Ingestion:** Convierte archivos crudos masivos (ej. logs de Netflow en CSV) a Parquet (ZSTD) y los sube directamente a S3 en milisegundos.
-* **Hive Partitioning:** Organiza automáticamente los archivos en carpetas optimizadas para consultas (`year=X/month=Y/tenant_id=Z`).
-* **Storage Adapters:** Soporte nativo y transparente para almacenamiento en Disco Local y AWS S3.
-* **Integridad Garantizada:** Verifica matemáticamente que los datos exportados coincidan exactamente con el origen antes de ejecutar sentencias `DELETE`.
-* **ORM Analítico Integrado:** Incluye una clase base (`DataDrain::Record`) compatible con `ActiveModel` para consultar y destruir particiones históricas de forma idiomática.
-* **Observabilidad Estructurada:** Todos los eventos emiten logs en formato `key=value` compatibles con Datadog, CloudWatch y `exis_ray`. Los fallos de logging nunca interrumpen el flujo principal.
+- **ETL de alto rendimiento:** millones de registros de Postgres a Parquet sin cargar objetos en RAM Ruby.
+- **File ingestion:** convierte CSV, JSON o Parquet locales a Parquet (ZSTD) particionado y los sube a S3.
+- **Hive partitioning:** organiza archivos en `key=val/key=val/...` para prefix scans eficientes.
+- **Storage adapters:** soporte transparente para disco local y AWS S3.
+- **Integridad garantizada:** verificación matemática Postgres vs Parquet antes de cualquier `DELETE`.
+- **ORM analítico:** clase base `DataDrain::Record` (compatible `ActiveModel`) para consultar y purgar particiones históricas.
+- **Observabilidad estructurada:** logs `key=value` compatibles con Datadog, CloudWatch y `exis_ray`. Fallos del logger nunca interrumpen el flujo principal.
 
 ## Instalación
 
-Agrega esta línea al `Gemfile` de tu aplicación o microservicio:
-
 ```ruby
+# Gemfile
 gem 'data_drain', git: 'https://github.com/gedera/data_drain.git', branch: 'main'
 ```
 
-Y ejecuta:
 ```bash
-$ bundle install
+bundle install
 ```
 
 ## Configuración
 
-Crea un inicializador en tu aplicación (ej. `config/initializers/data_drain.rb`) para configurar las credenciales y el comportamiento del motor:
-
 ```ruby
+# config/initializers/data_drain.rb
 DataDrain.configure do |config|
-  # Almacenamiento (:local o :s3)
-  config.storage_mode = ENV.fetch('STORAGE_MODE', 'local').to_sym
+  config.storage_mode = ENV.fetch('STORAGE_MODE', 'local').to_sym  # :local o :s3
 
-  # AWS S3 (Requerido solo si storage_mode es :s3)
-  # config.aws_region = ENV['AWS_REGION']
-  # config.aws_access_key_id = ENV['AWS_ACCESS_KEY_ID']
-  # config.aws_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+  # AWS S3 (solo si storage_mode == :s3)
+  config.aws_region            = ENV['AWS_REGION']
+  config.aws_access_key_id     = ENV['AWS_ACCESS_KEY_ID']
+  config.aws_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
 
-  # Base de Datos PostgreSQL de Origen (Requerido solo para DataDrain::Engine)
+  # PostgreSQL origen (solo para Engine)
   config.db_host = ENV.fetch('DB_HOST', '127.0.0.1')
   config.db_port = ENV.fetch('DB_PORT', '5432')
   config.db_user = ENV.fetch('DB_USER', 'postgres')
   config.db_pass = ENV.fetch('DB_PASS', '')
   config.db_name = ENV.fetch('DB_NAME', 'core_production')
 
-  # Rendimiento y Tuning de Postgres
-  config.batch_size     = 5000 # Registros a borrar por transacción
-  config.throttle_delay = 0.5  # Segundos de pausa entre borrados
+  # Tuning de purga
+  config.batch_size                          = 5000  # registros por DELETE
+  config.throttle_delay                      = 0.5   # segundos entre lotes
+  config.idle_in_transaction_session_timeout = 0     # 0 = DESACTIVADO (mandatorio en purgas masivas)
 
-  # Timeout de inactividad de transacciones en PostgreSQL (en milisegundos).
-  # El valor 0 DESACTIVA el timeout (sin límite de tiempo).
-  # Mandatorio para purgas de gran volumen donde cada lote puede tardar segundos.
-  config.idle_in_transaction_session_timeout = 0
+  # Tuning de DuckDB
+  config.limit_ram     = '2GB'                # evita OOM en contenedores
+  config.tmp_directory = '/tmp/duckdb_work'   # spill-to-disk (preferir SSD/NVMe)
 
   config.logger = Rails.logger
-
-  # Tuning de DuckDB
-  # Límite máximo de RAM para las consultas en memoria de DuckDB (ej. '2GB', '512MB').
-  # Evita que el proceso muera por OOM en contenedores con memoria limitada.
-  config.limit_ram = '2GB'
-
-  # Directorio temporal de DuckDB para desbordar memoria (spill to disk) durante
-  # transformaciones pesadas o creación de archivos Parquet masivos.
-  # Se recomienda que este directorio resida en un disco SSD/NVMe rápido.
-  config.tmp_directory = '/tmp/duckdb_work'
 end
 ```
 
 ## Uso
 
-El framework provee cuatro herramientas principales: **Ingestor de Archivos**, **Drenaje de Base de Datos**, **ORM Analítico** y **Orquestación con AWS Glue**.
-
-### 1. Ingestión de Archivos Crudos (FileIngestor)
-
-Ideal para servicios que generan grandes volúmenes de datos (ej. métricas de Netflow). Toma un archivo local, lo transforma, lo comprime a Parquet y lo sube particionado a S3.
+### Ingesta de archivos crudos (FileIngestor)
 
 ```ruby
-ingestor = DataDrain::FileIngestor.new(
+DataDrain::FileIngestor.new(
   bucket:              'my-bucket-store',
-  source_path:         '/tmp/netflow_metrics_1600.csv',
+  source_path:         '/tmp/netflow_metrics.csv',
   folder_name:         'netflow',
-  partition_keys:      %w[year month isp_id],
+  partition_keys:      %w[isp_id year month],
   select_sql:          "*, EXTRACT(YEAR FROM timestamp) AS year, EXTRACT(MONTH FROM timestamp) AS month",
   delete_after_upload: true
-)
-
-ingestor.call
+).call
 ```
 
-### 2. Extracción y Purga de BD (Engine)
-
-Ideal para crear ventanas rodantes de retención (ej. mantener solo 6 meses de datos vivos en Postgres y archivar el resto).
+### Extracción y purga (Engine)
 
-**Flujo completo (Export + Verify + Purge):**
+Ventanas rodantes de retención: archivar 6 meses atrás y purgar el origen.
 
 ```ruby
-engine = DataDrain::Engine.new(
+DataDrain::Engine.new(
   bucket:         'my-bucket-store',
   start_date:     6.months.ago.beginning_of_month,
   end_date:       6.months.ago.end_of_month,
   table_name:     'versions',
   partition_keys: %w[year month]
-)
-
-engine.call
+).call
 ```
 
-**Modo Purga con Exportación Externa (skip_export):**
+### Modo `skip_export` (delegar export a Glue/EMR)
 
-Si tu arquitectura ya utiliza **AWS Glue** o **AWS EMR** para mover datos pesados, puedes configurar DataDrain para que actúe únicamente como garante de integridad. En este modo omite la exportación pero verifica matemáticamente que los datos existan en el Data Lake antes de eliminarlos de PostgreSQL.
+DataDrain solo verifica integridad y purga; el export ya lo hizo otra herramienta.
 
 ```ruby
-engine = DataDrain::Engine.new(
+DataDrain::Engine.new(
   bucket:         'my-bucket-store',
   start_date:     6.months.ago.beginning_of_month,
   end_date:       6.months.ago.end_of_month,
   table_name:     'versions',
   partition_keys: %w[year month],
   skip_export:    true
-)
-
-engine.call
+).call
 ```
 
-### 3. Orquestación con AWS Glue (Big Data)
-
-Para tablas de gran volumen (**ej. > 500GB o 1TB**), se recomienda delegar el movimiento de datos a **AWS Glue** (basado en Apache Spark) para evitar saturar el servidor de Ruby. `DataDrain` actúa como el orquestador que dispara el Job, espera a que termine y luego realiza la validación y purga.
+### Orquestación con AWS Glue (tablas 1TB+)
 
 ```ruby
-config = DataDrain.configuration
-bucket = "my-bucket"
-table  = "versions"
-
-# 1. Disparar el Job de Glue y esperar su finalización exitosa
 DataDrain::GlueRunner.run_and_wait(
   "my-glue-export-job",
   {
@@ -148,137 +113,72 @@ DataDrain::GlueRunner.run_and_wait(
     "--db_user"      => config.db_user,
     "--db_password"  => config.db_pass,
     "--db_table"     => table,
-    "--partition_by" => "year,month,isp_id"
+    "--partition_by" => "isp_id,year,month"
   }
 )
 
-# 2. Una vez que Glue exportó el TB, DataDrain valida integridad y purga Postgres
 DataDrain::Engine.new(
-  bucket:         bucket,
-  folder_name:    table,
-  start_date:     start_date,
-  end_date:       end_date,
-  table_name:     table,
-  partition_keys: %w[year month isp_id],
-  skip_export:    true
+  bucket:, folder_name: table, start_date:, end_date:,
+  table_name: table, partition_keys: %w[isp_id year month],
+  skip_export: true
 ).call
 ```
 
-#### Script de AWS Glue (PySpark) compatible con DataDrain
-
-Crea un Job en la consola de AWS Glue (Spark 4.0+) y utiliza este script como base:
-
-```python
-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
+Script PySpark de referencia: [`docs/glue_pyspark_example.py`](docs/glue_pyspark_example.py).
 
-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']} WHERE created_at >= '{args['start_date']}' AND created_at < '{args['end_date']}'"
-}
-
-df = spark.read.format("jdbc").options(**options).load()
-
-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()
-```
-
-### 4. Consultar el Data Lake (Record)
-
-Para consultar los datos archivados sin salir de Ruby, crea un modelo que herede de `DataDrain::Record`.
+### Consultar el Data Lake (Record)
 
 ```ruby
-# app/models/archived_version.rb
 class ArchivedVersion < DataDrain::Record
-  self.bucket       = 'my-bucket-storage'
-  self.folder_name  = 'versions'
-  self.partition_keys = [:year, :month, :isp_id]
+  self.bucket         = 'my-bucket-storage'
+  self.folder_name    = 'versions'
+  self.partition_keys = [:isp_id, :year, :month]  # orden = jerarquía Hive
 
   attribute :id,             :string
   attribute :item_type,      :string
-  attribute :item_id,        :string
   attribute :event,          :string
-  attribute :whodunnit,      :string
   attribute :created_at,     :datetime
   attribute :object,         :json
   attribute :object_changes, :json
 end
-```
-
-Consultas optimizadas mediante Hive Partitioning:
 
-```ruby
 # Búsqueda puntual aislando la partición exacta
-version = ArchivedVersion.find("un-uuid", year: 2026, month: 3, isp_id: 42)
-puts version.object_changes # => {"status" => ["active", "suspended"]}
+ArchivedVersion.find("uuid", isp_id: 42, year: 2026, month: 3)
 
 # Colecciones
-history = ArchivedVersion.where(limit: 10, year: 2026, month: 3, isp_id: 42)
-```
-
-### 5. Destrucción de Datos (Retención y Cumplimiento)
-
-El framework permite eliminar físicamente carpetas completas en S3 o Local utilizando comodines.
-
-```ruby
-# Elimina todo el historial de un cliente a través de todos los años
-ArchivedVersion.destroy_all(isp_id: 42)
+ArchivedVersion.where(limit: 10, isp_id: 42, year: 2026, month: 3)
 
-# Elimina todos los datos de marzo de 2024 globalmente
-ArchivedVersion.destroy_all(year: 2024, month: 3)
+# Eliminación (retención y cumplimiento)
+ArchivedVersion.destroy_all(isp_id: 42)              # todo el historial de un cliente
+ArchivedVersion.destroy_all(year: 2024, month: 3)    # un mes globalmente
 ```
 
-## Arquitectura
+## Convenciones críticas
 
-DataDrain implementa el patrón **Storage Adapter**, lo que permite aislar completamente la lógica del sistema de archivos de los motores de procesamiento.
-
-* **Conexión DuckDB thread-local:** `DataDrain::Record` mantiene una conexión DuckDB por thread (`Thread.current[:data_drain_duckdb]`). Cada thread inicializa su propia conexión una sola vez, incluyendo la carga de extensiones como `httpfs`. Tener esto en cuenta en entornos Puma o Sidekiq.
-* **Storage Adapter cacheado:** `DataDrain::Storage.adapter` cachea la instancia del adaptador. Si `storage_mode` cambia en runtime, llamar `DataDrain::Storage.reset_adapter!` para invalidar el cache.
-* **ORM Analítico con sanitización:** `DataDrain::Record` incluye sanitización de parámetros para prevenir inyección SQL al consultar archivos Parquet.
+- **Rangos de fecha semi-abiertos:** siempre `created_at >= START AND created_at < END_BOUNDARY`. Nunca `<= end_of_day`.
+- **Orden de `partition_keys`:** debe coincidir entre escritura (Engine/FileIngestor) y lectura (Record). Mismatch → DuckDB devuelve vacío sin error.
+- **Cambiar `storage_mode` en runtime:** llamar `DataDrain::Storage.reset_adapter!` después.
+- **`verify_integrity`** es la única salvaguarda antes de purgar. Si falla, el flujo retorna `false` y aborta el `DELETE`.
 
 ## Observabilidad
 
-Todos los eventos emiten logs estructurados en formato `key=value` procesables por herramientas como Datadog, CloudWatch Logs Insights o `exis_ray`:
-
 ```
 component=data_drain event=engine.complete table=versions duration_s=12.4 export_duration_s=8.1 purge_duration_s=3.9 count=150000
-component=data_drain event=engine.integrity_error table=versions duration_s=5.2 count=150000
 component=data_drain event=engine.purge_heartbeat table=versions batches_processed_count=100 rows_deleted_count=500000
-component=data_drain event=file_ingestor.complete source_path=/tmp/data.csv duration_s=2.1 count=85000
 component=data_drain event=glue_runner.failed job=my-export-job run_id=jr_abc123 status=FAILED duration_s=301.0
 ```
 
-Los fallos internos del sistema de logging nunca interrumpen el flujo principal de datos.
+Formato `key=value`. Tiempos con sufijo `_s` (Float). Contadores con `_count` (Integer). Sin unidades en valores. Fallos internos del logger nunca interrumpen el flujo principal.
+
+## Contribuir
+
+```bash
+bundle install
+bundle exec rspec       # tests
+bundle exec rubocop     # linting
+bin/console             # REPL
+```
 
 ## Licencia
 
-La gema está disponible como código abierto bajo los términos de la Licencia MIT.
+MIT.

data/lib/data_drain/engine.rb

@@ -5,6 +5,7 @@ require "pg"
 
 module DataDrain
   # Motor principal de extracción y purga de datos (DataDrain).
+  # rubocop:disable Metrics/ClassLength, Metrics/AbcSize, Metrics/MethodLength, Naming/AccessorMethodName
   #
   # Orquesta el flujo ETL desde PostgreSQL hacia un Data Lake analítico
   # delegando la interacción del almacenamiento al adaptador configurado.
@@ -21,29 +22,31 @@ module DataDrain
     # @option options [Array<String, Symbol>] :partition_keys Columnas para particionar.
     # @option options [String] :primary_key (Opcional) Clave primaria para borrado. Por defecto 'id'.
     # @option options [String] :where_clause (Opcional) Condición SQL extra.
-    # @option options [Boolean] :skip_export (Opcional) Si es true, no realiza el export a Parquet, solo validación y purga.
+    # @option options [Boolean] :skip_export (Opcional) Si true, no exporta
+    #   a Parquet — solo valida y purga (para uso con GlueRunner).
     def initialize(options)
-      @start_date     = options.fetch(:start_date).beginning_of_day
-      
-      # Usamos el inicio del día siguiente como límite superior estricto (<)
-      # Esto evita problemas de precisión con los microsegundos al usar end_of_day
-      @end_date       = options.fetch(:end_date).to_date.next_day.beginning_of_day
-      
-      @table_name     = options.fetch(:table_name)
-      @folder_name    = options.fetch(:folder_name, @table_name)
-      @select_sql     = options.fetch(:select_sql, "*")
-      @partition_keys = options.fetch(:partition_keys)
-      @primary_key    = options.fetch(:primary_key, "id")
-      @where_clause   = options[:where_clause]
-      @bucket         = options[:bucket]
-      @skip_export    = options.fetch(:skip_export, false)
+      @start_date = options.fetch(:start_date).beginning_of_day
+
+      @end_date = options.fetch(:end_date).to_date.next_day.beginning_of_day
 
-      @config  = DataDrain.configuration
-      @logger  = @config.logger
+      @table_name = options.fetch(:table_name)
+      Validations.validate_identifier!(:table_name, @table_name)
+
+      @folder_name = options.fetch(:folder_name, @table_name)
+      @select_sql = options.fetch(:select_sql, "*")
+      @partition_keys = options.fetch(:partition_keys)
+      @primary_key = options.fetch(:primary_key, "id")
+      Validations.validate_identifier!(:primary_key, @primary_key)
+      @where_clause = options[:where_clause]
+      @bucket = options[:bucket]
+      @skip_export = options.fetch(:skip_export, false)
+
+      @config = DataDrain.configuration
+      @logger = @config.logger
       @adapter = DataDrain::Storage.adapter
 
       database = DuckDB::Database.open(":memory:")
-      @duckdb  = database.connect
+      @duckdb = database.connect
     end
 
     # Ejecuta el flujo completo del motor: Setup, Conteo, Exportación (opcional), Verificación y Purga.
@@ -51,7 +54,8 @@ module DataDrain
     # @return [Boolean] `true` si el proceso finalizó con éxito, `false` si falló la integridad.
     def call
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      safe_log(:info, "engine.start", { table: @table_name, start_date: @start_date.to_date, end_date: @end_date.to_date })
+      safe_log(:info, "engine.start",
+               { table: @table_name, start_date: @start_date.to_date, end_date: @end_date.to_date })
 
       setup_duckdb
 
@@ -62,7 +66,8 @@ module DataDrain
 
       if @pg_count.zero?
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        safe_log(:info, "engine.skip_empty", { table: @table_name, duration_s: duration.round(2), db_query_duration_s: db_query_duration.round(2) })
+        safe_log(:info, "engine.skip_empty",
+                 { table: @table_name, duration_s: duration.round(2), db_query_duration_s: db_query_duration.round(2) })
         return true
       end
 
@@ -90,18 +95,19 @@ module DataDrain
 
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
         safe_log(:info, "engine.complete", {
-          table: @table_name,
-          duration_s: duration.round(2),
-          db_query_duration_s: db_query_duration.round(2),
-          export_duration_s: export_duration.round(2),
-          integrity_duration_s: integrity_duration.round(2),
-          purge_duration_s: purge_duration.round(2),
-          count: @pg_count
-        })
+                   table: @table_name,
+                   duration_s: duration.round(2),
+                   db_query_duration_s: db_query_duration.round(2),
+                   export_duration_s: export_duration.round(2),
+                   integrity_duration_s: integrity_duration.round(2),
+                   purge_duration_s: purge_duration.round(2),
+                   count: @pg_count
+                 })
         true
       else
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        safe_log(:error, "engine.integrity_error", { table: @table_name, duration_s: duration.round(2), count: @pg_count })
+        safe_log(:error, "engine.integrity_error",
+                 { table: @table_name, duration_s: duration.round(2), count: @pg_count })
         false
       end
     end
@@ -142,7 +148,12 @@ module DataDrain
       @adapter.prepare_export_path(@bucket, @folder_name)
 
       # Determinamos el path base de destino según el adaptador
-      dest_path = @config.storage_mode.to_sym == :s3 ? "s3://#{@bucket}/#{@folder_name}/" : File.join(@bucket, @folder_name, "")
+      dest_path = if @config.storage_mode.to_sym == :s3
+                    "s3://#{@bucket}/#{@folder_name}/"
+                  else
+                    File.join(@bucket,
+                              @folder_name, "")
+                  end
 
       pg_sql = "SELECT #{@select_sql} FROM public.#{@table_name} WHERE #{base_where_sql}"
       pg_sql = pg_sql.gsub("'", "''")
@@ -154,7 +165,7 @@ module DataDrain
         ) TO '#{dest_path}'
         (
           FORMAT PARQUET,
-          PARTITION_BY (#{@partition_keys.join(', ')}),
+          PARTITION_BY (#{@partition_keys.join(", ")}),
           COMPRESSION 'ZSTD',
           OVERWRITE_OR_IGNORE 1
         );
@@ -180,7 +191,8 @@ module DataDrain
         return false
       end
 
-      safe_log(:info, "engine.integrity_check", { table: @table_name, pg_count: @pg_count, parquet_count: parquet_result })
+      safe_log(:info, "engine.integrity_check",
+               { table: @table_name, pg_count: @pg_count, parquet_count: parquet_result })
       @pg_count == parquet_result
     end
 
@@ -189,11 +201,11 @@ module DataDrain
       safe_log(:info, "engine.purge_start", { table: @table_name, batch_size: @config.batch_size })
 
       conn = PG.connect(
-        host:     @config.db_host,
-        port:     @config.db_port,
-        user:     @config.db_user,
+        host: @config.db_host,
+        port: @config.db_port,
+        user: @config.db_user,
         password: @config.db_pass,
-        dbname:   @config.db_name
+        dbname: @config.db_name
       )
 
       unless @config.idle_in_transaction_session_timeout.nil?
@@ -223,10 +235,10 @@ module DataDrain
         # Heartbeat cada 100 lotes para monitorear procesos largos de 1TB
         if (batches_processed % 100).zero?
           safe_log(:info, "engine.purge_heartbeat", {
-            table: @table_name,
-            batches_processed_count: batches_processed,
-            rows_deleted_count: total_deleted
-          })
+                     table: @table_name,
+                     batches_processed_count: batches_processed,
+                     rows_deleted_count: total_deleted
+                   })
         end
 
         sleep(@config.throttle_delay) if @config.throttle_delay.positive?
@@ -235,4 +247,5 @@ module DataDrain
       conn&.close
     end
   end
+  # rubocop:enable Metrics/ClassLength, Metrics/AbcSize, Metrics/MethodLength, Naming/AccessorMethodName
 end