tenant_partition 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f9ccf1323d98dd3c78356387de4666127584d7539098e6501d326da1d107fa0
-  data.tar.gz: 05e849e009ee93921e6de9b8f207a6ae91781e2b177295d2ae23def5df5e07b1
+  metadata.gz: e675f290b7cbe1ef13c1d6db7ec36894a92c169c82ae42112a1b0979c220f9f1
+  data.tar.gz: 4470f638d2f110c48d9f22a1b8a685f2c598dd01292cb867617a45782d7def11
 SHA512:
-  metadata.gz: 368ec2f0cfc8b312ca5b5ac61eb7ace18da414faae68846e6353e7058cb5079f04777a0c6418fdd03ddd66da90df188f05d23c43dce8292a556a13d30ca48da1
-  data.tar.gz: ecab7244f3a6e106c96a27954b2df753fd1ac0143d67423b35b653c7816dfc973b946b538f1b6a6afb6dae7b0d44ff358b607bb6d394b86e17e0b9704ef86034
+  metadata.gz: 87115b8fc726b431102c6ea6d53103f71370d643a3fc543504ceb94df1d718eedd4041092a7f2384ecb98e9825447ba88281a32035ee244081b04579bda041c6
+  data.tar.gz: 3d535affbac9ea2101aaf1d8ecd415f379fb0e8cfa0d1a826b5d02e01567bd1a90f87ae01dd9be53744d8fe975e467a1362ac24f773e417b17d4635ec6b4d0e6

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [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.
+
 ## [0.2.0] - 2026-02-13
 ### Changed (Breaking Changes)
 - **Arquitectura:** Se eliminó la clase `TenantPartition::Base` y la necesidad de crear modelos de infraestructura en el namespace `Partition::`.

data/README.md

@@ -7,6 +7,7 @@ A diferencia de otras soluciones que dependen de esquemas (schemas) o hackeos a
 ## 🚀 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.
@@ -33,7 +34,8 @@ bundle install
 
 ## ⚙️ Configuración Inicial
 
-Crea un inicializador para definir tu clave de partición global (por ejemplo, `:isp_id`, `:account_id`, `:tenant_id`).
+### 1. Inicializador
+Crea un archivo para definir tu clave de partición global (por ejemplo, `:isp_id`, `:account_id`, `:tenant_id`).
 
 ```ruby
 # config/initializers/tenant_partition.rb
@@ -44,105 +46,105 @@ TenantPartition.configure do |config|
 end
 ```
 
----
-
-## 🏗 Estrategias de Uso
-
-La gema utiliza un patrón "Opt-In". Incluir el módulo no altera tus modelos hasta que lo activas explícitamente. Puedes elegir la estrategia que mejor se adapte a tu proyecto:
-
-### Opción A: Global (Recomendado)
-Incluye el concern en `ApplicationRecord`. Esto **NO** particiona tus tablas, solo habilita la posibilidad de usar la macro `partition_table` en el futuro. Es ideal para mantener el código limpio.
+### 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.
 
 ```ruby
 # app/models/application_record.rb
 class ApplicationRecord < ActiveRecord::Base
   primary_abstract_class
 
-  # Habilita la herramienta, pero permanece inactiva por defecto.
-  include TenantPartition::Concerns::Partitioned
-end
-```
-
-### Opción B: Local (A la carta)
-Si prefieres no tocar `ApplicationRecord` o estás en un sistema legacy, puedes incluir el concern solo en los modelos específicos.
-
-```ruby
-# app/models/conversation.rb
-class Conversation < ApplicationRecord
+  # Habilita la herramienta (modo inactivo por defecto)
   include TenantPartition::Concerns::Partitioned
-  partition_table # Activación inmediata
 end
 ```
 
 ---
 
-## 📖 Referencia de Macros y Métodos
+## 🛠 Guía de Implementación
 
-Una vez que incluyes `TenantPartition::Concerns::Partitioned` en tu clase, obtienes acceso a las siguientes herramientas:
+### Paso 1: Migración de Base de Datos
 
-### 1. La Macro de Activación: `partition_table`
+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.
 
-Es el interruptor de encendido. Debe llamarse al inicio de la definición del modelo.
+#### Opción A: Usando Enteros (BigInt) - Recomendado
 
 ```ruby
-class Conversation < ApplicationRecord
-  # Uso estándar (usa la key configurada globalmente, ej: :isp_id)
-  partition_table
+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|
+      t.string :subject
+      t.text :body
+      t.timestamps
 
-  # Uso personalizado (para modelos con keys únicas, ej: :year)
-  # partition_table key: :year
+      # Nota: No definas :id ni :isp_id aquí, el helper lo hace por ti.
+    end
+  end
 end
 ```
 
-**¿Qué hace esta macro internamente?**
-1.  Configura la **Primary Key Compuesta** (`[:id, :partition_key]`).
-2.  Registra el modelo en el sistema de mantenimiento de la gema.
-3.  Inyecta los métodos de gestión de infraestructura (ver abajo).
-4.  Agrega el scope `for_partition(value)`.
+#### Opción B: Usando UUIDs
 
-### 2. Métodos de Gestión de Infraestructura (Class Methods)
+```ruby
+class CreateConversations < ActiveRecord::Migration[7.1]
+  def change
+    enable_extension 'pgcrypto' # Necesario para gen_random_uuid()
 
-Estos métodos se inyectan en tu modelo **solo después** de llamar a `partition_table`. Úsalos para gestionar el ciclo de vida de las tablas físicas.
+    create_partitioned_table :conversations, id_type: :uuid do |t|
+      t.string :subject
+      t.timestamps
+    end
+  end
+end
+```
 
-| Método | Descripción | Ejemplo |
-| :--- | :--- | :--- |
-| `create_partition(val)` | Crea la tabla física en Postgres (`CREATE TABLE ... PARTITION OF ...`). | `Conversation.create_partition(100)` |
-| `drop_partition(val)` | Elimina la tabla física y sus datos (`DROP TABLE ...`). | `Conversation.drop_partition(100)` |
-| `partition_table_exists?(val)` | Devuelve `true` si la tabla física existe en la BD. | `Conversation.partition_table_exists?(100)` |
-| `partition_table_name(val)` | Devuelve el nombre real de la tabla hija. | `Conversation.partition_table_name(100)` <br> *=> "conversations_isp_100"* |
+### Paso 2: Configurar el Modelo
 
----
+Usa la macro `partition_table` para activar la funcionalidad en el modelo correspondiente.
 
-## 🛠 Guía de Implementación
+```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
+end
+```
 
-### 1. Migración de Base de Datos
+**¿Necesitas una key diferente para un solo modelo?**
+```ruby
+class AuditLog < ApplicationRecord
+  # Este modelo se particiona por año, ignorando la config global
+  partition_table key: :year
+end
+```
 
-PostgreSQL necesita que la tabla padre se cree con la opción `PARTITION BY LIST`.
+### Paso 3: Crear y Eliminar Tenants
 
-```ruby
-class CreateConversations < ActiveRecord::Migration[7.1]
-  def up
-    # 1. Crear la tabla padre particionada (id: false es importante)
-    create_table :conversations, id: false, options: "PARTITION BY LIST (isp_id)" do |t|
-      t.bigserial :id, null: false
-      t.integer :isp_id, null: false # Tu partition key
+Gestiona el ciclo de vida de las particiones utilizando los métodos de clase inyectados.
 
-      t.string :subject
-      t.timestamps
-    end
+```ruby
+# Crear partición física para el ISP con ID 100
+Conversation.create_partition(100)
+# => Crea la tabla "conversations_isp_100"
 
-    # 2. Definir la Primary Key Compuesta (Requerido por Postgres)
-    execute "ALTER TABLE conversations ADD PRIMARY KEY (id, isp_id);"
+# Verificar si existe
+Conversation.partition_table_exists?(100)
+# => true
 
-    # 3. Crear tabla DEFAULT (Recomendado para evitar errores de inserción)
-    execute "CREATE TABLE conversations_default PARTITION OF conversations DEFAULT;"
-  end
-# ...
+# Eliminar partición (CUIDADO: Borra datos)
+Conversation.drop_partition(100)
+# => Elimina "conversations_isp_100"
 ```
 
-### 2. Callbacks de Aprovisionamiento
-
-Es común automatizar la creación de particiones cuando se crea un nuevo Tenant (ej. un nuevo ISP o Cliente).
+#### Automatización con Callbacks
+Es común crear las particiones automáticamente cuando nace un nuevo Tenant.
 
 ```ruby
 # app/models/isp.rb
@@ -150,7 +152,7 @@ class Isp < ApplicationRecord
   after_create :provision_infrastructure
 
   def provision_infrastructure
-    # Método helper que crea las particiones en TODOS los modelos registrados
+    # Helper global que crea particiones en TODOS los modelos registrados
     TenantPartition.create!(self.id)
   end
 end
@@ -160,10 +162,10 @@ end
 
 ## 🧹 Mantenimiento y Datos Huérfanos
 
-Si insertas datos con un `isp_id` para el cual no has creado una partición (y tienes una tabla `DEFAULT`), los datos caerán ahí.
+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.
 
 ### Auditoría
-Verifica si tienes datos en las tablas default:
+Verifica si tienes datos "mal ubicados" en las tablas default:
 
 ```bash
 bundle exec rake tenant_partition:audit
@@ -172,7 +174,7 @@ bundle exec rake tenant_partition:audit
 ```
 
 ### Limpieza (Cleanup)
-Crea las particiones faltantes y mueve los datos automáticamente:
+Crea las particiones faltantes y mueve los datos automáticamente a su hogar correcto:
 
 ```bash
 bundle exec rake tenant_partition:cleanup
@@ -184,9 +186,9 @@ bundle exec rake tenant_partition:cleanup
 
 ## 🛡️ Producción y Seguridad
 
-La gema incluye un `SafetyGuard` que impide ejecutar comandos destructivos (`drop_partition`, `destroy!`) en entorno de producción a menos que se fuerce explícitamente.
+La gema incluye un `SafetyGuard` que impide ejecutar comandos destructivos (`drop_partition`, `destroy!`) en entorno de producción para evitar catástrofes.
 
-Para ejecutar tareas destructivas en producción, debes setear la variable de entorno:
+Si realmente necesitas borrar un tenant en producción, debes autorizarlo explícitamente:
 
 ```bash
 DISABLE_TENANT_PARTITION_GUARD=true bundle exec rake tenant_partition:destroy_tenant[123]
@@ -194,6 +196,25 @@ DISABLE_TENANT_PARTITION_GUARD=true bundle exec rake tenant_partition:destroy_te
 
 ---
 
+## 📖 Referencia de 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étodos de Instancia (Modelos)
+* `partition_table(key: nil)`: Macro de activació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.
+
+---
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/tenant_partition/schema/statements.rb

@@ -10,15 +10,18 @@ module TenantPartition
       # @param table_name [Symbol] Nombre de la tabla.
       # @param options [Hash] Opciones de migración estándar.
       # @option options [Symbol] :partition_key Clave opcional para sobreescribir la global.
+      # @option options [Symbol] :id_type Tipo de ID (:uuid o :bigint). Default: :bigint.
       # @yield [t] Bloque de definición de tabla (ActiveRecord::ConnectionAdapters::TableDefinition).
       def create_partitioned_table(table_name, **options, &block)
         key = options.delete(:partition_key) || TenantPartition.configuration&.partition_key
+        id_type = options.delete(:id_type) || :bigint # Default conservador (BigInt)
+
         raise TenantPartition::Error, "Falta 'partition_key'." unless key
 
         configure_pk_and_options(options, key)
 
         create_table(table_name, **options) do |t|
-          setup_partitioning(t, key, block)
+          setup_partitioning(t, key, id_type, block)
         end
 
         create_default_partition(table_name)
@@ -33,9 +36,17 @@ module TenantPartition
       private
 
       # Configura las columnas y definiciones dentro del bloque create_table.
-      def setup_partitioning(table, key, block)
-        table.uuid :id, null: false, default: -> { "gen_random_uuid()" }
+      def setup_partitioning(table, key, id_type, block)
+        # Definimos la ID según la preferencia del usuario
+        if id_type == :uuid
+          table.uuid :id, null: false, default: -> { "gen_random_uuid()" }
+        else
+          table.bigserial :id, null: false
+        end
+
+        # Ejecutamos el bloque del usuario (definición de columnas adicionales)
         block.call(table)
+
         ensure_partition_column(table, key)
       end
 
@@ -50,7 +61,9 @@ module TenantPartition
       def ensure_partition_column(table, key)
         return if table.columns.any? { |c| c.name == key.to_s }
 
-        table.column key, :string, null: false
+        # Si no la definió, la creamos (asumiendo integer por defecto para claves foráneas típicas)
+        # Si el usuario quiere un UUID como partition key, debería definirlo explícitamente en el bloque.
+        table.integer key, null: false
       end
 
       # Crea la tabla _default para capturar datos sin partición asignada.

data/lib/tenant_partition/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TenantPartition
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tenant_partition
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - gabriel