tenant_partition 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e675f290b7cbe1ef13c1d6db7ec36894a92c169c82ae42112a1b0979c220f9f1
-  data.tar.gz: 4470f638d2f110c48d9f22a1b8a685f2c598dd01292cb867617a45782d7def11
+  metadata.gz: 968c88d57e55597859aceca92e0404d0430d8277f8dd84ebb20d25d0fb1b011f
+  data.tar.gz: 46fc3262411b92a3083373710b6cffac249201910ff8344a619610ed88b0cfd3
 SHA512:
-  metadata.gz: 87115b8fc726b431102c6ea6d53103f71370d643a3fc543504ceb94df1d718eedd4041092a7f2384ecb98e9825447ba88281a32035ee244081b04579bda041c6
-  data.tar.gz: 3d535affbac9ea2101aaf1d8ecd415f379fb0e8cfa0d1a826b5d02e01567bd1a90f87ae01dd9be53744d8fe975e467a1362ac24f773e417b17d4635ec6b4d0e6
+  metadata.gz: 1aa3eb1a9a6ae2596b69458aebf7b8b77c985aa7087cac89ef679adefd59b0636835fba9e8ea9ee544f0d4065a18be6887d00a281236ad8bc50c82b03d58c9a1
+  data.tar.gz: e335c13f9df1178a53296599f99593e5fe3489e83403229a46f1e53fa41b572558ea1ca66947602c2e392dcb86188630a2c95d16473a861a1f0e26e5f4ee047a

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-09
+### Added (Zero-Downtime Migrations)
+- **Migraciones Online:** Nueva suite de herramientas para migrar tablas masivas en producción sin tiempo de inactividad (Zero-Downtime).
+- **Schema Statements:** Se agregaron los helpers `create_partition_sync_trigger`, `remove_partition_sync_trigger` y `swap_partitioned_tables` para manejar el Live Sync mediante Triggers de base de datos y Cutover atómico.
+- **Backfill Engine (`TenantPartition::Migrator`):** Nueva clase para mover millones de registros en segundo plano. Incluye resolución automática de conflictos (`UPSERT`) para convivir con la replicación en vivo, y soporte nativo de paginación por fechas (`created_at`) para tablas que usan UUIDs.
+- **Generador de Rails:** Nuevo comando `rails g tenant_partition:online_migration` que genera automáticamente las migraciones de 5 fases necesarias para migrar una tabla de forma segura.
+- **Rake Tasks:** Nueva tarea `rake tenant_partition:backfill_data` para ejecutar el copiado de datos fácilmente desde la consola o background jobs.
+
+### Changed
+- **Railtie:** Se actualizó la carga de tareas Rake para incluir dinámicamente todos los archivos `.rake` del directorio `tasks/`, permitiendo que coexistan las tareas de mantenimiento y migración.
+
 ## [0.2.1] - 2026-02-13
 ### Added
 - **Mejora en Migraciones:** El helper `create_partitioned_table` ahora acepta la opción `id_type: :uuid` o `id_type: :bigint` (por defecto). Esto permite usar particionamiento con IDs enteros seriales estándar o UUIDs según la necesidad del proyecto.

data/README.md

@@ -1,24 +1,25 @@
-# TenantPartition
+# TenantPartition 🏢
 
-**TenantPartition** es una solución robusta y "Rails-native" para implementar **Particionamiento Declarativo (List Partitioning)** de PostgreSQL en aplicaciones Ruby on Rails.
+**TenantPartition** es un framework de infraestructura "Rails-native" diseñado para implementar **Particionamiento Declarativo (List Partitioning)** de PostgreSQL en aplicaciones Ruby on Rails (7.1+).
 
-A diferencia de otras soluciones que dependen de esquemas (schemas) o hackeos a la conexión de base de datos, `tenant_partition` utiliza características nativas de PostgreSQL para dividir tablas gigantes en tablas físicas más pequeñas por tenant (Cliente, ISP, Organización, etc.), manteniendo la experiencia de desarrollo de ActiveRecord estándar.
+A diferencia de otras soluciones multi-tenant que dependen de múltiples esquemas (schemas) o hackeos a nivel de consultas (row-level filtering), `tenant_partition` utiliza características nativas del motor de PostgreSQL para dividir físicamente tablas gigantes en tablas más pequeñas y ultrarrápidas por tenant (Cliente, ISP, Organización, etc.). Todo esto, manteniendo intacta la experiencia de desarrollo estándar de ActiveRecord.
 
 ## 🚀 Características Principales
 
