Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rckbrcls/world-cup-project

SQL-first FIFA World Cup database project with PostgreSQL rules, lifecycle tools, and an operational browsing client.
https://github.com/rckbrcls/world-cup-project

database-course fastapi football natural-language-query nextjs ollama postgresql react sql typescript world-cup

Last synced: 30 days ago
JSON representation

SQL-first FIFA World Cup database project with PostgreSQL rules, lifecycle tools, and an operational browsing client.

Awesome Lists containing this project

README 

          
# Projeto de Banco de Dados da Copa do Mundo



Projeto acadêmico de banco de dados para SCC0640, baseado em

`docs/brief/BD-Projeto-2026.pdf`.



O projeto modela um sistema de gerenciamento de Copas do Mundo FIFA em

PostgreSQL e fornece um protótipo Python de linha de comando para as

demonstrações exigidas.



## Escopo



- Modelo relacional PostgreSQL para edições da Copa do Mundo, seleções, grupos,

  partidas, elencos, árbitros, estádios, eventos e classificações.

- Regras de negócio orientadas por SQL por meio de chaves, restrições, funções,

  visões e gatilhos.

- Script SQL direto para popular o conjunto de dados de demonstração.

- Protótipo terminal em Python que lê parâmetros de login do banco, executa os

  10 relatórios obrigatórios, solicita ao Ollama local a conversão de linguagem

  natural para SQL, mostra feedback de planejamento por etapas, mostra o SQL

  gerado antes da execução e trata erros do PostgreSQL.



## Arquivos Principais



- `docs/brief/BD-Projeto-2026.pdf`: enunciado original da disciplina.

- `sql/ddl.sql`: esquema, restrições, índices, funções de validação, gatilhos e

  funções de relatório obrigatórias.

- `sql/dml.sql`: ponto de entrada do conjunto de dados de demonstração.

- `src/terminal/presentation/`: comandos Typer e renderização terminal com

  Rich.

- `src/terminal/application/`: catálogo de consultas, planejamento da

  Consulta Natural e orquestração dos casos de uso do terminal.

- `src/terminal/domain/`: contratos de relatório usados pelo fluxo de consultas

  obrigatórias.

- `src/terminal/infrastructure/`: adaptadores de PostgreSQL, configurações,

  repositório e Ollama.

- `docker/Dockerfile`: imagem de contêiner para o protótipo.

- `compose.yaml`: orquestração principal de PostgreSQL, Ollama e protótipo.

- `submission/`: arquivos da entrega final da disciplina.



## Requisitos Mínimos



Para os caminhos com Docker Compose:



- Docker Engine ou Docker Desktop com Docker Compose v2.

- Conexão com a internet na primeira execução, porque a imagem do app e o

  modelo do Ollama podem ser baixados.

- Terminal interativo com suporte a stdin/TTY, pois o protótipo solicita dados

  de conexão pelo teclado.

- Pelo menos 15 GB livres em disco para imagens, volumes do PostgreSQL/Ollama e

  modelo local.

- 8 GB de memória RAM como mínimo prático; 16 GB são recomendados para o

  Ollama rodar com mais folga.



Antes de executar, escolha uma das duas opções abaixo. A opção 1 é a mais

simples para avaliadores que querem tudo isolado no Docker. A opção 2 é a

recomendada para macOS com Apple Silicon, porque o Ollama nativo pode usar a

aceleração Apple/Metal, enquanto o Ollama dentro do Docker Desktop para macOS

pode ficar limitado à CPU.



## Opção 1 - Docker completo



Use esta opção quando quiser PostgreSQL, Ollama e protótipo inteiramente no

Docker Compose. Ela é indicada para Linux/Windows com aceleração de GPU

disponível para containers, ou para máquinas em que a execução CPU-only seja

aceitável. No Docker Desktop para macOS, o Ollama dentro do container pode rodar

sem GPU/Metal e ficar bem mais lento.



1. Instale e abra o Docker Desktop ou Docker Engine com Docker Compose v2.

2. Confirme que o Docker responde:



```bash

docker compose version

```



3. Execute o protótipo completo:



```bash

docker compose run --rm app

```



Esse comando inicia PostgreSQL, aplica `sql/ddl.sql` e `sql/dml.sql` no primeiro

volume do banco, inicia o Ollama em container, baixa `gemma4:e2b` quando

necessário e abre o protótipo terminal. O download do modelo acontece apenas

quando o volume `ollama-data` ainda não possui o modelo. O Compose já fixa

banco, usuário, senha, endereço interno do Ollama e modelo; não é necessário

criar arquivo de configuração nem exportar variáveis antes de rodar.



Quando o terminal solicitar conexão com o banco, pressione Enter para aceitar os

valores padrão do Docker:



```text

servidor=db

porta=5432

banco=copa_mundo

usuario=copa_mundo

senha=copa_mundo

```



## Opção 2 - macOS com Ollama local



