Connect PGAdapter to the emulator

This page shows how to connect PGAdapter to the Spanner emulator. The emulator runs locally, and you can use to it to develop and test your applications without creating a Google Cloud project or a billing account. As the emulator stores data only in memory, all state, including data, schema, and configs, is lost on restart. The emulator offers the same APIs as the Spanner production service and is intended for local development and testing, not for production deployments.

You can connect PGAdapter to the emulator in three different ways:

  • Run a prebuilt combined Docker container with both PGAdapter and the emulator.
  • Run both the emulator and PGAdapter on your local machine.
  • Run both the emulator and PGAdapter in a Docker network.

Combined Docker container

Run the prebuilt Docker image that contains both PGAdapter and the emulator. The PGAdapter instance in the Docker container is automatically configured to connect to the emulator in the container.

Start the Docker container with the following command.

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

You don't need to specify a project, instance, or database name when starting the container. It will by default use the project name emulator-project and instance name test-instance. Any database that you connect to is automatically created by PGAdapter.

You can connect to PGAdapter and execute statements with psql with the following command.

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

The database test-database is automatically created. Execute these statements to verify that you are connected to a PostgreSQL-dialect database database:

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;

You can also connect directly to the emulator inside the Docker container, for example with the gcloud CLI.

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"

Run the emulator and PGAdapter on your local machine

You can run both the emulator and PGAdapter on your local machine, and connect PGAdapter to the emulator with the following commands.

First start the emulator.

gcloud emulators spanner start

Then start PGAdapter and connect it to the emulator. Note that you must start PGAdapter as a Java application on your local machine for it to be able to access the emulator. If you start PGAdapter in a Docker container, it isn't able to access the emulator that is running on your local host.

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

The additional command-line arguments for PGAdapter that are used to connect to the emulator are:

  • -c "": This instructs PGAdapter to not use any credentials.
  • -r autoConfigEmulator=true: This instructs PGAdapter to connect to localhost:9010, which is the default emulator host and port. It also instructs PGAdapter to automatically create any database that a user connects to. This means that you don't need to create a database before connecting to it.

You can connect to PGAdapter and execute statements with psql with the following command.

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

The database test-database is automatically created. Execute these statements to verify that you are connected to a PostgreSQL-dialect database database:

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;

Run the emulator and PGAdapter in a Docker network

You can run both the emulator and PGAdapter in a Docker network and connect PGAdapter to the emulator with the following commands.

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

Both PGAdapter and the emulator are started in the same Docker network, and PGAdapter is configured to connect to the emulator. The additional command-line arguments for PGAdapter that are used to connect to the emulator are:

  • -c "": This instructs PGAdapter to not use any credentials.
  • -r autoConfigEmulator=true: This instructs PGAdapter to automatically create any database that a user connects to. This means that you don't need to create a database before connecting to it.
  • -e emulator:9010: -e specifies the endpoint that PGAdapter should connect to. emulator:9010 is the name and port number of the emulator in the same Docker network.
  • -x: This allows connections to PGAdapter from your local machine.

You can connect to PGAdapter and execute statements with psql with the following command.

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

The database test-database is automatically created. Execute these statements to verify that you are connected to a PostgreSQL-dialect database database:

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;

You can also connect directly to the emulator in the Docker network, for example with the gcloud CLI.

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"