Conectar o PGAdapter ao emulador

Esta página mostra como conectar o PGAdapter ao emulador do Spanner. O emulador é executado localmente e pode ser usado para desenvolver e testar seus aplicativos sem criar um Google Cloud projeto ou uma conta de faturamento. Como o emulador armazena dados apenas na memória, todo o estado, incluindo dados, esquema e configurações, é perdido na reinicialização. O emulador oferece as mesmas APIs que o serviço de produção do Spanner e destina-se ao desenvolvimento e teste locais, não para implantações de produção.

É possível conectar o PGAdapter ao emulador de três maneiras diferentes:

  • Execute um contêiner Docker combinado predefinido com o PGAdapter e o emulador.
  • Execute o emulador e o PGAdapter na sua máquina local.
  • Execute o emulador e o PGAdapter em uma rede do Docker.

Contêiner do Docker combinado

Execute a imagem pré-criada do Docker que contém o PGAdapter e o emulador. A instância do PGAdapter no contêiner do Docker é configurada automaticamente para se conectar ao emulador no contêiner.

Inicie o contêiner do Docker com o comando a seguir.

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

Não é necessário especificar um projeto, uma instância ou um nome de banco de dados ao iniciar o contêiner. Por padrão, ele vai usar o nome do projeto emulator-project e o nome da instância test-instance. Qualquer banco de dados ao qual você se conecta é criado automaticamente pelo PGAdapter.

É possível se conectar ao PGAdapter e executar instruções com psql usando o comando abaixo.

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

O banco de dados test-database é criado automaticamente. Execute estas instruções para verificar se você está conectado a um banco de dados de dialetos do 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;

Também é possível se conectar diretamente ao emulador dentro do contêiner do Docker, por exemplo, com a CLI 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"

Execute o emulador e o PGAdapter na sua máquina local

É possível executar o emulador e o PGAdapter na máquina local e conectar o PGAdapter ao emulador com os comandos abaixo.

Primeiro, inicie o emulador.

gcloud emulators spanner start

Em seguida, inicie o PGAdapter e conecte-o ao emulador. É necessário iniciar o PGAdapter como um aplicativo Java na máquina local para que ele possa acessar o emulador. Se você iniciar o PGAdapter em um contêiner do Docker, ele não poderá acessar o emulador em execução no 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

Os argumentos de linha de comando adicionais para o PGAdapter que são usados para se conectar ao emulador são:

  • -c "": instrui o PGAdapter a não usar credenciais.
  • -r autoConfigEmulator=true: instrui o PGAdapter a se conectar a localhost:9010, que é o host e a porta padrão do emulador. Ele também instruí o PGAdapter a criar automaticamente qualquer banco de dados ao qual um usuário se conecte. Isso significa que você não precisa criar um banco de dados antes de se conectar a ele.

É possível se conectar ao PGAdapter e executar instruções com psql usando o comando abaixo.

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

O banco de dados test-database é criado automaticamente. Execute estas instruções para verificar se você está conectado a um banco de dados do 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;

Executar o emulador e o PGAdapter em uma rede do Docker

É possível executar o emulador e o PGAdapter em uma rede Docker e conectar o PGAdapter ao emulador com os comandos abaixo.

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

O PGAdapter e o emulador são iniciados na mesma rede do Docker, e o PGAdapter é configurado para se conectar ao emulador. Os argumentos adicionais de linha de comando para o PGAdapter que são usados para se conectar ao emulador são:

  • -c "": instrui o PGAdapter a não usar credenciais.
  • -r autoConfigEmulator=true: instrui o PGAdapter a criar automaticamente qualquer banco de dados ao qual um usuário se conecte. Isso significa que você não precisa criar um banco de dados antes de se conectar a ele.
  • -e emulator:9010: -e especifica o endpoint ao qual o PGAdapter precisa se conectar. emulator:9010 é o nome e o número da porta do emulador na mesma rede do Docker.
  • -x: permite conexões com o PGAdapter da sua máquina local.

É possível se conectar ao PGAdapter e executar instruções com psql usando o comando abaixo.

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

O banco de dados test-database é criado automaticamente. Execute estas instruções para verificar se você está conectado a um banco de dados de dialetos do 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;

Também é possível se conectar diretamente ao emulador na rede Docker, por exemplo, com a CLI 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"