-* **API Simple (Opt-in):** Usa `partition_table` en tus modelos para activar la magia.
-* **Migraciones Inteligentes:** Helper `create_partitioned_table` que maneja la complejidad de Postgres automáticamente.
-* **Soporte Nativo CPK:** Compatible con **Composite Primary Keys** de Rails 7.1+.
-* **Sin Magic Strings:** Usa métodos explícitos (`create_partition`, `drop_partition`).
-* **Gestión de Datos Huérfanos:** Herramientas para mover datos de la tabla "Default" a su partición correcta automáticamente.
-* **Safety Guards:** Protección contra borrados accidentales en Producción.
-* **Tasks de Mantenimiento:** Rake tasks integradas para auditoría y limpieza.
+* **API Simple y Opt-in:** Activa el particionamiento en tus modelos simplemente agregando la macro `partition_table`.
+* **Zero-Downtime Migrations (2 Fases):** Herramientas de nivel empresarial para migrar tablas masivas en producción sin detener el servicio, con barreras anti-errores para despliegues en CI/CD.
+* **Introspección Dinámica (Safe Deploys):** El código de tus modelos detecta automáticamente si la tabla en la base de datos ya fue particionada, permitiendo desplegar tu código *antes* de finalizar las migraciones de infraestructura.
+* **Smart Hashing para UUIDs:** Evasión automática del límite de 63 caracteres de PostgreSQL en el nombrado de tablas al usar UUIDs largos como claves de partición.
+* **Sincronización en Tiempo Real (Live Sync):** Triggers de base de datos automatizados con resolución de conflictos (`UPSERT`) integrada.
+* **Backfill Engine con Auto-Aprovisionamiento JIT:** Motor de copiado en segundo plano que crea automáticamente las particiones hijas al vuelo (Just-In-Time) a medida que descubre nuevos tenants.
+* **Soporte Nativo CPK:** Totalmente compatible con **Composite Primary Keys** de Rails 7.1+.
+* **Gestión de Datos Huérfanos:** Auditoría y auto-reparación de registros que caen en la partición `_default`.
 
 ---
 
 ## 📦 Instalación
 
-Agrega esto a tu `Gemfile`:
+Agrega la gema a tu `Gemfile`:
 
 ```ruby
 gem 'tenant_partition'
@@ -30,191 +31,218 @@ Y ejecuta:
 bundle install
 ```
 
+**Requisitos mínimos:** Ruby 3.2+, Rails 7.1+ y PostgreSQL 13+ (Optimizado para PG 17). *(Nota: La gema incluye "magia" retrocompatible para operar en Rails 6.0+ bajo su propio riesgo).*
+
 ---
 
 ## ⚙️ Configuración Inicial
 
-### 1. Inicializador
-Crea un archivo para definir tu clave de partición global (por ejemplo, `:isp_id`, `:account_id`, `:tenant_id`).
+**1. Configuración Global**
+Crea un archivo de inicialización para definir tu clave de partición base (por ejemplo, `:isp_id`, `:account_id` o `:tenant_id`).
 
 ```ruby
 # config/initializers/tenant_partition.rb
-
 TenantPartition.configure do |config|
-  # Esta es la columna que actuará como discriminador global
+  # Columna que actuará como discriminador principal en toda la base de datos
   config.partition_key = :isp_id
 end
 ```
 
-### 2. Habilitar en ApplicationRecord
-Incluye el concern en tu modelo base. **No te preocupes, esto no particiona nada por defecto**, solo habilita la posibilidad de usar la macro `partition_table` en tus modelos.
+**2. Habilitar el DSL en ActiveRecord**
+Inyecta el comportamiento base en tu aplicación. Esto **no** particiona tus modelos por defecto, solo les da la habilidad de entender la macro de la gema.
 
 ```ruby
 # app/models/application_record.rb
 class ApplicationRecord < ActiveRecord::Base
   primary_abstract_class
 
-  # Habilita la herramienta (modo inactivo por defecto)
   include TenantPartition::Concerns::Partitioned
 end
 ```
 
 ---
 
-## 🛠 Guía de Implementación
+## 🛠 Guía 1: Tablas Nuevas (Green Field)
 
