Migrar da versão 15.5.2 e anteriores do AlloyDB Omni para a versão mais recente

Esta página contém instruções para migrar da versão 15.5.2 e anteriores para a versão mais recente do AlloyDB Omni.

A partir do AlloyDB Omni 15.5.4, você controla o AlloyDB Omni com ferramentas comuns de gerenciamento de pacotes.

Se você já tiver uma instalação do AlloyDB Omni, siga as instruções desta página para migrar para a nova instalação de imagem única.

Pré-requisitos

Antes de começar a fazer upgrade para a versão mais recente do AlloyDB Omni, conclua os pré-requisitos a seguir, se ainda não tiver feito isso.

Fazer upgrade para o AlloyDB Omni 15.5.2

A versão mais recente do AlloyDB Omni que oferece suporte à CLI do AlloyDB Omni é a 15.5.2. Para verificar a versão do AlloyDB Omni, execute o seguinte comando:

sudo alloydb version

A saída será assim:

AlloyDB Omni CLI version: 1.6
AlloyDB Omni database server version: 15.5.2

Se a saída mostrar uma versão do banco de dados anterior à 15.5.2, execute o comando a seguir para fazer upgrade:

sudo alloydb database-server upgrade

Coletar informações sobre a instalação atual

  1. Execute este comando:

    cat /var/alloydb/config/dataplane.conf

  2. Na saída do comando cat, anote os valores das seguintes variáveis para referência:

    • DATADIR_PATH, por exemplo, /var/alloydb/main
    • ENABLE_ALLOYDB_AI, por exemplo, FALSE
    • PGPORT, por exemplo, 5432
    • INSTANCE_TYPE, por exemplo, PRIMARY/READ_REPLICA

Descartar índices ScaNN criados com a extensão postgres_ann

A extensão postgres_ann foi renomeada como alloyd_scann. Se você instalou a extensão postgres_ann e criou índices ScaNN usando a extensão, é necessário excluir todos os índices ScaNN e desinstalar a extensão antes de fazer um upgrade.

Para lidar com qualquer impacto no seu banco de dados devido à renomeação da extensão postgres_ann, siga estas etapas:

  1. Executar e se conectar ao AlloyDB Omni.

  2. Identifique todas as tabelas que usam o índice ScaNN.

     \c DATABASE_NAME
 select schemaname, relname, indexrelname, indextype, indexconfig, indexsize, indexscan FROM pg_stat_ann_indexes;

    Substitua DATABASE_NAME pelo nome do banco de dados em que você quer executar a consulta.

  3. Salve as definições e os parâmetros do índice como um DDL de despejo usando um utilitário como pg_dump para recriar os índices ScaNN mais tarde.

    pg_dump -st TABLE_NAME DATABASE_NAME

    Substitua:

    • DATABASE_NAME: o nome do banco de dados.
    • TABLE_NAME: o nome da tabela.

  4. Exclua os índices ScaNN criados usando o índice postgres_ann.

    DROP INDEX INDEX_NAME;

    Substitua INDEX_NAME pelo nome do banco de dados em que você quer executar a consulta.

  5. Verifique se nenhum dos seus bancos de dados inclui índices ScaNN. Use a consulta SQL a seguir para verificar a exclusão: o SQL a seguir precisa retornar um conjunto de resultados vazio.

     \c DATABASE_NAME
 select schemaname, relname, indexrelname, indextype, indexconfig, indexsize, indexscan FROM pg_stat_ann_indexes;

  6. Desative a extensão postgres_ann seguindo estas etapas:

    1. Verifique se a extensão postgres_ann está instalada no seu banco de dados.
    select * from pg_extension;
    1. Remova a extensão postgres_ann.
    DROP EXTENSION postgres_ann CASCADE;
    1. Verifique se a extensão postgres_ann não está mais instalada no seu banco de dados.
    select * from pg_extension;

