Apresentamos o Hardcharger™: o servidor do DuckDB 2.0, construído sobre o protocolo aberto Warp SQL

O Hardcharger™ é o novo servidor de código aberto da GizmoData para o DuckDB 2.0. Ele coloca o DuckDB na rede para todas as pessoas e aplicações que precisam dele e fala Warp SQL, um protocolo aberto que escrevemos para levar SQL por HTTP comum e devolver Apache Arrow. Em uma única máquina AWS Graviton5, ele executou 22 consultas derivadas do TPC-H sobre 1 TB em 42,4 segundos, cerca de 9 centavos de dólar de computação. Todos os recursos estão incluídos: controle de acesso com políticas de linha e mascaramento, login único (SSO), TLS mútuo, um log de auditoria, instrumentação e uma interface web integrada. Não há edições nem chaves de licença, e ele é de código aberto sob a licença Apache-2.0.

O Hardcharger é o sucessor do GizmoSQL, escrito do zero para o DuckDB 2.0. Este artigo explica por que criamos um produto novo em vez de um GizmoSQL 2.0, o que o Warp SQL muda, qual é a velocidade dele (com as ressalvas) e como colocá-lo para rodar em cerca de um minuto.

Por que um produto novo

O GizmoSQL transformou o DuckDB, uma biblioteca que roda dentro do processo, em um servidor: sessões simultâneas, autenticação, TLS e um endpoint Arrow Flight SQL que JDBC, ADBC, ferramentas de BI e assistentes de IA conseguiam acessar. Clientes o usam em produção, em suas próprias máquinas e no GizmoData Cloud. Operá-lo junto com eles nos ensinou três coisas.

• O transporte era o ponto de atrito. O Arrow Flight SQL roda sobre gRPC. Isso significa HTTP/2 de ponta a ponta, proxies e balanceadores de carga compatíveis com gRPC, código gerado em todos os clientes e nenhum cliente simples para navegador. Na nossa própria nuvem, cada recarga de um proxy compartilhado enviava um GOAWAY às conexões gRPC de longa duração, e as chamadas seguintes delas falhavam.
• A segurança pertence ao núcleo. O Flight SQL deixa o login, as sessões e a posse dos handles a cargo de cada servidor, então cada servidor precisa acertar tudo isso sozinho. Queríamos essas regras no protocolo, onde nenhum servidor pode esquecer uma delas.
• Recursos não deveriam ficar bloqueados. O controle de acesso, a instrumentação e o SSO do GizmoSQL eram recursos Enterprise que exigiam uma chave de licença. Toda equipe que opera um DuckDB compartilhado precisa deles.

O DuckDB 2.0 foi o momento de corrigir as três coisas de uma vez. O Hardcharger é um servidor independente sobre a API C v2 do DuckDB 2.0; não é uma extensão do DuckDB nem uma adaptação do código do GizmoSQL. Ele adotou a bateria de testes do GizmoSQL como critério de aceitação, não a estrutura dele. O GizmoSQL mantém seu nome e seu protocolo Flight SQL e continua recebendo manutenção por cerca de seis meses; o Hardcharger usa apenas nomes próprios (variáveis HARDCHARGER_*, funções hardcharger_*), para que os dois nunca se confundam na mesma máquina.

Warp SQL: SQL por HTTP, resultados em Arrow

Mantivemos a melhor parte do Flight SQL, o formato colunar Apache Arrow na transmissão, e substituímos o resto. O Warp SQL é um protocolo aberto (Apache-2.0) para executar SQL sobre HTTP/1.1 e TLS comuns. Resultados, parâmetros de consulta e cargas em massa são streams Arrow IPC; as mensagens de controle são pequenos documentos JSON. A versão 1.0 é definitiva: daqui em diante, o protocolo só muda por acréscimos.

