Configurar slots de replicação usando o operador AlloyDB Omni no Kubernetes

Este documento descreve como criar slots de replicação lógica no AlloyDB Omni. A replicação lógica no AlloyDB Omni é usada para transmitir continuamente mudanças de dados específicas do banco de dados de origem (editor) para outros bancos de dados ou aplicativos (assinantes). 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. Portanto, 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.

Configurar o cluster do editor e do assinante

Antes de criar os slots de replicação, é necessário criar o cluster de emissor e assinante com a replicação lógica ativada. O parâmetro wal_level precisa ser definido como logical nos respectivos manifestos.

Para criar um cluster de banco de dados do editor com a replicação lógica ativada, crie e aplique um manifesto DBCluster.

Confira a seguir um exemplo de manifesto do editor:

apiVersion: v1
kind: Secret
metadata:
  name: db-pw-mydbc
type: Opaque
data:
  mydbc: "Q2hhbmdlTWUxMjM="
---
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: mydbc
spec:
  databaseVersion: "15.7.0"
  spec:
  availability:
    numberOfStandbys: 1
  primarySpec:
    parameters:
      wal_level: "logical"
    adminUser:
      passwordRef:
        name: db-pw-mydbc
    resources:
      cpu: 1
      memory: 8Gi
      disks:
      - name: DataDisk
        size: 10Gi

Para criar um cluster de banco de dados de assinante com a replicação lógica ativada, crie e aplique um manifesto DBCluster.

Confira a seguir um exemplo de manifesto do assinante:

apiVersion: v1
kind: Secret
metadata:
  name: db-pw-subscriber
type: Opaque
data:
  subscriber: "Q2hhbmdlTWUxMjM=" #ChangeMe123
---
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: subscriber
spec:
  databaseVersion: "15.7.0"
  primarySpec:
    parameters:
      wal_level: "logical"
    adminUser:
      passwordRef:
        name: db-pw-subscriber
    resources:
      memory: 10Gi
      cpu: 1
      disks:
      - name: DataDisk
        size: 40Gi
—

Criar um slot de replicação

Depois de criar os clusters de editor e assinante, é possível criar um slot de replicação lógica usando o recurso Replication no cluster de editor. Cada recurso Replication é 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 do editor, aplique o seguinte manifesto:

apiVersion: v1
kind: Secret
metadata:
  name: USER_PASSWORD_SECRET_NAME
  namespace: USER_PASSWORD_SECRET_NAMESPACE
type: Opaque
data:
  rep-user-pw: BASE64_ENCODED_PASSWORD
---
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

Substitua:

  • REPLICATION_NAME: um nome para esse recurso Replication, por exemplo, replication-1.
  • NAMESPACE: o namespace do Kubernetes para esse recurso Replication. Ele precisa corresponder ao namespace do cluster do banco de dados.
  • DB_CLUSTER_NAME: o nome do cluster do banco de dados, atribuído quando você o criou.
  • DECODER_PLUGIN: definido como o plug-in de decodificação, como pgoutput, que você quer usar para a replicação lógica. Para mais informações sobre os vários plug-ins de decodificação, consulte Plug-ins de saída.
  • DATABASE_NAME: definido como o nome do banco de dados com as alterações que 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): definido como o nome do aplicativo que vai se conectar ao slot de replicação. Este campo é obrigatório quando o modo de streaming está definido como síncrono.
  • REPLICATION_MODE (opcional): definido como false para replicação assíncrona. Se você quiser ativar a replicação síncrona, mas com a desvantagem de 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.
  • 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 secreto, 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 segredo do Kubernetes para o usuário do aplicativo está localizado. Obrigatório, se o usuário do aplicativo estiver definido.
  • BASE64_ENCODED_PASSWORD (opcional): a senha codificada em base64 do usuário do aplicativo. Obrigatório, se o usuário do aplicativo estiver definido.

Conceder permissões ao usuário da replicação

Para conceder permissões de replicação e publicação ao usuário de replicação no cluster do editor, siga estas etapas:

  1. 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 postgres do banco de dados.
    • DATABASE_NAME: o banco de dados em que o assinante quer se inscrever.
  2. 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;
    

Criar publicação e assinatura

Criar publicação

Para criar uma publicação no cluster do editor, siga estas etapas:

  1. 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 postgres do banco de dados.
    • DATABASE_NAME: o banco de dados em que o assinante quer se inscrever.
  2. 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 assinar.
    • TABLE_NAME: a tabela em que o assinante quer se inscrever.

Criar assinatura

Para criar uma assinatura no cluster de assinantes, siga estas etapas:

  1. Conecte-se ao pod principal no cluster de assinantes usando psql:

    psql -h IP_ADDRESS -U USERNAME -d DATABASE_NAME

    Substitua:

    • IP_ADDRESS: o endereço IP do pod principal do cluster de assinantes.
    • USERNAME: o usuário postgres do banco de dados.
    • DATABASE_NAME: o banco de dados em que o assinante quer se inscrever.
  2. Crie uma assinatura executando o seguinte comando:

    CREATE SUBSCRIPTION SUBSCRIPTION_NAME CONNECTION 'host=IP_ADDRESS port=PORT user=REPLICATION_USER dbname=DATABASE_NAME password=PASSWORD sslmode=require' PUBLICATION PUBLICATION_NAME WITH (slot_name=REPLICATION_SLOT_NAME, create_slot=false);
    
    alter subscription SUBSCRIPTION_NAME refresh publication ;
    

    Substitua:

    • SUBSCRIPTION_NAME: o nome da assinatura.
    • IP_ADDRESS: o endereço IP do pod principal do cluster do editor.

Todas as atualizações na tabela do cluster do editor são replicadas na tabela do cluster do assinante.

Conferir o status do slot de replicação

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

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

O campo status e outros detalhes sã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 usado para se conectar ao banco de dados. O status TRUE na coluna READY indica que o slot está pronto para streaming. Quando o aplicativo se conecta ao slot de replicação, o status na coluna HEALTHY muda para TRUE.

Limitações

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

    Para excluir 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 do editor. As configurações do assinante não são compatíveis.

  • 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 na reserva promovida após um failover. Depois que o slot de replicação é recriado, a posição do stream no slot não está mais disponível, e todos os apps que se inscreveram no stream precisam se reconectar e reproduzir o stream.

A seguir