Legacy-Authentifizierungsschema für die S3-API

Vor Version 0.10.0 hatte DuckDB keinen Secrets-Manager. Deshalb wurden Konfiguration und Authentifizierung gegenüber S3-Endpunkten über Variablen gesteuert. Diese Seite dokumentiert das Legacy-Authentifizierungsschema für die S3-API.

Warning Diese Seite beschreibt eine veraltete Methode, Secrets als DuckDB-Einstellungen zu speichern. Das erhöht das Risiko, Secrets versehentlich preiszugeben (z. B. durch Ausgabe ihrer Werte). Verwenden Sie diese Methoden daher nicht zum Speichern von Secrets. Der empfohlene Weg zur Konfiguration und Authentifizierung von S3-Endpunkten ist die Verwendung von Secrets.

Legacy-Authentifizierungsschema

Um von S3 lesen oder nach S3 schreiben zu können, muss die richtige Region gesetzt sein:

SET s3_region = 'us-east-1';

Optional kann der Endpunkt konfiguriert werden, falls ein Objektspeicher-Server außerhalb von AWS verwendet wird:

SET s3_endpoint = '⟨domain⟩.⟨tld⟩:⟨port⟩';

Wenn der Endpunkt kein SSL verwendet, führen Sie aus:

SET s3_use_ssl = false;

Der Wechsel zwischen Path-Style- und Vhost-Style-URLs ist möglich mit:

SET s3_url_style = 'path';

Beachten Sie jedoch, dass dazu auch der Endpunkt aktualisiert werden muss. Für AWS S3 ist es beispielsweise erforderlich, den Endpunkt auf s3.⟨region⟩.amazonaws.com{:.language-sql .highlight} zu ändern.

Nach der Konfiguration von Endpunkt und Region können öffentliche Dateien gelesen werden. Um auch private Dateien zu lesen, können Authentifizierungsdaten hinterlegt werden:

SET s3_access_key_id = '⟨aws_access_key_id⟩';
SET s3_secret_access_key = '⟨aws_secret_access_key⟩';

Alternativ werden auch temporäre S3-Anmeldedaten unterstützt. Dazu muss zusätzlich ein Session-Token gesetzt werden:

SET s3_session_token = '⟨aws_session_token⟩';

Die aws-Erweiterung ermöglicht das Laden von AWS-Anmeldedaten.

Konfiguration pro Anfrage

Neben der oben beschriebenen globalen S3-Konfiguration können bestimmte Werte pro Anfrage gesetzt werden. So lassen sich mehrere Sätze von Anmeldedaten, Regionen usw. verwenden. Dazu werden sie als Query-Parameter an die S3-URI angehängt. Alle oben aufgeführten einzelnen Konfigurationswerte können als Query-Parameter gesetzt werden. Zum Beispiel:

SELECT *
FROM 's3://bucket/file.parquet?s3_access_key_id=accessKey&s3_secret_access_key=secretKey';

Mehrere Konfigurationen pro Abfrage sind ebenfalls möglich:

SELECT *
FROM 's3://bucket/file.parquet?s3_access_key_id=accessKey1&s3_secret_access_key=secretKey1' t1
INNER JOIN 's3://bucket/file.csv?s3_access_key_id=accessKey2&s3_secret_access_key=secretKey2' t2;

Konfiguration

Für den S3-Upload gibt es einige zusätzliche Konfigurationsoptionen, die Standardwerte sollten jedoch für die meisten Anwendungsfälle ausreichen.

Zusätzlich können die meisten Konfigurationsoptionen über Umgebungsvariablen gesetzt werden:

DuckDB-Einstellung	Umgebungsvariable	Hinweis
s3_region	AWS_REGION	Hat Vorrang vor AWS_DEFAULT_REGION
s3_region	AWS_DEFAULT_REGION
s3_access_key_id	AWS_ACCESS_KEY_ID
s3_secret_access_key	AWS_SECRET_ACCESS_KEY
s3_session_token	AWS_SESSION_TOKEN
s3_endpoint	DUCKDB_S3_ENDPOINT
s3_use_ssl	DUCKDB_S3_USE_SSL
s3_requester_pays	DUCKDB_S3_REQUESTER_PAYS