Sign inSign up

flaviomagacho/aitosql

By flaviomagacho

Updated 11 months ago

MCP para acesso a dados de banco sql

Image
0

593

flaviomagacho/aitosql repository overview

🐳 Docker Hub Repository Overview

flaviomagacho/aitosql


📋 Informações Gerais

CampoValor
Nome da Imagemflaviomagacho/aitosql
Status AtualAGUARDANDO PRIMEIRA PUBLICAÇÃO
Repositório GitHubmagacho/aiToSql
URL Docker Hubhttps://hub.docker.com/r/flaviomagacho/aitosql
Visibilidade🌍 Pública
Multi-Arquitetura✅ Sim (amd64, arm64)

📦 Tags Disponíveis

Após a primeira release bem-sucedida, as seguintes tags estarão disponíveis:

TagDescriçãoUso Recomendado
latestÚltima versão estável publicada⚠️ Desenvolvimento
0.3.0Versão específica 0.3.0✅ Produção
v0.3.0Versão específica com prefixo 'v'✅ Produção
0.2.0Versão anterior 0.2.0📦 Histórico
v0.2.0Versão anterior com prefixo 'v'📦 Histórico
🎯 Estratégia de Tags
REL-0.3.0 (Git Tag)
    ↓
Gera 3 tags Docker:
    ├─ flaviomagacho/aitosql:latest
    ├─ flaviomagacho/aitosql:0.3.0
    └─ flaviomagacho/aitosql:v0.3.0

🏗️ Arquiteturas Suportadas

ArquiteturaStatusPlataforma
linux/amd64Intel/AMD 64-bit
linux/arm64Apple Silicon, ARM servers
💻 Base Image
  • OS: Ubuntu 22.04 (Jammy)
  • Java: OpenJDK 21
  • Runtime: Spring Boot 3.4.0

🚀 Como Usar

1️⃣ Pull Básico
# Última versão
docker pull flaviomagacho/aitosql:latest

# Versão específica (recomendado para produção)
docker pull flaviomagacho/aitosql:0.3.0
2️⃣ Execução Rápida (Detecção Automática de Driver)
# O driver JDBC é detectado automaticamente da URL!
docker run -d \
  --name aitosql \
  -e DB_URL="jdbc:postgresql://localhost:5432/mydb" \
  -e DB_USERNAME="readonly_user" \
  -e DB_PASSWORD="secure_password" \
  -p 8080:8080 \
  flaviomagacho/aitosql:0.3.0

🎯 Novo! Não é necessário especificar DB_TYPE - o driver é detectado automaticamente da URL JDBC.

3️⃣ Usando Docker Compose
PostgreSQL
version: '3.8'
services:
  aitosql:
    image: flaviomagacho/aitosql:0.3.0
    environment:
      DB_URL: jdbc:postgresql://postgres:5432/mydb
      DB_USERNAME: readonly_user
      DB_PASSWORD: secure_password
      # DB_TYPE não é mais necessário - detectado automaticamente!
    ports:
      - "8080:8080"
    depends_on:
      - postgres
  
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: admin123
    ports:
      - "5432:5432"
MySQL
version: '3.8'
services:
  aitosql:
    image: flaviomagacho/aitosql:0.3.0
    environment:
      DB_URL: jdbc:mysql://mysql:3306/mydb
      DB_USERNAME: readonly_user
      DB_PASSWORD: secure_password
      # DB_TYPE não é mais necessário - detectado automaticamente!
    ports:
      - "8080:8080"
    depends_on:
      - mysql
  
  mysql:
    image: mysql:8
    environment:
      MYSQL_DATABASE: mydb
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_USER: readonly_user
      MYSQL_PASSWORD: secure_password
    ports:
      - "3306:3306"

🔧 Variáveis de Ambiente

VariávelObrigatóriaDescriçãoExemplo
DB_URLJDBC connection URLjdbc:postgresql://host:5432/db
DB_USERNAMEDatabase username (READ-ONLY)readonly_user
DB_PASSWORDDatabase passwordsecure_password
DB_TYPEDatabase type (auto-detectado)postgresql, mysql, oracle, sqlserver
SERVER_PORTPorta do servidor (padrão: 8080)8080
SPRING_PROFILES_ACTIVESpring profilesprod
🎯 Detecção Automática de Driver JDBC

Novidade na v0.3.0+: O driver JDBC é automaticamente detectado da URL!

Bancos Suportados:
  • PostgreSQL: jdbc:postgresql://...org.postgresql.Driver
  • MySQL: jdbc:mysql://...com.mysql.cj.jdbc.Driver
  • SQL Server: jdbc:sqlserver://...com.microsoft.sqlserver.jdbc.SQLServerDriver
  • Oracle: jdbc:oracle:...oracle.jdbc.OracleDriver
