data_drain 0.1.9 → 0.1.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08913cb191ba486527ec51ccd55531693dad08f5f1d8e1d655252beb1122a9d5'
-  data.tar.gz: 167c9a4b5895df254a198e6c4e09ad27d68f199dc8032f118dcd08341b10999a
+  metadata.gz: 97d660cb624931d75d6f39e51527c58faf180b7ab727d9c85a7fa44079dc76a0
+  data.tar.gz: 932c85dcf3542e52b0f3981281e6a93a757ac194153c8b0b7080a79857613ed5
 SHA512:
-  metadata.gz: d7396d81fa1a61dee43533452ac17a695619dd77da8f26e4be3cb33f5eaa55c5f0f6697a339212def3e811730a22e80d71c4e8b5bb74b6890e3a71656f470815
-  data.tar.gz: 83a9f514895f61460d9e9f1eb284e9acd8d4b1610c495d7ce9d72f2123a08e2d5380a50b7d820a409e0d62674a9f8611c74df967aac4b11982ce03933adb995e
+  metadata.gz: d30e7aaf152e576821b2b2c9a3a68cba01a4c3db6941209e0d0ad0ffb7f69f763e5cf93bd90ac0964a4a2b9b5a5582e348c6f9f5599a5c3ddb24df45168e6418
+  data.tar.gz: f71de76a5075e99eea50a83d0c0d1831091c011a2a64e17b4f3ea206fe8f50ec4bcd2309dfb3096478995c75b4bbfc384431af0d5a5bf3ff446522fa06857891

data/.claude/settings.local.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -sf -X POST -H \"Content-Type: application/json\" -H \"X-Emdash-Token: $EMDASH_HOOK_TOKEN\" -H \"X-Emdash-Pty-Id: $EMDASH_PTY_ID\" -H \"X-Emdash-Event-Type: notification\" -d @- \"http://127.0.0.1:$EMDASH_HOOK_PORT/hook\" || true"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -sf -X POST -H \"Content-Type: application/json\" -H \"X-Emdash-Token: $EMDASH_HOOK_TOKEN\" -H \"X-Emdash-Pty-Id: $EMDASH_PTY_ID\" -H \"X-Emdash-Event-Type: stop\" -d @- \"http://127.0.0.1:$EMDASH_HOOK_PORT/hook\" || true"
+          }
+        ]
+      }
+    ]
+  }
+}

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 ## [Unreleased]
 
