# S3 e httpfs

> Consulte o Amazon S3 e armazenamento compatível com S3 a partir do DuckLocal com o httpfs do DuckDB: configure credenciais, navegue por buckets e execute SQL em arquivos remotos.

Source: https://ducklocal.app/docs/pt/s3

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:

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

## 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:

```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](data-sources.md#supported-file-formats).

## Limitações {#limitations}

- **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

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