PostgreSQL-Erweiterung und der Secret Manager

Benutzeranmeldedaten und andere Verbindungsdetails der PostgreSQL-Datenbank können mit dem DuckDB-Secrets Manager gespeichert werden. Mit der folgenden Syntax kann ein Secret erstellt werden:

CREATE SECRET (
    TYPE postgres,
    HOST '127.0.0.1',
    PORT 5432,
    DATABASE postgres,
    USER 'postgres',
    PASSWORD ''
);

Die Informationen aus dem Secret werden verwendet, wenn ATTACH aufgerufen wird. Wir können die PostgreSQL-Verbindungszeichenkette leer lassen, um alle im Secret gespeicherten Informationen zu verwenden.

ATTACH '' AS postgres_db (TYPE postgres);

Wir können die PostgreSQL-Verbindungszeichenkette verwenden, um einzelne Optionen zu überschreiben. Um uns beispielsweise mit einer anderen Datenbank zu verbinden und dabei dieselben Anmeldedaten zu verwenden, können wir nur den Datenbanknamen wie folgt überschreiben.

ATTACH 'dbname=my_other_db' AS postgres_db (TYPE postgres);

Standardmäßig sind erstellte Secrets temporär. Secrets können mit dem Befehl CREATE PERSISTENT SECRET dauerhaft gespeichert werden. Persistente Secrets können sitzungsübergreifend verwendet werden.

Mehrere Secrets verwalten

Benannte Secrets können verwendet werden, um Verbindungen zu mehreren PostgreSQL-Datenbankinstanzen zu verwalten. Secrets können bei der Erstellung einen Namen erhalten.

CREATE SECRET postgres_secret_one (
    TYPE postgres,
    HOST '127.0.0.1',
    PORT 5432,
    DATABASE postgres,
    USER 'postgres',
    PASSWORD ''
);

Das Secret kann dann explizit über den Parameter SECRET in ATTACH referenziert werden.

ATTACH '' AS postgres_db_one (TYPE postgres, SECRET postgres_secret_one);

Warning Vermeiden Sie es, Anmeldedaten direkt in die Verbindungszeichenkette aufzunehmen. Wenn ein Verbindungsfehler auftritt, kann die vollständige Verbindungszeichenkette (einschließlich Ihrer Anmeldedaten) in der Terminalausgabe erscheinen. Für bessere Sicherheit speichern Sie Anmeldedaten über von DuckDB verwaltete Secrets.

Secret-Konfigurationsoptionen

Secrets vom Typ postgres unterstützen eine Reihe von Konfigurationsoptionen. Die folgenden Optionen sind nach den entsprechenden Verbindungsoptionen von libpq benannt:

HOST
HOSTADDR
PORT
DBNAME
USER
PASSWORD
PASSFILE
REQUIRE_AUTH
CHANNEL_BINDING
CONNECT_TIMEOUT
CLIENT_ENCODING
OPTIONS
APPLICATION_NAME
FALLBACK_APPLICATION_NAME
KEEPALIVES
KEEPALIVES_IDLE
KEEPALIVES_INTERVAL
KEEPALIVES_COUNT
TCP_USER_TIMEOUT
REPLICATION
GSSENCMODE
SSLMODE
REQUIRESSL
SSLNEGOTIATION
SSLCOMPRESSION
SSLCERT
SSLKEY
SSLKEYLOGFILE
SSLPASSWORD
SSLCERTMODE
SSLROOTCERT
SSLCRL
SSLCRLDIR
SSLSNI
REQUIREPEER
SSL_MIN_PROTOCOL_VERSION
SSL_MAX_PROTOCOL_VERSION
MIN_PROTOCOL_VERSION
MAX_PROTOCOL_VERSION
KRBSRVNAME
GSSLIB
GSSDELEGATION
SCRAM_CLIENT_KEY
SCRAM_SERVER_KEY
SERVICE
TARGET_SESSION_ATTRS
LOAD_BALANCE_HOSTS
OAUTH_ISSUER
OAUTH_CLIENT_ID
OAUTH_CLIENT_SECRET
OAUTH_SCOPE

Die folgenden Optionen sind auf die entsprechenden Schlüssel umbenannt:

DATABASE – Alias für DBNAME
HOSTNAME – Alias für HOST
USERNAME – Alias für USER

Anstelle einzelner Verbindungsoptionen kann die vollständige Verbindungs-URI angegeben werden:

URI – Verbindungs-URI

Eine zusätzliche Option wird für die AWS-RDS-IAM-Authentifizierung verwendet, Details siehe im nächsten Abschnitt:

AWS_RDS_SECRET – der Name des Secrets vom Typ rds

AWS-RDS-IAM-Authentifizierung

Verwaltete PostgreSQL-Datenbanken auf RDS/Aurora-Diensten erlauben die Verwendung der IAM-Authentifizierung. In diesem Fall wird das Authentifizierungstoken mit dem AWS SDK erzeugt und muss alle 15 Minuten erneuert werden.

Die postgres-Erweiterung unterstützt die IAM-Authentifizierung, wenn das Passwort nicht im Secret angegeben wird, sondern stattdessen einer der konfigurierten AWS Credential Providers verwendet wird, um das Passwort zu erzeugen, das von der postgres-Erweiterung automatisch erneuert wird.

Verbindung mit IAM-Authentifizierung von der Kommandozeile

Dieser Abschnitt veranschaulicht den Vorgang mit dem Dienstprogramm psql, nicht mit DuckDB. Diese Methode kann verwendet werden, um die Konfiguration zu prüfen, bevor DuckDB-Secrets eingerichtet werden.