• Consultas curtas levam uma única ida e volta. Um POST executa uma instrução e transmite as linhas de volta na mesma resposta.
• Consultas longas sobrevivem a redes reais. Envie, receba um handle, consulte o status e busque o resultado depois. Um download interrompido continua a partir do lote em que parou, e nenhuma requisição precisa durar mais que o tempo limite de um proxy.
• Resultados grandes e cargas grandes se dividem. Um cliente pode ler um resultado grande como várias partições, por conexões separadas ao mesmo tempo, e enviar uma carga em massa como várias partes confirmadas em uma única transação: tudo ou nada.
• Funciona com o que você já usa. Qualquer proxy reverso, balanceador de carga ou API gateway que deixa passar HTTP deixa passar Warp SQL. O mesmo vale para o curl e para o fetch de um navegador.
• É descrito e testado. O protocolo tem uma descrição OpenAPI 3.1, que o Hardcharger serve em /warp/v1/openapi.json, e uma suíte de conformidade caixa-preta com 282 testes diz a qualquer implementação se ela segue a especificação.

Esta é uma consulta completa, sem nenhum driver:

TOKEN=$(curl -s localhost:31337/warp/v1/auth/token -H 'Content-Type: application/json' \
  -d '{"grant_type": "password", "username": "hardcharger", "password": "change-me"}' | jq -r .access_token)
