S3 e httpfs
DuckLocal può leggere oggetti da S3 e da storage compatibili con S3 tramite l'estensione httpfs di DuckDB. Configurala dal pulsante S3 nella barra del titolo.
Configura le credenziali
La finestra di dialogo ha quattro campi:
| Campo | Predefinito | Note |
|---|---|---|
| Endpoint | s3.amazonaws.com | http:// viene rispettato; altrimenti si usa HTTPS |
| Region | us-east-1 | Inviata così come è scritta |
| Access Key ID | — | Obbligatorio |
| Secret Access Key | — | Obbligatoria, mascherata, con un interruttore per mostrarla |
Confermando viene eseguito l'equivalente di:
INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE SECRET ducklocal_s3 (
TYPE s3, PROVIDER config,
KEY_ID '…', SECRET '…',
REGION '…', ENDPOINT '…'
);Le credenziali valgono solo per la sessione. Non vengono scritte su disco e vengono cancellate quando apri o cambi database, quindi dopo devi riconfigurarle. Non c'è un altro modo per cancellarle se non riconfigurarle.
Sfoglia
Una volta configurato, nella barra laterale compare una radice S3. I suoi contenuti si caricano solo quando la espandi: la radice elenca i bucket, e ogni bucket o prefisso elenca i suoi oggetti. Bucket e prefissi sono ordinati, e gli oggetti mostrano una dimensione leggibile. Usa il pulsante di aggiornamento per ricaricare un livello o riprovare dopo un errore.
L'elenco si ferma a 1.000 voci per livello, anche quando la risposta dichiara che ce ne sono altre. Non c'è paginazione più profonda, né campo di filtro per prefisso, né ricerca — un bucket con più di mille oggetti allo stesso livello apparirà completo anche quando non lo è.
Interroga gli oggetti
Facendo clic su un oggetto la cui chiave ha l'estensione di un file di dati, l'editor attivo si riempie con:
SELECT *
FROM 's3://bucket/key'
LIMIT 100;È una query normale: la lettura passa da httpfs, quindi vale il comportamento di read_parquet / read_csv_auto di DuckDB, compreso il pushdown — filtri e selezione delle colonne vengono spinti nella lettura del file. La query sostituisce quello che conteneva la scheda attiva.
Solo le chiavi riconosciute come file di dati sono cliccabili. Le estensioni riconosciute sono le stesse dei file locali; vedi Sorgenti di dati.
Limiti
- La navigazione è in sola lettura. Il browser S3 non offre azioni di caricamento, download su file, eliminazione, copia o creazione di bucket. Le query scaricano comunque i dati remoti.
- Nessun token di sessione. L'intestazione
X-Amz-Security-Tokennon viene mai inviata, quindi le credenziali temporanee STS non funzionano — usa chiavi di lunga durata, oppure un endpoint che accetta solo chiave e secret. - Lo stile dell'endpoint è quasi sempre automatico. Gli URL S3 possono indirizzare un bucket in due modi: indirizzamento virtual-hosted o path style. L'indirizzamento virtual-hosted viene usato quando l'host contiene
amazonaws.com, altrimenti si usa il path style. Per i gateway self-hosted di solito è quello che vuoi; per uno che richiede l'altro stile non c'è modo di imporlo. - Una region sbagliata viene ritentata una volta, usando la region che DuckDB riporta. Se anche quel tentativo fallisce, l'errore viene mostrato così com'è.
- La rete è necessaria:
INSTALL httpfsscarica l'estensione al primo uso. La navigazione invia richieste HTTP o HTTPS all'endpoint configurato (http://seleziona HTTP; altrimenti si usa HTTPS). Queste richieste inviano metadati come nomi di bucket e prefissi di chiavi, più informazioni di autenticazione in intestazioni firmate; la navigazione non carica file di database locali né risultati di query. Le query sugli oggetti remoti scaricano i dati sulla tua macchina tramitehttpfs.
Risoluzione dei problemi
| Sintomo | Causa probabile |
|---|---|
| La navigazione fallisce subito dopo la configurazione | Region o endpoint sbagliati; controlla il messaggio mostrato nella barra laterale |
| Errori su un endpoint self-hosted | Stile di indirizzamento sbagliato, o un endpoint che richiede un token di sessione |
Errore di installazione di httpfs | Nessuna rete, o un proxy che blocca il download dell'estensione |
| Le credenziali sembrano dimenticate | È stato aperto o cambiato un database, che per scelta le cancella |
Quando DuckLocal è pacchettizzato come app firmata, caricare l'estensione httpfs richiede l'entitlement com.apple.security.cs.disable-library-validation; lo script di packaging distribuito lo include già.
