PgBouncer-Verbindungspooler verwenden

Auf dieser Seite wird beschrieben, wie Sie den PgBouncer-Verbindungspooler für AlloyDB Omni mit dem AlloyDB Omni Kubernetes-Operator aktivieren und verwenden.

Viele Anwendungen, insbesondere Webanwendungen, öffnen und schließen häufig Datenbankverbindungen, was die Datenbankinstanz erheblich belasten kann. PgBouncer hilft, die Instanzlast zu reduzieren, indem Verbindungen effizienter verwaltet werden. Durch die Wiederverwendung von Verbindungen minimiert PgBouncer die Anzahl der Verbindungen zur Datenbankinstanz und schafft so Ressourcen auf der Instanz frei.

PgBouncer-Dienst erstellen

Mit dem AlloyDB Omni Kubernetes-Operator können Sie einen speziellen PgBouncer-Dienst für Ihre Datenbank erstellen. Sie können dann über den PgBouncer-Dienst auf die Datenbank zugreifen, um vom Verbindungs-Pooling zu profitieren.

Es gibt eine spezielle benutzerdefinierte Ressourcendefinition (CRD), mit der Sie Ihren PgBouncer-Dienst nach Bedarf konfigurieren können.

So erstellen Sie einen PgBouncer-Dienst für Ihre Datenbank:

  1. So erstellen Sie eine benutzerdefinierte PgBouncer-Ressource in Ihrem Kubernetes-Cluster:

    apiVersion: alloydbomni.dbadmin.goog/v1
kind: PgBouncer
metadata:
  name: PGBOUNCER_NAME
spec:
  dbclusterRef: DB_CLUSTER_NAME
  allowSuperUserAccess: true
  podSpec:
    resources:
      memory: 1Gi
      cpu: 1
    image: "gcr.io/alloydb-omni/operator/pgbouncer:1.23.1"
  parameters:
    pool_mode: POOL_MODE
    ignore_startup_parameters: IGNORE_STARTUP_PARAMETERS
    default_pool_size: DEFAULT_POOL_SIZE
    max_client_conn: MAXIMUM_CLIENT_CONNECTIONS
    max_db_connections: MAXIMUM_DATABASE_CONNECTIONS
  serviceOptions:
    type: "ClusterIP"

    Ersetzen Sie Folgendes:

    • PGBOUNCER_NAME: der Name Ihrer benutzerdefinierten PgBouncer-Ressource.
    • DB_CLUSTER_NAME: der Name Ihres AlloyDB Omni-Datenbankclusters. Dies ist der Name des Datenbankclusters, den Sie beim Erstellen angegeben haben.
    • POOL_MODE: Gibt an, wann eine Datenbankverbindung von anderen Clients wiederverwendet werden kann. Legen Sie einen der folgenden Werte für den Parameter fest:
      • session: Die Datenbankverbindung wird nach der Client-Trennung wieder an den Pool zurückgegeben. Wird standardmäßig verwendet.
      • transaction: Die Datenbankverbindung wird nach Abschluss der Transaktion wieder an den Pool freigegeben.
      • statement: Die Datenbankverbindung wird nach Abschluss der Abfrage wieder an den Pool freigegeben. Transaktionen, die mehrere Anweisungen umfassen, sind in diesem Modus nicht zulässig.
    • IGNORE_STARTUP_PARAMETERS: Gibt Parameter an, die von PgBouncer nicht zulässig sind, sodass sie beim Starten ignoriert werden, z. B. extra_float_digits. Weitere Informationen finden Sie unter PgBouncer-Konfiguration.
    • DEFAULT_POOL_SIZE: die Anzahl der zulässigen Datenbankverbindungen pro Nutzer-Datenbank-Paar, z. B. 8.
    • MAXIMUM_CLIENT_CONNECTIONS: Die maximale Anzahl von Clientverbindungen, z. B. 800.
    • MAXIMUM_DATABASE_CONNECTIONS: die maximale Anzahl von Datenbankverbindungen, z. B. 160.

  2. Wenden Sie das Manifest an:

    kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

    Ersetzen Sie PATH_TO_MANIFEST durch den Pfad zu Ihrer Manifestdatei, z. B. /fleet/config/pgbouncer.yaml.

  3. Führen Sie die folgende Abfrage aus, um zu prüfen, ob das von Ihnen erstellte PgBouncer-Objekt bereit ist:

    kubectl get pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME  -n NAMESPACE -w

    Ersetzen Sie NAMESPACE durch den Namen des Kubernetes-Namespace für Ihr PgBouncer-Objekt.

    Die Ausgabe sieht in etwa so aus:

    NAMESPACE   NAME          ENDPOINT        STATE
