Criar um slot de replicação e uma publicação

Selecione uma versão da documentação:

Neste documento, descrevemos como criar slots de replicação lógica no AlloyDB Omni. No PostgreSQL, a replicação lógica é um método para copiar mudanças de dados de um banco de dados de editor para um ou mais assinantes, que podem ser bancos de dados ou outros aplicativos. É possível ativar e configurar a replicação lógica em clusters criados com o operador do AlloyDB Omni no Kubernetes.

As mudanças transmitidas podem ser atualizações, inserções ou exclusões de linhas individuais. Os assinantes se conectam ao editor por um slot de replicação exclusivo que garante uma conexão persistente. Uma conexão persistente mantém o estado de streaming de dados. Assim, se ocorrer uma interrupção, o streaming será retomado de onde parou.

Para mais informações sobre a replicação lógica no PostgreSQL, consulte Replicação lógica.

Os snippets de código nesta página são exemplos que podem ser usados como modelos, substituindo os valores pelos dos seus recursos do AlloyDB Omni.

Antes de começar

Criar um cluster de editores

Antes de criar os slots de replicação, é necessário criar o cluster de editor com a replicação lógica ativada. Defina o parâmetro wal_level como logical no manifesto DBCluster.

Para criar um cluster de banco de dados de editor com a replicação lógica ativada, aplique o seguinte manifesto:

  apiVersion: v1
  kind: Secret
  metadata:
    name: db-pw-DB_CLUSTER_NAME
    namespace: DB_CLUSTER_NAMESPACE
  type: Opaque
  data:
    DB_CLUSTER_NAME: "ENCODED_PASSWORD"
  ---
  apiVersion: alloydbomni.dbadmin.goog/v1
  kind: DBCluster
  metadata:
    name: DB_CLUSTER_NAME
    namespace: DB_CLUSTER_NAMESPACE
  spec:
    databaseVersion: "ALLOYDB_OMNI_VERSION"
    spec:
    availability:
      numberOfStandbys: 1
    primarySpec:
      parameters:
        wal_level: "logical"
      adminUser:
        passwordRef:
          name: db-pw-DB_CLUSTER_NAME
      resources:
        cpu: CPU_COUNT
        memory: MEMORY_SIZE
        disks:
        - name: DataDisk
          size: DISK_SIZE

Substitua:

  • DB_CLUSTER_NAME: o nome do cluster de banco de dados, por exemplo, publisher.

  • DB_CLUSTER_NAMESPACE (opcional): o namespace em que você quer criar o cluster de banco de dados. Por exemplo, publisher-namespace.

  • ENCODED_PASSWORD: a senha de login do banco de dados para a função do usuário padrão postgres, codificada como uma string base64. Por exemplo, Q2hhbmdlTWUxMjM= para ChangeMe123.

  • ALLOYDB_OMNI_VERSION: a versão do AlloyDB Omni, 15.7.0 ou mais recente.

  • CPU_COUNT: o número de CPUs disponíveis para cada instância de banco de dados no cluster.

  • MEMORY_SIZE: a quantidade de memória por instância de banco de dados deste cluster de banco de dados. Recomendamos definir isso como 8 gigabytes por CPU. Por exemplo, se você definiu cpu como 2 anteriormente neste manifesto, recomendamos definir memory como 16Gi.

  • DISK_SIZE: o tamanho do disco por instância de banco de dados, por exemplo, 10Gi.

Criar um slot de replicação

Depois de criar o cluster de editor, você pode criar um slot de replicação lógica usando o recurso Replication no cluster de editor. Cada recurso Replication está associado a um recurso de cluster de banco de dados correspondente. Um cluster de banco de dados pode ter vários recursos de replicação lógica associados a ele.

Para configurar um slot de replicação no cluster de publicação, aplique o seguinte manifesto:

$ cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: USER_PASSWORD_SECRET_NAME
  namespace: USER_PASSWORD_SECRET_NAMESPACE
