PGAdapter をエミュレータに接続する

このページでは、PGAdapter を Spanner エミュレータに接続する方法について説明します。このエミュレータはローカルで実行され、Google Cloud プロジェクトや請求先アカウントを作成せずにアプリケーションの開発とテストに使用できます。エミュレータはメモリにのみデータを格納するため、再起動するとデータ、スキーマ、構成など、すべての状態が失われます。このエミュレータは Spanner の本番環境サービスと同じ API を提供し、本番環境へのデプロイではなく、ローカルでの開発とテストを目的として作られています。

PGAdapter をエミュレータに接続する方法は 3 つあります。

  • PGAdapter とエミュレータの両方と統合されたビルド済みの Docker コンテナを実行する。
  • エミュレータと PGAdapter の両方をローカルマシンで実行する。
  • エミュレータと PGAdapter の両方を Docker ネットワークで実行する。

統合された Docker コンテナ

PGAdapter とエミュレータの両方を含むビルド済みの Docker イメージを実行します。Docker コンテナ内の PGAdapter インスタンスは、コンテナ内のエミュレータに接続するように自動的に構成されます。

次のコマンドを使用して Docker コンテナを起動します。

docker pull gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator
docker run -d \
  -p 5432:5432 \
  -p 9010:9010 \
  -p 9020:9020 \
  gcr.io/cloud-spanner-pg-adapter/pgadapter-emulator

コンテナの起動時にプロジェクト名、インスタンス名、データベース名を指定する必要はありません。デフォルトでは、プロジェクト名 emulator-project とインスタンス名 test-instance が使用されます。接続するデータベースはすべて、PGAdapter によって自動的に作成されます。

PGAdapter に接続して次のコマンドを含む psql のステートメントを実行します。

psql -h localhost -p 5432 -d test-database

データベース test-database が自動的に作成されます。次のステートメントを実行して、PostgreSQL 言語データベースに接続されていることを確認します。

create table my_table (
  id bigint not null primary key,
  value varchar
);
insert into my_table (id, value) values (1, 'One');
select * from my_table;

gcloud CLI などを使用して Docker コンテナ内のエミュレータに直接接続することもできます。

gcloud config configurations create emulator
gcloud config set auth/disable_credentials true
gcloud config set project emulator-project
gcloud config set api_endpoint_overrides/spanner http://localhost:9020/
gcloud spanner instances list
gcloud spanner databases execute-sql test-database \
  --instance=test-instance \
  --sql="select * from my_table"

エミュレータと PGAdapter をローカルマシンで実行する

エミュレータと PGAdapter の両方をローカルマシンで実行し、次のコマンドを使用して PGAdapter をエミュレータに接続します。

まず、エミュレータを起動します。

gcloud emulators spanner start

次に、PGAdapter を起動してエミュレータに接続します。エミュレータにアクセスするには、PGAdapter をローカルマシンで Java アプリケーションとして起動する必要があります。Docker コンテナで PGAdapter を起動すると、ローカルホストで実行されているエミュレータにアクセスできません。

wget https://storage.googleapis.com/pgadapter-jar-releases/pgadapter.tar.gz \
  && tar -xzvf pgadapter.tar.gz
java -jar pgadapter.jar -p emulator-project -i test-instance \
  -c "" \
  -r autoConfigEmulator=true

エミュレータへの接続に使用される PGAdapter の追加のコマンドライン引数は次のとおりです。

  • -c "": PGAdapter に認証情報を使用しないように指示します。
  • -r autoConfigEmulator=true: PGAdapter に、localhost:9010（デフォルトのエミュレータ ホストとポート）に接続するよう指示します。これによって、PGAdapter にユーザーが接続するデータベースを自動的に作成することも指示します。つまり、データベースに接続する前にデータベースを作成する必要はありません。

PGAdapter に接続して次のコマンドを含む psql のステートメントを実行します。

psql -h localhost -p 5432 -d test-database

データベース test-database が自動的に作成されます。次のステートメントを実行して、PostgreSQL 言語データベースに接続されていることを確認します。

create table my_table (
  id bigint not null primary key,
  value varchar
);
insert into my_table (id, value) values (1, 'One');
select * from my_table;

エミュレータと PGAdapter を Docker ネットワークで実行する

エミュレータと PGAdapter の両方を Docker ネットワークで実行し、次のコマンドを使用して PGAdapter をエミュレータに接続します。

cat <<EOT > docker-compose.yml
version: "3.9"
services:
  emulator:
    image: "gcr.io/cloud-spanner-emulator/emulator"
    pull_policy: always
    container_name: spanner-emulator
    ports:
      - "9010:9010"
      - "9020:9020"
  pgadapter:
    depends_on:
      emulator:
        condition: service_started
    image: "gcr.io/cloud-spanner-pg-adapter/pgadapter"
    pull_policy: always
    container_name: pgadapter-connected-to-emulator
    command:
      - "-p emulator-project"
      - "-i test-instance"
      - "-r autoConfigEmulator=true"
      - "-e emulator:9010"
      - "-c \"\""
      - "-x"
    ports:
      - "5432:5432"
EOT
docker compose up -d

PGAdapter とエミュレータはどちらも同じ Docker ネットワークで起動され、PGAdapter はエミュレータに接続するように構成されます。エミュレータへの接続に使用される PGAdapter の追加のコマンドライン引数は次のとおりです。

  • -c "": PGAdapter に認証情報を使用しないように指示します。
  • -r autoConfigEmulator=true: PGAdapter にユーザーが接続するデータベースを自動的に作成するように指示します。つまり、データベースに接続する前にデータベースを作成する必要はありません。
  • -e emulator:9010: -e は PGAdapter が接続するエンドポイントを指定します。emulator:9010 は、同じ Docker ネットワーク内にあるエミュレータの名前とポート番号です。
  • -x: これにより、ローカルマシンから PGAdapter への接続が可能になります。

PGAdapter に接続して次のコマンドを含む psql のステートメントを実行します。

psql -h localhost -p 5432 -d test-database

データベース test-database が自動的に作成されます。次のステートメントを実行して、PostgreSQL 言語データベースに接続されていることを確認します。

create table my_table (
  id bigint not null primary key,
  value varchar
);
insert into my_table (id, value) values (1, 'One');
select * from my_table;

gcloud CLI などを使用して Docker ネットワーク内のエミュレータに直接接続することもできます。

gcloud config configurations create emulator
gcloud config set auth/disable_credentials true
gcloud config set project emulator-project
gcloud config set api_endpoint_overrides/spanner http://localhost:9020/
gcloud spanner instances list
gcloud spanner databases execute-sql test-database \
  --instance=test-instance \
  --sql="select * from my_table"