Migração de região

A migração de região move um projeto existente da região em que foi criado para outra. Você recorre a ela quando seu tráfego se aproximou de outra região (menor latência de ida e volta), ou quando um requisito de conformidade ou de residência de dados exige que seus dados fiquem em uma jurisdição específica.

A migração muda onde seus dados ficam, não o que eles são. Seus branches, roles, bancos de dados e as linhas dentro deles são todos transferidos. A única coisa que muda no lado do cliente é o host na sua string de conexão — seu projeto aterrissa em um novo host de endpoint na região de destino, então sua DATABASE_URL precisa ser reapontada assim que a transição for concluída.

How it works

Uma migração gerenciada roda como uma cópia controlada e validada, com uma transição explícita que você aprova. As etapas:

1. Congelamento — o projeto de origem é colocado brevemente em um estado somente leitura / suspenso para que a cópia tenha um alvo consistente e imóvel.
2. Dump — um dump lógico de cada branch é tirado da região de origem.
3. Transferência — o dump é movido para a região de destino via TLS.
4. Restauração — o dump é restaurado em um projeto recém-provisionado na região de destino.
5. Validação — o destino é verificado quanto à equivalência byte a byte com a origem: a impressão digital do esquema, as contagens de linhas por tabela e as somas de verificação de conteúdo devem todas coincidir antes de a migração ser oferecida para a transição.
6. Confirmação — nada comuta automaticamente. Você revisa os resultados da validação e confirma explicitamente a transição.
7. Transição — os endpoints ativos do projeto são reapontados para a região de destino. O host da string de conexão muda.

Se você cancelar antes da transição, ou se a validação falhar em qualquer etapa, a migração reverte: o andaime de destino é descartado e o projeto de origem é retirado de seu estado somente leitura, intacto.

Size guidance

A janela somente leitura escala com o tamanho dos seus dados:

• Menos de 10 GB — normalmente conclui em menos de 15 minutos.
• 10–100 GB — uma janela estendida; planeje um período somente leitura mais longo e agende-o fora dos horários de pico.
• Mais de 100 GB — entre em contato com o suporte para uma migração assistida. Projetos grandes são migrados com um runbook prático em vez do fluxo de autoatendimento.

Managed migration (console)

A migração de região gerenciada está sendo lançada gradualmente. O assistente descrito aqui está sendo habilitado progressivamente; se você ainda não vê Migrate region nas configurações do seu projeto, use o runbook manual abaixo, que funciona em todos os projetos hoje.

O assistente do console percorre o fluxo acima:

1. Abra o projeto e vá em Settings → Migrate region.
2. Selecionar destino — escolha a região de destino no menu suspenso. A região atual é exibida para referência.
3. Revisar o impacto — o assistente resume o que está prestes a acontecer: a janela somente leitura que o projeto vai experimentar, e o fato de que o host da string de conexão muda na transição.
4. Monitorar o progresso — cada branch mostra seu próprio progresso por dump → transferência → restauração. O assistente transmite o status enquanto a migração roda.
5. Revisar a validação — quando a cópia é concluída, os resultados da validação são exibidos por branch: coincidência da impressão digital do esquema, da contagem de linhas e da soma de verificação.
6. Confirmar a troca — assim que a validação estiver verde, confirme a transição. Este é o ponto sem retorno automático.
7. Atualizar DATABASE_URL — após a transição, copie a nova string de conexão do cartão de endpoint e atualize a DATABASE_URL da sua aplicação. O host mudou; todo o resto é igual.

Manual migration runbook

Este runbook funciona hoje, em qualquer plano. Ele usa ferramentas padrão do Postgres e as strings de conexão públicas, então não tem dependência do fluxo gerenciado. O formato é: subir um novo projeto na região de destino, copiar os dados com pg_dump / pg_restore, verificar, depois reapontar e excluir o projeto antigo.

1. Create the destination project

Crie um novo projeto na região de destino (console New project, ou a API). Faça corresponder a versão maior do Postgres do projeto de origem. Anote a string de conexão do novo projeto a partir do cartão de endpoint.

2. Dump the source

Faça o dump a partir da string de conexão do projeto de origem no formato custom. --no-owner e --no-privileges mantêm o dump portável entre os roles recém-criados no destino:

pg_dump \
  --format=custom \
  --no-owner \
  --no-privileges \
  "postgresql://app:SOURCE_PWD@ep_SOURCE.kisenon.com:5432/main?sslmode=require" \
  --file=migration.dump

3. Restore into the destination

Restaure na string de conexão do projeto de destino. --single-transaction mais --exit-on-error torna a restauração tudo-ou-nada: se algo falhar, o destino fica limpo em vez de carregado pela metade:

pg_restore \
  --no-owner \
  --no-privileges \
  --single-transaction \
  --exit-on-error \
  --dbname "postgresql://app:DEST_PWD@ep_DEST.kisenon.com:5432/main?sslmode=require" \
  migration.dump

4. Verify

Confirme que o destino coincide com a origem antes de fazer a transição. Compare as contagens de linhas por tabela contra ambas as strings de conexão:

SELECT relname, n_live_tup
FROM pg_stat_user_tables
ORDER BY relname;

Para uma verificação mais forte, faça uma checagem por amostragem das somas de verificação de conteúdo nas tabelas mais importantes. Execute isto contra a origem e o destino e compare os resultados:

SELECT md5(string_agg(t::text, '' ORDER BY t)) AS checksum
FROM my_table AS t;

Contagens de linhas e somas de verificação coincidentes significam que os dados foram transferidos intactos.

5. Cut over and clean up

Reaponte a DATABASE_URL da sua aplicação para a string de conexão do destino. Assim que você confirmar que a aplicação está saudável contra o novo projeto, exclua o projeto antigo para parar de ser cobrado por ele:

keon projects delete <old-project-id>

Excluir um projeto é irreversível — faça isso apenas depois de verificar o destino e transferir todo o tráfego para ele.

FAQ

How much downtime should I expect?

Para uma migração gerenciada, a única interrupção é a janela somente leitura durante a cópia — as escritas são pausadas, as leituras continuam. A janela escala com o tamanho dos dados (veja orientação de tamanho): menos de 15 minutos para projetos abaixo de 10 GB, mais longa para os maiores. Para o runbook manual, o tempo de inatividade é a janela que você escolhe para parar as escritas enquanto faz o dump, restaura e verifica.

Can I cancel a migration?

Sim — a qualquer momento antes da transição final. Cancelar descarta o andaime de destino e devolve o projeto de origem ao normal; a origem nunca é modificada até você confirmar a troca, então um cancelamento deixa você exatamente onde começou.

What happens to my branches?

Cada branch é migrado. Esteja ciente de que um dump-and-restore lógico achata o histórico copy-on-write: cada branch é transferido com seus dados atuais, mas a relação fork-at-LSN entre um branch filho e seu pai não é preservada — os branches de destino começam do zero a partir dos dados migrados em vez de compartilhar páginas. Os dados estão intactos; a linhagem de armazenamento compartilhado não.

Do my passwords and roles survive?

Os roles são recriados como parte de subir o projeto de destino, e os dados que eles possuem são transferidos. Como o runbook manual faz o dump com --no-owner --no-privileges, a propriedade dos roles e os grants não são carregados pelo dump — você os reaplica no destino. Trate a paridade de role/senha como algo a verificar e restabelecer após a migração, não como automático. O fluxo gerenciado recria os roles do projeto para você, mas a mesma cautela se aplica: confirme que o role de login e a senha da sua aplicação funcionam contra o destino antes da transição.

Do my connection strings change?

Sim — o host muda, porque seu projeto se move para um novo host de endpoint na região de destino. Você atualiza DATABASE_URL (e qualquer outro lugar onde o host esteja codificado de forma fixa) uma vez, na transição. Suas chaves de API (nsk_…) têm escopo de conta e não são afetadas por uma migração de região.

Is my data encrypted in transit?

Sim. A transferência entre regiões roda sobre TLS, e tanto o dump da origem quanto a restauração no destino usam as conexões padrão do Postgres sslmode=require descritas em Strings de conexão.

Related

• Regiões — o catálogo entre o qual você migra.
• Projetos — a unidade que migra como um todo.
• Strings de conexão — o formato de fio cujo host muda na transição.
• Branches — os filhos copy-on-write, e como dump/restore afeta a linhagem deles.