Use esta opção em Macs com Apple Silicon. O PostgreSQL e o protótipo continuam

no Docker Compose, mas o Ollama roda nativo no macOS para poder usar a

aceleração Apple/Metal.



1. Instale o Ollama para macOS pelo site oficial: .

2. Abra o aplicativo Ollama. Na primeira abertura, permita que ele instale o

   comando `ollama` no terminal se o macOS solicitar essa confirmação.

3. Abra um novo terminal e confirme que a CLI foi instalada:



```bash

ollama --version

```



Se o comando não existir, feche e abra novamente o app Ollama e aceite a criação

do atalho da CLI. Pela instalação padrão, o app cria um link para o comando em

`/usr/local/bin`.



4. Baixe o modelo padrão:



```bash

ollama pull gemma4:e2b

```



5. Confirme que o servidor local do Ollama responde:



```bash

curl http://localhost:11434/api/tags

```



A resposta deve ser um JSON com a lista de modelos instalados. Verifique se

`gemma4:e2b` aparece nessa lista.



6. Faça um teste curto de geração antes de abrir o protótipo:



```bash

curl http://localhost:11434/api/generate \

  -d '{"model":"gemma4:e2b","prompt":"Responda apenas OK.","stream":false}'

```



Esse teste também carrega o modelo na memória, então pode demorar na primeira

execução. Se quiser confirmar o processador usado pelo Ollama, rode:



```bash

ollama ps

```



Na coluna `PROCESSOR`, o Ollama indica se o modelo está em CPU, GPU ou uma

mistura de CPU/GPU.



7. Execute o protótipo com o serviço que aponta para o Ollama do macOS:



```bash

docker compose run --rm app-local-ollama

```



Esse serviço sobe o PostgreSQL e o app, mas não sobe o container `ollama`. O app

usa `OLLAMA_BASE_URL=http://host.docker.internal:11434` para acessar o Ollama

nativo do macOS. No prompt de conexão do banco, pressione Enter para aceitar os

mesmos padrões do Docker: servidor `db`, porta `5432`, banco `copa_mundo`,

usuário `copa_mundo` e senha `copa_mundo`.



Depois da conexão, o protótipo oferece:



- estado do banco;

- os 10 relatórios SQL obrigatórios;

- conversa da Consulta Natural por meio do Ollama local, com feedback de

  planejamento por etapas;

- execução SQL controlada, com SQL visível e tratamento de erros.



Durante desenvolvimento, uma imagem Docker antiga pode continuar executando uma

versão anterior do código. Depois de alterar arquivos em `src/`, reconstrua a

imagem do serviço usado antes de testar novamente pelo Docker Compose.



Se aparecer uma falha de autenticação por senha mesmo aceitando esses padrões,

o volume `postgres-data` provavelmente já foi inicializado antes com outra

senha. A imagem oficial do PostgreSQL só aplica a senha inicial na primeira

criação do volume; em um banco já existente, informe a senha original no prompt

ou recrie o volume apenas quando quiser descartar os dados locais.



Na opção Docker completo, PostgreSQL e Ollama ficam internos ao Compose. Na

opção macOS, somente o Ollama nativo precisa estar acessível na máquina local.



Referências operacionais:



- Ollama para macOS: 

- FAQ do Ollama sobre GPU no Docker: 

- GPU no Docker Desktop: 



## Execução Manual de Desenvolvimento



Use este caminho apenas se não quiser usar Docker Compose. Crie um banco

PostgreSQL local com banco, usuário e senha `copa_mundo`, então aplique os

arquivos SQL nesta ordem:



```bash

psql "postgresql://copa_mundo:copa_mundo@localhost:5432/copa_mundo" -f sql/ddl.sql

psql "postgresql://copa_mundo:copa_mundo@localhost:5432/copa_mundo" -f sql/dml.sql

```



Instale as dependências Python e garanta que o modelo esteja disponível no

Ollama local:



```bash

uv sync

ollama pull gemma4:e2b

```



Execute o protótipo terminal manualmente com:



```bash

uv run terminal

```



Quando o protótipo solicitar a conexão local, use:



```text

servidor=localhost

porta=5432

banco=copa_mundo

usuario=copa_mundo

senha=copa_mundo

```



A conversa da Consulta Natural também pode ser aberta diretamente:



```bash

uv run terminal consulta-natural conversa

```



Dentro da conversa, `executar` executa apenas a proposta SQL validada mais

recente, e `sair` retorna ao menu.



## Pacote Final



O diretório de entrega da disciplina é `submission/` e deve manter estes oito

arquivos:



- `01.ER.pdf`

- `02.ER.xml`

- `03.Relacional.pdf`

- `04.Relacional.xml`

- `05.DDL.sql`

- `06.DML.sql`

- `07.Prototipo.zip`

- `08.Instrucoes.txt`



Se os XMLs draw.io forem alterados, abra-os no diagrams.net/draw.io e exporte

novamente os PDFs correspondentes antes da entrega oficial.