db2 package

Subpackages

• db2.utils package
  • Module contents
    • Converter
    • DictIterator
    • TupleIterator

Module contents

class db2.DB2Connection(filename: str, late_commit=False)

Base: object

Classe para conectar-se com um banco de dados DB2.

Esta classe abstrai a maioria das funções do módulo ibm_db, enquanto oferece métodos de conveniência para inserir, modificar e recuperar linhas do banco de dados.

Parâmetros:

• filename – Nome de um arquivo json com os dados de login para o banco de dados.

• late_commit – Se as modificações no banco de dados devem ser retardadas até o fim da execução da cláusula with.

Exemplo:

from db2 import DB2Connection

with DB2Connection(caminho_para_arquivo_com_credenciais.json) as conn:
    conn.modify('''
        CREATE TABLE TEST (
            A1 INTEGER NOT NULL,
            A2 VARCHAR(9) NOT NULL
        );
    ''')

    conn.insert("TEST", {'A1': 1, 'A2': 'olá mundo'})

create_tables(filename: str)

Cria tabelas, se elas não existirem, a partir de um arquivo em disco.

Tabelas também podem ser criadas a partir do comando modify.

Parâmetros:

filename – Caminho para um arquivo SQL com os comandos para criar as tabelas. Cada comando de criação de tabelas deve estar separado por dois espaços em branco.

Exemplo:

caminho_para_arquivo_com_comandos.sql

CREATE TABLE USERS_TEST_IBMDB2(
    ID INTEGER NOT NULL PRIMARY KEY,
    NAME VARCHAR(10) NOT NULL,
    AGE INTEGER NOT NULL
);

INSERT INTO USERS_TEST_IBMDB2(ID, NAME, AGE) VALUES (1, 'HENRY', 32);
INSERT INTO USERS_TEST_IBMDB2(ID, NAME, AGE) VALUES (2, 'JOHN', 20);

main.py

import os
from db2 import DB2Connection

with DB2Connection(caminho_para_arquivo_com_credenciais.json) as db2_conn:
    db2_conn.create_tables(caminho_para_arquivo_com_comandos.sql)
    query_str = '''
        SELECT *
        FROM USERS_TEST_IBMDB2;
     '''
    df = db2_conn.query_to_dataframe(query_str)

    print(df)

get_columns(table_name: str, schema_name: str = None) → list

Retorna um dicionário com o tipo de dados das colunas de uma tabela.

Parâmetros:

• table_name – O nome da coluna, com ou sem o SCHEMA prefixado.

• schema_name – Opcional - o nome do schema do qual a tabela pertence. O padrão é None (schema padrão do banco)

Retorna:

Uma lista de dicionários, onde para cada dicionário contém as informações da coluna. O tipo das colunas é o tipo no formato IBM DB2 (e.g. DECIMAL(10, 2), FLOAT, INTEGER, VARCHAR, etc).

Exemplo:

from db2 import DB2Connection

with DB2Connection(caminho_para_arquivo_com_credenciais.json) as conn:
    column_types = conn.get_columns(schema_name=None, table_name='DB2_TEST_TABLE_1')
    print(column_types)

insert(table_name: str, row: dict, suppress=False, throw=False) → int

Insere uma tupla (apresentada como um dicionário) em uma tabela.

Parâmetros:

• table_name – Nome da tabela onde os dados serão inseridos.

• row – Um dicionário onde as chaves são nomes de colunas e seus valores os valores de uma tupla em um banco de dados.

• suppress – Opcional - se warnings devem ser suprimidos na saída do console.

• throw – Opcional - se, ao ocorrer um erro no comando SQL, uma exceção deve ser lançada

Retorna:

A quantidade de linhas inseridas

Exemplo:

from db2 import DB2Connection

with DB2Connection(caminho_para_arquivo_com_credenciais.json) as conn:
    to_input = [
        {'A1': 1, 'A2': 1.17, 'A3': 3.2, 'A4': '2024-12-31', 'A5': 'olá mundo'},
        {'A1': 2, 'A2': 32.500, 'A3': 7.2, 'A4': '1970-01-01', 'A5': 'olá henry'}
    ]
    for inp in to_input:
        n_rows_affected = conn.insert('DB2_TEST_TABLE_1', inp)
        print(n_rows_affected)

insert_or_update_table(table_name: str, where: dict, row: dict, suppress: bool = False, throw: bool = False) → int

Dada uma tabela em DB2 e um conjunto de informações (apresentados como um dicionário), insere OU atualiza estas informações no banco de dados.

No parâmetro where, deve ser passado as informações que localizam a linha no banco de dados. No parâmetro row, devem ser passadas todas as informações, inclusive as que estão contidas na cláusula where.

Parâmetros:

• table_name – Nome da tabela onde os dados serão inseridos ou atualizados.

• where – Dicionário com a cláusula WHERE. As chaves do dicionário são os nomes das colunas, e seus valores os valores da tupla a ser buscada.

• row – Um dicionário onde as chaves são nomes de colunas e seus valores os valores de uma tupla em um banco de dados.

