Ir para o conteúdo

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:

CampoPadrãoObservações
Endpoints3.amazonaws.comhttp:// é respeitado; caso contrário, usa-se HTTPS
Regiãous-east-1Enviada como digitada
Access Key ID—Obrigatório
Secret Access Key—Obrigatório, mascarado, com um botão para revelar

Confirmar executa o equivalente a:

sql
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.

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:

sql
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-Token nunca é 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 httpfs busca 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 do httpfs.

Solução de problemas ​

SintomaCausa provável
A navegação falha logo depois de configurarRegião ou endpoint errados; confira a mensagem mostrada na barra lateral
Erros em um endpoint auto-hospedadoEstilo de endereçamento errado, ou um endpoint que exige um token de sessão
Erro de instalação do httpfsSem rede, ou um proxy que bloqueia o download da extensão
As credenciais parecem esquecidasUm 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.

Publicado sob a licença Apache-2.0.