dbv2        mypgbouncer
dbv2        mypgbouncer
dbv2        mypgbouncer
dbv2        mypgbouncer                   WaitingForDeploymentReady
dbv2        mypgbouncer                   Acquiring IP
dbv2        mypgbouncer   10.138.15.231   Ready

Verbindung zum Endpunkt des Verbindungspoolers herstellen

Sie können eine Verbindung zum PgBouncer-Verbindungspooler innerhalb oder außerhalb eines Kubernetes-Clusters herstellen.

Verbindung innerhalb eines Kubernetes-Clusters herstellen

So stellen Sie mit dem psql-Client eine Verbindung zum Endpunkt des Verbindungspoolers her:

  1. So erstellen Sie einen Pod:

    apiVersion: v1
kind: Pod
metadata:
  name: postgres
spec:
  containers:
  - image: "docker.io/library/postgres:latest"
    command:
     - "sleep"
     - "604800"
    name: db-client

  2. Wenden Sie das Manifest an:

    kubectl apply -f PATH_TO_MANIFEST -n NAMESPACE

  3. Stellen Sie eine Verbindung zur containerisierten Anwendung her:

    kubectl exec -it postgres -n NAMESPACE -- bash

  4. Prüfen Sie die SSL-Verbindung zum PgBouncer-Endpunkt mit dem psql-Client:

    export PGSSLMODE="require"; psql -h HOST -d postgres -U postgres -p PORT

    Ersetzen Sie Folgendes:

    • HOST: Der Endpunkt des Verbindungspoolers, den Sie mit dem Befehl kubectl get pgbouncers.alloydbomni.dbadmin.goog -n NAMESPACE abrufen. Wenn PgBouncer nicht als Dienst freigegeben ist, verwenden Sie seine IP-Adresse.
    • PORT: Der Port, auf dem PgBouncer wartet.

    Im Terminalfenster wird der psql-Anmeldetext angezeigt, der mit einem postgres=#-Prompt endet.

Verbindung von außerhalb eines Kubernetes-Clusters herstellen

Wenn Sie von außerhalb eines Kubernetes-Clusters auf den PgBouncer-Verbindungspooler zugreifen möchten, legen Sie das Feld type im Attribut serviceOptions auf LoadBalancer fest. Dadurch wird ein loadbalancer-Dienst erstellt.

  1. So erstellen Sie eine benutzerdefinierte PgBouncer-Ressource in Ihrem Kubernetes-Cluster:

    apiVersion: alloydbomni.dbadmin.goog/v1
kind: PgBouncer
metadata:
name: PGBOUNCER_NAME
spec:
dbclusterRef: DB_CLUSTER_NAME
allowSuperUserAccess: true
replicaCount: 2
parameters:
  pool_mode: POOL_MODE
  ignore_startup_parameters: IGNORE_STARTUP_PARAMETERS
  default_pool_size: DEFAULT_POOL_SIZE
  max_client_conn: MAXIMUM_CLIENT_CONNECTIONS
  max_db_connections: MAXIMUM_DATABASE_CONNECTIONS
podSpec:
  resources:
    memory: 1Gi
    cpu: 1
  image: "gcr.io/alloydb-omni/operator/pgbouncer:1.23.1"
serviceOptions:
  type: "LoadBalancer"

  2. Wenden Sie das Manifest an:

    kubectl apply -f PATH_TO_MANIFEST

  3. Führen Sie die folgende Abfrage aus, um zu prüfen, ob das von Ihnen erstellte PgBouncer-Objekt bereit ist:

    kubectl get pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME  -n NAMESPACE -w

    Die Ausgabe sieht in etwa so aus:

    NAME          ENDPOINT       STATE
mypgbouncer   10.138.15.207   Ready

PgBouncer-Einstellungen konfigurieren

Verwenden Sie die folgenden Parameter, um die PGBouncer-Einstellungen zu konfigurieren:

Parameter Beschreibung Standardwert
pool_mode Gibt an, wann eine Datenbankverbindung von anderen Clients wiederverwendet werden kann.
Zulässige Werte:
  • session: Die Datenbankverbindung wird nach der Client-Trennung wieder an den Pool zurückgegeben.
  • transaction: Die Datenbankverbindung wird nach Abschluss der Transaktion wieder an den Pool freigegeben.
  • statement: Die Datenbankverbindung wird nach Abschluss der Abfrage wieder an den Pool freigegeben.
    Transaktionen, die mehrere Anweisungen umfassen, sind in diesem Modus nicht zulässig.
 session
ignore_startup_parameters Gibt Parameter an, die von PgBouncer nicht zulässig sind, damit sie beim Start ignoriert werden.
default_pool_size Die Anzahl der zulässigen Datenbankverbindungen pro Nutzer-Datenbank-Paar. 20
max_client_conn Die maximale Anzahl von Clientverbindungen. 100
max_db_connections Die maximale Anzahl von Datenbankverbindungen. 0

PgBouncer-Bereitstellung anpassen

AlloyDB Omni verwendet benutzerdefinierte Ressourcen, um seine Komponenten zu verwalten. Wenn Sie die PgBouncer-Bereitstellung in AlloyDB Omni in Kubernetes anpassen möchten, ändern Sie die benutzerdefinierte Ressource PgBouncer so:

  1. Liste der benutzerdefinierten PgBouncer-Ressourcen auflisten:

    kubectl get pgbouncers -n NAMESPACE

    Ersetzen Sie NAMESPACE durch den Namespace, in dem Sie AlloyDB Omni bereitgestellt haben.

  2. Wenn Sie die Ressource ändern möchten, öffnen Sie die Deklarationsdatei für die PgBouncer-Ressource in Ihrem Standardeditor:

    kubectl edit pgbouncers PGBOUNCER_NAME -n NAMESPACE

  3. Suchen Sie in der Deklarationsdatei den Abschnitt podSpec mit der Konfiguration und ändern Sie nach Bedarf eines der folgenden Felder:

    • resources: die für Ihren Container definierten cpu und memory:

      apiVersion: alloydbomni.dbadmin.goog/v1
kind: PgBouncer
metadata:
  name: PGBOUNCER_NAME
spec:
  dbclusterRef: DB_CLUSTER_NAME
  replicaCount: 2
  parameters:
    pool_mode: POOL_MODE
    ignore_startup_parameters: IGNORE_STARTUP_PARAMETERS
    default_pool_size: DEFAULT_POOL_SIZE
    max_client_conn: MAXIMUM_CLIENT_CONNECTIONS
    max_db_connections: MAXIMUM_DATABASE_CONNECTIONS
  podSpec:
    resources:
      memory: 1Gi
      cpu: 1
...

    • image: der Pfad zum PgBouncer-Image-Tag:

      ...
  podSpec:
    resources:
      memory: 1Gi
      cpu: 1
    image: IMAGE
...

    • schedulingconfig: Fügen Sie den Abschnitt nodeaffinity hinzu, um festzulegen, wo die PgBouncer-Pods geplant werden:

      ...
  podSpec:
    resources:
      memory: 1Gi
      cpu: 1
    image: IMAGE
    schedulingconfig:
      nodeaffinity:
        NODE_AFFINITY_TYPE:
          nodeSelectorTerms:
          - matchExpressions:
            - key: LABEL_KEY
              operator: OPERATOR_VALUE
              values:
              - pgbouncer
...

      Ersetzen Sie Folgendes:

      • NODE_AFFINITY_TYPE: Legen Sie für den Parameter einen der folgenden Werte fest:
        • requiredDuringSchedulingIgnoredDuringExecution: Kubernetes plant den Pod genau anhand der definierten Regeln.
        • preferredDuringSchedulingIgnoredDuringExecution: Der Kubernetes-Planer versucht, einen Knoten zu finden, der der definierten Regel für die Planung entspricht. Wenn es keinen solchen Knoten gibt, wird die Ausführung von Kubernetes auf einen anderen Knoten im Cluster geplant.
      • LABEL_KEY: Das Label des Knotens für den Schlüssel, der als Standortindikator dient und eine gleichmäßige Pod-Verteilung im Cluster ermöglicht, z. B. nodetype.
      • OPERATOR_VALUE: Stellt die Beziehung eines Schlüssels zu einer Reihe von Werten dar. Legen Sie einen der folgenden Werte für den Parameter fest:
        • In: Das Array „values“ darf nicht leer sein.
        • NotIn: Das Array „values“ darf nicht leer sein.
        • Exists: Das Array „values“ muss leer sein.
        • DoesNotExist: Das Array „values“ muss leer sein.
        • Gt: Das Werte-Array muss ein einzelnes Element enthalten, das als Ganzzahl interpretiert wird.
        • Lt: Das Werte-Array muss ein einzelnes Element enthalten, das als Ganzzahl interpretiert wird.

  4. Speichern Sie die Deklarationsdatei nach dem Anwenden der Änderungen. Der AlloyDB Omni Kubernetes-Operator wendet die Änderungen automatisch auf Ihre PgBouncer-Bereitstellung an.

