Online DDL (rds_online_ddl) - ApsaraDB RDS: Central de Documentação do Alibaba Cloud

Alterar uma coluna para um tipo não compatível em binário — como converter uma coluna int4 para int8 — força o PostgreSQL a reescrever a tabela inteira. Durante a reescrita, a tabela é bloqueada e todas as leituras e gravações ficam suspensas. Embora muitas operações DDL no PostgreSQL (como CREATE INDEX CONCURRENTLY) suportem execução concorrente, alterações de tipo de coluna não compatíveis em binário ainda exigem uma reescrita completa da tabela com bloqueio. A extensão rds_online_ddl elimina essa janela de bloqueio, permitindo alterar tipos de colunas em tabelas ativas sem interromper o tráfego da aplicação.

Pré-requisitos

Antes de começar, verifique se sua instância atende a todos os requisitos abaixo:

Versão principal do engine: PostgreSQL 12 ou posterior
Versão secundária do engine: 20250830 ou posterior
Parâmetro da instância: wal_level está definido como logical. Para alterar esse parâmetro, consulte Modificar parâmetros da instância.
Schema da tabela: A tabela de destino possui uma chave primária ou uma constraint UNIQUE
Conta: Uma conta privilegiada está criada na instância

Instalar e remover a extensão

Importante

Execute esses comandos usando uma conta privilegiada.

Instalar:

CREATE EXTENSION rds_online_ddl;

Para verificar a instalação, execute:

SELECT * FROM pg_extension;

Remover:

DROP EXTENSION rds_online_ddl;

Alterar o tipo de uma coluna online

Chame rds_online_ddl.alter_table() com o nome completo da tabela e uma instrução ALTER TABLE:

SELECT rds_online_ddl.alter_table('<schema>.<table>', '<ALTER TABLE statement>');

Parâmetro	Descrição
`<schema>.<table>`	Nome completo da tabela, por exemplo `public.orders`
`<ALTER TABLE statement>`	Uma cláusula padrão `ALTER COLUMN ... TYPE`, por exemplo `ALTER COLUMN id TYPE int8`

Exemplo: atualizar uma coluna inteira de int4 para int8

Crie uma tabela de teste e carregue dados de amostra.

CREATE TABLE test (id int4 PRIMARY KEY, info TEXT);
INSERT INTO test SELECT x, repeat(x::text, 2) FROM generate_series(1, 1000000) AS x;

Execute a alteração online do tipo da coluna.

SELECT rds_online_ddl.alter_table('public.test', 'ALTER COLUMN id TYPE int8');

(Opcional) Monitore o progresso. Em tabelas grandes, a operação pode levar bastante tempo. Para acompanhar o status, consulte a view de progresso:

Campo	Descrição
`insert_initial`	Linhas de dados históricos copiadas até o momento
`nindexes_built`	Índices criados na tabela temporária
`nindexes_total`	Total de índices a criar
`insert_applied` / `update_applied` / `delete_applied`	Alterações incrementais aplicadas por tipo de operação
`insert_decoded` / `update_decoded` / `delete_decoded`	Alterações incrementais decodificadas por tipo de operação

SELECT * FROM rds_online_ddl.pg_stat_progress_online_ddl;

Antes de executar em produção

Teste primeiro. Execute a mesma operação em um ambiente de teste e verifique os resultados antes de aplicar em dados de produção.
Verifique o espaço em disco. A operação requer espaço livre equivalente a pelo menos 2x o tamanho total da tabela e seus índices. Por exemplo, se a tabela e seus índices somam 10 GB, tenha ao menos 20 GB livres.
Faça backup dos seus dados. Confirme que existe um backup válido antes de prosseguir.

Como funciona

A extensão evita bloqueios prolongados na tabela operando sobre uma cópia temporária e substituindo-a ao final. O bloqueio exclusivo na etapa 6 é mantido apenas pelo tempo necessário para a troca.

O processo completo:

Crie uma tabela temporária com o mesmo schema da tabela original.
Execute a operação ALTER COLUMN TYPE especificada na tabela temporária.
Copie os dados históricos da tabela original para a tabela temporária.
Crie todos os índices da tabela original na tabela temporária.
Use decodificação lógica para sincronizar as alterações incrementais (inserções, atualizações e exclusões) geradas durante as etapas anteriores na tabela temporária, garantindo a consistência final dos dados.
Adquira um bloqueio exclusivo breve na tabela original e atualize seu schema.
Troque os arquivos subjacentes da tabela original pelos da tabela temporária, incluindo todos os índices.
Exclua a tabela temporária e confirme a transação.

A operação é atômica. Se falhar ou for interrompida em qualquer ponto, a tabela retorna automaticamente ao schema original — nenhuma recuperação manual é necessária.

Limitações

Limitação	Detalhes
Tipos de tabela não suportados	Tabelas com constraints de chave estrangeira não são suportadas. Tabelas particionadas não são suportadas. Apenas tabelas regulares são suportadas.
Armazenamento	Requer aproximadamente 2x o tamanho total da tabela original e seus índices em espaço livre em disco.
Cláusula `USING`	A cláusula `USING` do `ALTER TABLE` pode não ser totalmente suportada devido a limitações da replicação lógica. Teste em um ambiente que não seja de produção antes de usar em produção.

Solução de problemas

Sintoma	Causa provável	Resolução
`alter_table()` falha imediatamente	A tabela de destino não possui chave primária ou constraint UNIQUE	Adicione uma constraint `PRIMARY KEY` ou `UNIQUE` à tabela antes de executar a operação
`alter_table()` falha imediatamente	`wal_level` não está definido como `logical`	Defina `wal_level` como `logical` nos parâmetros da instância e reinicie a instância
Erro de espaço em disco insuficiente	O espaço livre em disco é inferior a 2x o tamanho da tabela	Libere espaço em disco ou expanda o armazenamento da instância antes de prosseguir

Faturamento

A extensão rds_online_ddl é gratuita.