Postgres MCP Pro

Um servidor MCP para PostgreSQL que oferece ajuste de índices, planos de explicação, verificações de integridade e execução segura de SQL.

GitHub
3.3k
Experimente este MCPPatrocinado

Documentação

Postgres MCP Pro Logo

License: MIT PyPI - Version Discord Twitter Follow Contributors

Um servidor MCP Postgres com ajuste de índices, planos de execução, verificações de saúde e execução segura de SQL.

Visão Geral

O Postgres MCP Pro é um servidor Model Context Protocol (MCP) de código aberto criado para apoiar você e seus agentes de IA durante todo o processo de desenvolvimento—desde a codificação inicial, passando por testes e implantação, até o ajuste e a manutenção em produção.

O Postgres MCP Pro faz muito mais do que apenas encapsular uma conexão com o banco de dados.

Os recursos incluem:

  • 🔍 Saúde do Banco de Dados - analisa saúde dos índices, utilização de conexões, cache de buffers, saúde do vacuum, limites de sequências, atraso de replicação e muito mais.
  • ⚡ Ajuste de Índices - explora milhares de índices possíveis para encontrar a melhor solução para sua carga de trabalho, usando algoritmos de nível industrial.
  • 📈 Planos de Consulta - valida e otimiza o desempenho revisando planos EXPLAIN e simulando o impacto de índices hipotéticos.
  • 🧠 Inteligência de Esquema - geração de SQL com consciência de contexto baseada no entendimento detalhado do esquema do banco de dados.
  • 🛡️ Execução Segura de SQL - controle de acesso configurável, incluindo suporte a modo somente leitura e análise segura de SQL, tornando-o utilizável tanto para desenvolvimento quanto para produção.

O Postgres MCP Pro suporta os transportes Standard Input/Output (stdio) e Server-Sent Events (SSE), oferecendo flexibilidade em diferentes ambientes.

Para mais contexto sobre por que criamos o Postgres MCP Pro, consulte nossa publicação de lançamento no blog.

Demonstração

De Inutilizável a Extremamente Rápido

  • Desafio: Geramos um aplicativo de filmes usando um assistente de IA, mas o código ORM SQLAlchemy rodava extremamente lento.
  • Solução: Usando o Postgres MCP Pro com o Cursor, corrigimos os problemas de desempenho em minutos.

O que fizemos:

  • 🚀 Corrigimos o desempenho - incluindo consultas ORM, indexação e cache
  • 🛠️ Corrigimos uma página quebrada - orientando o agente a explorar os dados, corrigir consultas e adicionar conteúdo relacionado.
  • 🧠 Melhoramos os melhores filmes - explorando os dados e corrigindo a consulta ORM para exibir resultados mais relevantes.

Veja o vídeo abaixo ou leia o comentário passo a passo.

https://github.com/user-attachments/assets/24e05745-65e9-4998-b877-a368f1eadc13

Início Rápido

Pré-requisitos

Antes de começar, certifique-se de ter:

  1. Credenciais de acesso ao seu banco de dados.
  2. Docker ou Python 3.12 ou superior.

Credenciais de Acesso

Você pode confirmar que suas credenciais de acesso são válidas usando psql ou uma ferramenta gráfica como o pgAdmin.

Docker ou Python

A escolha entre Docker ou Python é sua. Geralmente recomendamos Docker porque usuários de Python podem encontrar mais problemas específicos de ambiente. No entanto, muitas vezes faz sentido usar o método com o qual você está mais familiarizado.

Instalação

Escolha um dos seguintes métodos para instalar o Postgres MCP Pro:

Opção 1: Usando Docker

Baixe a imagem Docker do servidor MCP Postgres MCP Pro. Esta imagem contém todas as dependências necessárias, fornecendo uma maneira confiável de executar o Postgres MCP Pro em diversos ambientes.

docker pull crystaldba/postgres-mcp

Opção 2: Usando Python

Se você tiver o pipx instalado, pode instalar o Postgres MCP Pro com:

pipx install postgres-mcp

Caso contrário, instale o Postgres MCP Pro com uv:

uv pip install postgres-mcp

Se você precisar instalar o uv, consulte as instruções de instalação do uv.

Configure Seu Assistente de IA

Fornecemos instruções completas para configurar o Postgres MCP Pro com o Claude Desktop. Muitos clientes MCP possuem arquivos de configuração semelhantes; você pode adaptar estas etapas para funcionar com o cliente de sua escolha.