Como Funciona:
# ❌ ANTES: Era necessário especificar o driver
docker run -e DB_URL="..." -e DB_TYPE="postgresql" ...

# ✅ AGORA: Driver detectado automaticamente
docker run -e DB_URL="jdbc:postgresql://..." ...

💡 Dica: Você ainda pode usar DB_TYPE se preferir ser explícito, mas não é mais obrigatório!

Para mais detalhes, veja: JDBC Driver Auto-Detection

⚠️ Segurança
  • SEMPRE use um usuário com permissões READ-ONLY (SELECT apenas)
  • Evite expor credenciais no código ou logs
  • Use secrets management em produção (Kubernetes secrets, AWS Secrets Manager, etc.)

📊 Endpoints da API

1️⃣ Health Check
GET http://localhost:8080/actuator/health
2️⃣ Schema Introspection
GET http://localhost:8080/api/mcp/model-context

Retorna a estrutura completa do banco de dados.

3️⃣ Execute Query
POST http://localhost:8080/api/mcp/execute-search
Content-Type: application/json

{
  "sql": "SELECT * FROM users LIMIT 10"
}
4️⃣ Table Details
GET http://localhost:8080/api/mcp/table-details?tableName=users
5️⃣ List Triggers
GET http://localhost:8080/api/mcp/triggers?tableName=orders

📈 Estatísticas e Métricas

Tamanho da Imagem (Estimado)
Camadas:
├─ Ubuntu Jammy base: ~30MB
├─ OpenJDK 21: ~200MB
├─ Application JAR: ~50MB
└─ Total comprimido: ~150MB
Performance
  • Startup time: ~5-10 segundos
  • Memory footprint: ~256MB-512MB (ajustável via JVM options)
  • CPU: Mínimo 0.5 cores

🔄 Pipeline de Publicação

Workflow Automatizado
graph LR
    A[Git Tag REL-X.X.X] --> B[GitHub Actions]
    B --> C[Run Tests]
    C --> D[Generate Coverage Report]
    D --> E[Build Docker Multi-Arch]
    E --> F[Push to Docker Hub]
    F --> G[Create GitHub Release]
    G --> H[Update README]
Gatilhos (Triggers)
  • Build: A cada commit no main
  • Publish: Apenas em tags REL-X.X.X

📜 Histórico de Versões

VersãoDataStatusNotas
0.3.02025-10-29🔄 Em ProgressoMulti-arch support (arm64)
0.2.02025-10-28⏳ AguardandoDocker containerization
0.1.02025-10-28⏳ AguardandoInitial release

🐛 Troubleshooting

Problema: Container não inicia
# Verificar logs
docker logs aitosql

# Verificar conectividade com banco
docker exec -it aitosql curl -s http://localhost:8080/actuator/health
Problema: Erro de conexão com banco
  • ✅ Verifique se DB_URL está correto
  • ✅ Confirme que o banco está acessível do container
  • ✅ Use host.docker.internal para acessar localhost do host
Problema: Permissão negada
  • ✅ Verifique se o usuário tem permissões SELECT
  • ✅ Confirme que o firewall permite conexões

🔐 Secrets Necessárias (GitHub Actions)

Para publicar no Docker Hub, configure as seguintes secrets:

# Listar secrets
gh secret list

# Criar secrets
gh secret set DOCKERHUB_USERNAME --body "magacho"
gh secret set DOCKERHUB_TOKEN --body "seu-token-aqui"
Como Obter Token do Docker Hub
  1. Acesse https://hub.docker.com/settings/security
  2. New Access Token
  3. Nome: github-actions-aitosql
  4. Permissões: Read, Write, Delete
  5. Copie o token e configure no GitHub

🎯 Roadmap de Publicação

✅ Fase 1: Preparação (Concluída)
  • Dockerfile otimizado
  • Multi-arquitetura (amd64, arm64)
  • Workflow GitHub Actions
  • Docker Compose examples
🔄 Fase 2: Primeira Publicação (Em Progresso)
  • Configurar secrets Docker Hub
  • Criar tag REL-0.3.0
  • Validar publicação
  • Testar pull e execução
📋 Fase 3: Documentação
  • README no Docker Hub
  • Exemplos de uso
  • Badges de status


📞 Suporte


📄 Licença

Este projeto é open source. Veja o arquivo LICENSE no repositório para mais detalhes.


Última Atualização: 2025-10-29 Mantido por: Flavio Magacho (@magacho)

Tag summary

Content type

Image

Digest

sha256:39690e54d

Size

140 MB

Last updated

11 months ago

docker pull flaviomagacho/aitosql