+## [0.1.14] - 2026-03-17
+
+- Feature: Implementación de **Logging Estructurado** en toda la gema (\`key=value\`) para mejor observabilidad en producción.
+- Optimization: Caching automático de adaptadores de almacenamiento para mejorar el rendimiento de consultas repetidas.
+- Testing: Mejora en la robustez de los tests de \`Engine\` desacoplándolos de cambios menores en el setup de DuckDB.
+
+## [0.1.13] - 2026-03-17
+
+- Feature: Parametrización total en la orquestación con Glue. Se añadieron \`s3_bucket\`, \`s3_folder\` y \`partition_by\` como argumentos dinámicos, permitiendo que el mismo Job de Glue sirva para múltiples tablas y destinos.
+
+## [0.1.12] - 2026-03-17
+
+- Feature: Parametrización dinámica de la base de datos en \`GlueRunner\` y el script de PySpark. Ahora se pasan \`db_url\`, \`db_user\`, \`db_password\` y \`db_table\` como argumentos al Job de Glue.
+
+## [0.1.11] - 2026-03-17
+
+- Feature: Se agregó \`DataDrain::GlueRunner\` para orquestar Jobs de AWS Glue.
+- Feature: Soporte oficial para procesamiento de Big Data (ej. tablas de 1TB) mediante delegación a AWS Glue.
+- Documentation: Se incluyó un script maestro de PySpark en el README compatible con el formato de la gema.
+
+## [0.1.10] - 2026-03-17
+
+- Feature: Se agregó la opción \`skip_export\` a \`DataDrain::Engine\`. Permite utilizar herramientas externas (como AWS Glue) para la exportación de datos, dejando que DataDrain se encargue solo de la validación de integridad y la purga de PostgreSQL.
+
 ## [0.1.9] - 2026-03-17
 
 - Fix: Mejora en la precisión del rango de fechas en consultas SQL usando límites semi-abiertos (<) para evitar pérdida de registros por microsegundos.

data/README.md

@@ -98,39 +98,118 @@ ingestor.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).
+Ideal para crear Ventanas Rodantes de retención (ej. mantener solo 6 meses de datos vivos en Postgres y archivar el resto). 
 
-```ruby
-# lib/tasks/archive.rake
-task versions: :environment do
-  target_date = 6.months.ago.beginning_of_month
-
-  select_sql = <<~SQL
-    id, item_type, item_id, event, whodunnit,
-    object::VARCHAR AS object,
-    object_changes::VARCHAR AS object_changes,
-    created_at,
-    EXTRACT(YEAR FROM created_at)::INT AS year,
-    EXTRACT(MONTH FROM created_at)::INT AS month,
-    isp_id
-  SQL
+**Modo Purga con Exportación Externa (AWS Glue):** 
+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, el motor omitirá el paso de exportación, pero verificará matemáticamente que los datos existan en el Data Lake antes de proceder a eliminarlos de PostgreSQL.
 
+```ruby
+# lib/tasks/archive_with_glue.rake
+task purge_only: :environment do
   engine = DataDrain::Engine.new(
     bucket:         'my-bucket-store',
-    start_date:     target_date.beginning_of_month,
-    end_date:       target_date.end_of_month,
+    start_date:     6.months.ago.beginning_of_month,
+    end_date:       6.months.ago.end_of_month,
     table_name:     'versions',
-    select_sql:     select_sql,
-    partition_keys: %w[year month isp_id],
-    where_clause:   "event = 'update'"
+    partition_keys: %w[year month],
+    skip_export:    true # ⚡️ No exporta nada, solo valida S3 y purga Postgres
   )
 
-  # Cuenta, exporta a Parquet, verifica integridad y purga Postgres.
   engine.call
 end
 ```
 
-### 3. Consultar el Data Lake (Record)
+### 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.
+
+```ruby
+# 1. Disparar el Job de Glue y esperar su finalización exitosa
+config = DataDrain.configuration
+bucket = "my-bucket"
+table  = "versions"
+
+DataDrain::GlueRunner.run_and_wait(
+  "my-glue-export-job",
+  {
+    "--start_date"    => start_date.to_fs(:db),
+    "--end_date"      => end_date.to_fs(:db),
+    "--s3_bucket"     => bucket,
+    "--s3_folder"     => table,
+    "--db_url"        => "jdbc:postgresql://#{config.db_host}:#{config.db_port}/#{config.db_name}",
+    "--db_user"       => config.db_user,
+    "--db_password"   => config.db_pass,
+    "--db_table"      => table,
+    "--partition_by"  => "year,month,isp_id" # <--- Columnas dinámicas
+  }
+)
+
+# 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 # <--- Modo Validación + Purga
+).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. Está diseñado para extraer datos de PostgreSQL de forma dinámica:
+
+```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
+
+# Parámetros recibidos desde DataDrain::GlueRunner
+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)
+
+# 1. Leer de PostgreSQL (vía JDBC dinámico)
+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()
+
+# 2. Agregar columnas de partición temporales (Hive Partitioning)
+df_final = df.withColumn("year", year(col("created_at"))) \
+             .withColumn("month", month(col("created_at")))
+
+# 3. Escribir a S3 en Parquet con compresión ZSTD
+# Construimos el path dinámicamente: s3://bucket/folder/
+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`.
 

data/data_drain.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
 
   # 💡 Dependencias Core de la Gema
   spec.add_dependency "activemodel", ">= 6.0"
+  spec.add_dependency "aws-sdk-glue", "~> 1.0"
   spec.add_dependency "aws-sdk-s3", "~> 1.114"
   spec.add_dependency "duckdb", "~> 1.4"
   spec.add_dependency "pg", ">= 1.2"

data/lib/data_drain/engine.rb

@@ -20,6 +20,7 @@ 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.
     def initialize(options)
       @start_date     = options.fetch(:start_date).beginning_of_day
       
@@ -34,6 +35,7 @@ module DataDrain
       @primary_key    = options.fetch(:primary_key, "id")
       @where_clause   = options[:where_clause]
       @bucket         = options[:bucket]
+      @skip_export    = options.fetch(:skip_export, false)
 
       @config  = DataDrain.configuration
       @logger  = @config.logger
@@ -43,30 +45,34 @@ module DataDrain
       @duckdb  = database.connect
     end
 
-    # Ejecuta el flujo completo del motor: Setup, Conteo, Exportación, Verificación y Purga.
+    # Ejecuta el flujo completo del motor: Setup, Conteo, Exportación (opcional), Verificación y Purga.
     #
     # @return [Boolean] `true` si el proceso finalizó con éxito, `false` si falló la integridad.
     def call
-      @logger.info "[DataDrain Engine] 🚀 Preparando '#{@table_name}' (#{@start_date.to_date} a #{@end_date.to_date})..."
+      @logger.info "component=data_drain event=engine.start table=#{@table_name} start_date=#{@start_date.to_date} end_date=#{@end_date.to_date}"
 
       setup_duckdb
 
       @pg_count = get_postgres_count
 
       if @pg_count.zero?
-        @logger.info "[DataDrain Engine] ⏭️ No hay registros que cumplan las condiciones."
+        @logger.info "component=data_drain event=engine.skip_empty table=#{@table_name}"
         return true
       end
 
-      @logger.info "[DataDrain Engine] 📦 Exportando #{@pg_count} registros a Parquet..."
-      export_to_parquet
+      if @skip_export
+        @logger.info "component=data_drain event=engine.skip_export table=#{@table_name}"
+      else
+        @logger.info "component=data_drain event=engine.export_start table=#{@table_name} count=#{@pg_count}"
+        export_to_parquet
+      end
 
       if verify_integrity
         purge_from_postgres
-        @logger.info "[DataDrain Engine] ✅ Proceso completado exitosamente para '#{@table_name}'."
+        @logger.info "component=data_drain event=engine.complete table=#{@table_name}"
         true
       else
-        @logger.error "[DataDrain Engine] ❌ ERROR de integridad en '#{@table_name}'. Abortando purga."
+        @logger.error "component=data_drain event=engine.integrity_error table=#{@table_name}"
         false
       end
     end
@@ -141,17 +147,17 @@ module DataDrain
         SQL
         parquet_result = @duckdb.query(query).first.first
       rescue DuckDB::Error => e
-        @logger.error "[DataDrain Engine] ❌ Error leyendo Parquet: #{e.message}"
+        @logger.error "component=data_drain event=engine.parquet_read_error table=#{@table_name} error=#{e.message}"
         return false
       end
 
-      @logger.info "[DataDrain Engine] 📊 Verificación -> Postgres: #{@pg_count} | Parquet: #{parquet_result}"
+      @logger.info "component=data_drain event=engine.integrity_check table=#{@table_name} pg_count=#{@pg_count} parquet_count=#{parquet_result}"
       @pg_count == parquet_result
     end
 
     # @api private
     def purge_from_postgres
-      @logger.info "[DataDrain Engine] 🗑️ Purgando en base de datos (Lotes de #{@config.batch_size})..."
+      @logger.info "component=data_drain event=engine.purge_start table=#{@table_name} batch_size=#{@config.batch_size}"
 
       conn = PG.connect(
         host:     @config.db_host,

data/lib/data_drain/file_ingestor.rb

@@ -30,10 +30,10 @@ module DataDrain
     # Ejecuta el flujo de ingestión.
     # @return [Boolean] true si el proceso fue exitoso.
     def call
-      @logger.info "[DataDrain FileIngestor] 🚀 Iniciando ingestión de '#{@source_path}'..."
+      @logger.info "component=data_drain event=file_ingestor.start source_path=#{@source_path}"
 
       unless File.exist?(@source_path)
-        @logger.error "[DataDrain FileIngestor] ❌ El archivo origen no existe: #{@source_path}"
+        @logger.error "component=data_drain event=file_ingestor.file_not_found source_path=#{@source_path}"
         return false
       end
 
@@ -47,7 +47,7 @@ module DataDrain
 
       # 1. Conteo de seguridad
       source_count = @duckdb.query("SELECT COUNT(*) FROM #{reader_function}").first.first
-      @logger.info "[DataDrain FileIngestor] 📊 Encontrados #{source_count} registros para procesar."
+      @logger.info "component=data_drain event=file_ingestor.count source_path=#{@source_path} count=#{source_count}"
 
       if source_count.zero?
         cleanup_local_file
@@ -73,15 +73,15 @@ module DataDrain
         );
       SQL
 
-      @logger.info "[DataDrain FileIngestor] ☁️ Escribiendo en el Data Lake..."
+      @logger.info "component=data_drain event=file_ingestor.export_start dest_path=#{dest_path}"
       @duckdb.query(query)
 
-      @logger.info "[DataDrain FileIngestor] ✅ Archivo ingerido y comprimido exitosamente."
+      @logger.info "component=data_drain event=file_ingestor.complete source_path=#{@source_path}"
 
       cleanup_local_file
       true
     rescue DuckDB::Error => e
-      @logger.error "[DataDrain FileIngestor] ❌ Error de DuckDB durante la ingestión: #{e.message}"
+      @logger.error "component=data_drain event=file_ingestor.duckdb_error source_path=#{@source_path} error=#{e.message}"
       false
     ensure
       @duckdb&.close
@@ -107,7 +107,7 @@ module DataDrain
     def cleanup_local_file
       if @delete_after_upload && File.exist?(@source_path)
         File.delete(@source_path)
-        @logger.info "[DataDrain FileIngestor] 🗑️ Archivo temporal local eliminado."
+        @logger.info "component=data_drain event=file_ingestor.cleanup source_path=#{@source_path}"
       end
     end
   end

data/lib/data_drain/glue_runner.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "aws-sdk-glue"
+
+module DataDrain
+  # Orquestador para AWS Glue. Permite disparar y monitorear Jobs en AWS
+  # para delegar el movimiento masivo de datos (ej. tablas de 1TB).
+  class GlueRunner
+    # Dispara un Job de Glue y espera a que termine exitosamente.
+    #
+    # @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.
+    # @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)
+      config = DataDrain.configuration
+      client = Aws::Glue::Client.new(region: config.aws_region)
+
+      config.logger.info "component=data_drain event=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
+        run_info = client.get_job_run(job_name: job_name, run_id: run_id).job_run
+        status = run_info.job_run_state
+
+        case status
+        when "SUCCEEDED"
+          config.logger.info "component=data_drain event=glue_runner.complete job=#{job_name} run_id=#{run_id}"
+          return true
+        when "FAILED", "STOPPED", "TIMEOUT"
+          error_msg = run_info.error_message || "Sin mensaje de error disponible."
+          config.logger.error "component=data_drain event=glue_runner.failed job=#{job_name} run_id=#{run_id} status=#{status} error=#{error_msg}"
+          raise "Glue Job #{job_name} (Run ID: #{run_id}) falló con estado #{status}."
+        else
+          config.logger.info "component=data_drain event=glue_runner.polling job=#{job_name} run_id=#{run_id} status=#{status} next_check_in=#{polling_interval}s"
+          sleep polling_interval
+        end
+      end
+    end
+  end
+end

data/lib/data_drain/record.rb

@@ -85,7 +85,7 @@ module DataDrain
     # @return [Integer] Cantidad de particiones físicas eliminadas.
     def self.destroy_all(**partitions)
       adapter = DataDrain::Storage.adapter
-      DataDrain.configuration.logger.info "[DataDrain] 🗑️ Ejecutando destroy_all en #{folder_name} con: #{partitions.inspect}"
+      DataDrain.configuration.logger.info "component=data_drain event=record.destroy_all folder=#{folder_name} partitions=#{partitions.inspect}"
 
       adapter.destroy_partitions(bucket, folder_name, partition_keys, partitions)
     end
@@ -118,7 +118,7 @@ module DataDrain
         begin
           result = connection.query(sql)
         rescue DuckDB::Error => e
-          DataDrain.configuration.logger.warn "[DataDrain] ⚠️ Ruta o archivo no encontrado: #{e.message}"
+          DataDrain.configuration.logger.warn "component=data_drain event=record.parquet_not_found error=#{e.message}"
           return []
         end
 

data/lib/data_drain/storage.rb

@@ -11,20 +11,28 @@ module DataDrain
     class InvalidAdapterError < DataDrain::Error; end
 
     # Resuelve e instancia el adaptador de almacenamiento correspondiente
-    # basándose en la configuración actual del framework.
+    # basándose en la configuración actual del framework. La instancia se
+    # cachea para evitar allocations innecesarias entre queries.
     #
     # @return [DataDrain::Storage::Base] Una instancia de Local o S3.
     # @raise [InvalidAdapterError] Si el storage_mode no es válido.
     def self.adapter
-      mode = DataDrain.configuration.storage_mode
-      case mode.to_sym
-      when :local
-        Local.new(DataDrain.configuration)
-      when :s3
-        S3.new(DataDrain.configuration)
-      else
-        raise InvalidAdapterError, "Storage mode '#{mode}' no está soportado."
+      @adapter ||= begin
+        mode = DataDrain.configuration.storage_mode
+        case mode.to_sym
+        when :local
+          Local.new(DataDrain.configuration)
+        when :s3
+          S3.new(DataDrain.configuration)
+        else
+          raise InvalidAdapterError, "Storage mode '#{mode}' no está soportado."
+        end
       end
     end
+
+    # Descarta el adaptador cacheado. Llamar cuando cambia storage_mode.
+    def self.reset_adapter!
+      @adapter = nil
+    end
   end
 end

data/lib/data_drain/version.rb

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

data/lib/data_drain.rb

@@ -8,6 +8,7 @@ require_relative "data_drain/storage"
 require_relative "data_drain/engine"
 require_relative "data_drain/record"
 require_relative "data_drain/file_ingestor"
+require_relative "data_drain/glue_runner"
 
 # Registramos el tipo JSON personalizado de ActiveModel
 require_relative "data_drain/types/json_type"
@@ -28,6 +29,7 @@ module DataDrain
     # @api private
     def reset_configuration!
       @configuration = Configuration.new
+      DataDrain::Storage.reset_adapter!
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_drain
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.14
 platform: ruby
 authors:
 - Gabriel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-17 00:00:00.000000000 Z
+date: 2026-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-glue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: aws-sdk-s3
   requirement: !ruby/object:Gem::Requirement
@@ -74,6 +88,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/settings.local.json"
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
@@ -87,6 +102,7 @@ files:
 - lib/data_drain/engine.rb
 - lib/data_drain/errors.rb
 - lib/data_drain/file_ingestor.rb
+- lib/data_drain/glue_runner.rb
 - lib/data_drain/record.rb
 - lib/data_drain/storage.rb
 - lib/data_drain/storage/base.rb