# S3 et httpfs

> Interrogez Amazon S3 et le stockage compatible depuis DuckLocal avec httpfs : identifiants, parcours des buckets et SQL sur des fichiers distants.

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

DuckLocal peut lire des objets dans S3 et dans un stockage compatible S3 grâce à
l'extension `httpfs` de DuckDB. Configurez-la depuis le bouton **S3** de la barre
de titre.

## Configurer les identifiants

La boîte de dialogue a quatre champs :

| Champ | Valeur par défaut | Remarques |
| --- | --- | --- |
| Endpoint | `s3.amazonaws.com` | `http://` est respecté ; sinon HTTPS est utilisé |
| Region | `us-east-1` | Envoyée telle quelle |
| Access Key ID | — | Obligatoire |
| Secret Access Key | — | Obligatoire, masquée, avec un bouton pour l'afficher |

Confirmer exécute l'équivalent de :

```sql
INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE SECRET ducklocal_s3 (
  TYPE s3, PROVIDER config,
  KEY_ID '…', SECRET '…',
  REGION '…', ENDPOINT '…'
);
```

**Les identifiants ne durent que le temps de la session.** Ils ne sont pas
écrits sur le disque et sont effacés quand vous ouvrez ou changez de base de
données, vous devez donc les reconfigurer ensuite. Il n'existe pas d'autre moyen
de les effacer que de les reconfigurer.

## Parcourir

Une fois configuré, une racine **S3** apparaît dans la barre latérale. Son
contenu ne se charge qu'à son dépliage : la racine liste les buckets, et chaque
bucket ou préfixe liste ses objets. Les buckets et préfixes sont triés, et les
objets affichent une taille lisible. Utilisez le bouton d'actualisation pour
recharger un niveau ou réessayer après une erreur.

Le listage est plafonné à **1 000 entrées par niveau**, même quand la réponse en
annonce davantage. Il n'y a pas de pagination plus profonde, pas de zone de
filtre par préfixe et pas de recherche — un bucket qui contient plus de mille
objets à un niveau paraîtra complet alors qu'il ne l'est pas.

## Interroger des objets

Cliquer sur un objet dont la clé a une extension de fichier de données remplit
l'éditeur actif avec :

```sql
SELECT *
FROM 's3://bucket/key'
LIMIT 100;
```

C'est une requête ordinaire : la lecture passe par `httpfs`, le comportement de
`read_parquet` / `read_csv_auto` de DuckDB s'applique donc, y compris le
pushdown — les filtres et la sélection de colonnes sont poussés dans la lecture
du fichier. La requête remplace le contenu de l'onglet actif.

Seules les clés reconnues comme fichiers de données sont cliquables. Les
extensions reconnues sont les mêmes que pour les fichiers locaux ; voir
[Sources de données](data-sources.md#supported-file-formats).

## Limites {#limitations}

- **La navigation est en lecture seule.** Le navigateur S3 n'offre aucune action
  d'envoi, de téléchargement vers un fichier, de suppression, de copie ou de
  création de bucket. Les requêtes, elles, téléchargent bien les données
  distantes.
- **Pas de jetons de session.** L'en-tête `X-Amz-Security-Token` n'est jamais
  envoyé, les identifiants temporaires STS ne fonctionnent donc pas — utilisez
  des clés de longue durée, ou un endpoint qui accepte la clé et le secret
  seuls.
- **Le style d'endpoint est presque toujours automatique.** Une URL S3 peut
  désigner un bucket de deux façons : adressage virtuel par nom d'hôte ou style
  chemin. L'adressage virtuel est utilisé quand l'hôte contient `amazonaws.com`,
  le style chemin sinon. Pour une passerelle auto-hébergée, c'est en général ce
  que vous voulez ; pour celle qui a besoin de l'autre style, aucun forçage
  n'est possible.
- Une région erronée est retentée une fois, avec la région que DuckDB renvoie.
  Si cela échoue aussi, l'erreur est affichée telle quelle.
- Le réseau est nécessaire : `INSTALL httpfs` récupère l'extension au premier
  usage. La navigation envoie des requêtes HTTP ou HTTPS à l'endpoint configuré
  (`http://` sélectionne HTTP ; sinon HTTPS est utilisé). Ces requêtes
  transportent des métadonnées comme les noms de buckets et les préfixes de
  clés, ainsi que des informations d'authentification dans des en-têtes signés ;
  la navigation n'envoie ni fichiers de base de données locaux ni résultats de
  requête. Les requêtes sur des objets distants téléchargent les données sur
  votre machine via `httpfs`.

## Dépannage

| Symptôme | Cause probable |
| --- | --- |
| La navigation échoue juste après la configuration | Région ou endpoint erroné ; vérifiez le message affiché dans la barre latérale |
| Erreurs sur un endpoint auto-hébergé | Style d'adressage erroné, ou endpoint qui exige un jeton de session |
| Erreur d'installation de `httpfs` | Pas de réseau, ou un proxy qui bloque le téléchargement de l'extension |
| Les identifiants semblent oubliés | Une base de données a été ouverte ou changée, ce qui les efface par conception |

Quand DuckLocal est empaqueté comme application signée, le chargement de
l'extension `httpfs` exige l'habilitation
`com.apple.security.cs.disable-library-validation` ; le script d'empaquetage
livré l'inclut déjà.
