data_drain 0.1.14 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97d660cb624931d75d6f39e51527c58faf180b7ab727d9c85a7fa44079dc76a0
-  data.tar.gz: 932c85dcf3542e52b0f3981281e6a93a757ac194153c8b0b7080a79857613ed5
+  metadata.gz: c5a97927218d94763cdead9362a4a0a0a40fe4a1b8b327f0f074117a66a10a46
+  data.tar.gz: a5f28048457a43d86942472b36946955e0aa88c9d75cb85158d27f44c986aec2
 SHA512:
-  metadata.gz: d30e7aaf152e576821b2b2c9a3a68cba01a4c3db6941209e0d0ad0ffb7f69f763e5cf93bd90ac0964a4a2b9b5a5582e348c6f9f5599a5c3ddb24df45168e6418
-  data.tar.gz: f71de76a5075e99eea50a83d0c0d1831091c011a2a64e17b4f3ea206fe8f50ec4bcd2309dfb3096478995c75b4bbfc384431af0d5a5bf3ff446522fa06857891
+  metadata.gz: 5f538227b8eda210214fa448ede9f3247fa73bf997a2cfb04ca0a1b37c81b096198ad250b4e3dcf2f902a4f54eee16cb69233e68e03d65aca68c6bf497de72e4
+  data.tar.gz: 93f7b591e556713614c0310415301787605cf3cefc26718e94b74ee1ab60cec17ffaeaaec3d7b8ce5bb31deb40a51b1007d60bd9cdcba1211e4a8e06f1079293

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.1.15] - 2026-03-23
+
+- Performance: Medición de duraciones con reloj monotónico (`Process.clock_gettime`) en eventos terminales de `Engine`, `FileIngestor` y `GlueRunner`.
+- Fix: `idle_in_transaction_session_timeout` ahora se aplica correctamente cuando el valor es `0` (desactiva el timeout). Antes `0.present?` evaluaba a `false` y se ignoraba.
+- Fix: Objeto `DuckDB::Database` en `Record` ahora se ancla en el thread-local junto a la conexión, previniendo garbage collection prematura.
+- Fix: `Storage.adapter` cachea la instancia en vez de crearla en cada llamada.
+- Documentation: Agregado `CLAUDE.md` con guía de arquitectura y estándares del proyecto.
+
 ## [0.1.14] - 2026-03-17
 
 - Feature: Implementación de **Logging Estructurado** en toda la gema (\`key=value\`) para mejor observabilidad en producción.

data/CLAUDE.md

@@ -0,0 +1,56 @@
+# DataDrain - Contexto de Desarrollo
+
+## Arquitectura y Patrones Core
+
+- **Engine (`DataDrain::Engine`):** Orquesta el flujo ETL: Conteo → Export → Verify → Purge. El paso de export es omitible con `skip_export: true` (para delegar a AWS Glue).
+- **Storage Adapters (`DataDrain::Storage`):** Patrón Strategy. La instancia se cachea en `DataDrain::Storage.adapter`. Si `storage_mode` cambia en runtime, llamar `DataDrain::Storage.reset_adapter!` antes de la próxima operación.
+- **Analytical ORM (`DataDrain::Record`):** Interfaz tipo ActiveRecord de solo lectura sobre Parquet vía DuckDB. Usa una conexión DuckDB por thread (`Thread.current[:data_drain_duckdb_conn]`) que se inicializa una vez y se reutiliza — nunca se cierra explícitamente. Tener en cuenta en Puma/Sidekiq.
+- **Glue Orchestrator (`DataDrain::GlueRunner`):** Para tablas 1TB+. Patrón: `GlueRunner.run_and_wait(...)` seguido de `Engine.new(..., skip_export: true).call` para verificar + purgar.
+
+## Convenciones Críticas
+
+### Seguridad en Purga
+`purge_from_postgres` nunca debe ejecutarse si `verify_integrity` devuelve `false`. La verificación matemática de conteos (Postgres vs Parquet) es el único gate de seguridad antes de borrar datos.
+
+### Precisión de Fechas
+Las consultas SQL de rango siempre deben usar **límites semi-abiertos**:
+```sql
+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.
+
+### Idempotencia
+Las exportaciones usan `OVERWRITE_OR_IGNORE 1` de DuckDB. Los procesos son seguros de reintentar.
+
+### `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.
+
+## Logging
+
+Seguir los estándares globales definidos en `~/.claude/CLAUDE.md`. Reglas específicas de este proyecto:
+
+- Formato obligatorio: `component=data_drain event=<clase>.<suceso> [campos]`
+- El campo `source` lo inyecta automáticamente `exis_ray` vía `ExisRay::Tracer` — DataDrain no debe incluirlo ni recibirlo como parámetro
+- Nunca logs puramente descriptivos, con emojis ni con prefijos entre corchetes
+- DEBUG siempre en forma de bloque: `logger.debug { "k=#{v}" }`
+- Duraciones con reloj monotónico: `Process.clock_gettime(Process::CLOCK_MONOTONIC)`
+- Filtrar datos sensibles (`password`, `token`, `secret`, `api_key`, `auth`) → `[FILTERED]`
+
+## Código Ruby
+
+- Todo código nuevo o modificado debe pasar `bundle exec rubocop` sin ofensas
+- Documentación pública con YARD (`@param`, `@return`, `@raise`, `@example`)
+- No modificar ni agregar YARD/comentarios a código existente no tocado
+
+## Comandos
+
+```bash
+bundle exec rspec       # tests
+bundle exec rubocop     # linting
+bin/console             # REPL de desarrollo
+```
+
+## Rendimiento
+
+- `limit_ram` y `tmp_directory` en la configuración evitan OOM en contenedores
+- DuckDB usa spill-to-disk automáticamente cuando `tmp_directory` está seteado

data/lib/data_drain/engine.rb

@@ -49,6 +49,7 @@ 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)
       @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
