---
name: pg_apply_sql
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def pg_apply_sql(dsn: str, sql_path: str) -> int"
description: "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."
tags: [postgres, market-intel, infra]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [psycopg2]
params:
  - name: dsn
    desc: "Cadena de conexion PostgreSQL en formato postgresql://user:pass@host:port/dbname."
  - name: sql_path
    desc: "Ruta al archivo .sql a aplicar (ej. db/migrations/001_init.sql)."
output: "Numero entero de statements no vacios aplicados (split por ;), minimo 1 si el script no esta vacio; 0 si el archivo esta vacio."
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/infra/pg_apply_sql.py"
---

## Ejemplo

```python
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.