data_drain 0.1.9 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08913cb191ba486527ec51ccd55531693dad08f5f1d8e1d655252beb1122a9d5'
-  data.tar.gz: 167c9a4b5895df254a198e6c4e09ad27d68f199dc8032f118dcd08341b10999a
+  metadata.gz: 9c484ac47a5f767491fa8d8e48dbdb53ccdd55d756a6a0eb90d7bbeb0d28f68a
+  data.tar.gz: 18526e071ac821f7c19127cb53dad875108ede9ab9b7bfe40a1d17bde877a6cc
 SHA512:
-  metadata.gz: d7396d81fa1a61dee43533452ac17a695619dd77da8f26e4be3cb33f5eaa55c5f0f6697a339212def3e811730a22e80d71c4e8b5bb74b6890e3a71656f470815
-  data.tar.gz: 83a9f514895f61460d9e9f1eb284e9acd8d4b1610c495d7ce9d72f2123a08e2d5380a50b7d820a409e0d62674a9f8611c74df967aac4b11982ce03933adb995e
+  metadata.gz: abf18e9f987f24cb2e58fb71be8a15f92f867f6e671b174e6414b7a44a5626a316235c091bd59708c1ddc93c755db87ec92af117573c68213d0f2238165728be
+  data.tar.gz: '00124804ef7f7c9dc2c67d47a1a2304d4dc996b0caff24548acbe913e85f5ae43d410eac6725f264f9b9648d49c7dc8bdc0baed77e5ea958bfa3fc8cea08ee9d'

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [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,7 +45,7 @@ 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
@@ -58,8 +60,12 @@ module DataDrain
         return true
       end
 
-      @logger.info "[DataDrain Engine] 📦 Exportando #{@pg_count} registros a Parquet..."
-      export_to_parquet
+      if @skip_export
+        @logger.info "[DataDrain Engine] ⏭️ Modo 'Skip Export' activo. Saltando paso de exportación..."
+      else
+        @logger.info "[DataDrain Engine] 📦 Exportando #{@pg_count} registros a Parquet..."
+        export_to_parquet
+      end
 
       if verify_integrity
         purge_from_postgres

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 "[DataDrain GlueRunner] 🚀 Disparando 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 "[DataDrain GlueRunner] ✅ Job completado con éxito."
+          return true
+        when "FAILED", "STOPPED", "TIMEOUT"
+          error_msg = run_info.error_message || "Sin mensaje de error disponible."
+          config.logger.error "[DataDrain GlueRunner] ❌ ERROR: El Job terminó con estado #{status}: #{error_msg}"
+          raise "Glue Job #{job_name} (Run ID: #{run_id}) falló con estado #{status}."
+        else
+          config.logger.info "[DataDrain GlueRunner] ⏳ Estado: #{status}. Esperando #{polling_interval}s..."
+          sleep polling_interval
+        end
+      end
+    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.13"
 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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_drain
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.13
 platform: ruby
 authors:
 - Gabriel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-17 00:00:00.000000000 Z
+date: 2026-03-20 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
@@ -87,6 +101,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