S3 e httpfs
O DuckLocal consegue ler objetos do S3 e de armazenamento compatível com S3 por meio da extensão httpfs do DuckDB. Configure-a pelo botão S3 na barra de título.
Configure as credenciais
A caixa de diálogo tem quatro campos:
| Campo | Padrão | Observações |
|---|---|---|
| Endpoint | s3.amazonaws.com | http:// é respeitado; caso contrário, usa-se HTTPS |
| Região | us-east-1 | Enviada como digitada |
| Access Key ID | — | Obrigatório |
| Secret Access Key | — | Obrigatório, mascarado, com um botão para revelar |
Confirmar executa o equivalente a:
INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE SECRET ducklocal_s3 (
TYPE s3, PROVIDER config,
KEY_ID '…', SECRET '…',
REGION '…', ENDPOINT '…'
);As credenciais duram apenas a sessão. Elas não são gravadas em disco e são apagadas quando você abre ou troca de banco de dados, então você precisa configurá-las de novo depois. Não há outra forma de apagá-las além de configurar de novo.
Navegue
Uma vez configurado, uma raiz S3 aparece na barra lateral. Seu conteúdo carrega apenas quando é expandido: a raiz lista os buckets, e cada bucket ou prefixo lista seus objetos. Buckets e prefixos são ordenados, e os objetos mostram um tamanho legível. Use o botão de atualizar para recarregar um nível ou tentar de novo depois de um erro.
A listagem é limitada a 1.000 entradas por nível, mesmo quando a resposta diz que há mais disponíveis. Não há paginação mais profunda, nem caixa de filtro por prefixo, nem busca — um bucket com mais de mil objetos em um nível vai parecer completo quando não está.
Consulte objetos
Clicar em um objeto cuja chave tem uma extensão de arquivo de dados preenche o editor ativo com:
SELECT *
FROM 's3://bucket/key'
LIMIT 100;Isso é uma consulta comum: a leitura passa pelo httpfs, então o comportamento de read_parquet / read_csv_auto do DuckDB se aplica, incluindo o pushdown — os filtros e a seleção de colunas são empurrados para a leitura do arquivo. A consulta substitui o que a aba ativa tinha.
Apenas chaves reconhecidas como arquivos de dados são clicáveis. As extensões reconhecidas são as mesmas dos arquivos locais; veja Fontes de dados.
Limitações
- A navegação é somente leitura. O navegador não tem ação de upload, download para arquivo, exclusão, cópia ou criação de bucket. As consultas ainda baixam dados remotos.
- Sem tokens de sessão. O cabeçalho
X-Amz-Security-Tokennunca é enviado, então credenciais temporárias STS não vão funcionar — use chaves de longa duração, ou um endpoint que aceite apenas chave e segredo. - O estilo de endpoint é quase sempre automático. URLs de S3 podem endereçar um bucket de duas formas: endereçamento virtual-hosted ou estilo de caminho. O endereçamento virtual-hosted é usado quando o host contém
amazonaws.com, e o estilo de caminho caso contrário. Para gateways auto-hospedados isso geralmente é o que você quer; para um que precise do outro estilo, não há como forçar. - Uma região errada é tentada de novo uma vez, usando a região que o DuckDB informa de volta. Se isso também falhar, o erro é mostrado como está.
- É preciso rede:
INSTALL httpfsbusca a extensão no primeiro uso. A navegação envia requisições HTTP ou HTTPS para o endpoint configurado (http://seleciona HTTP; caso contrário, usa-se HTTPS). Essas requisições enviam metadados como nomes de bucket e prefixos de chave, além de informações de autenticação em cabeçalhos assinados; a navegação não envia arquivos de banco de dados locais nem resultados de consulta. Consultas sobre objetos remotos baixam dados para a sua máquina por meio dohttpfs.
Solução de problemas
| Sintoma | Causa provável |
|---|---|
| A navegação falha logo depois de configurar | Região ou endpoint errados; confira a mensagem mostrada na barra lateral |
| Erros em um endpoint auto-hospedado | Estilo de endereçamento errado, ou um endpoint que exige um token de sessão |
Erro de instalação do httpfs | Sem rede, ou um proxy que bloqueia o download da extensão |
| As credenciais parecem esquecidas | Um banco de dados foi aberto ou trocado, o que as apaga por design |
Quando o DuckLocal é empacotado como um app assinado, carregar a extensão httpfs precisa do entitlement com.apple.security.cs.disable-library-validation; o script de empacotamento distribuído já o inclui.