Wenn die IAM-Authentifizierung mit dem Kommandozeilenwerkzeug psql durchgeführt wird, sind die folgenden von AWS empfohlenen Verbindungsschritte:

Authentifizierungstoken mit der aws-CLI erzeugen.

Dieses Token als Verbindungsoption password übergeben:

export RDSHOST="database-1-instance-1.xxx.eu-west-1.rds.amazonaws.com"
psql "host=$RDSHOST port=5432 dbname=postgres user=postgres sslmode=require password=$(aws rds generate-db-auth-token --hostname $RDSHOST --port 5432 --username postgres --region eu-west-1)"

Secrets für die IAM-Authentifizierung konfigurieren

Die Authentifizierung über die postgres-Erweiterung verwendet dieselbe Logik wie bei psql:

Das Secret vom Typ rds wird verwendet, um das Authentifizierungstoken zu erzeugen. Es nimmt dieselben Konfigurationsparameter wie der Befehl aws rds generate-db-auth-token im Beispiel oben:

CREATE SECRET aws_rds_secret1 (
    TYPE rds,
    PROVIDER credential_chain,
    CHAIN 'env;sso;',
    REGION 'eu-west-1',
    RDS_USER 'postgres',
    RDS_HOST 'database-1-instance-1.xxxxxxxxxxxx.eu-west-1.rds.amazonaws.com',
    RDS_PORT '5432'
);

Das Secret vom Typ postgres wird verwendet, um den Rest der Verbindungszeichenkette zu erzeugen. Es nimmt dieselben Parameter wie das psql-Dienstprogramm im Beispiel oben (und zusätzlich alle relevanten weiteren libpq-Konfigurationsoptionen) und erfordert die Angabe des Namens des rds-Secrets, das verwendet wird, um das Authentifizierungstoken zu erzeugen und regelmäßig (automatisch) zu erneuern, das als password an den Server übergeben wird:
```
CREATE SECRET pg_rds_secret1 (
    TYPE postgres,
    HOST 'database-1-instance-1.xxxxxxxxxxxx.eu-west-1.rds.amazonaws.com',
    PORT '5432',
    USER 'postgres',
    DATABASE 'postgres',
    SSLMODE require,
    AWS_RDS_SECRET aws_rds_secret1
);
```

Das Secret vom Typ rds erfordert, dass die aws-Erweiterung installiert ist, und erlaubt es, die AWS Credential Chain auf dieselbe Weise wie beim Secret vom Typ s3 zu konfigurieren. Details finden Sie in der AWS-Erweiterungsdokumentation.

Secrets in einer PostgreSQL-Datenbank speichern

Der DuckDB-Secrets Manager unterstützt steckbare Storage Providers. Die postgres-Erweiterung implementiert das Speichern der Secrets (beliebigen Typs) als Datensätze in einer PostgreSQL-Datenbanktabelle.

Das folgende Beispiel initialisiert den Secrets-Speicher und fügt das Secret in die Tabelle duckdb_secrets ein:

ATTACH 'postgres:' AS p1 (
    SECRET pg_rds_secret1,
    SECRET_STORAGE_TABLE duckdb_secrets
);

CREATE OR REPLACE SECRET s3_secret1 IN postgres_p1 (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN 'env;sso;',
    PROFILE 'DatabaseAdministrator-⟨account_id⟩',
    REGION 'eu-west-1'
);

Wenn die Klausel IN postgres_⟨attached_database⟩{:.language-sql .highlight} von CREATE SECRET angegeben wird, wird das Secret in der Tabelle duckdb_secrets der angegebenen angehängten Datenbank persistiert.

Warning Secrets werden unverschlüsselt im Binärformat in die Datenbanktabelle geschrieben. Es wird empfohlen, diesen Provider für Secrets zu verwenden, die keine vertraulichen Anmeldedaten enthalten (wie das s3-Beispiel oben). Für Multi-Tenant-Szenarien wird erwartet, dass Postgres-Row-Level-Security-Richtlinien verwendet werden können, um zu verhindern, dass Benutzer Secrets anderer Benutzer sehen.

Ein anderer Tabellenname (beispielsweise in einem anderen Schema) kann im Parameter SECRET_STORAGE_TABLE des ATTACH-Befehls angegeben werden.

Wenn die Standardtabelle duckdb_secrets verwendet wird, ist es nicht notwendig, den Parameter SECRET_STORAGE_TABLE anzugeben. Wenn eine PostgreSQL-Datenbank angehängt wird, wird die Tabelle mit dem Standardnamen duckdb_secrets automatisch geprüft. Falls sie existiert, wird die Secret-Storage-Instanz für diese angehängte Datenbank registriert, sodass alle gespeicherten Secrets in der aktuellen Sitzung verfügbar sind. Das erlaubt die Verwendung solcher persistenten Secrets in „Direct-Attach“-Szenarien, wenn nur eine Verbindungszeichenkette an den Befehl duckdb übergeben wird (andere DuckDB-Clients können eine etwas andere Syntax erfordern):

duckdb postgres:postgresql://username:password@127.0.0.1:5432/db1

Diese Methode kann auch mit DuckLake (mit PostgreSQL-Katalog) verwendet werden, wenn ein S3-/Object-Storage-Zugriffssecret in der Katalogdatenbank gespeichert ist:

duckdb ducklake:postgres:postgresql://username:password@127.0.0.1:5432/db1

Secrets, die in der jeweiligen angehängten Datenbank gespeichert sind, können mit der folgenden Abfrage aufgelistet werden:

FROM duckdb_secrets() WHERE storage = 'postgres_⟨attached_database⟩';

Um den PostgreSQL-Secret-Storage vollständig zu deaktivieren, übergeben Sie den leeren String '' im Parameter SECRET_STORAGE_TABLE.