Ir para o conteúdo
Promovaweb

Como o app conversa com o banco

Um app que abre conexões sem controle esgota o limite do servidor, porque cada conexão com o PostgreSQL usa um processo próprio. A conexão é o canal por onde o app envia comandos e recebe resultados, por TCP na porta padrão 5432 ou por socket local. Um pool reaproveita esse canal entre as consultas.

Ficha e sumário da página

Referência técnica
PostgreSQL 18.7
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. A string de conexão
  2. Do driver ao processo do servidor
  3. O limite de conexões
  4. Pool de conexões
  5. O que o banco vê de cada conexão

A string de conexão

A string de conexão diz ao driver onde fica o servidor, qual banco abrir e com qual usuário entrar. A documentação da libpq, a biblioteca oficial de cliente em C, aceita dois formatos equivalentes. O formato de URI começa com postgresql:// ou postgres://, como em postgresql://app@db:5432/loja?sslmode=require. O formato de palavras-chave lista pares soltos, como host=db port=5432 dbname=loja user=app.

Cada parte da URI é opcional. Sem host nem configuração externa, a libpq tenta um socket Unix local nos sistemas que oferecem esse recurso. No Windows, usa localhost. Sem porta na URI nem configuração por outra fonte, usa o padrão da compilação, normalmente 5432. Sem nome de banco, usa o nome do usuário. Os parâmetros depois do ? ajustam o comportamento da conexão: sslmode define se a criptografia é exigida, connect_timeout limita a espera em segundos e application_name identifica o app nas listas de conexões do servidor.

A senha também cabe na URI, depois de dois-pontos no usuário, mas pode aparecer em logs e no histórico do terminal se você registrar a string completa. A libpq aceita um arquivo de senhas, como .pgpass, para separar a credencial do endereço. Na imagem oficial do servidor, POSTGRES_PASSWORD_FILE lê a senha usada na inicialização a partir de um arquivo, como um secret do Docker. Essa variável não configura a autenticação do cliente, conforme a referência de variáveis de ambiente do PostgreSQL.

Do driver ao processo do servidor

O driver traduz as chamadas do seu código para o protocolo do PostgreSQL. A libpq é uma biblioteca de cliente que oferece esse acesso por TCP ou por socket Unix. Você configura o driver conforme a linguagem e o ambiente do app, mas o servidor recebe mensagens do protocolo, executa SQL e devolve resultados pela conexão.

  1. Driver do app

    postgresql://app@db:5432/loja

    Lê a string, abre o socket TCP e envia usuário e banco.

  2. Processo supervisor

    porta 5432

    Recebe a conexão e cria um processo backend para ela.

  3. Autenticação

    pg_hba.conf

    Confere banco, usuário e endereço de origem e escolhe o método, como scram-sha-256.

  4. Processo backend

    uma conexão, um processo

    Executa cada comando da sessão até o app desconectar.

O caminho de uma conexão nova até o primeiro comando: o processo supervisor recebe na porta padrão 5432 e cria o backend, que autentica o cliente conforme o pg_hba.conf.

A documentação chama esse desenho de modelo cliente e servidor com um processo por usuário. O processo supervisor, conhecido como postmaster, escuta a porta e cria um processo backend a cada conexão nova. Esse backend mantém o estado da sessão, como as variáveis definidas com SET, as tabelas temporárias e a transação aberta. Ele também ocupa memória própria enquanto a conexão existe, mesmo parada, à espera do próximo comando.

O pg_hba.conf é o arquivo de autenticação baseada em host, guardado na pasta do cluster. Cada linha combina tipo de conexão, banco, usuário e faixa de endereços com um método. A primeira linha que combina com a conexão define o método usado. O método scram-sha-256 confere a senha sem trafegá-la em texto aberto. O método trust aceita a conexão sem senha nenhuma e cabe só em laboratório.

O limite de conexões

O parâmetro max_connections define quantas conexões o servidor aceita ao mesmo tempo. Segundo a documentação, o padrão costuma ser 100. A mudança só vale depois de reiniciar o servidor. Acima do limite, a conexão nova recebe um erro na hora de entrar, sem fila de espera. Por padrão, três dessas vagas ficam reservadas a superusuários pelo parâmetro superuser_reserved_connections. Outra reserva pode ser configurada com reserved_connections para roles autorizadas.

Esse número acaba rápido numa VPS com vários apps. Um backend com quatro workers, cada um com um pool de dez conexões, pode ocupar até 40 vagas antes do n8n e do Metabase abrirem as deles. Como cada conexão é um processo com memória própria, aumentar max_connections sem medir também aumenta o consumo de memória do servidor.

Pool de conexões

Um pool mantém um conjunto de conexões abertas e empresta cada uma ao código durante uma consulta ou uma transação. Uma conexão TCP nova exige negociar a rede, autenticar o cliente e criar o processo no servidor, além de negociar a criptografia quando ela está habilitada. Enquanto a conexão permanece aberta no pool, as requisições seguintes reaproveitam esse trabalho.

Um pool pode ficar dentro do próprio app, no driver ou no ORM, conforme os recursos da biblioteca escolhida. Ele limita quantas conexões cada processo do app abre. Quando vários apps ou muitos workers dividem o mesmo servidor, entra um pool externo, como o PgBouncer, que fica entre os apps e o PostgreSQL.

O PgBouncer oferece três modos. No modo de sessão, a conexão do servidor fica com o cliente até ele desconectar, com todos os recursos do PostgreSQL disponíveis. No modo de transação, a conexão volta ao pool no fim de cada transação, o que atende muito mais clientes com poucas conexões reais. O preço desse modo é perder recursos que dependem da sessão, como variáveis definidas com SET fora da transação. O modo de comando devolve a conexão depois de cada comando e proíbe transações com mais de um comando.

O que o banco vê de cada conexão

A visão pg_stat_activity lista uma linha por processo do servidor, com usuário, banco, endereço de origem, application_name, estado e a consulta em andamento. Ela mostra quantas conexões cada app ocupa e quais ficaram paradas dentro de uma transação aberta, um estado que segura versões antigas das linhas e atrasa a limpeza das tabelas. Essa relação entre transação aberta e limpeza aparece na página Transações e concorrência.

O próximo assunto é o que o seu código grava por essa conexão: tabelas, chaves primárias e estrangeiras e as restrições que o servidor confere, na página Tabelas, chaves e restrições.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.