Configuração do Claude Desktop

Você precisará editar o arquivo de configuração do Claude Desktop para adicionar o Postgres MCP Pro. A localização deste arquivo depende do seu sistema operacional:

  • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json

Você também pode usar o item de menu Settings no Claude Desktop para localizar o arquivo de configuração.

Agora você editará a seção mcpServers do arquivo de configuração.

Se você estiver usando Docker
{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

A imagem Docker do Postgres MCP Pro remapeará automaticamente o nome de host localhost para funcionar de dentro do contêiner.

  • MacOS/Windows: Usa host.docker.internal automaticamente
  • Linux: Usa 172.17.0.1 ou o endereço de host apropriado automaticamente
Se você estiver usando uvx
{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": [
        "postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}
Se você estiver usando pipx
{
  "mcpServers": {
    "postgres": {
      "command": "postgres-mcp",
      "args": [
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}
Se você estiver usando uv
{
  "mcpServers": {
    "postgres": {
      "command": "uv",
      "args": [
        "run",
        "postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}
URI de Conexão

Substitua postgresql://... pela sua URI de conexão do banco de dados Postgres.

Modo de Acesso

O Postgres MCP Pro suporta múltiplos modos de acesso para dar a você controle sobre as operações que o agente de IA pode realizar no banco de dados:

  • Modo Irrestrito: Permite acesso total de leitura/gravação para modificar dados e esquema. É adequado para ambientes de desenvolvimento.
  • Modo Restrito: Limita as operações a transações somente leitura e impõe restrições sobre a utilização de recursos (atualmente apenas o tempo de execução). É adequado para ambientes de produção.

Para usar o modo restrito, substitua --access-mode=unrestricted por --access-mode=restricted nos exemplos de configuração acima.

Outros Clientes MCP

Muitos clientes MCP possuem arquivos de configuração semelhantes aos do Claude Desktop, e você pode adaptar os exemplos acima para funcionar com o cliente de sua escolha.

  • Se você estiver usando Cursor, navegue de Command Palette para Cursor Settings e abra a aba MCP para acessar o arquivo de configuração.
  • Se você estiver usando Windsurf, navegue de Command Palette para Open Windsurf Settings Page para acessar o arquivo de configuração.
  • Se você estiver usando Goose, execute goose configure e selecione Add Extension.
  • Se você estiver usando Qodo Gen, abra o painel de Chat, clique em Connect more tools, clique em + Add new MCP e adicione a nova configuração.

Transporte SSE

O Postgres MCP Pro suporta o transporte SSE, que permite que múltiplos clientes MCP compartilhem um único servidor, possivelmente um servidor remoto. Para usar o transporte SSE, você precisa iniciar o servidor com a opção --transport=sse.

Por exemplo, com Docker execute:

docker run -p 8000:8000 \
  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
  crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse

Em seguida, atualize a configuração do seu cliente MCP para chamar o servidor MCP. Por exemplo, no mcp.json do Cursor ou no cline_mcp_settings.json do Cline, você pode colocar:

{
    "mcpServers": {
        "postgres": {
            "type": "sse",
            "url": "http://localhost:8000/sse"
        }
    }
}

Para o Windsurf, o formato em mcp_config.json é ligeiramente diferente:

{
    "mcpServers": {
        "postgres": {
            "type": "sse",
            "serverUrl": "http://localhost:8000/sse"
        }
    }
}

Instalação de Extensões do Postgres (Opcional)

Para habilitar o ajuste de índices e a análise abrangente de desempenho, você precisa carregar as extensões pg_stat_statements e hypopg no seu banco de dados.

  • A extensão pg_stat_statements permite que o Postgres MCP Pro analise estatísticas de execução de consultas. Por exemplo, isso permite entender quais consultas estão rodando lentamente ou consumindo recursos significativos.
  • A extensão hypopg permite que o Postgres MCP Pro simule o comportamento do planejador de consultas do Postgres após a adição de índices.

Instalando extensões no AWS RDS, Azure SQL ou Google Cloud SQL

Se o seu banco de dados Postgres estiver rodando em um serviço gerenciado por provedor de nuvem, as extensões pg_stat_statements e hypopg já devem estar disponíveis no sistema. Nesse caso, você pode simplesmente executar comandos CREATE EXTENSION usando um papel com privilégios suficientes:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS hypopg;

Instalando extensões em Postgres autogerenciado

Se você gerencia sua própria instalação do Postgres, pode ser necessário fazer trabalho adicional. Antes de carregar a extensão pg_stat_statements, você deve garantir que ela esteja listada no shared_preload_libraries no arquivo de configuração do Postgres. A extensão hypopg também pode exigir instalação adicional no nível do sistema (por exemplo, através do seu gerenciador de pacotes), pois nem sempre acompanha o Postgres.

Exemplos de Uso

Obter Visão Geral da Saúde do Banco de Dados

Pergunte:

Verifique a saúde do meu banco de dados e identifique quaisquer problemas.

Analisar Consultas Lentas

Pergunte:

Quais são as consultas mais lentas no meu banco de dados? E como posso acelerá-las?

Obter Recomendações Sobre Como Acelerar as Coisas

Pergunte:

Meu aplicativo está lento. Como posso torná-lo mais rápido?

Gerar Recomendações de Índices

Pergunte:

Analise minha carga de trabalho no banco de dados e sugira índices para melhorar o desempenho.

Otimizar uma Consulta Específica

Pergunte:

Ajude-me a otimizar esta consulta: SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id WHERE orders.created_at > '2023-01-01';

API do Servidor MCP

O padrão MCP define vários tipos de endpoints: Ferramentas, Recursos, Prompts e outros.

O Postgres MCP Pro fornece funcionalidade apenas por meio de ferramentas MCP. Escolhemos essa abordagem porque o ecossistema de clientes MCP tem amplo suporte para ferramentas MCP. Isso contrasta com a abordagem de outros servidores MCP Postgres, incluindo o Servidor MCP Postgres de Referência, que usam recursos MCP para expor informações de esquema.

Ferramentas do Postgres MCP Pro:

Nome da FerramentaDescrição
list_schemasLista todos os esquemas de banco de dados disponíveis na instância PostgreSQL.
list_objectsLista objetos de banco de dados (tabelas, visualizações, sequências, extensões) dentro de um esquema especificado.
get_object_detailsFornece informações sobre um objeto de banco de dados específico, por exemplo, as colunas, restrições e índices de uma tabela.
execute_sqlExecuta instruções SQL no banco de dados, com limitações somente leitura quando conectado em modo restrito.
explain_queryObtém o plano de execução de uma consulta SQL descrevendo como o PostgreSQL a processará e expondo o modelo de custos do planejador de consultas. Pode ser invocado com índices hipotéticos para simular o comportamento após a adição de índices.
get_top_queriesRelata as consultas SQL mais lentas com base no tempo total de execução usando dados de pg_stat_statements.
analyze_workload_indexesAnalisa a carga de trabalho do banco de dados para identificar consultas que consomem muitos recursos e, em seguida, recomenda índices ideais para elas.
analyze_query_indexesAnalisa uma lista de consultas SQL específicas (até 10) e recomenda índices ideais para elas.
analyze_db_healthRealiza verificações abrangentes de saúde, incluindo: taxas de acerto do cache de buffers, saúde das conexões, validação de restrições, saúde dos índices (duplicados/não utilizados/inválidos), limites de sequências e saúde do vacuum.

Projetos Relacionados

Servidores MCP Postgres

  • Query MCP. Um servidor MCP para Supabase Postgres com arquitetura de segurança em três camadas e suporte à API de gerenciamento Supabase.
  • PG-MCP. Um servidor MCP para PostgreSQL com opções flexíveis de conexão, planos de execução, contexto de extensões e muito mais.
  • Servidor MCP PostgreSQL de Referência. Uma implementação simples de servidor MCP que expõe informações de esquema como recursos MCP e executa consultas somente leitura.
  • Servidor MCP Postgres Supabase. Este servidor MCP fornece recursos de gerenciamento do Supabase e é mantido ativamente pela comunidade Supabase.
  • Servidor MCP Nile. Um servidor MCP que fornece acesso à API de gerenciamento do serviço Postgres multi-tenant da Nile.
  • Servidor MCP Neon. Um servidor MCP que fornece acesso à API de gerenciamento do serviço Postgres serverless da Neon.
  • Servidor MCP Wren. Fornece um mecanismo semântico que alimenta inteligência de negócios para Postgres e outros bancos de dados.

Ferramentas de DBA (incluindo ofertas comerciais)

  • Otimizador de Banco de Dados Aiven. Uma ferramenta que fornece análise holística de carga de trabalho de banco de dados, otimizações de consulta e outras melhorias de desempenho.
  • dba.ai. Um assistente de administração de banco de dados com IA que se integra ao GitHub para resolver problemas de código.
  • pgAnalyze. Uma plataforma abrangente de monitoramento e análise para identificar gargalos de desempenho, otimizar consultas e alertas em tempo real.
  • Postgres.ai. Uma experiência de chat interativa que combina uma extensa base de conhecimento do Postgres e GPT-4.
  • Xata Agent. Um agente de IA de código aberto que monitora automaticamente a saúde do banco de dados, diagnostica problemas e fornece recomendações usando raciocínio e playbooks baseados em LLM.

Utilitários Postgres

  • Dexter. Uma ferramenta para gerar e testar índices hipotéticos no PostgreSQL.
  • PgHero. Um painel de desempenho para Postgres, com recomendações. O Postgres MCP Pro incorpora verificações de saúde do PgHero.
  • PgTune. Heurísticas para ajustar a configuração do Postgres.

Perguntas Frequentes

Como o Postgres MCP Pro é diferente de outros servidores MCP Postgres? Existem muitos servidores MCP que permitem que um agente de IA execute consultas em um banco de dados Postgres. O Postgres MCP Pro também faz isso, mas também adiciona ferramentas para entender e melhorar o desempenho do seu banco de dados Postgres. Por exemplo, ele implementa uma versão do Algoritmo Anytime do Database Tuning Advisor para Microsoft SQL Server, um algoritmo moderno de nível industrial para ajuste automático de índices.

Postgres MCP ProOutros Servidores MCP Postgres
✅ Verificações de saúde de banco de dados determinísticas❌ Consultas de saúde geradas por LLM não reproduzíveis
✅ Estratégias de busca de indexação baseadas em princípios❌ Suposições de IA generativa para melhorias de indexação
✅ Análise de carga de trabalho para encontrar os principais problemas❌ Análise de problemas inconsistente
✅ Simula melhorias de desempenho❌ Tente você mesmo e veja se funciona

O Postgres MCP Pro complementa a IA generativa adicionando ferramentas determinísticas e algoritmos clássicos de otimização. A combinação é confiável e flexível.

Por que as ferramentas MCP são necessárias quando o LLM pode raciocinar, gerar SQL, etc? LLMs são inestimáveis para tarefas que envolvem ambiguidade, raciocínio ou linguagem natural. No entanto, quando comparados a código procedural, eles podem ser lentos, caros, não determinísticos e às vezes produzir resultados não confiáveis. No caso de ajuste de banco de dados, temos algoritmos bem estabelecidos, desenvolvidos ao longo de décadas, que comprovadamente funcionam. O Postgres MCP Pro permite combinar o melhor dos dois mundos, emparelhando LLMs com algoritmos clássicos de otimização e outras ferramentas procedurais.

Como você testa o Postgres MCP Pro? O teste é fundamental para garantir que o Postgres MCP Pro seja confiável e preciso. Estamos construindo um conjunto de cargas de trabalho adversariais geradas por IA, projetadas para desafiar o Postgres MCP Pro e garantir que ele tenha um bom desempenho em uma ampla variedade de cenários.

Quais versões do Postgres são suportadas? Nossos testes atualmente focam no Postgres 15, 16 e 17. Planejamos suportar as versões 13 a 17 do Postgres.

Quem criou este projeto? Este projeto é criado e mantido por Crystal DBA.

Roteiro

A definir

Você e suas necessidades são um fator crítico para o que construímos. Diga-nos o que você gostaria de ver abrindo uma issue ou um pull request. Você também pode nos contatar no Discord.

Notas Técnicas

Esta seção inclui uma visão geral de alto nível das considerações técnicas que influenciaram o design do Postgres MCP Pro.

Ajuste de Índices

Os desenvolvedores sabem que índices ausentes são uma das causas mais comuns de problemas de desempenho em bancos de dados. Os índices fornecem métodos de acesso que permitem ao Postgres localizar rapidamente os dados necessários para executar uma consulta. Quando as tabelas são pequenas, os índices fazem pouca diferença, mas à medida que o tamanho dos dados cresce, a diferença na complexidade algorítmica entre uma varredura de tabela e uma busca por índice torna-se significativa (tipicamente O(n) vs O(log n), potencialmente mais se houver junções em múltiplas tabelas).

A geração de índices sugeridos no Postgres MCP Pro ocorre em várias etapas:

  1. Identifique consultas SQL que precisam de ajuste. Se você sabe que está tendo um problema com uma consulta SQL específica, pode fornecê-la. O Postgres MCP Pro também pode analisar a carga de trabalho para identificar alvos de ajuste de índices. Para isso, ele depende da extensão pg_stat_statements, que registra o tempo de execução e o consumo de recursos de cada consulta.

    Uma consulta é candidata a ajuste de índices se for um dos principais consumidores de recursos, seja por execução ou em agregado. Atualmente, usamos o tempo de execução como proxy para o consumo cumulativo de recursos, mas também pode fazer sentido analisar recursos específicos, por exemplo, o número de blocos acessados ou o número de blocos lidos do disco. A ferramenta analyze_query_workload foca em consultas lentas, usando o tempo médio por execução com limites para contagem de execuções e tempo médio de execução. Os agentes também podem chamar get_top_queries, que aceita um parâmetro para tempo médio vs. tempo total de execução, e então passar essas consultas para analyze_query_indexes para obter recomendações de índices.

    Sistemas sofisticados de ajuste de índices usam "compressão de carga de trabalho" para produzir um subconjunto representativo de consultas que reflita as características da carga de trabalho como um todo, reduzindo o problema para algoritmos downstream. O Postgres MCP Pro realiza uma forma limitada de compressão de carga de trabalho normalizando consultas para que aquelas geradas a partir do mesmo modelo apareçam como uma só. Ele pondera cada consulta igualmente, uma simplificação que funciona quando os benefícios da indexação são grandes.

  2. Gerar índices candidatos. Depois de termos uma lista de consultas SQL que queremos melhorar por meio de indexação, geramos uma lista de índices que podemos adicionar. Para isso, analisamos o SQL e identificamos quaisquer colunas usadas em filtros, junções, agrupamento ou ordenação.

    Para gerar todos os índices possíveis, precisamos considerar combinações dessas colunas, porque o Postgres suporta índices multicoluna. Na implementação atual, incluímos apenas uma permutação de cada índice multicoluna possível, selecionada aleatoriamente. Fazemos essa simplificação para reduzir o espaço de busca, pois permutações frequentemente têm desempenho equivalente. No entanto, esperamos melhorar nessa área.

  3. Buscar a configuração de índices ideal. Nosso objetivo é encontrar a combinação de índices que equilibre de forma ideal os benefícios de desempenho em relação aos custos de armazenamento e manutenção desses índices. Estimamos a melhoria de desempenho usando os recursos "e se?" fornecidos pela extensão hypopg. Isso simula como o otimizador de consultas do Postgres executará uma consulta após a adição de índices e relata mudanças com base no modelo de custo real do Postgres.

    Um desafio é que gerar planos de consulta geralmente requer conhecimento dos valores específicos de parâmetros usados na consulta. A normalização de consultas, necessária para reduzir as consultas em consideração, remove constantes de parâmetros. Valores de parâmetros fornecidos via variáveis de ligação também não estão disponíveis para nós.

    Para resolver esse problema, produzimos constantes realistas que podemos fornecer como parâmetros, amostrando as estatísticas da tabela. Na versão 16, o Postgres adicionou funcionalidade de plano de explain genérico, mas tem limitações, por exemplo em torno de cláusulas LIKE, que nossa implementação não possui.

    A estratégia de busca é crítica porque avaliar todas as combinações possíveis de índices é viável apenas em situações simples. Isso é o que mais diferencia várias abordagens de indexação. Adaptando a abordagem do algoritmo Anytime da Microsoft, empregamos uma estratégia de busca gulosa, ou seja, encontramos a melhor solução de um índice, depois encontramos o melhor índice para adicionar a essa para produzir uma solução de dois índices. Nossa busca termina quando o orçamento de tempo é esgotado ou quando uma rodada de exploração não produz ganhos acima do limite mínimo de melhoria de 10%.

  4. Análise de custo-benefício. Quando confrontados com duas alternativas de indexação, uma que produz melhor desempenho e outra que requer mais espaço, como decidimos qual escolher? Tradicionalmente, os consultores de índices pedem um orçamento de armazenamento e otimizam o desempenho em relação a esse orçamento. Também consideramos um orçamento de armazenamento, mas realizamos uma análise de custo-benefício ao longo da otimização.

    Enquadramos isso como o problema de selecionar um ponto ao longo da frente de Pareto—o conjunto de escolhas para as quais melhorar uma métrica de qualidade necessariamente piora outra. Em um mundo ideal, poderíamos avaliar o custo do armazenamento e o benefício do desempenho melhorado em termos monetários. No entanto, há uma abordagem mais simples e prática: observar as mudanças em termos relativos. A maioria das pessoas concordaria que uma melhoria de desempenho de 100x vale a pena, mesmo que o custo de armazenamento seja 2x. Em nossa implementação, usamos um parâmetro configurável para definir esse limite. Por padrão, exigimos que a mudança no log (base 10) da melhoria de desempenho seja 2x a diferença no log do custo de espaço. Isso equivale a permitir um aumento máximo de 10x no espaço para uma melhoria de desempenho de 100x.

Nossa implementação está mais relacionada ao Algoritmo Anytime encontrado no Microsoft SQL Server. Em comparação com o Dexter, uma ferramenta de indexação automática para Postgres, buscamos um espaço maior e usamos heurísticas diferentes. Isso nos permite gerar melhores soluções ao custo de um tempo de execução mais longo.

Também mostramos o trabalho realizado em cada rodada da busca, incluindo uma comparação dos planos de consulta antes e depois da adição de cada índice. Isso dá ao LLM contexto adicional que ele pode usar ao responder às recomendações de indexação.

Experimental: Ajuste de Índices por LLM

O Postgres MCP Pro inclui um recurso experimental de ajuste de índices baseado em Otimização por LLM. Em vez de usar heurísticas para explorar possíveis configurações de índices, fornecemos o esquema do banco de dados e os planos de consulta a um LLM e pedimos que ele proponha configurações de índices. Em seguida, usamos hypopg para prever o desempenho com os índices propostos e alimentamos esses resultados de volta ao LLM para produzir um novo conjunto de sugestões. Repetimos esse processo até que várias rodadas de iteração não produzam melhorias adicionais.

A otimização de índices por LLM tem vantagens quando o espaço de busca de índices é grande, ou quando índices com muitas colunas precisam ser considerados. Como abordagens tradicionais baseadas em busca, ela depende da precisão das previsões de desempenho do hypopg.

Para realizar a otimização de índices por LLM, você deve fornecer uma chave de API da OpenAI definindo a variável de ambiente OPENAI_API_KEY.

Saúde do Banco de Dados

As verificações de saúde do banco de dados identificam oportunidades de ajuste e necessidades de manutenção antes que se tornem problemas críticos. Na versão atual, o Postgres MCP Pro adapta as verificações de saúde do banco de dados diretamente do PgHero. Estamos trabalhando para validar totalmente essas verificações e podemos estendê-las no futuro.

  • Saúde de Índices. Procura por índices não utilizados, índices duplicados e índices que estão inchados. Índices inchados fazem uso ineficiente das páginas do banco de dados. O autovacuum do Postgres limpa entradas de índice que apontam para tuplas mortas e marca as entradas como reutilizáveis. No entanto, ele não compacta as páginas de índice e, eventualmente, as páginas de índice podem conter poucas referências a tuplas vivas.
  • Taxa de Acerto do Cache de Buffer. Mede a proporção de leituras do banco de dados que são atendidas pelo cache de buffer em vez do disco. Uma baixa taxa de acerto do cache de buffer deve ser investigada, pois muitas vezes não é econômica e leva à degradação do desempenho da aplicação.
  • Saúde de Conexões. Verifica o número de conexões com o banco de dados e relata sua utilização. O maior risco é ficar sem conexões, mas um alto número de conexões ociosas ou bloqueadas também pode indicar problemas.
  • Saúde de Vacuum. O vacuum é importante por muitas razões. Uma crítica é evitar o estouro do ID de transação, que pode fazer o banco de dados parar de aceitar gravações. O mecanismo de controle de concorrência multiversão (MVCC) do Postgres requer um ID de transação único para cada transação. No entanto, como o Postgres usa um inteiro assinado de 32 bits para IDs de transação, ele precisa reutilizar IDs de transação após um máximo de 2 bilhões de transações. Para fazer isso, ele "congela" os IDs de transação de transações históricas, definindo-os todos para um valor especial que indica passado distante. Quando os registros vão para o disco pela primeira vez, eles são gravados com visibilidade para uma faixa de IDs de transação. Antes de reutilizar esses IDs de transação, o Postgres deve atualizar quaisquer registros em disco, "congelando-os" para remover as referências aos IDs de transação a serem reutilizados. Esta verificação procura por tabelas que exigem vacuum para evitar o estouro do ID de transação.
  • Saúde de Replicação. Verifica a saúde da replicação monitorando o atraso entre o primário e as réplicas, verificando o status da replicação e rastreando o uso de slots de replicação.
  • Saúde de Restrições. Durante a operação normal, o Postgres rejeita qualquer transação que causaria uma violação de restrição. No entanto, restrições inválidas podem ocorrer após o carregamento de dados ou em cenários de recuperação. Esta verificação procura por restrições inválidas.
  • Saúde de Sequências. Procura por sequências que estão em risco de exceder seu valor máximo.

Biblioteca Cliente Postgres

O Postgres MCP Pro usa psycopg3 para conectar ao Postgres usando I/O assíncrono. Por baixo dos panos, o psycopg3 usa a biblioteca libpq para conectar ao Postgres, fornecendo acesso ao conjunto completo de recursos do Postgres e uma implementação subjacente totalmente suportada pela comunidade Postgres.

Alguns outros servidores MCP baseados em Python usam asyncpg, o que pode simplificar a instalação ao eliminar a dependência de libpq. O Asyncpg também é provavelmente mais rápido que o psycopg3, mas não validamos isso nós mesmos. Benchmarks mais antigos relatam uma lacuna de desempenho maior, sugerindo que o psycopg3 mais novo reduziu a lacuna à medida que amadurece.

Equilibrando essas considerações, selecionamos psycopg3 em vez de asyncpg. Continuamos abertos a revisar essa decisão no futuro.

Configuração de Conexão

Como o Reference PostgreSQL MCP Server, o Postgres MCP Pro recebe as informações de conexão do Postgres na inicialização. Isso é conveniente para usuários que sempre se conectam ao mesmo banco de dados, mas pode ser complicado quando os usuários alternam entre bancos de dados.

Uma abordagem alternativa, adotada pelo PG-MCP, é fornecer detalhes de conexão por meio de chamadas de ferramentas MCP no momento do uso. Isso é mais conveniente para usuários que alternam entre bancos de dados e permite que um único servidor MCP suporte simultaneamente vários usuários finais.

Deve haver uma abordagem melhor do que qualquer uma dessas. Ambas têm fraquezas de segurança—poucos clientes MCP armazenam a configuração do servidor MCP com segurança (uma exceção é o Goose), e as credenciais fornecidas por meio de ferramentas MCP passam pelo LLM e são armazenadas no histórico do chat. Ambas também têm problemas de usabilidade em alguns cenários.

Informações de Esquema

O objetivo da ferramenta de informações de esquema é fornecer ao agente de IA chamador as informações necessárias para gerar SQL correto e eficiente. Por exemplo, suponha que um usuário pergunte: "Quantos voos decolaram de São Francisco e pousaram em Paris durante o último ano?" O agente de IA precisa encontrar a tabela que armazena os voos, as colunas que armazenam a origem e o destino, e talvez uma tabela que mapeie entre códigos de aeroporto e localizações de aeroportos.

Por que fornecer ferramentas de informações de esquema quando os LLMs são geralmente capazes de gerar o SQL para recuperar essas informações do Postgres diretamente?

Nossa experiência com o Claude indica que o LLM chamador é muito bom em gerar SQL para explorar o esquema do Postgres consultando o catálogo do sistema Postgres e o information schema (uma visão de metadados de banco de dados padronizada pela ANSI). No entanto, não sabemos se outros LLMs fazem isso de forma tão confiável e capaz.

Seria melhor fornecer informações de esquema usando recursos MCP em vez de ferramentas MCP?

O Reference PostgreSQL MCP Server usa recursos para expor informações de esquema em vez de ferramentas. Navegar por recursos é semelhante a navegar por um sistema de arquivos, então essa abordagem é natural de muitas maneiras. No entanto, o suporte a recursos é menos difundido do que o suporte a ferramentas no ecossistema de clientes MCP (veja exemplos de clientes). Além disso, embora o padrão MCP diga que os recursos podem ser acessados por agentes de IA ou humanos usuários finais, alguns clientes só suportam navegação humana da árvore de recursos.

Execução de SQL Protegida

A IA amplifica desafios de longa data de proteger bancos de dados contra uma série de ameaças, desde erros simples até ataques sofisticados de atores maliciosos. Se a ameaça é acidental ou maliciosa, uma estrutura de segurança semelhante se aplica, com objetivos que se enquadram em três categorias: confidencialidade, integridade e disponibilidade. A tensão familiar entre conveniência e segurança também é evidente e pronunciada.

O modo de execução de SQL protegida do Postgres MCP Pro foca na integridade. No contexto do MCP, estamos mais preocupados com SQL gerado por LLM causando danos—por exemplo, modificação ou exclusão não intencional de dados, ou outras alterações que possam contornar o processo de gerenciamento de mudanças de uma organização.

A maneira mais simples de fornecer integridade é garantir que todo SQL executado contra o banco de dados seja somente leitura. Uma maneira de fazer isso é criando um usuário de banco de dados com permissões somente leitura. Embora seja uma boa abordagem, muitos a consideram complicada na prática. O Postgres não fornece uma maneira de colocar uma conexão ou sessão em modo somente leitura, então o Postgres MCP Pro usa uma abordagem mais complexa para garantir a execução de SQL somente leitura sobre uma conexão de leitura e gravação.

O Postgres MCP Pro fornece um modo de transação somente leitura que impede modificações de dados e esquema. Como o Reference PostgreSQL MCP Server, usamos transações somente leitura para fornecer execução de SQL protegida.

Para tornar esse mecanismo robusto, precisamos garantir que o SQL não contorne de alguma forma o modo de transação somente leitura, por exemplo, emitindo uma instrução COMMIT ou ROLLBACK e depois iniciando uma nova transação.

Por exemplo, o LLM pode contornar o modo de transação somente leitura emitindo uma instrução ROLLBACK e depois iniciando uma nova transação. Por exemplo:

ROLLBACK; DROP TABLE users;

Para evitar casos como este, analisamos o SQL antes da execução usando a biblioteca pglast. Rejeitamos qualquer SQL que contenha instruções commit ou rollback. Felizmente, as linguagens populares de procedimentos armazenados do Postgres, incluindo PL/pgSQL e PL/Python, não permitem instruções COMMIT ou ROLLBACK. Se você tiver linguagens de procedimentos armazenados inseguras habilitadas em seu banco de dados, nossas proteções de somente leitura podem ser contornadas.

Atualmente, o Postgres MCP Pro fornece dois níveis de proteção para o banco de dados, um em cada extremo do espectro conveniência/segurança.

  • "Irrestrito" fornece máxima flexibilidade. É adequado para ambientes de desenvolvimento onde velocidade e flexibilidade são fundamentais, e onde não há necessidade de proteger dados valiosos ou sensíveis.
  • "Restrito" fornece um equilíbrio entre flexibilidade e segurança. É adequado para ambientes de produção onde o banco de dados está exposto a usuários não confiáveis, e onde é importante proteger dados valiosos ou sensíveis.

O modo irrestrito está alinhado com a abordagem do modo de execução automática do Cursor, onde o agente de IA opera com supervisão humana ou aprovações limitadas. Esperamos que a execução automática seja implantada em ambientes de desenvolvimento onde as consequências de erros são baixas, onde os bancos de dados não contêm dados valiosos ou sensíveis, e onde podem ser recriados ou restaurados a partir de backups quando necessário.

Projetamos o modo restrito para ser conservador, errando pelo lado da segurança mesmo que possa ser inconveniente. O modo restrito é limitado a operações somente leitura, e limitamos o tempo de execução de consultas para evitar que consultas de longa duração impactem o desempenho do sistema. Podemos adicionar medidas no futuro para garantir que o modo restrito seja seguro para uso com bancos de dados de produção.

Desenvolvimento do Postgres MCP Pro

As instruções abaixo são para desenvolvedores que desejam trabalhar no Postgres MCP Pro, ou usuários que preferem instalar o Postgres MCP Pro a partir do código-fonte.

Configuração de Desenvolvimento Local

  1. Instalar o uv:

    curl -sSL https://astral.sh/uv/install.sh | sh

  2. Clonar o repositório:

    git clone https://github.com/crystaldba/postgres-mcp.git
cd postgres-mcp

  3. Instalar dependências:

    uv pip install -e .
uv sync

  4. Executar o servidor:

    uv run postgres-mcp "postgres://user:password@localhost:5432/dbname"