Secrets Manager

Der Secrets Manager bietet eine einheitliche Benutzeroberfläche für Secrets über alle Backends, die sie verwenden. Secrets können beschränkt (scoped) werden, sodass unterschiedliche Speicherpräfixe unterschiedliche Secrets haben können – so lassen sich beispielsweise Daten verschiedener Organisationen in einer einzigen Abfrage verbinden. Secrets können auch persistiert werden, sodass sie nicht bei jedem Start von DuckDB erneut angegeben werden müssen.

Warning Persistente Secrets werden unverschlüsselt im Binärformat auf der Festplatte gespeichert.

Arten von Secrets

Secrets sind typisiert; ihr Typ gibt an, für welchen Dienst sie gedacht sind. Die meisten Secrets sind nicht standardmäßig in DuckDB enthalten, sondern werden von Erweiterungen registriert. Derzeit sind die folgenden Secret-Typen verfügbar:

Secret-Typ	Dienst / Protokoll	Erweiterung
azure	Azure Blob Storage	azure
ducklake	DuckLake	ducklake
gcs	Google Cloud Storage	httpfs
http	HTTP and HTTPS	httpfs
huggingface	Hugging Face	httpfs
iceberg	Iceberg REST Catalog	httpfs, iceberg
mysql	MySQL	mysql
postgres	PostgreSQL	postgres
quack	Quack	quack
r2	Cloudflare R2	httpfs
s3	AWS S3	httpfs
aws	AWS	[aws](% link docs/current/core_extensions/aws.md %})

Für jeden Typ gibt es einen oder mehrere „Secret Provider“, die angeben, wie das Secret erzeugt wird. Secrets können außerdem einen optionalen Scope haben: ein Dateipfad-Präfix, auf das das Secret zutrifft. Beim Abrufen eines Secrets für einen Pfad werden die Secret-Scopes mit dem Pfad verglichen und das passende Secret zurückgegeben. Bei mehreren passenden Secrets wird das mit dem längsten Präfix gewählt.

Ein Secret erstellen

Secrets können mit der SQL-Anweisung CREATE SECRET erstellt werden. Secrets können temporär oder persistent sein. Standardmäßig werden temporäre Secrets verwendet – sie werden im Speicher für die Lebensdauer der DuckDB-Instanz gehalten, ähnlich wie Einstellungen zuvor funktionierten. Persistente Secrets werden unverschlüsselt im Binärformat im Verzeichnis ~/.duckdb/stored_secrets gespeichert. Beim Start von DuckDB werden persistente Secrets aus diesem Verzeichnis gelesen und automatisch geladen.

Secret Provider

Um ein Secret zu erstellen, muss ein Secret Provider verwendet werden. Ein Secret Provider ist ein Mechanismus, über den ein Secret erzeugt wird. Zur Veranschaulichung unterstützt DuckDB für die Secret-Typen S3, GCS, R2 und AZURE derzeit zwei Provider: CONFIG und credential_chain. Der Provider CONFIG verlangt, dass der Benutzer alle Konfigurationsinformationen in CREATE SECRET übergibt, während der Provider credential_chain automatisch versucht, Anmeldedaten zu holen. Wird kein Secret Provider angegeben, wird der Provider CONFIG verwendet. Weitere Details zum Erstellen von Secrets mit unterschiedlichen Providern finden Sie auf den jeweiligen Seiten zu httpfs und azure.

Temporäre Secrets

Um ein temporäres, unbeschränktes Secret für den Zugriff auf S3 zu erstellen, können wir nun Folgendes verwenden:

CREATE SECRET my_secret (
    TYPE s3,
    KEY_ID 'my_secret_key',
    SECRET 'my_secret_value',
    REGION 'my_region'
);

Beachten Sie, dass wir hier implizit den Standard-Secret-Provider CONFIG verwenden.

Persistente Secrets

Um Secrets zwischen DuckDB-Datenbankinstanzen zu persistieren, können wir nun den Befehl CREATE PERSISTENT SECRET verwenden, z. B.:

CREATE PERSISTENT SECRET my_persistent_secret (
    TYPE s3,
    KEY_ID 'my_secret_key',
    SECRET 'my_secret_value'
);

Standardmäßig schreibt dies das Secret (unverschlüsselt) in das Verzeichnis ~/.duckdb/stored_secrets. Um das Secrets-Verzeichnis zu ändern, führen Sie aus:

SET secret_directory = 'path/to/my_secrets_dir';

Die Einstellung secret_directory gilt für die aktuelle DuckDB-Instanz und wird nicht über DuckDB-Instanzen hinweg persistiert. Wenn Sie ein eigenes Secrets-Verzeichnis verwenden, setzen Sie secret_directory beim Start einer neuen DuckDB-Instanz erneut, bevor Sie persistente Secrets aus diesem Verzeichnis erstellen oder verwenden.

Beachten Sie, dass das Setzen der Konfigurationsoption home_directory keinen Einfluss auf den Speicherort der Secrets hat.

Secrets löschen

Secrets können mit der Anweisung DROP SECRET gelöscht werden, z. B.:

DROP PERSISTENT SECRET my_persistent_secret;

Mehrere Secrets für denselben Diensttyp erstellen

Wenn zwei Secrets für einen Diensttyp existieren, kann der Scope entscheiden, welches verwendet werden soll. Zum Beispiel:

CREATE SECRET secret1 (
    TYPE s3,
    KEY_ID 'my_secret_key1',
    SECRET 'my_secret_value1',
    SCOPE 's3://⟨my-bucket⟩'
);

CREATE SECRET secret2 (
    TYPE s3,
    KEY_ID 'my_secret_key2',
    SECRET 'my_secret_value2',
    SCOPE 's3://⟨my-other-bucket⟩'
);

Wenn der Benutzer nun etwas von s3://⟨my-other-bucket⟩/something abfragt, wird für diese Anfrage automatisch das Secret secret2 gewählt. Um zu sehen, welches Secret verwendet wird, kann die skalare Funktion which_secret genutzt werden, die einen Pfad und einen Secret-Typ als Parameter entgegennimmt:

FROM which_secret('s3://⟨my-other-bucket⟩/file.parquet', 's3');

Secrets auflisten

Secrets können mit der eingebauten tabellenerzeugenden Funktion aufgelistet werden, z. B. über die Tabellenfunktion duckdb_secrets():

FROM duckdb_secrets();

Sensible Informationen werden geschwärzt.