fn_registry/python/functions/infra/pg_apply_sql.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
pg_apply_sql	function	py	infra	1.0.0	impure	def pg_apply_sql(dsn: str, sql_path: str) -> int	Lee un archivo .sql y ejecuta su contenido completo contra PostgreSQL en un solo cursor.execute via psycopg2. Multi-statement en una transaccion (sin parametros). Pensado para migraciones idempotentes (el SQL usa IF NOT EXISTS). Commit al exito. Retorna el numero de statements aplicados (split por ;), minimo 1 si el script no esta vacio.	postgres market-intel infra				false	error_go_core	psycopg2	name desc dsn Cadena de conexion PostgreSQL en formato postgresql://user:pass@host:port/dbname. name desc sql_path Ruta al archivo .sql a aplicar (ej. db/migrations/001_init.sql).	Numero entero de statements no vacios aplicados (split por ;), minimo 1 si el script no esta vacio; 0 si el archivo esta vacio.	false			python/functions/infra/pg_apply_sql.py

Ejemplo

import sys, os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "python", "functions"))
from infra.pg_apply_sql import pg_apply_sql

dsn = "postgresql://scraper:secret@localhost:5432/captacion"
# db/migrations/001_init.sql con:
#   CREATE TABLE IF NOT EXISTS leads_raw (
#       id SERIAL PRIMARY KEY, name TEXT, city TEXT, score INT,
#       snapshot_date DATE
#   );
n = pg_apply_sql(dsn, "db/migrations/001_init.sql")
print(f"aplicados {n} statements")  # aplicados 1 statements

Cuando usarla

Cuando necesitas aplicar un archivo de migracion .sql (crear tablas, indices, columnas) a Postgres antes de escribir datos. Usala al arrancar el pipeline de captacion_clientes para garantizar el schema, y para iterar sobre db/migrations/*.sql en orden.

Gotchas

• Idempotencia depende del SQL: el archivo DEBE usar IF NOT EXISTS / ON CONFLICT para poder re-aplicarse sin error. Esta funcion no lleva control de versiones de migracion — el caller decide que archivos aplica y en que orden.
• Todo el script va en UNA transaccion: si cualquier statement falla, se hace rollback de todo el archivo y se lanza RuntimeError.
• El conteo de statements (split(";")) es informativo y aproximado: un ; dentro de un string literal o de un cuerpo de funcion PL/pgSQL infla la cuenta. No lo uses como verdad exacta, solo como indicador.
• NO pasa parametros: el contenido del .sql se ejecuta tal cual. No metas datos no confiables en el archivo — es para DDL/migraciones controladas, no para input de usuario.
• Requiere psycopg2 instalado en el venv (import perezoso: el modulo importa sin la dependencia, pero la llamada falla con RuntimeError claro si falta).
• Archivo inexistente o ilegible lanza RuntimeError con la ruta.