queryapigate

QueryAPIGate é um serviço Flask único e auto-hospedado que executa SQL nos seus bancos de dados e retorna resultados em JSON, NDJSON, XML, YAML, CSV, TSV ou Excel. Salve uma consulta uma vez e ela se torna um endpoint REST versionado com parâmetros tipados e seguros contra injeção e histórico de execuções, sem escrever controllers, camadas de repositório, paginação, autenticação ou código repetitivo de serialização. O suporte a múltiplos bancos de dados inclui drivers nativos para MySQL, PostgreSQL, ClickHouse, SQLite, H2 e DuckDB, além de JDBC genérico para qualquer coisa com um driver jar (Oracle, SQL Server, DB2, Snowflake, etc.). O mesmo guard de SQL, pooling, binding de parâmetros e formatos de saída se aplicam independentemente do banco de dados subjacente. Recursos de segurança e controle de acesso: - Autenticação por chave de API com armazenamento de chave com hash SHA-256. - Senhas de conexão de banco de dados criptografadas em repouso via QUERYAPIGATE_SECRET_KEY, descriptografadas apenas em memória quando uma conexão é aberta. - Chaves de API com escopo: restrinja uma chave a conexões específicas e/ou a uma lista de permissões de consultas salvas; o acesso de escrita fica desativado a menos que seja explicitamente habilitado. - Coleções: agrupe consultas salvas e conceda a uma chave um grupo inteiro; mover uma consulta mostra uma prévia de quais chaves ganham ou perdem acesso. - Funções de permissão nomeadas: modelos reutilizáveis copiados para uma chave na criação. - Expiração de chave de API, revogação, limitação de taxa por chave e lista de permissões de IP (intervalos CIDR). - Guard de SQL permitindo apenas instruções únicas SELECT/WITH/SHOW/DESCRIBE/EXPLAIN por padrão, com parâmetros :name vinculados. Consultas salvas são versionadas — salvar com o mesmo nome cria uma nova versão em vez de sobrescrever, e ?version=1 ainda executa a anterior. Parâmetros podem declarar tipo, padrão, obrigatório/opcional, enum, intervalo numérico, comprimento e padrão; entrada inválida é rejeitada com um 400 campo a campo antes de chegar ao banco de dados. Formatos de resposta (JSON, NDJSON, XML, YAML, CSV, TSV, XLSX) são selecionáveis por requisição via ?format=. A paginação usa ?page e ?page_size com um cabeçalho X-Has-More. Para exportações completas, ?stream=true transmite todo o resultado do cursor do banco de dados em vez de armazenar em buffer — verificado com resultados de 1.000.000 de linhas e memória do servidor estável no MySQL, PostgreSQL e ClickHouse. Um comando de CLI (queryapigate export) envolve o mesmo caminho de streaming para uso em cron/systemd/Kubernetes CronJob. O cache de consultas suporta cache_ttl, Cache-Control, ETag, requisições condicionais, 304 Not Modified e um cabeçalho X-Cache HIT/MISS; nunca aplicado a escritas. A limitação de taxa combina um limite global do servidor baseado em IP com um limite opcional independente por chave. A observabilidade inclui logs JSON estruturados marcados com IDs de requisição, tempo de execução por consulta, avisos de consultas lentas e métricas Prometheus em /metrics cobrindo contagens de requisições/consultas, latências, ocupação do pool de conexões e rejeições por limite de taxa. Um dashboard Grafana incluído está disponível para métricas históricas. OpenAPI 3.0 é gerado em /openapi.json (validado em CI contra o validador oficial) com cada consulta salva como um endpoint tipado; /docs serve a Swagger UI, filtrada para o que cada chave pode acessar. A interface de administração integrada em /ui cobre gerenciamento de conexões, um editor SQL com destaque de sintaxe e navegação de esquema, execução/pré-visualização de consultas, EXPLAIN, gerenciamento de consultas salvas e versões, gerenciamento de chaves de API, um log de auditoria de alterações administrativas, histórico de execução por consulta, inspeção de respostas com árvores JSON recolhíveis, gráficos de barras rápidos para resultados numéricos e "copiar como curl"/"copiar como TSV" com um clique. Uma tela de Configurações somente leitura mostra cada variável de ambiente e seu valor efetivo, com segredos relatados apenas como configurados ou não. A instalação é via pip com extras opcionais de driver (mysql, postgres, clickhouse, h2, duckdb, all, encryption). SQLite e DuckDB não precisam de runtime externo; H2 e JDBC genérico exigem um runtime Java. Docker também é suportado. O comando `queryapigate examples load` instala quatro cenários de exemplo funcionais (API de relatórios, dados de dashboard, exportação em streaming, integração com parceiros) como coleções, consultas, funções e chaves de API prontas para uso. Os testes incluem testes unitários, testes de integração contra servidores reais MySQL, PostgreSQL, ClickHouse e H2 em CI, testes de integração DuckDB, fuzz testing do guard de SQL com Hypothesis, verificação estática de tipos com mypy, linting com ruff e CI em cada push. O projeto é licenciado sob FSL-1.1-MIT e requer Python 3.9+.