nia-etl-utils 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

nia_etl_utils/database.py

@@ -1,208 +1,309 @@
 """Módulo de conexão com bancos de dados PostgreSQL e Oracle.
 
-Fornece funções genéricas e wrappers de conveniência para estabelecer conexões
-com diferentes bancos de dados usando credenciais de variáveis de ambiente.
+Fornece funções para estabelecer conexões com bancos de dados usando
+configurações explícitas ou variáveis de ambiente.
+
+Examples:
+    Conexão com configuração explícita:
+
+    >>> from nia_etl_utils import conectar_postgresql, PostgresConfig
+    >>> config = PostgresConfig(
+    ...     host="localhost",
+    ...     port="5432",
+    ...     database="meu_banco",
+    ...     user="usuario",
+    ...     password="senha"
+    ... )
+    >>> with conectar_postgresql(config) as conn:
+    ...     conn.cursor.execute("SELECT * FROM tabela")
+    ...     dados = conn.cursor.fetchall()
+
+    Conexão com variáveis de ambiente:
+
+    >>> config = PostgresConfig.from_env("_OPENGEO")
+    >>> with conectar_postgresql(config) as conn:
+    ...     conn.cursor.execute("SELECT 1")
+
+    Wrappers de conveniência:
+
+    >>> with conectar_postgresql_nia() as conn:
+    ...     conn.cursor.execute("SELECT * FROM ouvidorias")
 """
-import sys
+
 import cx_Oracle
 import psycopg2
 from loguru import logger
 from psycopg2 import Error, OperationalError
-from sqlalchemy import create_engine
+from sqlalchemy import create_engine, text
 from sqlalchemy.engine import Engine
 
-from .env_config import obter_variavel_env
+from .config import OracleConfig, PostgresConfig
+from .exceptions import ConexaoError
+from .results import Conexao
+
 
+def conectar_postgresql(config: PostgresConfig) -> Conexao:
+    """Estabelece conexão com banco PostgreSQL.
 
-def conectar_postgresql(sufixo_env: str = "") -> tuple:
-    """Estabelece conexão genérica com banco de dados PostgreSQL usando psycopg2.
+    Cria uma conexão usando psycopg2 com os parâmetros fornecidos
+    na configuração. A conexão retornada suporta context manager
+    para fechamento automático.
 
     Args:
-        sufixo_env: Sufixo das variáveis de ambiente para conexão.
-                   Vazio ("") para banco padrão (DB_POSTGRESQL_*).
-                   "_OPENGEO" para OpenGeo (DB_POSTGRESQL_HOST_OPENGEO, etc).
+        config: Configuração de conexão PostgreSQL contendo host,
+            port, database, user e password.
 
     Returns:
-        tuple: (cursor, connection) — cursor e objeto de conexão ativa.
+        Conexao com cursor e connection ativos, pronta para uso.
 
     Raises:
-        SystemExit: Se houver erro ao estabelecer a conexão.
+        ConexaoError: Se houver falha ao estabelecer a conexão,
+            seja por credenciais inválidas, host inacessível ou
+            outros problemas de conectividade.
 
     Examples:
-        >>> # Conecta usando variáveis DB_POSTGRESQL_HOST, DB_POSTGRESQL_PORT, etc
-        >>> cur, conn = conectar_postgresql()
-        >>> cur.execute("SELECT * FROM tabela")
-        >>> resultados = cur.fetchall()
-        >>> cur.close()
-        >>> conn.close()
-
-        >>> # Conecta em OpenGeo usando DB_POSTGRESQL_HOST_OPENGEO, etc
-        >>> cur, conn = conectar_postgresql("_OPENGEO")
+        Com configuração explícita:
+
+        >>> config = PostgresConfig(
+        ...     host="localhost",
+        ...     port="5432",
+        ...     database="teste",
+        ...     user="user",
+        ...     password="pass"
+        ... )
+        >>> with conectar_postgresql(config) as conn:
+        ...     conn.cursor.execute("SELECT 1")
+        ...     resultado = conn.cursor.fetchone()
+        ...     print(resultado)
+        (1,)
+
+        Com variáveis de ambiente:
+
+        >>> config = PostgresConfig.from_env("_OPENGEO")
+        >>> with conectar_postgresql(config) as conn:
+        ...     conn.cursor.execute("SELECT COUNT(*) FROM tabela")
+
+        Sem context manager (requer fechamento manual):
+
+        >>> conn = conectar_postgresql(config)
+        >>> try:
+        ...     conn.cursor.execute("SELECT * FROM usuarios")
+        ...     usuarios = conn.cursor.fetchall()
+        ... finally:
+        ...     conn.fechar()
     """
-    try:
-        host = obter_variavel_env(f"DB_POSTGRESQL_HOST{sufixo_env}")
-        port = obter_variavel_env(f"DB_POSTGRESQL_PORT{sufixo_env}")
-        database = obter_variavel_env(f"DB_POSTGRESQL_DATABASE{sufixo_env}")
-        user = obter_variavel_env(f"DB_POSTGRESQL_USER{sufixo_env}")
-        password = obter_variavel_env(f"DB_POSTGRESQL_PASSWORD{sufixo_env}")
-
-        logger.info(f"Iniciando conexão PostgreSQL em {host}:{port}, database '{database}'...")
+    logger.info(
+        f"Conectando PostgreSQL em {config.host}:{config.port}, "
+        f"database '{config.database}'..."
+    )
 
+    try:
         connection = psycopg2.connect(
-            host=host,
-            port=port,
-            database=database,
-            user=user,
-            password=password
+            host=config.host,
+            port=config.port,
+            database=config.database,
+            user=config.user,
+            password=config.password
         )
         cursor = connection.cursor()
 
-        logger.success(f"Conexão PostgreSQL estabelecida: '{database}' em '{host}:{port}'")
-        return cursor, connection
+        logger.success(
+            f"Conexão PostgreSQL estabelecida: '{config.database}' "
+            f"em '{config.host}:{config.port}'"
+        )
+
+        return Conexao(cursor=cursor, connection=connection, database=config.database)
 
-    except OperationalError as error:
-        logger.error(f"Erro operacional PostgreSQL (sufixo: '{sufixo_env}'): {error}")
-        sys.exit(1)
-    except Error as error:
-        logger.error(f"Erro PostgreSQL (sufixo: '{sufixo_env}'): {error}")
-        sys.exit(1)
-    except Exception as error:
-        logger.error(f"Erro inesperado PostgreSQL (sufixo: '{sufixo_env}'): {error}")
-        sys.exit(1)
+    except OperationalError as e:
+        raise ConexaoError(
+            f"Erro operacional PostgreSQL ({config.database})",
+            details={"host": config.host, "port": config.port, "erro": str(e)}
+        ) from e
+    except Error as e:
+        raise ConexaoError(
+            f"Erro PostgreSQL ({config.database})",
+            details={"host": config.host, "port": config.port, "erro": str(e)}
+        ) from e
 
 
-def obter_engine_postgresql(sufixo_env: str = "") -> Engine:
-    """Cria uma engine SQLAlchemy genérica para PostgreSQL.
+def conectar_oracle(config: OracleConfig) -> Conexao:
+    """Estabelece conexão com banco Oracle.
+
+    Cria uma conexão usando cx_Oracle com os parâmetros fornecidos
+    na configuração. A conexão retornada suporta context manager
+    para fechamento automático.
 
     Args:
-        sufixo_env: Sufixo das variáveis de ambiente para conexão.
-                   Vazio ("") para banco padrão, "_OPENGEO" para OpenGeo.
+        config: Configuração de conexão Oracle contendo host,
+            port, service_name, user e password.
 
     Returns:
-        Engine configurada para PostgreSQL.
+        Conexao com cursor e connection ativos, pronta para uso.
 
     Raises:
-        SystemExit: Se houver erro na criação da conexão.
+        ConexaoError: Se houver falha ao estabelecer a conexão.
 
     Examples:
-        >>> import pandas as pd
-        >>> engine = obter_engine_postgresql()
-        >>> df = pd.read_sql("SELECT * FROM tabela", engine)
-
-        >>> # Engine para OpenGeo
-        >>> engine = obter_engine_postgresql("_OPENGEO")
+        Com configuração explícita:
+
+        >>> config = OracleConfig(
+        ...     host="oracle.empresa.com",
+        ...     port="1521",
+        ...     service_name="PROD",
+        ...     user="user",
+        ...     password="pass"
+        ... )
+        >>> with conectar_oracle(config) as conn:
+        ...     conn.cursor.execute("SELECT * FROM tabela WHERE ROWNUM <= 10")
+
+        Com variáveis de ambiente:
+
+        >>> config = OracleConfig.from_env()
+        >>> with conectar_oracle(config) as conn:
+        ...     conn.cursor.execute("SELECT SYSDATE FROM DUAL")
     """
