Esta página foi traduzida do inglês com assistência de IA. Se houver diferenças entre as duas, a versão em inglês é a referência.
Arquitetura
Veja também: [ Usar o StackQL ] [ Usar variáveis ] [ Uso de templates ]
Visão geral
O StackQL é uma interface SQL unificada para consultar e gerenciar infraestrutura na nuvem em vários providers. O diagrama de contêineres a seguir ilustra os principais componentes do sistema StackQL e suas interações.
Componentes principais
Pontos de entrada
O StackQL oferece vários pontos de entrada para executar consultas SQL:
-
CLI / Shell: um shell interativo e uma interface de linha de comando para executar consultas SQL diretamente no terminal. Os usuários podem executar consultas ad hoc e scripts ou usar o shell interativo para explorar.
-
Protocolo de comunicação do PostgreSQL: permite conexões de clientes PostgreSQL padrão, como
psql, DBeaver ou qualquer outra ferramenta compatível com o PostgreSQL. Isso permite uma integração transparente com os workflows de banco de dados e as ferramentas de BI existentes. -
Servidor MCP: um servidor Model Context Protocol que permite a integração com assistentes de IA, para que grandes modelos de linguagem consultem e gerenciem a infraestrutura por meio de linguagem natural.
Pipeline de processamento de consultas
-
Analisador sintático SQL: analisa a entrada SQL e a converte em uma árvore de sintaxe abstrata (AST) com uma gramática personalizada baseada em Yacc. O analisador sintático (implementado como
stackql-parser) valida a sintaxe SQL e a prepara para o planejamento da consulta. -
Mecanismo de consulta: a camada central de orquestração, que planeja e executa as consultas. Ele determina quais operações podem ser delegadas à camada de API e quais exigem processamento SQL local. O mecanismo de consulta cuida de:
- Planejamento e otimização de consultas
- Coordenação entre chamadas de API e execução SQL local
- Agregação e transformação de resultados
SDK de providers (omnisdk)
O SDK de providers, omnisdk, gerencia todas as interações com os provedores de nuvem. Ele substituiu o any-sdk no StackQL v1.0. As principais responsabilidades incluem:
-
Descoberta de providers: busca as especificações dos providers no StackQL Registry, que contém definições baseadas em OpenAPI para cada provedor de nuvem compatível, e, opcionalmente, verifica a assinatura ML-DSA-65 de cada documento antes de usá-lo.
-
Autenticação: cuida da autenticação de cada provider, com suporte a vários métodos de autenticação, incluindo chaves de API, tokens OAuth, credenciais de conta de serviço e outros. Cada definição de provider especifica seus requisitos de autenticação; uma sessão pode vincular o mesmo provider a vários aliases, cada um com credenciais próprias (consulte Sessões de provider).
-
Planejamento em grafo: planeja cada instrução como um grafo de trocas com os providers, ligadas por arestas de dados e de controle. Joins, subconsultas, CTEs e views passam pelo mesmo planejador, e as solicitações que um plano distribui em fan-out são executadas simultaneamente, dentro de limites por provider e por host.
-
Construção de solicitações de API: transforma consultas SQL nas chamadas de API REST adequadas para cada provider, cuidando da construção de endpoints, do mapeamento de parâmetros e da formatação das solicitações.
-
Paginação: trata automaticamente as respostas paginadas das APIs e abstrai a complexidade dos diferentes esquemas de paginação usados pelos diversos providers (baseados em cursor, em offset, em token etc.).
-
Pushdown de predicados: envia as condições que correspondem a parâmetros de solicitação, e o
LIMITquando nenhuma ordenação é necessária, nas solicitações ao provider, para reduzir o número de solicitações feitas e o volume de dados transferidos. -
Transformação de respostas: converte as respostas das APIs em linhas à medida que elas chegam, para staging no backend SQL ou streaming para o cliente.
As conexões SQL, o staging e a execução no backend permanecem no StackQL. O omnisdk não contém nenhum staging SQL e nunca recebe uma conexão de banco de dados; o StackQL passa a ele handles de relações e recebe cursores de linhas.
Backend SQL
O backend SQL executa operações relacionais sobre os dados de API materializados:
-
SQLite: um banco de dados incorporado usado para armazenamento temporário de tabelas e processamento relacional. Ideal para consultas ad hoc e conjuntos de dados menores.
-
PostgreSQL: um banco de dados externo opcional para armazenamento persistente, conjuntos de dados maiores e cargas de trabalho de análise avançada.
O backend SQL cuida de operações como:
- Operações JOIN entre vários providers ou recursos
- Funções de agregação (COUNT, SUM, AVG etc.)
- Ordenação e filtragem de dados materializados
- Expressões SQL complexas e subconsultas
Sistemas externos
Provedores de nuvem
O StackQL se conecta aos provedores de nuvem (AWS, GCP, Azure, Kubernetes, GitHub e muitos outros) por meio das APIs REST deles. Toda a comunicação é feita por HTTPS, e o SDK de providers cuida das particularidades das convenções de API de cada provedor.
StackQL Registry
O StackQL Registry hospeda as definições de providers - especificações baseadas em OpenAPI que descrevem os recursos e métodos disponíveis e seus mapeamentos. Os providers são versionados e podem ser baixados sob demanda com o comando REGISTRY PULL.
Fluxo de execução de consultas
- O usuário envia uma consulta SQL por um dos pontos de entrada (CLI, protocolo PostgreSQL ou MCP)
- O analisador sintático SQL valida a consulta e a converte em uma AST
- O mecanismo de consulta analisa a AST e cria um plano de execução
- Para as operações de provider, o SDK de providers:
- Busca a especificação do provider correspondente no Registry (se ela não estiver em cache)
- Faz a autenticação no provedor de nuvem
- Cria e executa as solicitações de API, tratando a paginação automaticamente
- Envia os predicados para a API sempre que possível
- Materializa os resultados no backend SQL
- O backend SQL executa as operações relacionais restantes
- Os resultados são retornados ao usuário no formato solicitado