PGAdapter starten

Auf dieser Seite wird beschrieben, wie Sie PGAdapter starten. Informationen zu PGAdapter finden Sie unter Über PGAdapter.

Sie können PGAdapter als eigenständigen Prozess in einem Docker-Container oder als Verarbeitungsprozess mit Ihrer Java-Anwendung starten. Wenn Sie PGAdapter starten, geben Sie das Projekt, die Cloud Spanner-Instanz und die Datenbank an, zu denen eine Verbindung hergestellt werden soll. Außerdem geben Sie den Pfad für eine JSON-formatierte Datei mit Anmeldedaten (Schlüsseldatei) an.

Standalone-Modell

java -jar pgadapter.jar -p PROJECT_NAME -i INSTANCE_NAME \
-d DATABASE_NAME -c CREDENTIALS_FILE_PATH \
ADDITIONAL_OPTIONS

Folgende Optionen sind erforderlich:

-p project_name
der Name des Projekts, in dem die Cloud Spanner-Datenbank ausgeführt wird.
-i instance_name
der Name der Cloud Spanner-Instanz.
-d database_name
der Name der Datenbank, zu der eine Verbindung hergestellt werden soll.
-c credentials_file_path
vollständiger Pfad für die Schlüsseldatei, die die Anmeldedaten des Dienstkontos im JSON-Format enthält. Wenn diese Option nicht festgelegt ist, werden Anmeldedaten aus dem Pfad gelesen, der durch die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS angegeben wird.

Informationen zum Erstellen und Herunterladen einer Schlüsseldatei im JSON-Format finden Sie unter Dienstkontoschlüssel erstellen.

Gewähren Sie dem Dienstkonto ausreichend Anmeldedaten für den Zugriff auf die Datenbank.

Folgende Optionen sind optional:

-q
Unterstützung für die psql-Schrägstriche-Befehle \d, \dt, \dn, \di und \l aktivieren. Kann nur mit einem psql-Client verwendet werden. Führt zu Leistungseinbußen und garantiert nicht zwangsläufig, dass die psql-Logik perfekt übereinstimmt. Daher wird diese Option für die Produktion nicht empfohlen.

Diese Option kann nicht mit der Option -j verwendet werden.

-s port
Port, den PGAdapter überwacht. Der Standardwert ist 5432 (der PostgreSQL-Standardport).
-v version_number

PostgreSQL-Versionsnummer, die dem Client während der Verbindung zur Verfügung gestellt werden soll. Der Standardwert ist 1.0.0.

Einige PostgreSQL-Anwendungen und -Treiber ermöglichen je nach Versionsnummer zusätzliche Funktionen. Cloud Spanner unterstützt diese Features möglicherweise nicht. Für das Vorschaurelease des PostgreSQL-Oberflächenfeatures wird nur der PostgreSQL-Client psql unterstützt.

-x

Aktivieren Sie Verbindungen von anderen Hosts als localhost. Nicht verwenden, wenn PGAdapter im eigenständigen Modus gestartet wird. Nur beim Starten in einem Docker-Container verwenden.

Aus Sicherheitsgründen akzeptiert PGAdapter standardmäßig Verbindungen nur vom localhost.

-j translation_file_path

Der vollständige Pfad für eine Datei mit einem JSON-Objekt, um eine SQL-Übersetzung basierend auf dem Austausch regulärer Ausdrücke durchzuführen. Dies ist eine erweiterte Option. Verwenden Sie diese Option, wenn Sie eine Abfrage für den PostgreSQL-Dialekt übersetzen möchten, aber entweder keinen Zugriff auf den Abfragequellcode haben oder den Quellcode nicht ändern möchten.

Zu den Schlüsseln im JSON-Objekt gehören input_pattern, output_pattern und matcher_array. Jedes Element, das mit input_pattern übereinstimmt, wird durch den String output_pattern ersetzt. Gruppen zur Erfassung regulärer Ausdrücke sind zulässig und ihre Reihenfolge wird mithilfe von matcher_array angegeben. Verwenden Sie %s im String output_pattern, um die Ersetzung der Übereinstimmung zu definieren. Legen Sie matcher_array auf [] fest, wenn input_pattern und output_pattern keine Übereinstimmungen angeben.

Alternativ können Sie die Java-Regeln vom Typ matcher.replaceAll() verwenden, um die übereinstimmenden Gruppennamen direkt im String output_pattern zu platzieren. Setzen Sie das Element in geschweifte Klammern mit vorangestelltem Dollarzeichen und lassen Sie matcher_array leer.

Benutzerdefinierte Muster werden internen Übereinstimmungen vorangestellt. Die Escapezeichen und die allgemeine Syntax für reguläre Ausdrücke stimmen mit der Java-Syntax für reguläre Ausdrücke überein. Weitere Informationen zur Syntax von regulären Ausdrücken für Java finden Sie unter Klassenmuster.

Dazu ein Beispiel:

{
  "commands":
    [
      {
        "input_pattern": "^SELECT * FROM users;$",
        "output_pattern": "SELECT 1;",
        "matcher_array": []
      },
      {
        "input_pattern": "^ab(?\\d)(?\\d)$",
        "output_pattern": "second number: %s, first number: %s",
        "matcher_array": ["secondgroup", "firstgroup"]
      },
      {
        "input_pattern": "^cd(?\\d)(?\\d)$",
        "output_pattern": "second number: ${secondgroup}, first number: ${firstgroup}",
        "matcher_array": []
      }
    ]
}
                  

In diesem Beispiel wird davon ausgegangen, dass die Eingabeabfragen so aussehen:

"SELECT * FROM users;"
"ab12"
"cd34"

Die Ausgabeabfragen wären dann:

"SELECT 1;"
"second number: 2, first number: 1"
"second number: 4, first number: 3"

Im folgenden einfachen Beispiel wird PGAdapter im eigenständigen Modus gestartet.

java -jar pgadapter.jar -p my-project -i my-instance -d my-database \
    -c /tmp/credentials.json -q -s 5432
            

Container

  1. Laden Sie das PGAdapter-Image in Docker.

    docker load -i pgadapter.tar
    
  2. Starten Sie PGAdapter.

    docker run -d -p 127.0.0.1:HOST-PORT:DOCKER-PORT \
        -v CREDENTIALS_FILE_PATH:/acct_credentials.json pgadapter:latest \
        -p PROJECT_NAME -i INSTANCE_NAME -d DATABASE_NAME  \
        -c /acct_credentials.json -q -x OTHER_PGAdapter_OPTIONS
    

    Zusätzlich zu den PGAdapter-Optionen zum Festlegen von Projekt, Instanz, Datenbank und Anmeldedaten sind folgende Optionen erforderlich:

    -p 127.0.0.1:host-port:docker-port

    Mit dieser Docker-Option wird der Port docker-port im Docker-Container dem Port host-port außerhalb des Containers zugeordnet. docker-port muss der Konfiguration von PGAdapter im Container entsprechen. Er muss immer 5432 lauten. host-port ist der Port, den Docker außerhalb des Containers auf Verbindungsanfragen überwachen soll. Es muss immer ein Port auf localhost sein.

    Weitere Informationen finden Sie in der Docker-Dokumentation unter Port veröffentlichen oder freigeben (-p, --expose).

    -v credentials_file_path:in_container_mount_point

    Diese Docker-Option bindet ein freigegebenes Volume. Sie ordnet den Hostpfad außerhalb des Containers einem Volume (Bereitstellungspunkt) innerhalb des Containers zu. Die Host- und Containerpfade werden durch einen Doppelpunkt (:) getrennt.

    Mit dieser Option kann PGAdapter auf die JSON-Anmeldedatendatei außerhalb des Containers zugreifen. Im vorherigen Beispiel verweist die Option -c auf den Bereitstellungspunkt innerhalb des Containers. In diesem Beispiel wird der im Container enthaltene Bereitstellungspunkt /acct_credentials.json genannt. Sie können ihm einen beliebigen Namen geben.

    Weitere Informationen finden Sie in der Docker-Dokumentation unter VOLUME (freigegebene Dateisysteme).

    -x

    Aktivieren Sie Verbindungen von anderen Hosts als localhost. Dies ist erforderlich, da der Port, der sich im Container befindet, dem Hostport zugeordnet ist, für PGAdapter nicht als localhost angezeigt wird.

    Die folgende Option ist optional:

    -q
    Unterstützung für die psql-Schrägstriche-Befehle \d, \dt, \dn, \di, und \l aktivieren Kann nur mit einem psql-Client verwendet werden. Führt zu Leistungseinbußen und garantiert nicht zwangsläufig, dass die psql-Logik perfekt übereinstimmt. Daher wird diese Option für die Produktion nicht empfohlen.

    Im folgenden Beispiel sind der Docker-Port und der Hostport auf den Standardport 5432 des PostgreSQL-Datenbankdienstes festgelegt.

    docker run -d -p 127.0.0.1:5432:5432 \
        -v /tmp/credentials.json:/acct_credentials.json pgadapter:latest \
        -p my_project -i my_instance -d my_database \
        -c /acct_credentials.json  -q -x
    

In-process

Erstellen und starten Sie eine PGAdapter-Instanz mit Ihrem Java-Code.

  1. Fügen Sie Ihrem Projekt google-cloud-spanner-pgadapter als Abhängigkeit hinzu.
  2. Erstellen Sie einen Server mit der Klasse com.google.cloud.spanner.pgadapter.ProxyServer.
  3. class PGProxyRunner {
        public static void main() {
            ProxyServer server = new ProxyServer(
              new OptionsMetadata(
                    "jdbc:cloudspanner:/projects/my-project-name"
                    + "/instances/my-instance-id"
                    + "/databases/my-database-name"
                    + ";credentials=/home/user/service-account-credentials.json"
                    + ";dialect=postgresql",
                    portNumber,
                    textFormat,
                    forceBinary,
                    authenticate,
                    psqlMode,
                    commandMetadataJSON)
            );
            server.startServer();
        }
    }
                  

Nächste Schritte