-### Paso 1: Migración de Base de Datos
+Si estás desarrollando un feature desde cero, particionar una tabla nueva es sumamente directo.
 
-Olvídate del SQL manual. Usa el helper `create_partitioned_table` que hace todo el trabajo sucio por ti:
-1.  Crea la tabla padre con `PARTITION BY LIST`.
-2.  Configura la Primary Key Compuesta `[:id, :partition_key]`.
-3.  Crea automáticamente la partición `_default` para capturar datos no asignados.
-
-#### Opción A: Usando Enteros (BigInt) - Recomendado
+### 1. La Migración
+Usa el helper `create_partitioned_table`. Este configura automáticamente la Primary Key Compuesta, la partición tipo `LIST` y la tabla `_default`.
 
 ```ruby
 class CreateConversations < ActiveRecord::Migration[7.1]
   def change
-    # partition_key: usa el default de la config (:isp_id) si no se especifica.
-    # id_type: :bigint por defecto.
-    create_partitioned_table :conversations do |t|
+    # Soporta id_type: :bigint (por defecto) o :uuid
+    create_partitioned_table :conversations, id_type: :uuid do |t|
       t.string :subject
       t.text :body
       t.timestamps
-
-      # Nota: No definas :id ni :isp_id aquí, el helper lo hace por ti.
+      
+      # 🪄 Nota: NO definas explícitamente el :id ni el :isp_id aquí. 
+      # La gema lo hace por ti automáticamente.
     end
   end
 end
 ```
 
-#### Opción B: Usando UUIDs
-
+### 2. El Modelo
 ```ruby
-class CreateConversations < ActiveRecord::Migration[7.1]
-  def change
-    enable_extension 'pgcrypto' # Necesario para gen_random_uuid()
-
-    create_partitioned_table :conversations, id_type: :uuid do |t|
-      t.string :subject
-      t.timestamps
-    end
-  end
+class Conversation < ApplicationRecord
+  # Activa la Composite Primary Key y los scopes de enrutamiento
+  partition_table 
 end
 ```
 
-### Paso 2: Configurar el Modelo
+---
+
+## 🔥 Guía 2: Migrar una Tabla Existente (Zero-Downtime)
+
+Si tienes una tabla legacy con millones de registros y necesitas particionarla en producción sin causar tiempo de inactividad, utiliza nuestra suite de migración en dos fases.
+
+*(⚠️ **Requisito:** La tabla original ya debe tener la columna de tu `partition_key` definida).*
+
+### Fase 1: Preparación, Código y Live Sync (Despliegue 1)
+Genera la infraestructura inicial ejecutando:
+
+```bash
+rails g tenant_partition:prepare versions isp_id
+```
 
-Usa la macro `partition_table` para activar la funcionalidad en el modelo correspondiente.
+Abre la migración generada en `db/migrate/`. Gracias a la **introspección**, la gema clonará la estructura de tu tabla original y configurará los triggers de PostgreSQL (`INSERT/UPDATE/DELETE`) en un solo paso:
 
 ```ruby
-# app/models/conversation.rb
-class Conversation < ApplicationRecord
-  # ¡Esto es todo!
-  # Automáticamente configura la Primary Key compuesta [:id, :isp_id]
-  # y los scopes necesarios.
-  partition_table
+def up
+  create_partitioned_table_from(
+    :versions_partitioned, :versions, partition_key: :isp_id, sync_triggers: true
+  )
 end
 ```
 
-**¿Necesitas una key diferente para un solo modelo?**
+**Activa la gema en tu modelo:** Agrega la macro a tu clase ActiveRecord.
 ```ruby
-class AuditLog < ApplicationRecord
-  # Este modelo se particiona por año, ignorando la config global
-  partition_table key: :year
+class Version < ApplicationRecord
+  partition_table 
 end
 ```
+*(🪄 **Safe Deploy:** Gracias a la Introspección Dinámica, la gema sabe que la base de datos aún no ha finalizado la migración. El modelo seguirá comportándose como una tabla normal sin romper tu aplicación).*
 
-### Paso 3: Crear y Eliminar Tenants
+**👉 Ejecuta `rails db:migrate` y despliega a producción.** A partir de este milisegundo, la base de datos enviará todo dato "vivo" nuevo a tu nueva tabla sombra, y tu código estará listo para el futuro.
 