type: Opaque
---
apiVersion: alloydbomni.dbadmin.goog/v1
kind: Replication
metadata:
  name: REPLICATION_NAME
  namespace: NAMESPACE
spec:
  dbcluster:
    name: DB_CLUSTER_NAME
  upstream:
    logicalReplication:
      pluginName: DECODER_PLUGIN
      databaseName: DATABASE_NAME
    applicationName: APPLICATION_NAME
    replicationSlotName: REPLICATION_SLOT_NAME
    synchronous: "REPLICATION_MODE"
    username: APPLICATION_USER
    password:
      name: USER_PASSWORD_SECRET_NAME
      namespace: USER_PASSWORD_SECRET_NAMESPACE
EOF

Substitua:

  • REPLICATION_NAME: um nome para esse recurso Replication. Por exemplo, replication-1.
  • NAMESPACE: o namespace do Kubernetes para este recurso Replication. Ele precisa corresponder ao namespace do cluster de banco de dados.
  • DB_CLUSTER_NAME: o nome do cluster de banco de dados, que você atribuiu ao criá-lo.
  • DECODER_PLUGIN: definido como o plug-in de decodificação, como pgoutput, que você quer usar para replicação lógica. Para mais informações sobre vários plug-ins de decodificação, consulte Plug-ins de saída.
  • DATABASE_NAME: defina como o nome do banco de dados cujas mudanças você quer transmitir para o slot de replicação. Verifique se o banco de dados já foi criado no cluster do editor.
  • APPLICATION_NAME (opcional): defina como o nome do aplicativo que se conectará ao slot de replicação. Esse campo é obrigatório quando o modo de streaming está definido como síncrono.
  • REPLICATION_MODE (opcional): defina como false para replicação assíncrona. Se você quiser ativar a replicação síncrona, mas à custa da velocidade, defina esse valor como true. O valor padrão é false, se não for definido explicitamente.
  • REPLICATION_SLOT_NAME: o nome do slot de replicação que será criado e usado pelo assinante. Por exemplo, logicalrepltestslot.
  • REPLICATION_USER (opcional): o nome do usuário que se conecta ao slot de replicação. Se você definir o usuário de replicação, será necessário definir o nome do secret, o namespace e a senha.
  • USER_PASSWORD_SECRET_NAME (opcional): o nome do secret do Kubernetes do usuário do aplicativo. Obrigatório se o usuário do aplicativo estiver definido.
  • USER_PASSWORD_SECRET_NAMESPACE (opcional): o namespace em que o secret do Kubernetes para o usuário do aplicativo está localizado. Obrigatório se o usuário do aplicativo estiver definido.

Ver o status do slot de replicação

Para conferir o status dos slots de replicação, execute o comando a seguir:

kubectl get replication.alloydbomni.dbadmin.goog REPLICATION_NAME -n NAMESPACE -oyaml

O campo status e outros detalhes estão incluídos na resposta:

apiVersion: alloydbomni.dbadmin.goog/v1
kind: Replication
metadata:
  name: REPLICATION_NAME
  namespace: NAMESPACE
...
...
status:
  conditions:
  - lastTransitionTime: "2025-01-25T06:49:25Z"
    message: Ready for replication
    reason: Ready
    status: "True"
    type: Ready
  - lastTransitionTime: "2025-01-25T06:49:25Z"
    message: Replication slot is not being used
    reason: Unhealthy
    status: "False"
    type: Healthy
  observedGeneration: 2
  upstream:
    host: DATABASE_ENDPOINT
    password:
      name: USER_PASSWORD_SECRET_NAME
      namespace: USER_PASSWORD_SECRET_NAMESPACE
    port: DATABASE_PORT
    replicationSlotName: REPLICATION_SLOT_NAME
    username: APPLICATION_USER

O DATABASE_ENDPOINT mostra o endereço IP que você usa para se conectar ao banco de dados. O status TRUE na coluna READY indica que o slot está pronto para transmissão. Quando o DBCluster ou o aplicativo assinante se conecta ao slot de replicação, o status na coluna HEALTHY muda para TRUE.