+    logger.info(
+        f"Conectando Oracle em {config.host}:{config.port}, "
+        f"service '{config.service_name}'..."
+    )
+
     try:
-        host = obter_variavel_env(f"DB_POSTGRESQL_HOST{sufixo_env}")
-        port = obter_variavel_env(f"DB_POSTGRESQL_PORT{sufixo_env}")
-        database = obter_variavel_env(f"DB_POSTGRESQL_DATABASE{sufixo_env}")
-        user = obter_variavel_env(f"DB_POSTGRESQL_USER{sufixo_env}")
-        password = obter_variavel_env(f"DB_POSTGRESQL_PASSWORD{sufixo_env}")
+        connection = cx_Oracle.connect(
+            user=config.user,
+            password=config.password,
+            dsn=config.dsn
+        )
+        cursor = connection.cursor()
 
-        connection_string = f"postgresql+psycopg2://{user}:{password}@{host}:{port}/{database}"
-        engine = create_engine(connection_string)
+        logger.success(
+            f"Conexão Oracle estabelecida: '{config.service_name}' "
+            f"em '{config.host}:{config.port}'"
+        )
 
-        # Testa a conexão
-        with engine.connect() as conn:
-            conn.execute("SELECT 1") # type: ignore
+        return Conexao(cursor=cursor, connection=connection, database=config.service_name)
 
-        logger.success(f"Engine PostgreSQL criada: '{database}' em '{host}:{port}'")
-        return engine
+    except cx_Oracle.DatabaseError as e:
+        raise ConexaoError(
+            f"Erro de banco Oracle ({config.service_name})",
+            details={"host": config.host, "port": config.port, "erro": str(e)}
+        ) from e
+    except cx_Oracle.InterfaceError as e:
+        raise ConexaoError(
+            f"Erro de interface Oracle ({config.service_name})",
+            details={"host": config.host, "port": config.port, "erro": str(e)}
+        ) from e
 
-    except OperationalError as error:
-        logger.error(f"Erro operacional ao criar engine PostgreSQL (sufixo: '{sufixo_env}'): {error}")
-        sys.exit(1)
-    except Exception as error:
-        logger.error(f"Erro inesperado ao criar engine PostgreSQL (sufixo: '{sufixo_env}'): {error}")
-        sys.exit(1)
 
+def obter_engine_postgresql(config: PostgresConfig) -> Engine:
+    """Cria engine SQLAlchemy para PostgreSQL.
 
-def conectar_oracle() -> tuple:
-    """Estabelece conexão com banco de dados Oracle.
+    Cria e testa uma engine SQLAlchemy usando a configuração fornecida.
+    A engine é útil para operações com pandas (read_sql, to_sql).
 
-    Usa variáveis de ambiente: DB_ORACLE_HOST, DB_ORACLE_PORT, DB_ORACLE_SERVICE_NAME,
-    DB_ORACLE_USER, DB_ORACLE_PASSWORD.
+    Args:
+        config: Configuração de conexão PostgreSQL.
 
     Returns:
-        tuple: (cursor, connection) — cursor e objeto de conexão ativa.
+        Engine SQLAlchemy configurada e testada.
 
     Raises:
-        SystemExit: Se houver erro ao estabelecer a conexão.
+        ConexaoError: Se houver falha ao criar ou testar a engine.
 
     Examples:
-        >>> cur, conn = conectar_oracle()
-        >>> cur.execute("SELECT * FROM tabela WHERE ROWNUM <= 10")
-        >>> resultados = cur.fetchall()
-        >>> fechar_conexao(cur, conn)
+        Leitura com pandas:
+
+        >>> import pandas as pd
+        >>> config = PostgresConfig.from_env()
+        >>> engine = obter_engine_postgresql(config)
+        >>> df = pd.read_sql("SELECT * FROM tabela", engine)
+
+        Escrita com pandas:
+
+        >>> df.to_sql("nova_tabela", engine, if_exists="replace", index=False)
     """
     try:
-        host = obter_variavel_env("DB_ORACLE_HOST")
-        port = obter_variavel_env("DB_ORACLE_PORT")
-        service_name = obter_variavel_env("DB_ORACLE_SERVICE_NAME")
-        user = obter_variavel_env("DB_ORACLE_USER")
-        password = obter_variavel_env("DB_ORACLE_PASSWORD")
+        engine = create_engine(config.connection_string)
 
-        logger.info(f"Iniciando conexão Oracle em {host}:{port}, service '{service_name}'...")
+        # Testa a conexão
+        with engine.connect() as conn:
+            conn.execute(text("SELECT 1"))
 
-        dsn = cx_Oracle.makedsn(host, port, service_name=service_name)
-        connection = cx_Oracle.connect(user=user, password=password, dsn=dsn)
-        cursor = connection.cursor()
+        logger.success(
+            f"Engine PostgreSQL criada: '{config.database}' "
+            f"em '{config.host}:{config.port}'"
+        )
+        return engine
 
-        logger.success(f"Conexão Oracle estabelecida: '{service_name}' em '{host}:{port}'")
-        return cursor, connection
+    except OperationalError as e:
+        raise ConexaoError(
+            f"Erro ao criar engine PostgreSQL ({config.database})",
+            details={"host": config.host, "port": config.port, "erro": str(e)}
+        ) from e
 
-    except cx_Oracle.DatabaseError as error:
-        logger.error(f"Erro de banco Oracle: {error}")
-        sys.exit(1)
-    except cx_Oracle.InterfaceError as error:
-        logger.error(f"Erro de interface Oracle: {error}")
-        sys.exit(1)
-    except Exception as error:
-        logger.error(f"Erro inesperado Oracle: {error}")
-        sys.exit(1)
 
+# =============================================================================
+# WRAPPERS DE CONVENIÊNCIA
+# =============================================================================
 
-def fechar_conexao(cursor, connection) -> None:
-    """Encerra cursor e conexão de banco de dados de forma segura.
 
-    Funciona para conexões PostgreSQL (psycopg2) e Oracle (cx_Oracle).
+def conectar_postgresql_nia() -> Conexao:
+    """Conecta no PostgreSQL do NIA usando variáveis de ambiente padrão.
 
-    Args:
-        cursor: Cursor ativo que será fechado.
-        connection: Conexão ativa que será encerrada.
+    Usa as variáveis: DB_POSTGRESQL_HOST, DB_POSTGRESQL_PORT,
+    DB_POSTGRESQL_DATABASE, DB_POSTGRESQL_USER, DB_POSTGRESQL_PASSWORD.
+
+    Returns:
+        Conexao configurada para o banco NIA.
+
+    Raises:
+        ConexaoError: Se houver falha ao conectar.
+        ConfiguracaoError: Se variáveis de ambiente estiverem ausentes.
 
     Examples:
-        >>> cur, conn = conectar_postgresql()
-        >>> # ... usar cursor ...
-        >>> fechar_conexao(cur, conn)
+        >>> with conectar_postgresql_nia() as conn:
+        ...     conn.cursor.execute("SELECT * FROM ouvidorias LIMIT 10")
+        ...     dados = conn.cursor.fetchall()
     """
-    try:
-        if cursor:
-            cursor.close()
-            logger.debug("Cursor fechado com sucesso.")
+    return conectar_postgresql(PostgresConfig.from_env())
 
-        if connection:
-            connection.close()
-            logger.debug("Conexão encerrada com sucesso.")
 