-Gestiona el ciclo de vida de las particiones utilizando los métodos de clase inyectados.
+### Fase 2: Backfill Histórico (Fase Manual)
+Con la app corriendo, copia el historial pesado ejecutando esta tarea (idealmente en un entorno de background job o consola de ops):
 
-```ruby
-# Crear partición física para el ISP con ID 100
-Conversation.create_partition(100)
-# => Crea la tabla "conversations_isp_100"
+Para tablas con **IDs Enteros**:
+```bash
+rake tenant_partition:backfill_data[PaperTrail::Version,versions_partitioned,id]
+```
+Para tablas con **UUIDs** (Paginación segura por fecha):
+```bash
+rake tenant_partition:backfill_data[PaperTrail::Version,versions_partitioned,created_at]
+```
+*(🪄 **Auto-Aprovisionamiento JIT:** El `Migrator` creará las particiones físicas al vuelo utilizando "Smart Hashing" para evitar los límites de 63 caracteres de PostgreSQL. Además, resolverá conflictos usando `ON CONFLICT DO UPDATE` para no pisar los datos vivos).*
 
-# Verificar si existe
-Conversation.partition_table_exists?(100)
-# => true
+### Fase 3: Cutover Atómico (Despliegue 2)
+Una vez que el Backfill termine al 100%, genera la migración de intercambio final:
 
-# Eliminar partición (CUIDADO: Borra datos)
-Conversation.drop_partition(100)
-# => Elimina "conversations_isp_100"
+```bash
+rails g tenant_partition:cutover versions isp_id
 ```
 
-#### Automatización con Callbacks
-Es común crear las particiones automáticamente cuando nace un nuevo Tenant.
+**👉 Ejecuta `rails db:migrate` y despliega a producción.** Una transacción atómica cruzará los nombres de las tablas y eliminará los triggers en 1 milisegundo. 
+En el instante en que los servidores se reinicien tras el deploy, tu modelo (`Version`) consultará a PostgreSQL, detectará que la tabla ahora sí es particionada, y activará automáticamente sus superpoderes (Composite Primary Keys y Partition Pruning). **¡Cero downtime logrado!**
+
+---
+
+## 🔍 Consultas y Rendimiento (Partition Pruning)
+
+Para que PostgreSQL sea extremadamente rápido, debe aprovechar el **Partition Pruning** (poda de particiones), yendo directamente a la tabla hija en lugar de escanear toda la base de datos.
+
+La gema inyecta automáticamente el scope `for_partition(valor)`.
 
+```ruby
+# ❌ LENTO: Escaneará todas las particiones hijas
+Conversation.where(status: 'active') 
+
+# ✅ ULTRARRÁPIDO: Va directamente a 'conversations_isp_123'
+Conversation.for_partition(123).where(status: 'active')
+```
+
+---
+
+## 🏗 Orquestación del Ciclo de Vida de los Tenants
+
+Debes crear la infraestructura física (la tabla hija) para cada Tenant a medida que nacen nuevos clientes en tu sistema.
+
+**Integración directa en tus Modelos:**
 ```ruby
 # app/models/isp.rb
 class Isp < ApplicationRecord
   after_create :provision_infrastructure
+  after_destroy :destroy_infrastructure
+
+  private
 
   def provision_infrastructure
-    # Helper global que crea particiones en TODOS los modelos registrados
+    # Crea las particiones en TODOS los modelos que tengan `partition_table`
     TenantPartition.create!(self.id)
   end
+
+  def destroy_infrastructure
+    TenantPartition.destroy!(self.id)
+  end
 end
 ```
 
----
+**Generador de API:**
+Si prefieres orquestar esto desde un microservicio externo, puedes generar un controlador pre-armado:
+```bash
+rails g tenant_partition:api_controller System
+# Creará: app/controllers/system/tenant_partitions_controller.rb
+```
 
-## 🧹 Mantenimiento y Datos Huérfanos
+---
 
-Si insertas datos con un `isp_id` para el cual no has creado una partición, Postgres los guardará en la tabla `_default` que creamos en la migración. `TenantPartition` incluye herramientas para detectar y corregir esto.
+## 🧹 Mantenimiento: Datos Huérfanos
 
-### Auditoría
-Verifica si tienes datos "mal ubicados" en las tablas default:
+Si un registro es insertado antes de que su tenant sea aprovisionado, PostgreSQL lo enviará de forma segura a la tabla `_default`. Puedes auditar y corregir esto con tareas Rake:
 
+**1. Auditoría (Encontrar datos perdidos):**
 ```bash
