Habilidade de Consulta Somente Leitura do PostgreSQL

Quando Usar

• Use ao consultar bancos de dados PostgreSQL e o acesso deve permanecer estritamente somente leitura
• Use ao explorar esquemas, tabelas e dados em várias conexões configuradas
• Use quando quiser proteção em profundidade contra INSERT/UPDATE/DELETE acidentais ou DDL

Execute consultas seguras e somente leitura em bancos de dados PostgreSQL configurados.

Requisitos

• Python 3.8+
• psycopg2-binary: pip install -r requirements.txt

Configuração

Crie connections.json no diretório da habilidade ou ~/.config/claude/postgres-connections.json.

Segurança: Defina as permissões do arquivo para 600, pois ele contém credenciais:

chmod 600 connections.json

{
  "databases": [
    {
      "name": "production",
      "description": "Main app database - users, orders, transactions",
      "host": "db.example.com",
      "port": 5432,
      "database": "app_prod",
      "user": "readonly_user",
      "password": "your-password",
      "sslmode": "require"
    }
  ]
}

Campos de Configuração

Uso

Listar bancos de dados configurados

python3 scripts/query.py --list

Consultar um banco de dados

python3 scripts/query.py --db production --query "SELECT * FROM users LIMIT 10"

Listar tabelas

python3 scripts/query.py --db production --tables

Mostrar esquema

python3 scripts/query.py --db production --schema

Limitar resultados

python3 scripts/query.py --db production --query "SELECT * FROM orders" --limit 100

Seleção de Banco de Dados

Combine a intenção do usuário com a descrição do banco de dados description:

Se não estiver claro, execute --list e pergunte ao usuário qual banco de dados.

Recursos de Segurança

• Sessão somente leitura: A conexão usa o modo readonly=True do PostgreSQL (proteção primária)
• Validação de consulta: Apenas consultas SELECT, SHOW, EXPLAIN, WITH são permitidas
• Instrução única: Múltiplas instruções por consulta são rejeitadas
• Suporte SSL: Modo SSL configurável para conexões criptografadas
• Tempo limite de consulta: Tempo limite de instrução de 30 segundos aplicado
• Proteção de memória: Máximo de 10.000 linhas por consulta para evitar OOM
• Limite de largura de coluna: Máximo de 100 caracteres por coluna para saída legível
• Sanitização de credenciais: Mensagens de erro não vazam senhas

Solução de Problemas

Códigos de Saída

• 0: Sucesso
• 1: Erro (configuração ausente, falha na autenticação, consulta inválida, erro no banco de dados)

Fluxo de Trabalho

1. Execute --list para mostrar os bancos de dados disponíveis
2. Combine a intenção do usuário com a descrição do banco de dados
3. Execute --tables ou --schema para explorar a estrutura
4. Execute a consulta com o LIMIT apropriado

Limitações

• As proteções somente leitura reduzem escritas acidentais, mas não podem substituir a política do servidor de banco de dados, gatilhos, extensões ou uma conta com privilégios excessivos. Use uma função de banco de dados com permissões somente leitura como controle primário.
• Os resultados das consultas podem conter dados pessoais, confidenciais ou regulamentados. Confirme o banco de dados pretendido e evite exportar ou compartilhar resultados sem autorização explícita.
• O script não substitui backups, auditorias, revisões de acesso ou controles de produção.