mtpk-postgres 0.1.1__tar.gz → 0.1.3__tar.gz

{mtpk_postgres-0.1.1 → mtpk_postgres-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtpk_postgres
-Version: 0.1.1
+Version: 0.1.3
 Summary: Librería para sincronización estructural de bases de datos Postgres con modelos Python (adaptación de mtpk_mariadb)
 Author-email: José Jesús Andrés Zambrana <jjandres@multiplika.es>
 License: MIT
@@ -45,9 +45,28 @@ pip install -e .
   reportan como `ENUM` (Postgres no permite distinguirlos después del hecho).
 - A diferencia de MariaDB, el DDL en Postgres es transaccional: los métodos de `ManagerDB` confirman (`COMMIT`)
   explícitamente tras crear tablas, triggers y procedimientos.
+- Columnas `VECTOR(n)` (extensión [pgvector](https://github.com/pgvector/pgvector), hay que crearla antes con
+  `CREATE EXTENSION IF NOT EXISTS vector;`): `Columna(tipo="VECTOR", longitud=n)`. Es una extensión propia de este
+  paquete, no existe en `mtpk-mariadb`.
+- Índices con método (`GIN`, `GIST`, `HNSW`/`IVFFlat` de pgvector, etc.): `Index(columnas=[...], metodo="hnsw",
+  opclass="vector_cosine_ops", with_opciones="m = 16, ef_construction = 64")`. `metodo` es incompatible con `unico`
+  (Postgres no permite índices UNIQUE con esos métodos).
 
 ## Historial
 
+- **0.1.3**: corrige un bug bloqueante en `comparar_generar_alter` — al crear una tabla nueva con una columna
+  `GENERATED ALWAYS AS (...) STORED` (p.ej. una columna de búsqueda `tsvector` calculada a partir de otra), la
+  siguiente pasada de comparación la trataba como una columna normal (la introspección no reconstruye la expresión
+  de generación) y proponía un `ALTER COLUMN` sobre ella justo después de crearla — algo que Postgres puede
+  rechazar cuando otras columnas dependen de la generada. Como `aplicar_cambios()` ejecuta todo en una única
+  transacción, ese fallo deshacía también la creación de las demás tablas. Ahora las columnas `generado` nunca se
+  comparan ni se alteran una vez existen (para cambiar su expresión hay que borrarlas y recrearlas a mano); de paso,
+  `Columna.to_sql()` ya respeta `not_null=True` en columnas generadas (antes se ignoraba).
+- **0.1.2**: soporte nativo para columnas `VECTOR(n)` (pgvector) e índices con método (`USING gin/hnsw/...`,
+  `opclass`, `WITH (...)`) en `Index`. La introspección (`obtener_columnas_postgres`) ahora reconoce las columnas
+  `vector` por su `udt_name` y reconstruye su dimensión leyendo el catálogo (`pg_attribute`/`format_type`); sin esto,
+  `data_type` llegaba como `'USER-DEFINED'` y `comparar_generar_alter` proponía un `ALTER COLUMN` en cada ejecución
+  aunque la columna no hubiera cambiado.
 - **0.1.1**: corrige un bug bloqueante — `Tabla` no enlazaba `indice.tabla`/`fk.tabla`/`columna.tabla` cuando
   `columnas`/`indices`/`foreign_keys` se pasaban directamente por el constructor (solo lo hacían `add_index()` y
   compañía). Como `Index.to_sql()` necesita esa referencia para generar el `CREATE INDEX`, cualquier tabla definida

{mtpk_postgres-0.1.1 → mtpk_postgres-0.1.3}/README.md

@@ -25,9 +25,28 @@ pip install -e .
   reportan como `ENUM` (Postgres no permite distinguirlos después del hecho).
 - A diferencia de MariaDB, el DDL en Postgres es transaccional: los métodos de `ManagerDB` confirman (`COMMIT`)
   explícitamente tras crear tablas, triggers y procedimientos.
+- Columnas `VECTOR(n)` (extensión [pgvector](https://github.com/pgvector/pgvector), hay que crearla antes con
+  `CREATE EXTENSION IF NOT EXISTS vector;`): `Columna(tipo="VECTOR", longitud=n)`. Es una extensión propia de este
+  paquete, no existe en `mtpk-mariadb`.
+- Índices con método (`GIN`, `GIST`, `HNSW`/`IVFFlat` de pgvector, etc.): `Index(columnas=[...], metodo="hnsw",
+  opclass="vector_cosine_ops", with_opciones="m = 16, ef_construction = 64")`. `metodo` es incompatible con `unico`
+  (Postgres no permite índices UNIQUE con esos métodos).
 
 ## Historial
 
+- **0.1.3**: corrige un bug bloqueante en `comparar_generar_alter` — al crear una tabla nueva con una columna
+  `GENERATED ALWAYS AS (...) STORED` (p.ej. una columna de búsqueda `tsvector` calculada a partir de otra), la
+  siguiente pasada de comparación la trataba como una columna normal (la introspección no reconstruye la expresión
+  de generación) y proponía un `ALTER COLUMN` sobre ella justo después de crearla — algo que Postgres puede
+  rechazar cuando otras columnas dependen de la generada. Como `aplicar_cambios()` ejecuta todo en una única
+  transacción, ese fallo deshacía también la creación de las demás tablas. Ahora las columnas `generado` nunca se
+  comparan ni se alteran una vez existen (para cambiar su expresión hay que borrarlas y recrearlas a mano); de paso,
+  `Columna.to_sql()` ya respeta `not_null=True` en columnas generadas (antes se ignoraba).
+- **0.1.2**: soporte nativo para columnas `VECTOR(n)` (pgvector) e índices con método (`USING gin/hnsw/...`,
+  `opclass`, `WITH (...)`) en `Index`. La introspección (`obtener_columnas_postgres`) ahora reconoce las columnas
+  `vector` por su `udt_name` y reconstruye su dimensión leyendo el catálogo (`pg_attribute`/`format_type`); sin esto,
+  `data_type` llegaba como `'USER-DEFINED'` y `comparar_generar_alter` proponía un `ALTER COLUMN` en cada ejecución
+  aunque la columna no hubiera cambiado.
 - **0.1.1**: corrige un bug bloqueante — `Tabla` no enlazaba `indice.tabla`/`fk.tabla`/`columna.tabla` cuando
   `columnas`/`indices`/`foreign_keys` se pasaban directamente por el constructor (solo lo hacían `add_index()` y
   compañía). Como `Index.to_sql()` necesita esa referencia para generar el `CREATE INDEX`, cualquier tabla definida

{mtpk_postgres-0.1.1 → mtpk_postgres-0.1.3}/mtpk_postgres/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.1.1"
+__version__ = "0.1.3"
 __author__ = "jjandres"
 
 from .interface import *

{mtpk_postgres-0.1.1 → mtpk_postgres-0.1.3}/mtpk_postgres/core_sync.py

@@ -62,12 +62,14 @@ class Columna:
     tipo: Literal[
         "TINYINT", "SMALLINT", "MEDIUMINT", "INT", "INTEGER", "BIGINT", "DECIMAL", "NUMERIC", "FLOAT", "DOUBLE",
         "CHAR", "VARCHAR", "TEXT", "TINYTEXT", "MEDIUMTEXT", "LONGTEXT", "BINARY", "VARBINARY", "BLOB", "TINYBLOB", "MEDIUMBLOB", "LONGBLOB",
-        "DATE", "TIME", "YEAR", "DATETIME", "TIMESTAMP", "ENUM", "SET", "BOOLEAN", "GEOMETRY", "POINT", "LINESTRING", "POLYGON"
+        "DATE", "TIME", "YEAR", "DATETIME", "TIMESTAMP", "ENUM", "SET", "BOOLEAN", "GEOMETRY", "POINT", "LINESTRING", "POLYGON",
+        "VECTOR"
     ]
-    """Tipo de dato del modelo (mismo vocabulario que mtpk-mariadb, traducido a Postgres en to_sql())"""
+    """Tipo de dato del modelo (mismo vocabulario que mtpk-mariadb, traducido a Postgres en to_sql());
+    VECTOR es una extensión propia de este paquete (no existe en mtpk-mariadb) para columnas `pgvector`."""
 
     longitud: Optional[int] = None
-    """Longitud para tipos como VARCHAR(n), CHAR(n)."""
+    """Longitud para tipos como VARCHAR(n), CHAR(n). Para VECTOR, es el número de dimensiones: VECTOR(n)."""
 
     precision: Optional[int] = None
     """Precisión para DECIMAL(p, s), etc."""
@@ -123,6 +125,7 @@ class Columna:
         "YEAR": "SMALLINT",
         "BOOLEAN": "BOOLEAN",
         "ENUM": "TEXT", "SET": "TEXT",
+        "VECTOR": "VECTOR",
     }
     _SIN_SOPORTE = {"GEOMETRY", "POINT", "LINESTRING", "POLYGON"}
 
@@ -135,6 +138,13 @@ class Columna:
             )
         base = self._MAPA_TIPOS.get(tipo_upper, tipo_upper)
 
+        if base == "VECTOR":
+            if self.longitud is None:
+                raise ValueError(
+                    f"La columna '{self.nombre}' es VECTOR pero no tiene 'longitud' (número de dimensiones)."
+                )
+            # Requiere la extensión pgvector: CREATE EXTENSION IF NOT EXISTS vector;
+            return f"{base}({self.longitud})"
         if base in {"VARCHAR", "CHAR"}:
             return f"{base}({self.longitud})"
         if base in {"DECIMAL", "NUMERIC"}:
@@ -156,6 +166,8 @@ class Columna:
 
         if self.generado:
             partes.append(f"{tipo_sql} GENERATED ALWAYS AS ({self.generado}) STORED")
+            if self.not_null:
+                partes.append("NOT NULL")
         else:
             partes.append(tipo_sql)
 
@@ -230,12 +242,20 @@ class Index:
     - Atributos:
         - `columnas`    (List[str]): Lista de nombres de columnas incluidas en el índice. Pueden ser una o varias (índice compuesto).
         - `nombre`      (str, opcional): Nombre personalizado del índice. Si no se indica, se generará automáticamente combinando los nombres de las columnas.
-        - `unico`       (bool): Indica si el índice es único (`UNIQUE`). Por defecto es `False`.
+        - `unico`       (bool): Indica si el índice es único (`UNIQUE`). Por defecto es `False`. Incompatible con `metodo`.
+        - `metodo`      (str, opcional): Método de acceso del índice (`USING <metodo>`), p.ej. `"gin"`, `"gist"` o `"hnsw"`/`"ivfflat"`
+                        (estos dos últimos requieren la extensión `pgvector`). Si no se indica, se usa el btree normal de Postgres.
+        - `opclass`     (str, opcional): Clase de operador a aplicar a cada columna del índice, p.ej. `"vector_cosine_ops"`
+                        para un HNSW/IVFFlat sobre una columna `VECTOR`, o `"gin_trgm_ops"` para búsqueda por trigramas.
+        - `with_opciones` (str, opcional): Contenido crudo de la cláusula `WITH (...)`, p.ej. `"m = 16, ef_construction = 64"` (HNSW).
         - `tabla`       (Tabla, opcional): Referencia a la tabla que contiene este índice. Se asigna automáticamente al añadir el índice a la tabla.
     """
     columnas: List[str]
     nombre: Optional[str] = None
     unico: bool = False
+    metodo: Optional[str] = None
+    opclass: Optional[str] = None
+    with_opciones: Optional[str] = None
     tabla: Optional["Tabla"] = field(default=None, repr=False)
 
     def to_sql(self) -> str:
@@ -243,8 +263,25 @@ class Index:
             raise ValueError(
                 f"El índice sobre {self.columnas} no está asociado a ninguna tabla; no se puede generar el CREATE INDEX."
             )
-        cols = ", ".join(f'"{c}"' for c in self.columnas)
+        if self.metodo and self.unico:
+            raise ValueError(
+                f"El índice sobre {self.columnas} no puede ser UNIQUE y usar 'metodo' ({self.metodo}) a la vez "
+                "(GIN/HNSW/IVFFlat no admiten UNIQUE en Postgres)."
+            )
+
         nombre = self.nombre or f"{'_'.join(self.columnas)}_{'uk' if self.unico else 'idx'}"
+
+        if self.metodo:
+            cols = ", ".join(
+                f'"{c}" {self.opclass}' if self.opclass else f'"{c}"'
+                for c in self.columnas
+            )
+            sql = f'CREATE INDEX IF NOT EXISTS "{nombre}" ON "{self.tabla.nombre}" USING {self.metodo} ({cols})'
+            if self.with_opciones:
+                sql += f" WITH ({self.with_opciones})"
+            return sql
+
+        cols = ", ".join(f'"{c}"' for c in self.columnas)
         tipo_sql = "UNIQUE INDEX" if self.unico else "INDEX"
         return f'CREATE {tipo_sql} IF NOT EXISTS "{nombre}" ON "{self.tabla.nombre}" ({cols})'
 
@@ -464,7 +501,7 @@ class Tabla:
             cursor.execute(
                 """
                 SELECT
-                    c.column_name, c.data_type, c.character_maximum_length,
+                    c.column_name, c.data_type, c.udt_name, c.character_maximum_length,
                     c.numeric_precision, c.numeric_scale, c.is_nullable,
                     c.column_default, c.is_identity,
                     COALESCE(pk.es_pk, false) AS es_pk,
@@ -496,21 +533,33 @@ class Tabla:
             filas = cursor.fetchall()
 
         checks_por_columna = self._obtener_opciones_check(conexion)
+        dimensiones_vector = self._obtener_dimensiones_vector(conexion)
 
         for fila in filas:
-            tipo_base = self._PG_A_MODELO.get(fila["data_type"], fila["data_type"].upper())
-            enum_opciones = None
-
-            if tipo_base == "TEXT" and fila["column_name"] in checks_por_columna:
-                # Postgres no distingue ENUM de SET tras reconstruir desde el CHECK: ambos
-                # se guardan como TEXT + CHECK (ver Columna.to_sql), así que se asume ENUM.
-                tipo_base = "ENUM"
-                enum_opciones = checks_por_columna[fila["column_name"]]
+            longitud = fila["character_maximum_length"]
+
+            if fila["udt_name"] == "vector":
+                # information_schema no expone el nº de dimensiones de un `vector(n)` (tipo de
+                # la extensión pgvector): data_type viene como 'USER-DEFINED' y
+                # character_maximum_length es NULL. Sin este caso especial, tipo_base quedaría
+                # como "USER-DEFINED" y nunca igualaría al "VECTOR" del modelo, provocando un
+                # ALTER COLUMN espurio en cada ejecución.
+                tipo_base = "VECTOR"
+                longitud = dimensiones_vector.get(fila["column_name"])
+                enum_opciones = None
+            else:
+                tipo_base = self._PG_A_MODELO.get(fila["data_type"], fila["data_type"].upper())
+                enum_opciones = None
+                if tipo_base == "TEXT" and fila["column_name"] in checks_por_columna:
+                    # Postgres no distingue ENUM de SET tras reconstruir desde el CHECK: ambos
+                    # se guardan como TEXT + CHECK (ver Columna.to_sql), así que se asume ENUM.
+                    tipo_base = "ENUM"
+                    enum_opciones = checks_por_columna[fila["column_name"]]
 
             col = Columna(
                 nombre=fila["column_name"],
                 tipo=tipo_base,
-                longitud=fila["character_maximum_length"],
+                longitud=longitud,
                 precision=fila["numeric_precision"],
                 escala=fila["numeric_scale"],
                 not_null=(fila["is_nullable"] == "NO"),
@@ -524,6 +573,33 @@ class Tabla:
 
         return columnas
 
+    def _obtener_dimensiones_vector(self, conexion) -> Dict[str, int]:
+        """
+        Devuelve {columna: dimensiones} para las columnas `vector(n)` (extensión pgvector) de
+        esta tabla, leyendo el modificador de tipo real desde los catálogos (atttypmod vía
+        format_type), ya que information_schema no lo expone para tipos definidos por extensión.
+        """
+        resultado: Dict[str, int] = {}
+        with conexion.cursor(row_factory=dict_row) as cursor:
+            cursor.execute(
+                """
+                SELECT a.attname AS columna,
+                       pg_catalog.format_type(a.atttypid, a.atttypmod) AS tipo_completo
+                FROM pg_attribute a
+                JOIN pg_class t ON t.oid = a.attrelid
+                JOIN pg_namespace n ON n.oid = t.relnamespace
+                JOIN pg_type ty ON ty.oid = a.atttypid
+                WHERE t.relname = %s AND n.nspname = 'public'
+                    AND ty.typname = 'vector' AND a.attnum > 0 AND NOT a.attisdropped
+                """,
+                (self.nombre,)
+            )
+            for fila in cursor.fetchall():
+                m = re.match(r"vector\((\d+)\)", fila["tipo_completo"] or "", re.IGNORECASE)
+                if m:
+                    resultado[fila["columna"]] = int(m.group(1))
+        return resultado
+
     def _obtener_opciones_check(self, conexion) -> Dict[str, List[str]]:
         """
         Reconstruye, de forma best-effort, las opciones de las columnas ENUM/SET (TEXT + CHECK)
@@ -697,6 +773,16 @@ class Tabla:
             col_real = reales.get(nombre)
             if not col_real:
                 col_alteraciones.append(f"ADD COLUMN {col_def.to_sql()}")
+            elif col_def.generado:
+                # Las columnas GENERATED ALWAYS AS (...) STORED no se comparan ni se alteran
+                # automáticamente una vez existen: la introspección no reconstruye la expresión
+                # de generación (obtener_columnas_postgres no la lee), así que cualquier columna
+                # "normal" reconstruida a partir de una generada se compararía con datos
+                # incompletos (p.ej. sin el NOT NULL que sí lleva la generada) y dispararía un
+                # ALTER espurio — que además Postgres puede rechazar de plano si otras columnas
+                # dependen de ella. Si la expresión cambia, hay que borrar y recrear la columna
+                # a mano.
+                continue
             elif not iguales(col_real, col_def):
                 if not tipos_iguales(col_real, col_def):
                     tipo_sql = col_def._tipo_sql()

{mtpk_postgres-0.1.1 → mtpk_postgres-0.1.3}/mtpk_postgres.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtpk_postgres
-Version: 0.1.1
+Version: 0.1.3
 Summary: Librería para sincronización estructural de bases de datos Postgres con modelos Python (adaptación de mtpk_mariadb)
 Author-email: José Jesús Andrés Zambrana <jjandres@multiplika.es>
 License: MIT
@@ -45,9 +45,28 @@ pip install -e .
   reportan como `ENUM` (Postgres no permite distinguirlos después del hecho).
 - A diferencia de MariaDB, el DDL en Postgres es transaccional: los métodos de `ManagerDB` confirman (`COMMIT`)
   explícitamente tras crear tablas, triggers y procedimientos.
+- Columnas `VECTOR(n)` (extensión [pgvector](https://github.com/pgvector/pgvector), hay que crearla antes con
+  `CREATE EXTENSION IF NOT EXISTS vector;`): `Columna(tipo="VECTOR", longitud=n)`. Es una extensión propia de este
+  paquete, no existe en `mtpk-mariadb`.
+- Índices con método (`GIN`, `GIST`, `HNSW`/`IVFFlat` de pgvector, etc.): `Index(columnas=[...], metodo="hnsw",
+  opclass="vector_cosine_ops", with_opciones="m = 16, ef_construction = 64")`. `metodo` es incompatible con `unico`
+  (Postgres no permite índices UNIQUE con esos métodos).
 
 ## Historial
 
+- **0.1.3**: corrige un bug bloqueante en `comparar_generar_alter` — al crear una tabla nueva con una columna
+  `GENERATED ALWAYS AS (...) STORED` (p.ej. una columna de búsqueda `tsvector` calculada a partir de otra), la
+  siguiente pasada de comparación la trataba como una columna normal (la introspección no reconstruye la expresión
+  de generación) y proponía un `ALTER COLUMN` sobre ella justo después de crearla — algo que Postgres puede
+  rechazar cuando otras columnas dependen de la generada. Como `aplicar_cambios()` ejecuta todo en una única
+  transacción, ese fallo deshacía también la creación de las demás tablas. Ahora las columnas `generado` nunca se
+  comparan ni se alteran una vez existen (para cambiar su expresión hay que borrarlas y recrearlas a mano); de paso,
+  `Columna.to_sql()` ya respeta `not_null=True` en columnas generadas (antes se ignoraba).
+- **0.1.2**: soporte nativo para columnas `VECTOR(n)` (pgvector) e índices con método (`USING gin/hnsw/...`,
+  `opclass`, `WITH (...)`) en `Index`. La introspección (`obtener_columnas_postgres`) ahora reconoce las columnas
+  `vector` por su `udt_name` y reconstruye su dimensión leyendo el catálogo (`pg_attribute`/`format_type`); sin esto,
+  `data_type` llegaba como `'USER-DEFINED'` y `comparar_generar_alter` proponía un `ALTER COLUMN` en cada ejecución
+  aunque la columna no hubiera cambiado.
 - **0.1.1**: corrige un bug bloqueante — `Tabla` no enlazaba `indice.tabla`/`fk.tabla`/`columna.tabla` cuando
   `columnas`/`indices`/`foreign_keys` se pasaban directamente por el constructor (solo lo hacían `add_index()` y
   compañía). Como `Index.to_sql()` necesita esa referencia para generar el `CREATE INDEX`, cualquier tabla definida

{mtpk_postgres-0.1.1 → mtpk_postgres-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mtpk_postgres"
-version = "0.1.1"
+version = "0.1.3"
 description = "Librería para sincronización estructural de bases de datos Postgres con modelos Python (adaptación de mtpk_mariadb)"
 readme = "README.md"
 requires-python = ">=3.9"