@@ -56,7 +57,8 @@ module DataDrain
       @pg_count = get_postgres_count
 
       if @pg_count.zero?
-        @logger.info "component=data_drain event=engine.skip_empty table=#{@table_name}"
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        @logger.info "component=data_drain event=engine.skip_empty table=#{@table_name} duration=#{duration.round(2)}s"
         return true
       end
 
@@ -69,10 +71,12 @@ module DataDrain
 
       if verify_integrity
         purge_from_postgres
-        @logger.info "component=data_drain event=engine.complete table=#{@table_name}"
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        @logger.info "component=data_drain event=engine.complete table=#{@table_name} duration=#{duration.round(2)}s"
         true
       else
-        @logger.error "component=data_drain event=engine.integrity_error table=#{@table_name}"
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        @logger.error "component=data_drain event=engine.integrity_error table=#{@table_name} duration=#{duration.round(2)}s"
         false
       end
     end
@@ -167,7 +171,7 @@ module DataDrain
         dbname:   @config.db_name
       )
 
-      if @config.idle_in_transaction_session_timeout.present?
+      unless @config.idle_in_transaction_session_timeout.nil?
         conn.exec("SET idle_in_transaction_session_timeout = #{@config.idle_in_transaction_session_timeout};")
       end
 

data/lib/data_drain/file_ingestor.rb

@@ -30,6 +30,7 @@ module DataDrain
     # Ejecuta el flujo de ingestión.
     # @return [Boolean] true si el proceso fue exitoso.
     def call
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       @logger.info "component=data_drain event=file_ingestor.start source_path=#{@source_path}"
 
       unless File.exist?(@source_path)
@@ -51,6 +52,8 @@ module DataDrain
 
       if source_count.zero?
         cleanup_local_file
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        @logger.info "component=data_drain event=file_ingestor.skip_empty source_path=#{@source_path} duration=#{duration.round(2)}s"
         return true
       end
 
@@ -76,12 +79,14 @@ module DataDrain
       @logger.info "component=data_drain event=file_ingestor.export_start dest_path=#{dest_path}"
       @duckdb.query(query)
 
-      @logger.info "component=data_drain event=file_ingestor.complete source_path=#{@source_path}"
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      @logger.info "component=data_drain event=file_ingestor.complete source_path=#{@source_path} duration=#{duration.round(2)}s"
 
       cleanup_local_file
       true
     rescue DuckDB::Error => e
-      @logger.error "component=data_drain event=file_ingestor.duckdb_error source_path=#{@source_path} error=#{e.message}"
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      @logger.error "component=data_drain event=file_ingestor.duckdb_error source_path=#{@source_path} error=#{e.message} duration=#{duration.round(2)}s"
       false
     ensure
       @duckdb&.close

data/lib/data_drain/glue_runner.rb

@@ -16,6 +16,7 @@ module DataDrain
     def self.run_and_wait(job_name, arguments = {}, polling_interval: 30)
       config = DataDrain.configuration
       client = Aws::Glue::Client.new(region: config.aws_region)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
       config.logger.info "component=data_drain event=glue_runner.start job=#{job_name}"
       resp = client.start_job_run(job_name: job_name, arguments: arguments)
@@ -27,11 +28,13 @@ module DataDrain
 
         case status
         when "SUCCEEDED"
-          config.logger.info "component=data_drain event=glue_runner.complete job=#{job_name} run_id=#{run_id}"
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+          config.logger.info "component=data_drain event=glue_runner.complete job=#{job_name} run_id=#{run_id} duration=#{duration.round(2)}s"
           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}"
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+          config.logger.error "component=data_drain event=glue_runner.failed job=#{job_name} run_id=#{run_id} status=#{status} error=#{error_msg} duration=#{duration.round(2)}s"
           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"

data/lib/data_drain/record.rb

@@ -27,7 +27,7 @@ module DataDrain
     #
     # @return [DuckDB::Connection] Conexión activa a DuckDB.
     def self.connection
-      Thread.current[:data_drain_duckdb_conn] ||= begin
+      Thread.current[:data_drain_duckdb] ||= begin
         db = DuckDB::Database.open(":memory:")
         conn = db.connect
 
@@ -36,8 +36,9 @@ module DataDrain
         conn.query("SET temp_directory='#{config.tmp_directory}'") if config.tmp_directory.present?
 
         DataDrain::Storage.adapter.setup_duckdb(conn)
-        conn
+        { db: db, conn: conn }
       end
+      Thread.current[:data_drain_duckdb][:conn]
     end
 
     # Consulta registros en el Data Lake filtrando por claves de partición.

data/lib/data_drain/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_drain
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.1.15
 platform: ruby
 authors:
 - Gabriel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-22 00:00:00.000000000 Z
+date: 2026-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -88,10 +88,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".claude/settings.local.json"
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md

data/.claude/settings.local.json

@@ -1,24 +0,0 @@
-{
-  "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"
-          }
-        ]
-      }
-    ]
-  }
-}