tenant_partition 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a64a55d18e146680cc0efa637a7551edd6c04e724f76ebcfed9024ee47f4d33a
+  data.tar.gz: 94486994c67028a1564f65de2f1b4ec40a9bea9b36d9f52634cfe3bf83c0687e
+SHA512:
+  metadata.gz: 24b43da02e5216554e7b5b7f343a0a5a298e9c3b3e10c6525e8c8e90e36f84782d0c51c2ac06748906a357e287a621ab47c667159799d2915b13426dd30b7a5c
+  data.tar.gz: 421aeb63c9ea4230e25da6ebe09bec7107de32b3fdd2eff0a5291c390937dfd24c6a3223ef1fdec096b6205f43fa5342c584cd811e01321be3a0636d21d883b7

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-01-26
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 gabriel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,199 @@
+# ActivePartition
+
+**ActivePartition** es un framework de infraestructura para Ruby on Rails (7.1+) diseñado para simplificar y automatizar la gestión de **Particionamiento por Lista (List Partitioning)** nativo de PostgreSQL.
+
+Específicamente construido para arquitecturas **Multi-tenant**, este framework resuelve la complejidad de:
+1.  **Composite Primary Keys (CPK):** Configuración automática de claves compuestas (`id` + `partition_key`) requeridas por ActiveRecord para soportar particionamiento.
+2.  **Orquestación Centralizada:** Una única interfaz para crear y eliminar particiones en **todos** los modelos de la aplicación simultáneamente.
+3.  **Mantenimiento Zero-Downtime:** Migración atómica de datos "huérfanos" (que cayeron en la tabla `DEFAULT`) hacia sus particiones correctas sin perder servicio.
+
+## 🚀 Características Principales
+
+* **Fachada de Servicio:** API unificada (`ActivePartition.create!`, `destroy!`, `audit`, `cleanup!`) para gestionar el ciclo de vida completo de los tenants.
+* **Introspección Inteligente:** Los modelos de negocio detectan automáticamente su configuración de infraestructura por convención (ej: `User` -> `Partition::User`).
+* **Migration DSL:** Helper `create_partitioned_table` para definir tablas particionadas y sus tablas `DEFAULT` en una sola instrucción.
+* **Seguridad Estricta:** Concern para controladores que valida Headers HTTP (`X-Tenant-ID`) para asegurar el contexto del tenant.
+* **Observabilidad:** Instrumentación integrada con `ActiveSupport::Notifications`.
+
+## 📋 Requisitos
+
+* **Ruby:** >= 3.2
+* **Ruby on Rails:** >= 7.1
+* **PostgreSQL:** >= 13.0 (Requerido para `gen_random_uuid()` nativo)
+
+## 📦 Instalación
+
+Agrega esto a tu `Gemfile`:
+
+```ruby
+gem 'tenant_partition'
+```
+
+Luego ejecuta:
+
+```bash
+bundle install
+```
+
+## ⚙️ Configuración
+
+Crea un inicializador en `config/initializers/activepartition.rb`. Es **obligatorio** definir la clave de partición.
+
+```ruby
+ActivePartition.configure do |config|
+  # 1. La columna que discrimina los tenants (ej: :isp_id, :account_id, :tenant_id)
+  config.partition_key = :isp_id
+
+  # 2. El Header HTTP para la seguridad en controladores API
+  config.header_name   = 'X-Tenant-ID'
+end
+```
+
+## 🛠 Guía de Uso
+
+### 1. Migraciones (Crear las Tablas)
+
+Usa el helper `create_partitioned_table`. Este método deshabilita el ID automático simple y configura una **Primary Key Compuesta** (`[:id, :partition_key]`) necesaria para que PostgreSQL permita el particionamiento.
+
+```ruby
+class CreateConversations < ActiveRecord::Migration[7.1]
+  def change
+    create_partitioned_table :conversations do |t|
+      # No definas t.primary_key. La gema crea (id, isp_id) automáticamente.
+      t.string :topic
+      t.timestamps
+    end
+  end
+end
+```
+
+### 2. Capa de Infraestructura (Modelos Partition)
+
+Define modelos que hereden de `ActivePartition::Base`. Estos modelos son responsables de las operaciones DDL (Create/Drop tables). Por convención, se recomienda usar el namespace `Partition::`.
+
+```ruby
+# app/models/partition/conversation.rb
+module Partition
+  class Conversation < ActivePartition::Base
+    # Hereda la configuración global (:isp_id) automáticamente.
+  end
+end
+```
+
+### 3. Capa de Negocio (Modelos Rails)
+
+En tus modelos estándar (`ApplicationRecord`), incluye el concern `Partitioned`.
+
+**Magia de Introspección:**
+Al incluir el concern, la gema busca automáticamente si existe un modelo de infraestructura asociado (ej: `Partition::Conversation`) y hereda su configuración.
+
+```ruby
+# app/models/conversation.rb
+class Conversation < ApplicationRecord
+  include ActivePartition::Concerns::Partitioned
+
+  # ¡Listo! Rails ahora sabe que la Primary Key es [:id, :isp_id]
+  # y aplica scopes automáticos.
+end
+```
+
+### 4. Orquestación (Ciclo de Vida del Tenant)
+
+Ya no necesitas crear particiones tabla por tabla. Usa la **Fachada** `ActivePartition` para gestionar la infraestructura de un tenant en **todos** los modelos registrados simultáneamente.
+
+**Crear un nuevo Tenant (Provisioning):**
+Ideal para usar en tu `RegistrationService` o `AfterCommit` de la creación del tenant.
+
+```ruby
+# En tu Service Object o Controller de registro
+def create_tenant
+  isp = Isp.create!(params)
+
+  # Busca TODOS los modelos particionados y crea las tablas físicas para este ID.
+  # Es idempotente: si alguna ya existe, la salta sin error.
+  ActivePartition.create!(isp.id)
+end
+```
+
+**Eliminar un Tenant (Deprovisioning):**
+
+```ruby
+# Esta operación realiza DETACH + DROP de las tablas físicas.
+# ¡Es destructiva e irreversible!
+ActivePartition.destroy!(old_isp.id)
+```
+
+### 5. Seguridad en Controladores
+
+Protege tus API endpoints asegurando que siempre reciban el ID del tenant.
+
+```ruby
+class ApiController < ActionController::API
+  include ActivePartition::Concerns::Controller
+
+  # Valida que el request traiga el header 'X-Tenant-ID'.
+  # Devuelve 400 Bad Request si falta.
+  before_action :require_partition_key!
+
+  def index
+    # current_partition_id contiene el valor seguro del Header
+    @chats = Conversation.for_partition(current_partition_id).all
+    render json: @chats
+  end
+end
+```
+
+## 🛡 Mantenimiento y Recuperación
+
+ActivePartition maneja el escenario de "Race Condition" donde llegan datos *antes* de que la partición exista. Esos datos caen automáticamente en la tabla `_default`.
+
+### Auditoría
+
+Verifica si tienes datos "fugados" en las tablas default:
+
+```ruby
+# Desde consola Rails
+report = ActivePartition.audit
+# => { "Partition::Conversation" => 14, "Partition::Message" => 0 }
+```
+
+O vía Rake task:
+```bash
+bundle exec rails active_partition:audit
+```
+
+### Limpieza (Cleanup)
+
+Mueve los datos huérfanos a sus particiones correspondientes de forma atómica y segura.
+
+```ruby
+# Ruby API (Ideal para Jobs nocturnos)
+ActivePartition.cleanup!
+```
+
+O vía Rake task:
+```bash
+bundle exec rails active_partition:cleanup
+```
+
+## 📊 Observabilidad
+
+Puedes suscribirte a los eventos para enviar métricas a tu sistema de monitoreo (Datadog, Prometheus, NewRelic).
+
+```ruby
+# config/initializers/notifications.rb
+ActiveSupport::Notifications.subscribe(/activepartition/) do |name, start, finish, id, payload|
+  duration = (finish - start) * 1000
+
+  case name
+  when "create.active_partition"
+    Rails.logger.info "📦 Partición creada: #{payload[:table]} para #{payload[:value]}"
+  when "populate.active_partition"
+    Rails.logger.info "🧹 Limpieza: #{payload[:count]} registros movidos en #{duration.round(2)}ms"
+  end
+end
+```
+
+## 📄 Licencia
+
+Este proyecto está disponible como código abierto bajo los términos de la [Licencia MIT](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/lib/activepartition/base.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module ActivePartition
+  # Clase base para la gestión de infraestructura de particionamiento en PostgreSQL.
+  #
+  # Proporciona una interfaz para manejar el ciclo de vida de las tablas físicas (Particiones).
+  #
+  # @abstract Hereda de esta clase para definir un recurso de partición.
+  # @example
+  #   class Partition::Chat < ActivePartition::Base
+  #     # Opcional: Sobrescribir la clave global
+  #     self.partition_key = :region_code
+  #   end
+  class Base
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    # Registra el atributo de partición en la subclase en el momento de la herencia.
+    def self.inherited(subclass)
+      super
+      # Intentamos definir el atributo por defecto si existe configuración global
+      key = ActivePartition.configuration&.partition_key
+      subclass.attribute key if key
+    end
+
+    class << self
+      attr_writer :parent_table, :prefix, :default_table
+
+      # Permite inyectar una clave de partición personalizada por clase
+      attr_writer :partition_key
+
+      def parent_table
+        @parent_table ||= name.demodulize.underscore.pluralize
+      end
+
+      # Prioridad: 1. Clave de la clase, 2. Clave global
+      def partition_key
+        @partition_key ||= ActivePartition.configuration&.partition_key ||
+          raise(ActivePartition::Error, "Clave de partición no configurada.")
+      end
+
+      def partition_key=(value)
+        @partition_key = value
+        attribute value # Define el atributo en ActiveModel automáticamente
+      end
+
+      def prefix
+        @prefix ||= "#{parent_table}_#{partition_key.to_s.gsub('_id', '')}"
+      end
+
+      def default_table
+        @default_table ||= "#{parent_table}_default"
+      end
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+
+      # Crea físicamente una partición en PostgreSQL.
+      def create(value)
+        # Importante: Usamos el método partition_key (no la variable) para respetar overrides
+        payload = { partition_key: partition_key, value: value, table: parent_table }
+
+        ActiveSupport::Notifications.instrument("create.active_partition", payload) do
+          name = partition_name(value)
+          sql = "CREATE TABLE IF NOT EXISTS #{name} PARTITION OF #{parent_table} FOR VALUES IN ('#{value}');"
+          connection.execute(sql)
+          new(partition_key => value)
+        end
+      end
+
+      def partition_name(value)
+        sanitized = value.to_s.gsub('-', '_')
+        "#{prefix}_#{sanitized}"
+      end
+
+      def exists?(value)
+        name = partition_name(value)
+        sql = <<-SQL.squish
+          SELECT 1 FROM pg_class c
+          JOIN pg_inherits i ON c.oid = i.inhrelid
+          JOIN pg_class p ON i.inhparent = p.oid
+          WHERE p.relname = '#{parent_table}' AND c.relname = '#{name}';
+        SQL
+        connection.execute(sql).any?
+      end
+
+      def find(value)
+        new(partition_key => value) if exists?(value)
+      end
+    end
+
+    # --- Métodos de Instancia ---
+
+    def partition_id
+      # CORRECCIÓN: Usamos public_send porque ActiveModel no tiene read_attribute
+      # Esto invoca al getter generado dinámicamente (ej: .isp_id)
+      public_send(self.class.partition_key)
+    end
+
+    def partition_table_name
+      self.class.partition_name(partition_id)
+    end
+
+    def persisted?
+      self.class.exists?(partition_id)
+    end
+
+    # Mueve registros desde la tabla por defecto hacia la partición atómicamente.
+    def populate_from_default(batch_size: 5000)
+      return 0 unless persisted?
+
+      parent  = self.class.parent_table
+      default = self.class.default_table
+      key     = self.class.partition_key
+      val     = partition_id
+
+      payload = { partition_key: key, value: val, parent_table: parent }
+
+      ActiveSupport::Notifications.instrument("populate.active_partition", payload) do |notification_payload|
+        total_moved = 0
+
+        loop do
+          batch_count = 0
+          self.class.connection.transaction do
+            # Usamos el ID para paginar el borrado/insertado
+            move_sql = <<-SQL.squish
+              WITH moved_rows AS (
+                DELETE FROM #{default}
+                WHERE #{key} = '#{val}'
+                AND id IN (
+                  SELECT id FROM #{default} WHERE #{key} = '#{val}' LIMIT #{batch_size}
+                )
+                RETURNING *
+              )
+              INSERT INTO #{parent} SELECT * FROM moved_rows;
+            SQL
+
+            result = self.class.connection.execute(move_sql)
+            batch_count = result.cmd_tuples
+          end
+
+          total_moved += batch_count
+          break if batch_count < batch_size
+        end
+
+        notification_payload[:count] = total_moved
+        total_moved
+      end
+    end
+
+    def destroy
+      return false unless persisted?
+
+      p_name = partition_table_name
+      p_table = self.class.parent_table
+
+      self.class.connection.transaction do
+        self.class.connection.execute("ALTER TABLE #{p_table} DETACH PARTITION #{p_name};")
+        self.class.connection.execute("DROP TABLE IF EXISTS #{p_name};")
+      end
+      true
+    rescue ActiveRecord::StatementInvalid
+      false
+    end
+  end
+end

data/lib/activepartition/concerns/controller.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ActivePartition
+  module Concerns
+    # Helpers y validaciones para controladores en arquitecturas Multi-tenant.
+    #
+    # Este módulo implementa una estrategia de extracción estricta:
+    # Solo acepta el ID de partición si viene en el Header HTTP configurado explícitamente.
+    #
+    # @example Configuración requerida
+    #   # config/initializers/active_partition.rb
+    #   ActivePartition.configure do |config|
+    #     config.partition_key = :isp_id
+    #     config.header_name = 'X-Tenant-ID' # <--- Obligatorio
+    #   end
+    #
+    # @example Uso en el controlador
+    #   class ApiController < ActionController::API
+    #     include ActivePartition::Concerns::Controller
+    #     before_action :require_partition_key!
+    #   end
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        # Expone el método a las vistas de Rails (erb, jbuilder, etc.)
+        helper_method :current_partition_id if respond_to?(:helper_method)
+      end
+
+      # Devuelve el valor del ID de partición actual extraído exclusivamente de los Headers.
+      #
+      # Utiliza únicamente el nombre de header definido en +ActivePartition.configuration.header_name+.
+      # No realiza inferencias ni busca en parámetros de la URL.
+      #
+      # @return [String, nil] El valor del header o nil si no está presente o configurado.
+      def current_partition_id
+        return @current_partition_id if defined?(@current_partition_id)
+
+        header_key = ActivePartition.configuration.header_name
+
+        # Si no se configuró un nombre de header, no podemos buscar nada.
+        return @current_partition_id = nil unless header_key.present?
+
+        @current_partition_id = request.headers[header_key]
+      end
+
+      # Filtro (before_action) para detener la ejecución si el ID de partición no está presente.
+      #
+      # Retorna un error 400 Bad Request si el header falta.
+      #
+      # @return [void]
+      def require_partition_key!
+        return if current_partition_id.present?
+
+        header_key = ActivePartition.configuration.header_name
+
+        # Mensaje de error detallado dependiendo de si es un error de configuración o de petición
+        error_message = if header_key.blank?
+                          "Server Configuration Error: 'header_name' is not configured in ActivePartition."
+                        else
+                          "Missing required header: '#{header_key}'"
+                        end
+
+        render json: {
+          error: "Partitioning Error",
+          message: error_message
+        }, status: :bad_request
+      end
+    end
+  end
+end

data/lib/activepartition/concerns/partitioned.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module ActivePartition
+  module Concerns
+    # Módulo de infraestructura para modelos de negocio (ApplicationRecord).
+    #
+    # Este concern es el encargado de adaptar el modelo de Rails para trabajar con
+    # la estructura de tablas particionadas de PostgreSQL. Su función crítica es
+    # configurar las **Primary Keys Compuestas (CPK)** requeridas por Rails 7.1+.
+    #
+    # ### Estrategia de Resolución de Claves
+    # El módulo determina qué columna usar como clave de partición siguiendo este orden de prioridad:
+    #
+    # 1. **Explícita:** Definida manualmente con `partitioned_by :key` en el modelo.
+    # 2. **Inferencia (Convención):** Busca si existe una clase de infraestructura asociada
+    #    (ej: para `Conversation` busca `Partition::Conversation`) y utiliza su configuración.
+    # 3. **Global:** Utiliza la clave definida en `ActivePartition.configure`.
+    #
+    # @example Modo Automático (Inferencia)
+    #   # Si Partition::LegacyChat tiene `self.partition_key = :region_id`
+    #   class LegacyChat < ApplicationRecord
+    #     include ActivePartition::Concerns::Partitioned
+    #     # Automáticamente configura PK: [:id, :region_id]
+    #   end
+    #
+    # @example Modo Manual (Override)
+    #   class Log < ApplicationRecord
+    #     include ActivePartition::Concerns::Partitioned
+    #     partitioned_by :custom_id
+    #   end
+    module Partitioned
+      extend ActiveSupport::Concern
+
+      included do
+        # Punto de entrada para inclusión directa.
+        # 'self' es la clase que incluye el módulo.
+        ActivePartition::Concerns::Partitioned.configure_model(self)
+      end
+
+      class_methods do
+        # Hook de Ruby disparado al heredar.
+        # Permite incluir el módulo en ApplicationRecord y que la configuración
+        # se aplique automáticamente a cada subclase en el momento de su definición.
+        #
+        # @param subclass [Class] La clase que está heredando.
+        def inherited(subclass)
+          super
+          ActivePartition::Concerns::Partitioned.configure_model(subclass)
+        end
+
+        # Define manualmente la clave de partición, ignorando la inferencia y la config global.
+        #
+        # @param key [Symbol] Nombre de la columna de partición.
+        def partitioned_by(key)
+          ActivePartition::Concerns::Partitioned.apply_configuration(self, key)
+        end
+      end
+
+      # --- Métodos de Utilería (Privados de la Gema) ---
+
+      # Orquesta la configuración del modelo.
+      # @api private
+      def self.configure_model(klass)
+        # Ignoramos clases abstractas para evitar errores de tabla inexistente.
+        return if klass.respond_to?(:abstract_class?) && klass.abstract_class?
+
+        # Resolvemos la clave correcta según la prioridad establecida.
+        key_to_use = resolve_partition_key(klass)
+
+        apply_configuration(klass, key_to_use) if key_to_use.present?
+      end
+
+      # Determina la clave de partición inspeccionando la infraestructura y la configuración.
+      #
+      # @param klass [Class] El modelo de negocio a inspeccionar.
+      # @return [Symbol, nil] La clave de partición encontrada o nil.
+      # @api private
+      def self.resolve_partition_key(klass)
+        # 1. Inferencia por Convención:
+        #    Buscamos la clase "Partition::NombreDelModelo".
+        #    Ej: Conversation -> Partition::Conversation
+        infra_class_name = "Partition::#{klass.name}"
+
+        # safe_constantize (ActiveSupport) devuelve la clase si existe, nil si no.
+        # No lanza excepciones si la constante no está definida.
+        infra_class = infra_class_name.safe_constantize
+
+        if infra_class && infra_class.respond_to?(:partition_key)
+          # Si existe el modelo de infraestructura, confiamos en su configuración.
+          return infra_class.partition_key
+        end
+
+        # 2. Configuración Global (Fallback):
+        ActivePartition.configuration&.partition_key
+      end
+
+      # Aplica la configuración de Primary Key y Scopes al modelo.
+      #
+      # @param klass [Class] El modelo a configurar.
+      # @param key [Symbol] La clave de partición.
+      # @api private
+      def self.apply_configuration(klass, key)
+        # Idempotencia:
+        # Si la clase ya tiene la PK compuesta correcta, no hacemos nada.
+        # Esto previene conflictos si se llama múltiples veces.
+        return if klass.primary_key.is_a?(Array) && klass.primary_key.include?(key.to_s)
+
+        # A. Configuración de CPK (Composite Primary Keys) - Rails 7.1+
+        #    Le dice a Rails que la identidad única es (id + partition_key).
+        klass.primary_key = [:id, key]
+
+        # B. Scope de Conveniencia
+        #    Permite usar Model.for_partition("uuid")
+        klass.scope :for_partition, ->(value) { where(key => value) }
+      end
+    end
+  end
+end

data/lib/activepartition/configuration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActivePartition
+  class Configuration
+    # @return [Symbol, nil] Columna de base de datos (ej: :isp_id)
+    attr_accessor :partition_key
+
+    # @return [String, nil] Nombre del Header HTTP personalizado (ej: 'X-Tenant-ID')
+    attr_accessor :header_name
+
+    def initialize
+      @partition_key = nil
+      @header_name = nil
+    end
+
+    def valid?
+      !partition_key.nil?
+    end
+  end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+
+      unless configuration.valid?
+        raise ActivePartition::Error, "Debe configurar un 'partition_key' en el inicializador de ActivePartition."
+      end
+    end
+  end
+end

data/lib/activepartition/railtie.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module ActivePartition
+  # Railtie encargado de integrar ActivePartition en el ciclo de vida de Rails.
+  #
+  # Su responsabilidad principal es inyectar los componentes de la gema (Tareas Rake,
+  # Helpers de Migración) en la aplicación anfitriona durante el proceso de arranque.
+  class Railtie < Rails::Railtie
+    # Bloque para cargar tareas Rake.
+    # Debe estar definido DENTRO de la clase Railtie para tener acceso al método +rake_tasks+.
+    #
+    # Carga las tareas de mantenimiento (audit, cleanup) para que estén
+    # disponibles mediante el comando `rails`.
+    rake_tasks do
+      # Usamos expand_path para asegurar que la ruta sea absoluta respecto a la gema,
+      # evitando errores de "file not found" dependiendo de dónde se ejecute el comando.
+      load File.expand_path("tasks/maintenance.rake", __dir__)
+    end
+
+    # Inicializador que se ejecuta cuando Rails carga los componentes de ActiveRecord.
+    #
+    # Inyecta los helpers de migración (como +create_partitioned_table+) directamente
+    # en el adaptador de PostgreSQL para extender el DSL de las migraciones.
+    initializer "active_partition.insert_schema_statements" do
+      ActiveSupport.on_load(:active_record) do
+        require "activepartition/schema/statements"
+
+        # Validación de seguridad:
+        # Solo inyectamos el módulo si el adaptador configurado es efectivamente PostgreSQL.
+        # Esto previene errores si la gema se instala en proyectos con MySQL o SQLite.
+        if defined?(ActiveRecord::ConnectionAdapters::PostgreSQLAdapter) && connection_db_config.adapter == "postgresql"
+          ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.include ActivePartition::Schema::Statements
+        end
+      end
+    end
+  end
+end

data/lib/activepartition/safety_guard.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ActivePartition
+  # Clase encargada de validar que el entorno y la configuración sean aptos
+  # para el funcionamiento de ActivePartition.
+  class SafetyGuard
+    # Versión mínima de PostgreSQL soportada para particionamiento nativo estable.
+    MIN_POSTGRES_VERSION = 13.0
+
+    # Ejecuta todas las validaciones de seguridad.
+    # @raise [ActivePartition::Error] Si alguna validación falla.
+    # @return [void]
+    def self.validate!
+      check_configuration!
+      return unless defined?(Rails) && Rails.env.to_s != 'test'
+
+      check_database_adapter!
+      check_postgres_version!
+    end
+
+    private
+
+    # Verifica que la clave de partición esté presente.
+    def self.check_configuration!
+      if ActivePartition.configuration.partition_key.nil?
+        raise ActivePartition::Error, "Falta configuración: 'partition_key' no ha sido definido."
+      end
+    end
+
+    # Asegura que se esté utilizando PostgreSQL.
+    def self.check_database_adapter!
+      adapter = ActiveRecord::Base.connection_db_config.adapter
+      unless adapter == "postgresql"
+        raise ActivePartition::Error, "Adaptador incompatible: ActivePartition solo soporta PostgreSQL (usando: #{adapter})."
+      end
+    end
+
+    # Verifica la versión de PostgreSQL mediante una consulta directa al motor.
+    def self.check_postgres_version!
+      version = ActiveRecord::Base.connection.select_value("SHOW server_version").to_f
+      if version < MIN_POSTGRES_VERSION
+        raise ActivePartition::Error, "Versión de PostgreSQL insuficiente: Se requiere v#{MIN_POSTGRES_VERSION}+ (detectada: #{version})."
+      end
+    rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
+      # Si no hay conexión aún, se posterga la validación
+    end
+  end
+end

data/lib/activepartition/schema/statements.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ActivePartition
+  module Schema
+    # Proporciona métodos adicionales para las migraciones de ActiveRecord
+    # enfocados en la automatización del particionamiento nativo de PostgreSQL.
+    module Statements
+      # Crea una tabla padre particionada por lista y genera automáticamente
+      # su partición por defecto (DEFAULT).
+      #
+      # CORRECCIÓN IMPORTANTE: Configura una Primary Key Compuesta (id + partition_key)
+      # para cumplir con los requisitos de unicidad de PostgreSQL en tablas particionadas.
+      #
+      # @param table_name [Symbol, String] El nombre de la tabla a crear.
+      # @param options [Hash] Opciones estándar + :partition_key opcional.
+      # @yield [t] Bloque para definir las columnas de la tabla.
+      def create_partitioned_table(table_name, **options, &block)
+        # Prioridad: 1. Opción pasada al método, 2. Configuración global
+        key = options.delete(:partition_key) || ActivePartition.configuration&.partition_key
+
+        unless key
+          raise ActivePartition::Error, "Debe configurar 'partition_key' globalmente o pasarlo como opción."
+        end
+
+        # --- LÓGICA DE PRIMARY KEY COMPUESTA ---
+        # 1. Desactivamos la creación automática del ID simple, ya que Postgres fallaría.
+        options[:id] = false
+
+        # 2. Definimos explícitamente que la PK está formada por el ID y la CLAVE DE PARTICIÓN.
+        # Esto genera en SQL: PRIMARY KEY (id, isp_id)
+        options[:primary_key] = [:id, key]
+
+        # 3. Inyectamos la estrategia de particionamiento
+        options[:options] = "PARTITION BY LIST (#{key})"
+
+        # Crear la tabla padre
+        create_table(table_name, **options) do |t|
+          # A. Como desactivamos id: false, debemos crear la columna ID manualmente.
+          # Usamos gen_random_uuid() para que sea autogenerado.
+          t.uuid :id, null: false, default: -> { "gen_random_uuid()" }
+
+          # B. Ejecutamos las definiciones del usuario
+          block.call(t)
+
+          # C. Inyección automática del atributo de partición si el usuario no lo definió.
+          # Nota: Si el usuario ya puso `t.uuid :isp_id` en su migración, esta línea la salta.
+          unless t.columns.any? { |c| c.name == key.to_s }
+            t.column key, :string, null: false
+          end
+        end
+
+        # Crear la partición DEFAULT
+        default_name = "#{table_name}_default"
+        execute <<-SQL.squish
+          CREATE TABLE IF NOT EXISTS #{default_name}
+          PARTITION OF #{table_name} DEFAULT;
+        SQL
+      end
+
+      # Elimina una tabla particionada y su tabla por defecto asociada.
+      def drop_partitioned_table(table_name)
+        drop_table(table_name, cascade: true)
+      end
+    end
+  end
+end

data/lib/activepartition/tasks/maintenance.rake

@@ -0,0 +1,14 @@
+# lib/activepartition/tasks/maintenance.rake
+# frozen_string_literal: true
+
+namespace :active_partition do
+  desc "Audita todas las tablas DEFAULT definidas en ActivePartition"
+  task audit: :environment do
+    ActivePartition.audit
+  end
+
+  desc "Limpia registros huérfanos moviéndolos a sus particiones"
+  task cleanup: :environment do
+    ActivePartition.cleanup!
+  end
+end

data/lib/activepartition/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActivePartition
+  VERSION = "0.1.0"
+end

data/lib/activepartition.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_model"
+require "active_support/all"
+
+# Carga de la versión y componentes internos
+require_relative "activepartition/version"
+require_relative "activepartition/configuration"
+require_relative "activepartition/safety_guard"
+require_relative "activepartition/base"
+require_relative "activepartition/concerns/partitioned"
+require_relative "activepartition/concerns/controller"
+
+# Integración con Ruby on Rails
+require_relative "activepartition/railtie" if defined?(Rails)
+
+# ActivePartition es el punto de entrada principal para la gestión de particionamiento
+# en PostgreSQL dentro de aplicaciones Rails.
+#
+# Actúa como una **Fachada** que centraliza:
+# 1. Configuración de la gema.
+# 2. Orquestación del ciclo de vida de los tenants (Crear/Borrar particiones).
+# 3. Mantenimiento y limpieza de datos huérfanos.
+module ActivePartition
+  # Error base para todas las excepciones de la gema.
+  class Error < StandardError; end
+
+  class << self
+    # @return [ActivePartition::Configuration] El objeto de configuración global.
+    attr_accessor :configuration
+
+    # Configura la gema mediante un bloque e inicializa las validaciones de seguridad.
+    #
+    # @yieldparam [ActivePartition::Configuration] config
+    # @return [void]
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+      SafetyGuard.validate!
+    end
+
+    # =========================================================================
+    # GRUPO 1: ORQUESTACIÓN DE TENANTS (Ciclo de Vida)
+    # =========================================================================
+
+    # Crea las particiones físicas para un tenant específico en TODOS los modelos registrados.
+    #
+    # Este método es **idempotente**: verifica si la partición existe antes de intentar crearla,
+    # evitando errores de SQL.
+    #
+    # @param partition_id [String, Integer] El ID del tenant (ej: el UUID del ISP).
+    # @return [void]
+    def create!(partition_id)
+      ensure_models_loaded!
+
+      log_info "CREATE", "Iniciando aprovisionamiento para ID: #{partition_id}"
+
+      partitionable_models.each do |model|
+        if model.exists?(partition_id)
+          log_info "SKIP", "#{model.name}: La partición ya existe."
+        else
+          model.create(partition_id)
+          log_info "OK", "#{model.name}: Partición creada exitosamente."
+        end
+      end
+    end
+
+    # Elimina (DETACH + DROP) las particiones físicas de un tenant en TODOS los modelos.
+    #
+    # @warning Esta acción es destructiva e irreversible. Borra los datos físicos.
+    #
+    # @param partition_id [String, Integer] El ID del tenant a eliminar.
+    # @return [void]
+    def destroy!(partition_id)
+      ensure_models_loaded!
+
+      log_info "DESTROY", "Eliminando infraestructura para ID: #{partition_id}"
+
+      partitionable_models.each do |model|
+        if model.exists?(partition_id)
+          partition = model.find(partition_id)
+          if partition.destroy
+            log_info "DROP", "#{model.name}: Partición eliminada."
+          else
+            log_error "FAIL", "#{model.name}: No se pudo eliminar la partición."
+          end
+        else
+          log_info "SKIP", "#{model.name}: No existe partición para borrar."
+        end
+      end
+    end
+
+    # =========================================================================
+    # GRUPO 2: MANTENIMIENTO Y OPS (Audit & Cleanup)
+    # =========================================================================
+
+    # Audita todas las tablas DEFAULT buscando registros "huérfanos".
+    #
+    # Un registro huérfano es aquel que se insertó en la tabla padre pero, al no existir
+    # su partición correspondiente en ese momento, cayó en la tabla _default.
+    #
+    # @return [Hash{String => Integer}] Mapa con el nombre del modelo y la cantidad de registros huérfanos.
+    # @example
+    #   ActivePartition.audit
+    #   # => { "Partition::Message" => 150, "Partition::Log" => 0 }
+    def audit
+      ensure_models_loaded!
+      report = {}
+
+      log_info "AUDIT", "Iniciando auditoría de tablas DEFAULT..."
+
+      partitionable_models.each do |model|
+        count = count_default_rows(model)
+        report[model.name] = count
+
+        if count > 0
+          log_warn "ALERTA", "#{model.name}: #{count} registros huérfanos encontrados."
+        else
+          log_info "OK", "#{model.name}: Tabla default limpia."
+        end
+      end
+
+      report
+    end
+
+    # Realiza una limpieza global moviendo registros huérfanos a sus particiones correctas.
+    #
+    # 1. Identifica qué IDs de tenant tienen datos en las tablas DEFAULT.
+    # 2. Verifica si ya existe la partición física para esos IDs.
+    # 3. Mueve los datos atómicamente.
+    #
+    # @return [void]
+    def cleanup!
+      ensure_models_loaded!
+      key = configuration.partition_key
+
+      log_info "CLEANUP", "Iniciando proceso de limpieza global..."
+
+      partitionable_models.each do |model|
+        # Obtenemos los IDs únicos presentes en la tabla default
+        orphan_ids = fetch_orphan_ids(model, key)
+
+        if orphan_ids.empty?
+          log_info "OK", "#{model.name}: Sin datos huérfanos."
+          next
+        end
+
+        log_warn "FIX", "#{model.name}: Procesando #{orphan_ids.count} tenants con datos huérfanos."
+
+        orphan_ids.each do |id|
+          partition = model.find(id)
+
+          if partition
+            moved = partition.populate_from_default
+            log_info "MOVE", "  -> ID #{id}: #{moved} registros recuperados."
+          else
+            log_error "ERROR", "  -> ID #{id}: La partición física no existe. Cree el tenant primero."
+          end
+        end
+      end
+    end
+
+    private
+
+    # Encuentra todas las clases cargadas que heredan de ActivePartition::Base.
+    # @return [Array<Class>]
+    def partitionable_models
+      ObjectSpace.each_object(Class).select { |klass| klass < ActivePartition::Base }
+    end
+
+    # Cuenta registros en la tabla default de un modelo de infraestructura.
+    # @return [Integer]
+    def count_default_rows(model)
+      model.connection.select_value("SELECT count(*) FROM #{model.default_table}").to_i
+    rescue ActiveRecord::StatementInvalid
+      0
+    end
+
+    # Obtiene los IDs de partición distintos que existen en la tabla default.
+    # @return [Array<String>]
+    def fetch_orphan_ids(model, key)
+      sql = "SELECT DISTINCT #{key} FROM #{model.default_table} WHERE #{key} IS NOT NULL"
+      model.connection.execute(sql).map { |r| r[key.to_s] }
+    rescue ActiveRecord::StatementInvalid
+      []
+    end
+
+    # Asegura que Rails haya cargado los modelos de infraestructura.
+    # Vital en modo Development donde la carga es perezosa (Lazy Loading).
+    def ensure_models_loaded!
+      return unless defined?(Rails)
+
+      partition_dir = Rails.root.join("app/models/partition")
+      return unless Dir.exist?(partition_dir)
+
+      # Forzamos la carga de todos los archivos en app/models/partition/
+      Dir[partition_dir.join("**/*.rb")].each { |file| require_dependency file }
+    end
+
+    # Helpers de Logging
+    def log_info(tag, msg)  = logger&.info(format_log(tag, msg))
+    def log_warn(tag, msg)  = logger&.warn(format_log(tag, msg))
+    def log_error(tag, msg) = logger&.error(format_log(tag, msg))
+
+    def format_log(tag, msg)
+      "[ActivePartition] [#{tag}] #{msg}"
+    end
+
+    def logger
+      defined?(Rails) ? Rails.logger : Logger.new($stdout)
+    end
+  end
+end

data/sig/activepartition.rbs

@@ -0,0 +1,4 @@
+module ActivePartition
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: tenant_partition
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- gabriel
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: Framework de infraestructura para Rails 7.1+ que automatiza el particionamiento
+  nativo (List Partitioning). Incluye soporte para Composite Primary Keys, orquestación
+  de tenants y migraciones zero-downtime.
+email:
+- gedera@wispro.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/activepartition.rb
+- lib/activepartition/base.rb
+- lib/activepartition/concerns/controller.rb
+- lib/activepartition/concerns/partitioned.rb
+- lib/activepartition/configuration.rb
+- lib/activepartition/railtie.rb
+- lib/activepartition/safety_guard.rb
+- lib/activepartition/schema/statements.rb
+- lib/activepartition/tasks/maintenance.rake
+- lib/activepartition/version.rb
+- sig/activepartition.rbs
+homepage: https://github.com/gedera/activepartition
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/gedera/tenant_partition
+  changelog_uri: https://github.com/gedera/tenant_partition/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Gestión de particiones PostgreSQL al estilo Rails.
+test_files: []