PgBouncer-Ressource löschen

Führen Sie den folgenden Befehl aus, um eine benutzerdefinierte PgBouncer-Ressource zu löschen:

kubectl delete pgbouncers.alloydbomni.dbadmin.goog PGBOUNCER_NAME -n NAMESPACE

Die Ausgabe sieht in etwa so aus:

pgbouncer.alloydbomni.dbadmin.goog "mypgbouncer" deleted

PgBouncer-Logs ansehen

So können Sie Logs jeder PgBouncer-Replikatinstanz in Ihrer AlloyDB Omni-Bereitstellung in Kubernetes aufrufen und analysieren:

  1. Rufen Sie eine Liste aller PgBouncer-Pods in Ihrem Namespace ab:

    kubectl get pods -n NAMESPACE

    Die Ausgabe sieht in etwa so aus:

    NAME                                          READY   STATUS    RESTARTS   AGE
al-092d-dbcluster-sample-0                    3/3     Running   0          3d1h
mypgbouncer-pgb-deployment-659869f95c-4kbgv   1/1     Running   0          27m

  2. So rufen Sie Logs für einen bestimmten Pod auf:

    kubectl logs -f POD_NAME -n NAMESPACE

    Die Ausgabe sieht in etwa so aus:

    2025-01-21 06:57:39.549 UTC [7] LOG kernel file descriptor limit: 1048576 (hard: 1048576); max_client_conn: 800, max expected fd use: 812
2025-01-21 06:57:39.550 UTC [7] LOG listening on 0.0.0.0:6432
2025-01-21 06:57:39.550 UTC [7] LOG listening on [::]:6432
2025-01-21 06:57:39.550 UTC [7] LOG listening on unix:/tmp/.s.PGSQL.6432
2025-01-21 06:57:39.550 UTC [7] LOG process up: PgBouncer 1.23.0, libevent 2.1.12-stable (epoll), adns: evdns2, tls: OpenSSL 3.0.13 30 Jan 2024
2025-01-21 06:58:17.012 UTC [7] LOG C-0x55f2b1b322a0: (nodb)/(nouser)@10.138.15.215:48682 registered new auto-database: alloydbadmin
2025-01-21 06:58:17.012 UTC [7] LOG S-0x55f2b1b4ecb0: alloydbadmin/alloydbpgbouncer@10.138.0.48:5432 new connection to server (from 10.12.1.113:53156)
2025-01-21 06:58:17.042 UTC [7] LOG S-0x55f2b1b4ecb0: alloydbadmin/alloydbpgbouncer@10.138.0.48:5432 SSL established: TLSv1.3/TLS_AES_256_GCM_SHA384/ECDH=prime256v1
2025-01-21 06:58:17.052 UTC [7] LOG C-0x55f2b1b322a0: pgbouncer/statsuser@10.138.15.215:48682 login attempt: db=pgbouncer user=statsuser tls=TLSv1.3/TLS_AES_256_GCM_SHA384 replication=no
2025-01-21 06:58:19.526 UTC [7] LOG C-0x55f2b1b322a0: pgbouncer/statsuser@10.138.15.215:48682 closing because: client close request (age=2s)
2025-01-21 06:58:20.344 UTC [7] LOG C-0x55f2b1b322a0: pgbouncer/statsuser@10.138.15.215:46796 login attempt: db=pgbouncer user=statsuser tls=TLSv1.3/TLS_AES_256_GCM_SHA384 replication=no

Leistung und Aktivität von PgBouncer überwachen