Configurar o cluster do editor

  1. Encontre o pod que você precisa.

    $ kubectl get pod -l "alloydbomni.internal.dbadmin.goog/dbcluster=DB_CLUSTER_NAME, alloydbomni.internal.dbadmin.goog/task-type=database, dbs.internal.dbadmin.goog/ha-role=Primary"

  2. Conecte-se ao pod principal no cluster do editor usando psql:

    psql -h IP_ADDRESS -U USERNAME -d DATABASE_NAME

    Substitua:

    • IP_ADDRESS: o endereço IP do pod principal do cluster do editor.
    • USERNAME: o usuário do Postgres do banco de dados.
    • DATABASE_NAME: o banco de dados em que o assinante quer se inscrever.

  3. Se o DATABASE_NAME especificado no recurso de replicação não existir, crie um banco de dados.

    CREATE DATABASE DATABASE_NAME;

  4. Opcional: para fins de teste, adicione uma tabela ao banco de dados e insira alguns dados. Você pode usar esses dados para observar a replicação do editor para o assinante.

    $ psql -h localhost -U postgres DATABASE_NAME
customer=# CREATE TABLE TABLE_NAME(
customer(#    ID INT PRIMARY KEY     NOT NULL,
customer(#    NAME           TEXT    NOT NULL,
customer(#    AGE            INT     NOT NULL,
customer(#    SALARY         REAL
customer(# );
CREATE TABLE
customer=# INSERT INTO TABLE_NAME (ID,NAME,AGE,SALARY) VALUES
customer-# (1, 'Quinn', 25, 65000.00),
customer-# (2, 'Kim', 22, 72250.00),
customer-# (3, 'Bola', 31, 53000.00),
customer-# (4, 'Sasha', 33, 105000.00),
customer-# (5, 'Yuri', 27, 85000.00);
INSERT 0 5
customer=# \dt
          List of relations
Schema |  Name   | Type  |  Owner
--------+---------+-------+----------
public | company | table | postgres
(1 row)

customer=# select * from TABLE_NAME;
id | name  | age | salary
----+-------+-----+--------
  1 | Quinn  |  25 |  65000
  2 | Kim  |  22 |  72250
  3 | Bola   |  31 |  53000
  4 | Sasha |  33 | 105000
  5 | Yuri |  27 |  85000
(5 rows)

    Substitua TABLE_NAME por uma tabela em que você quer armazenar os dados e a que o assinante se inscreve.

  5. Conceda as permissões:

    GRANT SELECT ON ALL TABLES IN SCHEMA public TO REPLICATION_USER;
GRANT USAGE ON SCHEMA public TO REPLICATION_USER;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO REPLICATION_USER;

  6. Crie a publicação executando o seguinte comando:

    CREATE PUBLICATION PUBLICATION_NAME;
ALTER PUBLICATION PUBLICATION_NAME ADD TABLE TABLE_NAME;

    Substitua:

    • PUBLICATION_NAME: o nome da publicação que o assinante vai usar para se inscrever.

Depois de criar a publicação, você pode configurar seu cluster de assinantes para replicação lógica ou configurar o aplicativo para iniciar a replicação.

Limitações

  • Não é possível atualizar a configuração do slot de replicação. Para atualizar a configuração, descarte o slot de replicação e recrie-o com a configuração atualizada.

    Para descartar o slot de replicação, execute o seguinte comando:

    kubectl delete replication.alloydbomni.dbadmin.goog REPLICATION_NAME -n NAMESPACE

  • Só é possível configurar o slot de replicação lógica no banco de dados publisher. A API de replicação não é compatível com DBCluster ou aplicativos assinantes de replicação lógica.

  • Se o cluster de banco de dados referenciado pelo objeto de replicação estiver configurado para alta disponibilidade, o slot de replicação lógica será recriado no standby promovido após um failover. Depois que o slot de replicação é recriado, a posição do stream no slot não fica mais disponível, e todos os aplicativos inscritos no stream precisam se reconectar e reproduzir o stream novamente.

A seguir