SESSION=$(curl -s localhost:31337/warp/v1/sessions -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{}' | jq -r .session_id)
curl -s localhost:31337/warp/v1/sessions/$SESSION/statements -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/vnd.apache.arrow.stream' \
  -d '{"sql": "SELECT 42 AS answer"}' > result.arrows
python -c "import pyarrow.ipc as ipc; print(ipc.open_stream(source='result.arrows').read_all())"

Os resultados são descritos como partições, cada uma com uma localização. Hoje, um servidor divide um resultado grande em partições nele mesmo; amanhã, um mecanismo distribuído poderá apontar essas partições para outras máquinas sem mudar o protocolo. O Warp SQL tem uma página própria em gizmodata.com/warp-sql, e sua especificação está no GitHub.

Segurança no protocolo, não acrescentada depois

O Warp SQL faz do comportamento seguro o único comportamento possível, então um servidor construído sobre ele não consegue pular uma verificação.

• Tokens bearer, nunca cookies. Um navegador nunca envia uma credencial Warp SQL por conta própria, então não há falsificação de requisições entre sites (CSRF) contra a qual se defender.
• Todo handle pertence ao seu dono. Sessões, instruções, resultados e uploads pertencem à identidade que os criou e são verificados a cada uso. Adivinhar o handle de outro usuário não dá acesso a nada.
• Login único na porta principal. O login pelo navegador com seu provedor OpenID Connect roda na própria porta e no próprio certificado do servidor. O servidor é o cliente confidencial do provedor: o segredo do cliente fica no servidor, PKCE e um nonce protegem a troca, e cada login é coletado uma única vez, com um segredo que nunca aparece em uma URL.
• Certificados como identidade. Com TLS mútuo, um cliente pode fazer login apenas com seu certificado. Os tokens de um login por certificado ficam vinculados a esse certificado (RFC 8705), então um token copiado não serve para nada sem a chave privada, e as listas de revogação são verificadas para cada certificado da cadeia.

Dentro do servidor, o controle de acesso é verificado dentro do DuckDB contra o próprio plano de cada instrução, depois do binding e de novo antes da otimização, então SQL aninhado, views e macros não conseguem contornar uma permissão. Tudo o que a verificação não consegue classificar é recusado. Arquivos de credenciais e de sistema no host (chaves SSH, credenciais de nuvem, a própria chave TLS do servidor) são recusados na camada de sistema de arquivos do DuckDB, seja quem for que peça, inclusive o administrador.

1 TB, as 22 consultas derivadas do TPC-H, em 42,4 segundos

Executamos uma carga de trabalho derivada do TPC-H, as 22 consultas dele sobre 1 TB de dados (fator de escala 1000), em uma AWS r9gd.24xlarge: Graviton5, 96 vCPUs, 742 GiB de memória e três discos NVMe locais em RAID 0, sob demanda a US$ 7,69 por hora. Cada consulta rodou três vezes; o resultado é a soma das médias das 22 consultas. Comparamos o Hardcharger com a referência anterior do GizmoSQL 1.42.0 usando DuckDB 1.5.6, no mesmo tipo de máquina.

• 42,4 segundos para as 22 consultas sobre 1 TB, o que custa US$ 0,090 de computação pelo preço sob demanda.
• 1,8× mais rápido que a referência anterior do GizmoSQL 1.42.0 com DuckDB 1.5.6 (77,0 s).

Médias de consultas selecionadas, com a referência DuckDB 1.5.x anterior para contexto:

O que considerar ao ler esses números:

• O Hardcharger usa DuckDB 2.0.0; a referência histórica do GizmoSQL usa DuckDB 1.5.6. A diferença de desempenho inclui as mudanças no mecanismo e não isola o efeito do protocolo do servidor.
• O cliente Hardcharger rodou na mesma máquina, por TLS para 127.0.0.1. As respostas dessas consultas têm poucas linhas cada, então a rede acrescenta pouco.
• As primeiras execuções, a frio, estão incluídas. Descartamos o cache de páginas e reiniciamos o Hardcharger antes de cada rodada. O resultado DuckDB 1.5.6 é uma referência histórica anterior.
• Somente configurações padrão: 96 threads, o limite de memória padrão do DuckDB, nada ajustado. Uma segunda rodada completa ficou a até 2% da primeira, e todas as consultas Hardcharger retornaram as contagens de linhas esperadas.

Concorrência: 3× as consultas por segundo, sem erros

Na fase de concorrência do ClickBench, o Hardcharger atingiu 3× as consultas por segundo da entrada publicada do GizmoSQL no ClickBench (0,350 contra 0,117 QPS) sem nenhum erro, na mesma classe de máquina (c6a.4xlarge); na entrada do GizmoSQL, 90% das consultas concorrentes falharam. Execução preliminar do Hardcharger 2.0.0-rc.1 (20 de outubro de 2026), aguardando a execução na versão GA.

É ao mover dados que o Warp SQL se destaca

As respostas dessas consultas são pequenas, então elas medem principalmente o mecanismo. Buscar e carregar resultados grandes mede o servidor e o protocolo. Entre duas máquinas AWS c8gn.8xlarge, com TLS nos dois servidores e a mediana de cinco execuções:

Todo resultado passa por um pipeline assíncrono: o DuckDB continua produzindo lotes Arrow de 122.880 linhas enquanto os lotes anteriores são comprimidos (lz4_frame ou zstd quando o cliente pede, em um pool de threads, pulando buffers que não encolheriam) e criptografados, e um resultado grande pode ser lido por várias conexões ao mesmo tempo. O método e os resultados completos estão no documento de benchmarks.

Todos os recursos incluídos, sem chaves de licença

Tudo o que era Enterprise no GizmoSQL está em todas as builds do Hardcharger, e cada recurso é ativado por sua própria opção:

• Controle de acesso baseado em papéis: usuários, papéis, permissões até o nível de coluna, posse de objetos e privilégios de sistema, gerenciados em SQL (CREATE ROLE, GRANT, REVOKE). Uma revogação também alcança as sessões abertas, e as mudanças chegam a todas as réplicas em cerca de um segundo. O repositório de permissões é o PostgreSQL em produção, ou um arquivo DuckDB para desenvolvimento e servidores únicos.
• Políticas de linha, tenants e mascaramento de colunas, regras de acesso por catálogo e Open Policy Agent, além de funções de tabela que respondem "quem pode fazer o quê" para cada usuário.
• Login do seu jeito: senhas, tokens, SSO via OIDC/JWKS, login pelo navegador, filtros de e-mails autorizados, TLS e TLS mútuo.
• Um log de auditoria que evidencia adulterações.
• Observabilidade: instrumentação de sessões e instruções em um arquivo DuckDB ou no PostgreSQL (o gravador acompanha cerca de 20.000 instruções por segundo no PostgreSQL), log de catálogo, perfis de consulta, um endpoint Prometheus /metrics e hardcharger_active_connections() para ver o que está rodando agora.
• Controle: fila de instruções, tempos limite, KILL SESSION, hardcharger_cancel() e desligamento controlado.
• DuckDB 2.0 com DuckLake e as extensões do DuckDB.
• Configurado do seu jeito: flags, variáveis de ambiente HARDCHARGER_* ou um arquivo YAML.
• Onde quer que você rode: Linux (x86-64 e arm64), macOS em Apple silicon e Windows (x64 e arm64, com MSIs), com as builds para macOS e Windows assinadas digitalmente; imagens Docker multiarquitetura; e um pacote Python que executa o servidor para você.
• Drivers: ADBC para Go, Python, C/C++, R e Rust; JDBC para Java e ferramentas de BI como o DBeaver; e um cliente JavaScript para Node, navegadores, Deno, Bun e Cloudflare Workers. Veja as integrações.

Uma interface web dentro do binário

O Hardcharger tem uma interface web compilada dentro do servidor: nada extra para instalar, servida na própria porta e no próprio certificado do servidor. Ela vem desativada; --web-ui a ativa.

• Editor SQL com até 20 abas, cada uma com sua própria sessão, transação e configurações. Execute a instrução sob o cursor, a seleção ou o script inteiro, com uma aba de resultado para cada conjunto de resultados. Uma transação aberta aparece como um selo com Commit e Rollback.
• Grade de resultados para até um milhão de linhas: ordene, filtre, redimensione, selecione como em uma planilha e copie para o Excel ou o Google Sheets como células, inclusive no Safari.
• Navegador de esquemas e preenchimento automático que seguem o controle de acesso: cada usuário vê apenas os catálogos, esquemas, tabelas e colunas que seus papéis permitem.
• Downloads em CSV, TSV, JSON ou Excel, ou do resultado inteiro, com os tipos, em Parquet ou Arrow; consultas salvas em pastas; e Run as com um dos seus papéis.
• Uma página de Sessions e uma página de API: a própria API Warp SQL do servidor no Swagger UI, onde Try it out executa as requisições neste servidor, com o seu login.
• Login com senha, com seu provedor de identidade ou com seu certificado de cliente.

Comece em um minuto

No macOS (Apple silicon) ou no Linux, instale o servidor e o cliente de linha de comando hardcharger com uma linha e depois inicie o servidor com a interface web ativada:

curl https://install.hardcharger.gizmodata.com | sh
HARDCHARGER_ADMIN_PASSWORD='change-me' ~/.hardcharger/bin/hardcharger-server --database my.duckdb --web-ui
# open http://localhost:31337/ui and sign in as hardcharger / change-me

Ou execute a imagem multiarquitetura (linux/amd64, linux/arm64), do registro do GitHub ou do Docker Hub:

docker run --rm -p 31337:31337 -p 31338:31338 \
  -e HARDCHARGER_ADMIN_PASSWORD='change-me' -e HARDCHARGER_WEB_UI=true \
  ghcr.io/gizmodata/hardcharger:latest

Ou inicie um servidor pelo Python, em um teste, notebook ou script. O pacote hardcharger baixa o servidor para a sua plataforma, verifica-o e o executa; o extra [adbc] acrescenta o cliente:

pip install "hardcharger[adbc]"

1import hardcharger
2
3with hardcharger.Server(password="change-me") as server, server.connect() as conn, conn.cursor() as cur:
4    print(server.uri)  # hardcharger://127.0.0.1:<port>?tls=false
5    cur.execute(operation="SELECT 42 AS answer")
6    print(cur.fetch_arrow_table())

Conecte-se

O cliente hardcharger é um shell interativo com histórico, preenchimento automático e destaque de sintaxe, e também executa scripts. Com um servidor local sem TLS, use --tls=false:

export HARDCHARGER_PASSWORD='change-me'
hardcharger --host localhost --tls=false --username hardcharger --quiet <<'SQL'
CREATE OR REPLACE TABLE trips AS SELECT * FROM (VALUES (1, 'Boston', 12.5), (2, 'Denver', 30.0)) t(id, city, miles);
SELECT city, miles FROM trips ORDER BY miles DESC;
SQL

OK, 2 rows affected
┌─────────┬──────────────┐
│  city   │    miles     │
│ varchar │ decimal(3,1) │
├─────────┼──────────────┤
│ Denver  │         30.0 │
│ Boston  │         12.5 │
├─────────┴──────────────┤
│ 2 rows  2 columns      │
└────────────────────────┘

Pelo Python, com o driver ADBC (pip install adbc-driver-hardcharger), incluindo parâmetros vinculados:

1from adbc_driver_hardcharger import dbapi as hardcharger
2
3with hardcharger.connect(uri="hardcharger://localhost?tls=false", username="hardcharger", password="change-me") as conn:
4    with conn.cursor() as cur:
5        cur.execute(operation="SELECT city, miles FROM trips WHERE miles > ?", parameters=[20])
6        print(cur.fetch_arrow_table())

Pelo Java, com o driver JDBC, um único jar para Java 17 ou posterior, sem gRPC, Netty nem protobuf:

Properties properties = new Properties();
properties.setProperty("user", "hardcharger");
properties.setProperty("password", "change-me");
properties.setProperty("useEncryption", "false"); // plain HTTP on localhost
try (Connection connection = DriverManager.getConnection("jdbc:hardcharger://localhost", properties);
     ResultSet rows = connection.createStatement().executeQuery("SELECT city, miles FROM trips ORDER BY id")) {
  while (rows.next()) {
    System.out.println(rows.getString("city") + " " + rows.getBigDecimal("miles"));
  }
}

A página de instalação cobre o Windows, os binários das versões e o pacote Python, e a documentação cobre todas as opções.

Vindo do GizmoSQL

Seu SQL é o do DuckDB nos dois (consulte as notas de versão do DuckDB para saber o que mudou entre o 1.x e o 2.0), e cada opção mantém seu significado; o que muda é o protocolo (Warp SQL em vez de Flight SQL, então use os drivers do Hardcharger) e os nomes. O guia de migração relaciona cada flag, variável de ambiente, função SQL, configuração, catálogo e métrica do GizmoSQL ao seu nome no Hardcharger, e também as opções do cliente.

O GizmoSQL 1.x não vai desaparecer de uma hora para outra: vamos continuar dando manutenção a ele por cerca de seis meses, para que você migre no seu ritmo. Se você é cliente do GizmoSQL, fale conosco e ajudaremos a planejar a migração.

A melhor forma de executá-lo: GizmoData Cloud

O Hardcharger está chegando ao GizmoData Cloud, nosso serviço totalmente gerenciado na AWS, no Google Cloud e no Azure. Você escolhe uma região e um tamanho; nós operamos os clusters, os certificados, os balanceadores de carga e os catálogos DuckLake, e você recebe um servidor ao qual pode se conectar com todos os drivers acima.

O que vem a seguir

• Números com o DuckDB 2.0.0. O mesmo benchmark, com todos os servidores na mesma versão 2.0.0 do DuckDB.
• Upload de dados pela interface web (em breve): CSV, TSV, Excel, Parquet, JSON ou Arrow para uma tabela nova ou existente, lidos no navegador e enviados pela ingestão em massa do Warp SQL em uma única transação.
• Hardcharger para iPhone e iPad (em breve): o servidor rodando dentro do app, com sua interface web e um console SQL nativo, além de servidores remotos com login único.
• Consultas distribuídas (em breve): o Warp SQL já descreve cada resultado como partições com localizações, então uma consulta poderá ser distribuída entre várias máquinas sem mudar o protocolo.

Código aberto, Apache-2.0

O Hardcharger, o Warp SQL, sua suíte de conformidade e os drivers são de código aberto sob a Apache License 2.0. Dê uma estrela no repositório no GitHub, leia a página do produto e venha dizer olá no Slack da comunidade GizmoData. Mal podemos esperar para ver o que você vai construir com ele.

Hardcharger™ e GizmoData™ são marcas comerciais da GizmoData LLC. DuckDB é uma marca comercial da DuckDB Foundation. Apache Arrow é uma marca comercial da Apache Software Foundation. TPC-H™ é uma marca comercial do Transaction Processing Performance Council (TPC).