Retorna:

Quantidade de linhas que foram afetadas pelo comando SQL

Exemplo:

from db2 import DB2Connection

with DB2Connection(caminho_para_arquivo_com_credenciais.json) as conn:
    conn.insert_or_update_table(
        'DB2_TEST_TABLE_1',
        {'A1': 4, 'A2': 1.17},
        {'A1': 4, 'A2': 1.17, 'A3': 3.2, 'A4': '2024-12-31', 'A5': 'olá mundo'}
    )
    # valor de A3: 3.2

    conn.insert_or_update_table(
        'DB2_TEST_TABLE_1',
        {'A1': 4, 'A2': 1.17},
        {'A1': 4, 'A2': 1.17, 'A3': 4.0, 'A4': '2024-12-31', 'A5': 'olá mundo'}
    )
    # valor de A3: 4.0

modify(sql: str, suppress=False, throw=False) → int

Realiza modificações (inserções, modificações, deleções) na base de dados.

Esse método é reservado a instruções que alteram o estado do banco de dados, Data Manipulation Language (DML).

Parâmetros:

• sql – O comando em SQL.

• suppress – Opcional - se warnings devem ser suprimidos na saída do console.

• throw – Opcional - se, ao ocorrer um erro no comando SQL, uma exceção deve ser lançada

Retorna:

Quantidade de linhas que foram afetadas pelo comando SQL

Exemplo:

from db2 import DB2Connection

with DB2Connection(caminho_para_arquivo_com_credenciais.json) as conn:
    conn.modify('DROP TABLE DB2_TEST_TABLE_1;')

query(sql: str, as_dict: bool = False) → TupleIterator | DictIterator

Realiza consultas à base de dados DB2.

Esse método é reservado a consultas do tipo Data Query Language (DQL).

Parâmetros:

• sql – A consulta em SQL.

• as_dict – Opcional - se o resultado deve ser um dicionário, ao invés de uma tupla.

Retorna:

Um iterator para as tuplas a serem retornadas.

Exemplo:

from db2 import DB2Connection

with DB2Connection(caminho_para_arquivo_com_credenciais.json) as conn:
    tuple_factory = conn.query(f'''
        SELECT *
        FROM DB2_TEST_TABLE_1;
    '''))
    # resultados são no formato (1, 1.17, 3.2, ...)

    dict_factory = conn.query(f'''
        SELECT *
        FROM DB2_TEST_TABLE_1;
    ''', as_dict=True))
    # resultados são no formato {'A1': 1, 'A2': 1.17, 'A3': 3.2, ...}

query_to_dataframe(sql: str) → DataFrame

Realiza uma consulta à base de dados DB2, convertendo automaticamente o resultado em um pandas.DataFrame.

IMPORTANTE: Se a consulta retornar uma tabela que ocupa muito espaço em disco (ou muitos recursos de rede), prefira definir o parâmetro fetch_first para um valor (e.g. 500 linhas).

Parâmetros:

sql – A consulta em SQL.

Retorna:

um pandas.DataFrame com o resultado da consulta.

Exemplo:

from db2 import DB2Connection
import pandas as pd

with DB2Connection(caminho_para_arquivo_com_credenciais.json) as conn:
    conn.insert(
        'DB2_TEST_TABLE_1',
        {'A1': 5, 'A2': 1.17, 'A3': 3.2, 'A4': '2024-01-01', 'A5': '2010_2020'}
    )
    conn.insert(
        'DB2_TEST_TABLE_1',
        {'A1': 6, 'A2': 32.500, 'A3': 7.2, 'A4': '2050-12-31', 'A5': '2011_2021'}
    )

    df = conn.query_to_dataframe('''SELECT * FROM DB2_TEST_TABLE_1;''')

update(table_name: str, where: dict, values: dict, suppress=False, throw=False) → int

Atualiza os valores de uma tupla (apresentada como um dicionário) em uma tabela.

Parâmetros:

• table_name – Nome da tabela onde os dados serão atualizados.

• where – Dicionário com a cláusula WHERE. As chaves do dicionário são os nomes das colunas, e seus valores os valores da tupla a ser atualizada.

• values – Valores a serem atualizados na tabela do banco de dados.

• suppress – Opcional - se warnings devem ser suprimidos na saída do console.

• throw – Opcional - se, ao ocorrer um erro no comando SQL, uma exceção deve ser lançada

Retorna:

A quantidade de linhas afetadas pelo comando update

Exemplo:

from db2 import DB2Connection

with DB2Connection(caminho_para_arquivo_com_credenciais.json) as conn:
    conn.insert(
        'DB2_TEST_TABLE_1',
        {'A1': 3, 'A2': 1.17, 'A3': 3.2, 'A4': '2024-12-31', 'A5': 'olá mundo'}
    )
    # valor de A3: 3.2

    conn.update(
        'DB2_TEST_TABLE_1',
        {'A1': 3, 'A2': 1.17},
        {'A3': 4}
    )
    # valor de A3: 4.0

exception db2.IBMDBError

Base: Exception