Conectar PGAdapter al emulador

En esta página se muestra cómo conectar PGAdapter al emulador de Spanner. El emulador se ejecuta de forma local y puedes usarlo para desarrollar y probar tus aplicaciones sin crear unGoogle Cloud proyecto ni una cuenta de facturación. Como el emulador solo almacena datos en la memoria, todo el estado, incluidos los datos, el esquema y las configuraciones, se pierde al reiniciar. El emulador ofrece las mismas APIs que el servicio de producción de Spanner y está diseñado para el desarrollo y las pruebas locales, no para las implementaciones de producción.

Puedes conectar PGAdapter al emulador de tres formas diferentes:

  • Ejecuta un contenedor Docker combinado prediseñado con PGAdapter y el emulador.
  • Ejecuta el emulador y PGAdapter en tu máquina local.
  • Ejecuta el emulador y PGAdapter en una red Docker.

Contenedor Docker combinado

Ejecuta la imagen Docker prediseñada que contiene tanto PGAdapter como el emulador. La instancia de PGAdapter del contenedor Docker se configura automáticamente para conectarse al emulador del contenedor.

Inicia el contenedor Docker con el siguiente comando.

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

No es necesario que especifiques el nombre de un proyecto, una instancia o una base de datos al iniciar el contenedor. De forma predeterminada, se usará el nombre del proyecto emulator-project y el nombre de la instancia test-instance. PGAdapter crea automáticamente cualquier base de datos a la que te conectes.

Puedes conectarte a PGAdapter y ejecutar instrucciones con psql con el siguiente comando.

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

La base de datos test-database se crea automáticamente. Ejecuta estas instrucciones para verificar que te has conectado a una base de datos con dialecto 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;

También puedes conectarte directamente al emulador dentro del contenedor Docker, por ejemplo, con la CLI de gcloud.

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"

Ejecutar el emulador y PGAdapter en tu máquina local

Puedes ejecutar tanto el emulador como PGAdapter en tu máquina local y conectar PGAdapter al emulador con los siguientes comandos.

Primero, inicia el emulador.

gcloud emulators spanner start

A continuación, inicia PGAdapter y conéctalo al emulador. Ten en cuenta que debes iniciar PGAdapter como una aplicación Java en tu máquina local para que pueda acceder al emulador. Si inicias PGAdapter en un contenedor de Docker, no podrá acceder al emulador que se esté ejecutando en tu host local.

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

Los argumentos de línea de comandos adicionales de PGAdapter que se usan para conectarse al emulador son los siguientes:

  • -c "": indica a PGAdapter que no use ninguna credencial.
  • -r autoConfigEmulator=true: indica a PGAdapter que se conecte a localhost:9010, que es el host y el puerto predeterminados del emulador. También indica a PGAdapter que cree automáticamente cualquier base de datos a la que se conecte un usuario. Esto significa que no es necesario crear una base de datos antes de conectarse a ella.

Puedes conectarte a PGAdapter y ejecutar instrucciones con psql con el siguiente comando.

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

La base de datos test-database se crea automáticamente. Ejecuta estas instrucciones para verificar que te has conectado a una base de datos con dialecto 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;

Ejecutar el emulador y PGAdapter en una red Docker

Puedes ejecutar tanto el emulador como PGAdapter en una red Docker y conectar PGAdapter al emulador con los siguientes comandos.

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

Tanto PGAdapter como el emulador se inician en la misma red Docker y PGAdapter se configura para conectarse al emulador. Los argumentos de línea de comandos adicionales de PGAdapter que se usan para conectarse al emulador son los siguientes:

  • -c "": indica a PGAdapter que no use ninguna credencial.
  • -r autoConfigEmulator=true: indica a PGAdapter que cree automáticamente cualquier base de datos a la que se conecte un usuario. Esto significa que no es necesario crear una base de datos antes de conectarse a ella.
  • -e emulator:9010: -e especifica el endpoint al que debe conectarse PGAdapter. emulator:9010 es el nombre y el número de puerto del emulador en la misma red de Docker.
  • -x: permite las conexiones a PGAdapter desde tu máquina local.

Puedes conectarte a PGAdapter y ejecutar instrucciones con psql con el siguiente comando.

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

La base de datos test-database se crea automáticamente. Ejecuta estas instrucciones para verificar que te has conectado a una base de datos con dialecto 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;

También puedes conectarte directamente al emulador en la red Docker, por ejemplo, con la CLI de gcloud.

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"