-    except Exception as error:
-        logger.warning(f"Erro ao fechar conexão: {error}")
-        # Não usa sys.exit(1) porque fechar conexão é cleanup
+def conectar_postgresql_opengeo() -> Conexao:
+    """Conecta no PostgreSQL OpenGeo usando variáveis de ambiente.
 
+    Usa as variáveis com sufixo _OPENGEO: DB_POSTGRESQL_HOST_OPENGEO, etc.
 
-# =============================================================================
-# WRAPPERS DE CONVENIÊNCIA - APIs específicas para bancos conhecidos
-# =============================================================================
+    Returns:
+        Conexao configurada para o banco OpenGeo.
+
+    Raises:
+        ConexaoError: Se houver falha ao conectar.
+        ConfiguracaoError: Se variáveis de ambiente estiverem ausentes.
+
+    Examples:
+        >>> with conectar_postgresql_opengeo() as conn:
+        ...     conn.cursor.execute("SELECT * FROM geo_data")
+    """
+    return conectar_postgresql(PostgresConfig.from_env("_OPENGEO"))
 
-def conectar_postgresql_nia() -> tuple:
-    """Conecta no PostgreSQL do NIA.
 
-    Usa variáveis de ambiente: DB_POSTGRESQL_HOST, DB_POSTGRESQL_PORT, etc.
+def conectar_oracle_ouvidorias() -> Conexao:
+    """Conecta no Oracle de Ouvidorias usando variáveis de ambiente.
+
+    Usa as variáveis: DB_ORACLE_HOST, DB_ORACLE_PORT,
+    DB_ORACLE_SERVICE_NAME, DB_ORACLE_USER, DB_ORACLE_PASSWORD.
 
     Returns:
-        tuple: (cursor, connection)
+        Conexao configurada para o Oracle.
+
+    Raises:
+        ConexaoError: Se houver falha ao conectar.
+        ConfiguracaoError: Se variáveis de ambiente estiverem ausentes.
+
+    Examples:
+        >>> with conectar_oracle_ouvidorias() as conn:
+        ...     conn.cursor.execute("SELECT * FROM SGOV.OUVIDORIAS")
     """
-    return conectar_postgresql("")
+    return conectar_oracle(OracleConfig.from_env())
 
 
 def obter_engine_postgresql_nia() -> Engine:
@@ -210,19 +311,17 @@ def obter_engine_postgresql_nia() -> Engine:
 
     Returns:
         Engine configurada para o banco NIA.
-    """
-    return obter_engine_postgresql("")
-
-
-def conectar_postgresql_opengeo() -> tuple:
-    """Conecta no PostgreSQL OpenGeo.
 
-    Usa variáveis de ambiente: DB_POSTGRESQL_HOST_OPENGEO, DB_POSTGRESQL_PORT_OPENGEO, etc.
+    Raises:
+        ConexaoError: Se houver falha ao criar engine.
+        ConfiguracaoError: Se variáveis de ambiente estiverem ausentes.
 
-    Returns:
-        tuple: (cursor, connection)
+    Examples:
+        >>> import pandas as pd
+        >>> engine = obter_engine_postgresql_nia()
+        >>> df = pd.read_sql("SELECT * FROM tabela", engine)
     """
-    return conectar_postgresql("_OPENGEO")
+    return obter_engine_postgresql(PostgresConfig.from_env())
 
 
 def obter_engine_postgresql_opengeo() -> Engine:
@@ -230,17 +329,14 @@ def obter_engine_postgresql_opengeo() -> Engine:
 
     Returns:
         Engine configurada para o banco OpenGeo.
-    """
-    return obter_engine_postgresql("_OPENGEO")
-
-
-def conectar_oracle_ouvidorias() -> tuple:
-    """Conecta no Oracle de Ouvidorias.
 
-    Alias para conectar_oracle() — mantido para compatibilidade semântica.
-    Usa variáveis de ambiente: DB_ORACLE_HOST, DB_ORACLE_PORT, etc.
+    Raises:
+        ConexaoError: Se houver falha ao criar engine.
+        ConfiguracaoError: Se variáveis de ambiente estiverem ausentes.
 
-    Returns:
-        tuple: (cursor, connection)
+    Examples:
+        >>> import pandas as pd
+        >>> engine = obter_engine_postgresql_opengeo()
+        >>> df = pd.read_sql("SELECT * FROM geo_tabela", engine)
     """
-    return conectar_oracle()
+    return obter_engine_postgresql(PostgresConfig.from_env("_OPENGEO"))