Pular para conteúdo

Definições de conexão com o Banco de Dados para o Registro de Camadas

Este documento descreve o fluxo de processo para estabelecer, manter e encerrar uma conexão com o banco de dados no plugin. A estrutura foi planejada para ser centralizada, garantindo uma única fonte que forneça informações atualizadas sobre o estado da conexão.

Iniciação do Processo pelo Usuário

O inicio da conexão começa com uma ação explícita do usuário.

  1. Ponto de Entrada: O usuário executa a ferramenta "00. Conexão - Banco de Dados" na Caixa de Ferramentas do QGIS, designada para iniciar ou encerrar uma sessão.

  2. Coleta de Dados: A interface da ferramenta solicita as credenciais de autenticação (usuário, senha, nome do banco).

  3. Disparo da Ação: Ao clicar em "Executar", a interface coleta os dados informados pelo usuário e os envia para um gerenciador assumir o controle do processo de conexão.

DbManager (Gerenciador Central de Conexão)

No centro dessa estrutura está o Gerenciador Central de Conexão, uma instância única chamada db_manager. Ele é implementado como um Singleton, ou seja, existe apenas uma instância da classe DbManagercompartilhada para todo o plugin. Isso é fundamental para garantir que não haja múltiplas conexões conflitantes e que todos os componentes conversem com a mesma fonte de dados. O gerenciador utiliza a biblioteca psycopg2 para se comunicar com o PostgreSQL e mantém o estado da sessão em atributos internos.

Cenário de Sucesso

  1. Tentativa de Conexão: O gerenciador utiliza as credenciais para se conectar ao servidor PostgreSQL.

  2. Armazenamento de Estado: Se a conexão for bem-sucedida, o db__manager popula seu dicionário interno, estabelecendo o estado "Conectado". 

    1
2
3
4
5
6
7
    # Atributo interno do db_manager
self.connection_details = {
    'host': 'localhost',
    'port': 5432,
    'dbname': 'meu_banco',
    'user': 'usuario_conectado'
}

  3. Extração e Cache de Metadados: Imediatamente após, ele consulta o banco para obter a lista de esquemas (schemas) disponíveis e armazena o resultado em cache. 

    1
2
    # Atributo interno do db_manager
self.schema_list = ['public', 'geoprocessamento', 'dados_brutos']
    > Esta é uma otimização crucial, pois permite que outras ferramentas acessem a lista de esquemas instantaneamente, sem novas consultas ao banco.

Cenário de Falha

  1. Captura de Exceção: Se qualquer passo falhar (ex: credenciais inválidas), o driver psycopg2 gera uma exceção.

  2. Tratamento e Reversão de Estado: O db__manager captura a exceção e executa uma rotina de limpeza para garantir a consistência. Ele redefine seus atributos de estado para o estado inicial "Desconectado". 

    1
2
3
    # Rollback em caso de falha
self.connection_details = {}
self.schema_list = []

  3. Geração de Log de Erro: A lista messages é preenchida com a mensagem de erro específica retornada pelo driver, explicando o motivo da falha.

Feedback ao Usuário

Após a conclusão da etapa anterior, o sistema informa o usuário e consolida seu estado.

  1. Retorno do Log: O db__manager retorna a lista messages (com logs de sucesso ou erro) para a ferramenta que iniciou a chamada.

  2. Apresentação do Feedback: A ferramenta do QGIS itera sobre a lista e exibe cada mensagem no painel de log, fornecendo ao usuário uma visão transparente do que aconteceu.

  3. Consolidação do Estado: Se a conexão foi bem-sucedida, o db__manager agora mantém o estado "Conectado", com os atributos connection_details e schema_list preenchidos e prontos para serem consultados por outras partes do plugin.

Manutenção e Encerramento da Sessão

  1. Uso da Conexão Compartilhada: Durante o estado "Conectado", qualquer outra ferramenta do plugin (ex: "01. Registro de Dados") que precise interagir com o banco de dados irá consultar o db__manager. Ela pode, por exemplo, pedir a schema_list para popular uma combobox ou solicitar o objeto de conexão ativo para executar suas próprias consultas.

  2. Encerramento da Conexão: O ciclo de vida termina quando o usuário solicita a desconexão (usando a mesma ferramenta "00. Conexão - Banco de Dados") ou por timeout de inatividade, o qual conta com um timer que é iniciado a partir do momento da conexão bem sucedida.

  3. Processo de Desconexão: O db__manager executa seu processo de limpeza final: fecha a conexão com o banco e, crucialmente, redefine self.connection_details e self.schema_list para seus estados vazios iniciais. O sistema retorna oficialmente ao estado "Desconectado", sem deixar rastros da sessão anterior.