-bundle exec rake tenant_partition:audit
+rake tenant_partition:audit
 # [TenantPartition] [AUDIT] Iniciando auditoría...
 # [TenantPartition] [ALERTA] Conversation: 450 registros huérfanos encontrados.
 ```
 
-### Limpieza (Cleanup)
-Crea las particiones faltantes y mueve los datos automáticamente a su hogar correcto:
-
-```bash
-bundle exec rake tenant_partition:cleanup
-# [TenantPartition] [FIX] Conversation: Procesando 2 tenants con datos huérfanos.
-# [TenantPartition] [MOVE] -> ID 101: 450 registros recuperados.
-```
-
----
-
-## 🛡️ Producción y Seguridad
-
-La gema incluye un `SafetyGuard` que impide ejecutar comandos destructivos (`drop_partition`, `destroy!`) en entorno de producción para evitar catástrofes.
-
-Si realmente necesitas borrar un tenant en producción, debes autorizarlo explícitamente:
-
+**2. Limpieza (Mover a su lugar correcto):**
+*(Asegúrate de haber aprovisionado el tenant primero)*
 ```bash
-DISABLE_TENANT_PARTITION_GUARD=true bundle exec rake tenant_partition:destroy_tenant[123]
+rake tenant_partition:cleanup
+# [TenantPartition] [MOVE] -> ID 101: 450 registros recuperados hacia su partición.
 ```
 
 ---
 
-## 📖 Referencia de API
+## 📖 Referencia Rápida de la API
 
-### `TenantPartition` (Global)
-* `configure { ... }`: Configuración inicial.
-* `create!(id)`: Crea particiones para el ID dado en **todos** los modelos registrados.
-* `destroy!(id)`: Elimina particiones para el ID dado en **todos** los modelos.
-* `exists?(id)`: Devuelve `true` si existe infraestructura para ese ID.
+**Módulo Global `TenantPartition`**
+* `.create!(id)`: Aprovisionamiento de tablas para un tenant en toda la app.
+* `.destroy!(id)`: Eliminación de tablas de un tenant (protegido en Prod).
+* `.exists?(id)`: Verifica infraestructura.
 
-### Métodos de Instancia (Modelos)
-* `partition_table(key: nil)`: Macro de activación.
+**Macros de Modelo**
+* `partition_table(key: nil)`: Activa particionamiento (opcional: sobreescribe clave).
+* `for_partition(value)`: Scope de búsqueda optimizada (con auto-casteo de tipos).
+* `create_partition(value)`, `drop_partition(value)`: Operaciones DDL manuales por modelo.
+* `partitions`: Devuelve nombres de tablas físicas hijas (incluyendo `_default`).
+* `partition_values`: Devuelve los IDs/valores de tenants que ya tienen partición.
 
-### Métodos de Clase (Modelos)
-* `create_partition(value)`: Crea tabla física.
-* `drop_partition(value)`: Borra tabla física.
-* `partition_table_exists?(value)`: Verifica existencia.
-* `partition_table_name(value)`: Devuelve el nombre real de la tabla en Postgres.
+**Helpers de Migraciones**
+* `create_partitioned_table(table_name, **options)`
+* `create_partitioned_table_from(target, source, sync_triggers: false, **options)`
+* `swap_partitioned_tables(legacy, partitioned)`
 
 ---
 
-## License
+## Licencia
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Esta gema está disponible como código abierto bajo los términos de la [MIT License](https://opensource.org/licenses/MIT).

data/lib/generators/tenant_partition/cutover_generator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module TenantPartition
+  module Generators
+    # Generador de la Fase 2 (Cutover) para migraciones Zero-Downtime.
+    #
+    # Este generador crea la migración final necesaria para completar el proceso de
+    # particionamiento en vivo. La migración generada se encarga de realizar un
+    # intercambio atómico (Swap) a nivel de PostgreSQL: renombra la tabla legacy a
+    # un nombre de respaldo, y activa la tabla particionada (sombra) con el nombre original,
+    # eliminando al mismo tiempo los triggers de sincronización temporal.
+    #
+    # @example Generar migración de cutover para la tabla 'versions'
+    #   rails g tenant_partition:cutover versions isp_id
+    class CutoverGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # @!attribute [r] table_name
+      #   @return [String] El nombre de la tabla legacy original.
+      argument :table_name, type: :string, banner: "nombre_de_la_tabla_actual"
+
+      # @!attribute [r] partition_key
+      #   @return [String] El nombre de la columna utilizada como clave de partición.
+      argument :partition_key, type: :string, banner: "columna_partition_key"
+
+      desc "Genera la Fase 2 (Cutover): Intercambia las tablas de forma atómica y elimina triggers."
+
+      # Método requerido por Rails::Generators::Migration para la nomenclatura de archivos.
+      # Determina el siguiente número (timestamp) para el archivo de migración.
+      #
+      # @param dirname [String] El directorio donde se guardarán las migraciones.
+      # @return [String] El prefijo numérico para el archivo.
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      # Crea el archivo de migración de cutover en la carpeta db/migrate.
+      # Utiliza la plantilla complete_online_migration.rb.erb.
+      #
+      # @return [void]
+      def create_cutover_migration
+        migration_template(
+          "complete_online_migration.rb.erb",
+          "db/migrate/complete_online_migration_for_#{table_name}.rb",
+          migration_version: migration_version
+        )
+      end
+
+      # Muestra en consola las instrucciones críticas y advertencias de seguridad
+      # una vez que el generador termina de ejecutarse exitosamente.
+      #
+      # @return [void]
+      # Muestra en consola las instrucciones críticas y advertencias de seguridad
+      # forzando la interpolación ERB para una mejor experiencia de usuario.
+      def show_readme
+        if behavior == :invoke
+          template_path = File.join(self.class.source_root, "CUTOVER_README")
+          parsed_readme = ERB.new(File.read(template_path)).result(binding)
+          puts "\n#{parsed_readme}\n"
+        end
+      end
+
+      private
+
+      # Obtiene la versión actual de ActiveRecord para inyectarla en la sintaxis de la migración.
+      #
+      # @return [String] Ejemplo: "[7.1]"
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      # Construye el nombre de la tabla destino (sombra) que ahora pasará a ser la principal.
+      #
+      # @return [String] Ejemplo: "versions_partitioned"
+      def target_table
+        "#{table_name}_partitioned"
+      end
+    end
+  end
+end

data/lib/generators/tenant_partition/prepare_generator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module TenantPartition
+  module Generators
+    # Generador de la Fase 1 (Preparación) para migraciones Zero-Downtime.
+    #
+    # Este generador crea la infraestructura inicial necesaria para comenzar a migrar
+    # una tabla legacy hacia una tabla particionada sin tiempo de inactividad.
+    # Específicamente, genera una migración que clona la estructura de la tabla
+    # original y establece los triggers de PostgreSQL para la sincronización en vivo (Live Sync).
+    #
+    # @example Generar migración de preparación para la tabla 'versions'
+    #   rails g tenant_partition:prepare versions isp_id
+    class PrepareGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # @!attribute [r] table_name
+      #   @return [String] El nombre de la tabla legacy que se desea migrar.
+      argument :table_name, type: :string, banner: "nombre_de_la_tabla_actual"
+
+      # @!attribute [r] partition_key
+      #   @return [String] El nombre de la columna que actuará como clave de partición.
+      argument :partition_key, type: :string, banner: "columna_partition_key"
+
+      desc "Genera la Fase 1 (Preparación): Crea la tabla sombra y los triggers de Live Sync."
+
+      # Método requerido por Rails::Generators::Migration para la nomenclatura de archivos.
+      # Determina el siguiente número (timestamp) para el archivo de migración.
+      #
+      # @param dirname [String] El directorio donde se guardarán las migraciones.
+      # @return [String] El prefijo numérico para el archivo.
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      # Crea el archivo de migración de preparación en la carpeta db/migrate.
+      # Utiliza la plantilla prepare_online_migration.rb.erb.
+      #
+      # @return [void]
+      def create_preparation_migration
+        migration_template(
+          "prepare_online_migration.rb.erb",
+          "db/migrate/prepare_online_migration_for_#{table_name}.rb",
+          migration_version: migration_version
+        )
+      end
+
+      # Muestra en consola las instrucciones de los siguientes pasos
+      # una vez que el generador termina de ejecutarse exitosamente.
+      #
+      # @return [void]
+      def show_readme
+        readme "PREPARE_README" if behavior == :invoke
+      end
+
+      private
+
+      # Obtiene la versión actual de ActiveRecord para inyectarla en la sintaxis de la migración.
+      #
+      # @return [String] Ejemplo: "[7.1]"
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      # Construye el nombre de la tabla destino (sombra) que recibirá los datos.
+      #
+      # @return [String] Ejemplo: "versions_partitioned"
+      def target_table
+        "#{table_name}_partitioned"
+      end
+    end
+  end
+end

data/lib/generators/tenant_partition/templates/CUTOVER_README

@@ -0,0 +1,22 @@
+===============================================================================
+🚀 ¡Fase 2: Cutover Generado Exitosamente!
+
+Has generado la migración final de intercambio atómico.
+
+⚠️  ¡ALTO! ANTES DE DESPLEGAR A PRODUCCIÓN ⚠️
+Asegúrate de que el proceso de Backfill masivo haya terminado al 100%.
+Puedes verificarlo reemplazando "Model" por tu clase real (ej. PaperTrail::Version) 
+y ejecutando esto en tu consola de Rails (`rails c`):
+
+  Model.count == Model.from('<%= table_name %>_partitioned').count
+
+Si te devuelve `true`, los números coinciden:
+1. Sube este código y ejecuta la migración en Producción (Despliegue 2).
+   Esto hará el intercambio atómico de Postgres en 1 milisegundo.
+
+2. ¡Listo! En el próximo reinicio de los servidores, tu modelo
+   detectará el cambio en la base de datos y activará automáticamente
+   sus superpoderes gracias a la Introspección Dinámica.
+
+¡Felicidades por lograr una migración Zero-Downtime perfecta!
+===============================================================================

data/lib/generators/tenant_partition/templates/PREPARE_README

@@ -0,0 +1,12 @@
+===============================================================================
+🪄 ¡Fase 1: Preparación Online Generada!
+
+1. Revisa el archivo de migración generado en db/migrate/.
+2. Sube este código a tu repositorio y despliega en Producción (Despliegue 1).
+3. Con la nueva tabla sombra ya creada en BD, ejecuta el Backfill histórico:
+   `rake tenant_partition:backfill_data[MiModelo,mi_tabla_partitioned]`
+
+Una vez que el copiado llegue al 100%, podrás generar el intercambio final
+con el comando de Fase 2:
+`rails g tenant_partition:cutover nombre_tabla partition_key`
+===============================================================================

data/lib/generators/tenant_partition/templates/complete_online_migration.rb.erb

@@ -0,0 +1,21 @@
+class CompleteOnlineMigrationFor<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def up
+    # 3. Intercambio Atómico (Cutover)
+    swap_partitioned_tables(:<%= table_name %>, :<%= target_table %>)
+
+    # La tabla original quedó renombrada como '<%= table_name %>_legacy' como backup.
+    # Cuando estés seguro de que todo funciona, puedes crear otra migración para borrarla.
+  end
+
+  def down
+    # Revierte el swap de nombres
+    swap_partitioned_tables(:<%= target_table %>, :<%= table_name %>)
+
+    # Restaura los triggers por si hay que volver atrás
+    create_partition_sync_trigger(
+      :<%= table_name %>,
+      :<%= target_table %>,
+      :<%= partition_key %>
+    )
+  end
+end

data/lib/generators/tenant_partition/templates/prepare_online_migration.rb.erb

@@ -0,0 +1,22 @@
+class PrepareOnlineMigrationFor<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def up
+    # 🪄 Magia de TenantPartition:
+    # Esto lee la tabla actual '<%= table_name %>', crea '<%= target_table %>'
+    # con exactamente las mismas columnas y automáticamente instala los triggers de sincronización.
+    create_partitioned_table_from(
+      :<%= target_table %>,
+      :<%= table_name %>,
+      partition_key: :<%= partition_key %>,
+      sync_triggers: true
+      # id_type: :uuid # Descomenta esto si tu tabla original usa UUIDs
+    ) do |t|
+      # Opcional: Agrega aquí índices para tu nueva tabla si los necesitas.
+      # Ejemplo: t.index [:mi_columna, :<%= partition_key %>]
+    end
+  end
+
+  def down
+    remove_partition_sync_trigger(:<%= table_name %>, :<%= target_table %>)
+    drop_partitioned_table(:<%= target_table %>)
+  end
+end