Sie können sich Messwerte für den PgBouncer-Verbindungspool nur mit einer speziellen statsuser ansehen, um auf die interne Statistikdatenbank von PgBouncer zuzugreifen. statsuser wird für die Authentifizierung beim Herstellen einer Verbindung zur PgBouncer-Datenbank verwendet.

  1. Stellen Sie über den psql-Client eine Verbindung zu AlloyDB Omni als Superuser oder Nutzer mit dem CREATE ROLE-Berechtigungslevel her:

    export PGPASSWORD="ChangeMe123"; export PGSSLMODE="require"; psql -h HOST -d postgres -U postgres -p PORT

    Die Ausgabe sieht in etwa so aus:

    psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 15.7)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

  2. Erstellen Sie die statsuser in AlloyDB Omni:

    postgres=# CREATE USER "statsuser" WITH PASSWORD 'tester';

    Die Ausgabe sieht in etwa so aus:

    CREATE ROLE
postgres=#

  3. Stellen Sie als statsuser eine Verbindung zur PgBouncer-Datenbank her:

    export PGPASSWORD="ChangeMe123"; export PGSSLMODE="require"; psql -h HOST -d pgbouncer -U statsuser -p PORT

    Die Ausgabe sieht in etwa so aus:

    psql (16.6 (Ubuntu 16.6-0ubuntu0.24.04.1), server 1.23.0/bouncer)
WARNING: psql major version 16, server major version 1.23.
Some psql features might not work.
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

  4. Führen Sie den Befehl SHOW STATS aus, um die PgBouncer-Leistung zu sehen und potenzielle Probleme zu identifizieren:

    pgbouncer=# SHOW STATS;

    Die Ausgabe sieht in etwa so aus:

         database   | total_server_assignment_count | total_xact_count | total_query_count | total_received | total_sent | total_xact_time | total_query_time | total_wait_time | avg_server_assignment_count | avg_xact_count | avg_query_count | avg_recv | avg_sent | avg_xact_time | avg_query_time | avg_wait_time
   -------------+-------------------------------+------------------+-------------------+----------------+------------+-----------------+------------------+-----------------+-----------------------------+----------------+-----------------+----------+----------+---------------+----------------+---------------
   alloydbadmin |                             1 |                0 |                 0 |              0 |        330 |               0 |                0 |           41730 |                           0 |              0 |               0 |        0 |        2 |             0 |              0 |         41730
   pgbouncer    |                             0 |                5 |                 5 |              0 |          0 |               0 |                0 |               0 |                           0 |              0 |               0 |        0 |        0 |             0 |              0 |             0
   (2 rows)

PgBouncer-Verbindungspool deaktivieren

Wenn Sie den PgBouncer-Verbindungspooler deaktivieren oder rückgängig machen möchten, gehen Sie so vor:

  1. Prüfen Sie den Status des Verbindungspoolers:

    kubectl get deployment fleet-controller-manager --namespace alloydb-omni-system  -o json | jq '.spec.template.spec.containers[0].args'

    Dieser Befehl zeigt das Bereitstellungsmanifest des primären Controllers für die Verwaltung der AlloyDB Omni-Flotte an. Suchen Sie im Bereich args des Arrays containers nach der Option --enable-pgbouncer:

    ...
 spec:
  containers:
  - name: fleet-controller-manager
    image:...
    args:
    --health-probe-bind-address=:8081",
    --metrics-bind-address=127.0.0.1:8080",
    --leader-elect",
    --image-registry=gcr.io",
    --data-plane-image-repository=alloydb-omni-staging",
    --control-plane-agents-image-repository=aedi-gbox",
    --control-plane-agents-tag=jan19v3",
    --additional-db-versions-for-test-only=latest",
    --enable-multiple-backup-solutions=true",
    --enable-pgbouncer=true

  2. Bearbeiten Sie die Konfiguration der Controllerbereitstellung, um den Verbindungspooler zu deaktivieren:

    kubectl edit deployment fleet-controller-manager --namespace alloydb-omni-system

  3. Ändern Sie im Bereitstellungsmanifest den Wert der Option --enable-pgbouncer von true in false:

    ...
--enable-pgbouncer=false

  4. Speichern Sie die Datei und beenden Sie den Editor. kubectl wendet die Änderung automatisch an.

Nächste Schritte