Aller au contenu

S3 et httpfs ​

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 :

ChampValeur par défautRemarques
Endpoints3.amazonaws.comhttp:// est respecté ; sinon HTTPS est utilisé
Regionus-east-1Envoyé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.

Limites ​

  • 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ômeCause probable
La navigation échoue juste après la configurationRé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 httpfsPas de réseau, ou un proxy qui bloque le téléchargement de l'extension
Les identifiants semblent oubliésUne 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à.

Publié sous licence Apache-2.0.