Fazer um upgrade no local

  1. Pare o banco de dados atual:

    sudo alloydb database-server stop

  2. Inicie o novo AlloyDB Omni de imagem única, montando seu diretório de dados anterior:

    docker run --name CONTAINER_NAME \
    -e POSTGRES_PASSWORD=PASSWORD \
    -e PGDATA=/var/lib/postgresql/data \
    -v /var/alloydb/main/data:/var/lib/postgresql/data \
    -v /dev/shm:/dev/shm \
    -p PGPORT:5432 \
    --network=host \
    --ulimit=nice=-20:-20 \
    --ulimit=core=-1:-1 \
    --log-driver=journald \
    -d google/alloydbomni:15.5.5

    Substitua:

    • CONTAINER_NAME: o nome para atribuir a este novo contêiner do AlloyDB Omni no registro de contêineres da máquina host, por exemplo, my-omni.

    • PASSWORD: a senha atribuída ao usuário postgres do novo contêiner após a criação.

    • PGPORT: o endereço IP da porta em que o AlloyDB Omni é executado. Esse é o valor que você anotou na etapa 2 de Coletar informações sobre a instalação atual.

    Os argumentos para docker run são os usados em versões anteriores do AlloyDB Omni, mas você pode personalizá-los ainda mais. Consulte Personalizar a instalação do AlloyDB Omni para saber mais.

  3. Se o tipo de instância do banco de dados for PRIMARY, execute o comando a seguir para criar os usuários abaixo. Esses são nomes de usuário que não estão em uso no momento, mas reservados para extensões futuras.

    for name in alloydbagent alloydbexport alloydbiamgroupuser alloydbiamuser alloydbimportexport alloydbobservability alloydbsqllogical alloydbsuperuser; do
  echo docker exec -it CONTAINER_NAME psql -h localhost -U postgres alloydbadmin \
    -c "CREATE ROLE ${name} NOLOGIN;" \
    -c "CREATE TABLE ${name}_table();" \
    -c "ALTER TABLE ${name}_table OWNER TO ${name};"
done

  4. Se ENABLE_ALLOYDB_AI estiver definido como TRUE, siga as instruções em Instalar o AlloyDB Omni com o AlloyDB AI para configurar o AlloyDB AI.

  5. Conecte-se ao banco de dados para verificar se os dados não foram alterados:

    docker exec -it CONTAINER_NAME psql -h localhost -U postgres

  6. Desinstale a CLI do AlloyDB Omni:

    sudo alloydb database-server uninstall

    A desinstalação da CLI do AlloyDB Omni não afeta os dados armazenados no AlloyDB Omni.

Recriar índices ScaNN usando a extensão alloydb_scann

Depois de fazer upgrade do AlloyDB Omni, a extensão alloydb_scann também é instalada. Siga as etapas abaixo para recriar os índices ScaNN que você excluiu na seção Excluir índices ScaNN criados com a extensão postgres_ann antes do upgrade.

  1. Crie a extensão alloydb_scann seguindo estas etapas:

    1. Para criar a extensão alloydb_scann, execute a seguinte consulta:
    create extension alloydb_scann cascade;
    1. Verifique se a extensão alloydb_scann foi criada. 
    select * from pg_extension;

  2. Recrie o índice ScaNN para a tabela e restaure as definições de índice DDL pg_dump anteriores.

    1. Crie o índice ScaNN na tabela:
    CREATE INDEX INDEX_NAME ON TABLE_NAME
    USING scann (VECTOR_COLUMN DISTANCE)
    WITH (num_leaves = NUM_LEAVES_VALUE);

    Substitua:

    • INDEX_NAME: o nome do índice.
    • TABLE_NAME: o nome da tabela.
    • VECTOR_COLUMN: o nome da coluna que armazena dados vetoriais.
    • DISTANCE: a função de distância a ser usada com esse índice.
    • NUM_LEAVES_VALUE: o número de partições a serem aplicadas ao índice.
    1. Verifique se o índice foi criado.
    \d TABLE_NAME
    1. Recomendado: faça backup dos dados de índices. Recomendamos criar um backup do seu banco de dados e índices como uma prática recomendada.