Supermarket Database

Sistema de Banco de Dados - Supermercado 🛒

Um projeto de banco de dados PostgreSQL totalmente dockerizado que implementa o esquema de dados de um supermercado com capacidades de integração MCP para Claude Desktop.

📋 Sumário

• Descrição do Projeto
• Pré-requisitos
• Estrutura do Projeto
• Instalação e Configuração
• Conexão ao pgAdmin
• Restauração do Banco de Dados
• Integração com Claude Desktop (MCP)
• Solução de Problemas

🎯 Descrição do Projeto

Este projeto fornece uma solução completa para o gerenciamento de dados de um supermercado utilizando PostgreSQL em contêineres Docker. Inclui:

• Banco de dados PostgreSQL: Esquema completo do supermercado
• Backup de dados: Arquivo de backup com estrutura e dados de teste
• Integração MCP: Configuração para uso com Claude Desktop
• Docker Compose: Configuração de infraestrutura automatizada

⚙️ Pré-requisitos

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

• Docker v20.10 ou superior
• Docker Compose v2.0 ou superior
• pgAdmin (para restauração do backup)
• Claude Desktop (opcional, para integração MCP)

📁 Estrutura do Projeto

DB_SUPERMARKET/
├── docker-compose.yml      # Configuración de Docker Compose
├── supermarket.backup      # Backup de la base de datos
└── README.md              # Documentación del proyecto

🚀 Instalação e Configuração

1. Iniciar os Contêineres

docker-compose up -d

Este comando iniciará dois serviços:

PostgreSQL (porta 5432):

• Usuário: admin
• Senha: admin
• Banco de dados: admin_db

pgAdmin (porta 8080):

• Email: admin@admin.com
• Senha: admin
• URL: http://localhost:8080

2. Verificar se os Contêineres estão em Execução

docker-compose ps

Você deverá ver dois contêineres em execução:

• postgres_db (PostgreSQL)
• pgadmin_web (pgAdmin)

🔗 Conexão ao pgAdmin

O pgAdmin está incluído como parte do stack Docker e é executado automaticamente. Você não precisa instalá-lo separadamente.

Acesso ao pgAdmin Web

1. Abrir navegador e acessar: http://localhost:8080

2. Fazer login com as credenciais:

   • Email: admin@admin.com
   • Senha: admin

Configurar Conexão ao Servidor PostgreSQL

Uma vez dentro do pgAdmin:

1. Adicionar novo servidor:

   • Clique direito em "Servers" → "Register" → "Server..."

2. Configurar aba "General":

   • Name: Supermercado DB (ou qualquer nome descritivo)

3. Configurar aba "Connection":

   • Host name/address: postgres (nome do serviço no Docker)
   • Port: 5432
   • Username: admin
   • Password: admin

4. Salvar a conexão:

   • Marcar "Save password" (recomendado)
   • Clicar em "Save"

✅ Verificar a Conexão

Uma vez configurado corretamente, você deverá ver:

• O servidor "Supermercado DB" no painel esquerdo
• O banco de dados admin_db expansível
• Possibilidade de explorar esquemas e tabelas

🚀 Acesso Rápido ao Query Tool

Para executar consultas SQL:

1. Expandir o servidor conectado
2. Expandir Databases → admin_db
3. Clicar com botão direito em admin_db → "Query Tool"
4. Pronto para executar comandos SQL!

🔧 Solução de Problemas do pgAdmin

Se você não conseguir acessar o pgAdmin:

• Verificar se ambos os contêineres estão em execução: docker-compose ps
• Verificar se a porta 8080 não está ocupada
• Revisar logs: docker-compose logs pgadmin

Se você não conseguir se conectar ao servidor PostgreSQL a partir do pgAdmin:

• Usar postgres como host (não localhost nem 127.0.0.1)
• Verificar se as credenciais estão exatamente: admin / admin
• Revisar logs do PostgreSQL: docker-compose logs postgres

🔄 Restauração do Banco de Dados

Passo 1: Criar o Papel (Role) PostgreSQL (CRÍTICO)

⚠️ IMPORTANTE: Antes de restaurar o backup, execute este comando SQL:

CREATE ROLE postgres;

Formas de executar este comando:

• pgAdmin → Query Tool
• Cliente de linha de comando SQL
• Qualquer cliente PostgreSQL (DBeaver, DataGrip, etc.)

Passo 2: Restaurar o Backup no pgAdmin

1. Abrir pgAdmin e conectar-se ao servidor PostgreSQL
2. Clicar com botão direito no banco de dados de destino
3. Selecionar "Restore..."
4. Configurar a restauração:
   • Format: Custom or tar
   • Filename: Selecionar supermarket.backup
   • Options: Marcar as opções necessárias
5. Executar a restauração

Passo 3: Verificar a Restauração

Execute uma consulta de teste para confirmar que os dados foram restaurados corretamente:

SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public';

🔌 Integração com Claude Desktop (MCP)

A integração com Model Context Protocol (MCP) permite que o Claude Desktop interaja diretamente com o banco de dados para análises e consultas inteligentes.

Configuração Passo a Passo

1. Verificar se o Banco de Dados está Ativo

docker-compose up -d
docker-compose ps

2. Configurar o Claude Desktop

Edite o arquivo de configuração do Claude Desktop no seu sistema:

📍 Localizações do arquivo de configuração:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuração a adicionar:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://admin:admin@localhost:5432/admin_db"
      ]
    }
  }
}

3. Reiniciar o Claude Desktop

Feche completamente o Claude Desktop e abra-o novamente para que a configuração tenha efeito.

✅ Verificação da Integração

Uma vez configurado corretamente, o Claude Desktop poderá:

• 🔍 Analisar o esquema do banco de dados automaticamente
• 📊 Executar consultas SQL em tempo real
• 💡 Gerar insights sobre os dados do supermercado
• 🔗 Responder perguntas sobre estrutura e conteúdo das tabelas

📝 Notas Importantes sobre MCP

• A URL de conexão deve corresponder exatamente à sua configuração de docker-compose.yml
• Se você modificar as credenciais do banco de dados, atualize também a configuração MCP
• O servidor MCP é baixado automaticamente na primeira execução
• Certifique-se de que não há conflitos de portas (5432 deve estar livre)

🛠️ Solução de Problemas

Erros Comuns na Restauração

Problema	Causa	Solução
role "postgres" does not exist	Não foi executado CREATE ROLE postgres;	Executar o comando SQL antes do restore
Conexão recusada	Docker não está em execução	Verificar com docker-compose ps
Permissões insuficientes	Usuário sem privilégios	Conectar-se como administrador

Comandos de Diagnóstico

Verificar papel (role) postgres:

SELECT * FROM pg_roles WHERE rolname = 'postgres';

Verificar conexão ao banco de dados:

docker-compose exec postgres psql -U admin -d admin_db -c "\l"

Ver logs do contêiner:

docker-compose logs postgres

Problemas de Integração MCP

Claude Desktop não detecta o banco de dados:

1. Verificar se o arquivo de configuração está na localização correta
2. Validar a sintaxe JSON do arquivo de configuração
3. Verificar se o banco de dados está acessível a partir de localhost:5432
4. Reiniciar completamente o Claude Desktop

Erro de conexão MCP:

1. Verificar se as credenciais na URL correspondem ao docker-compose.yml
2. Verificar se não há firewall bloqueando a porta 5432
3. Tentar a conexão manual com psql ou pgAdmin

---

Desenvolvido com ❤️ para o curso de Banco de Dados