Migración de región

La migración de región mueve un proyecto existente desde la región en la que fue creado a otra. Recurres a ella cuando tu tráfico se ha desplazado más cerca de otra región (menor latencia de ida y vuelta), o cuando un requisito de cumplimiento o de residencia de datos exige que tus datos vivan en una jurisdicción concreta.

La migración cambia dónde viven tus datos, no qué son. Tus branches, roles, bases de datos y las filas que contienen se trasladan todos. Lo único que cambia del lado del cliente es el host en tu cadena de conexión — tu proyecto aterriza en un nuevo host de endpoint en la región de destino, por lo que tu DATABASE_URL debe reapuntarse una vez completado el corte.

How it works

Una migración gestionada se ejecuta como una copia controlada y validada con un corte explícito que tú apruebas. Las etapas:

1. Congelación — el proyecto de origen se coloca brevemente en un estado de solo lectura / suspendido para que la copia tenga un objetivo coherente e inmóvil.
2. Volcado — se toma un volcado lógico de cada branch desde la región de origen.
3. Transferencia — el volcado se mueve a la región de destino a través de TLS.
4. Restauración — el volcado se restaura en un proyecto recién aprovisionado en la región de destino.
5. Validación — se comprueba que el destino sea byte-equivalente al origen: la huella del esquema, los recuentos de filas por tabla y las sumas de comprobación de contenido deben coincidir todos antes de que la migración se ofrezca para el corte.
6. Confirmación — nada conmuta automáticamente. Revisas los resultados de validación y confirmas explícitamente el corte.
7. Corte — los endpoints activos del proyecto se reapuntan a la región de destino. El host de la cadena de conexión cambia.

Si cancelas antes del corte, o si la validación falla en cualquier etapa, la migración revierte: el andamiaje de destino se descarta y el proyecto de origen se saca de su estado de solo lectura, intacto.

Size guidance

La ventana de solo lectura escala con el tamaño de tus datos:

• Menos de 10 GB — normalmente se completa en menos de 15 minutos.
• 10–100 GB — una ventana extendida; planifica un periodo de solo lectura más largo y prográmalo fuera de las horas pico.
• Más de 100 GB — contacta con soporte para una migración asistida. Los proyectos grandes se migran con un runbook manual en lugar del flujo de autoservicio.

Managed migration (console)

La migración de región gestionada se está desplegando progresivamente. El asistente descrito aquí se habilita de forma gradual; si todavía no ves Migrate region en los ajustes de tu proyecto, usa el runbook manual de abajo, que funciona en todos los proyectos hoy.

El asistente de la consola recorre el flujo anterior:

1. Abre el proyecto y ve a Settings → Migrate region.
2. Seleccionar destino — elige la región objetivo del desplegable. La región actual se muestra como referencia.
3. Revisar el impacto — el asistente resume lo que está a punto de suceder: la ventana de solo lectura que el proyecto experimentará, y el hecho de que el host de la cadena de conexión cambia en el corte.
4. Monitorizar el progreso — cada branch muestra su propio progreso a través de volcado → transferencia → restauración. El asistente transmite el estado mientras se ejecuta la migración.
5. Revisar la validación — cuando la copia se completa, los resultados de validación se muestran por branch: coincidencia de la huella del esquema, del recuento de filas y de la suma de comprobación.
6. Confirmar el cambio — una vez que la validación está en verde, confirma el corte. Este es el punto sin retorno automático.
7. Actualizar DATABASE_URL — tras el corte, copia la nueva cadena de conexión de la tarjeta de endpoint y actualiza la DATABASE_URL de tu aplicación. El host ha cambiado; todo lo demás es igual.

Manual migration runbook

Este runbook funciona hoy, en cualquier plan. Usa herramientas estándar de Postgres y las cadenas de conexión públicas, así que no depende del flujo gestionado. La forma es: levantar un proyecto nuevo en la región objetivo, copiar los datos con pg_dump / pg_restore, verificar, luego reapuntar y eliminar el proyecto antiguo.

1. Create the destination project

Crea un proyecto nuevo en la región objetivo (consola New project, o la API). Haz coincidir la versión mayor de Postgres del proyecto de origen. Anota la cadena de conexión del nuevo proyecto desde la tarjeta de endpoint.

2. Dump the source

Vuelca desde la cadena de conexión del proyecto de origen en formato custom. --no-owner y --no-privileges mantienen el volcado portable a través de los roles recién creados en el 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

Restaura en la cadena de conexión del proyecto de destino. --single-transaction más --exit-on-error hace que la restauración sea todo-o-nada: si algo falla, el destino queda limpio en lugar de cargado a medias:

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

Confirma que el destino coincide con el origen antes de cortar. Compara los recuentos de filas por tabla contra ambas cadenas de conexión:

SELECT relname, n_live_tup
FROM pg_stat_user_tables
ORDER BY relname;

Para una comprobación más fuerte, verifica por muestreo las sumas de comprobación de contenido en las tablas más importantes. Ejecuta esto contra el origen y el destino y compara los resultados:

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

Recuentos de filas y sumas de comprobación coincidentes significan que los datos se trasladaron intactos.

5. Cut over and clean up

Reapunta la DATABASE_URL de tu aplicación a la cadena de conexión del destino. Una vez que hayas confirmado que la aplicación está sana contra el nuevo proyecto, elimina el proyecto antiguo para dejar de pagar por él:

keon projects delete <old-project-id>

Eliminar un proyecto es irreversible — hazlo solo después de haber verificado el destino y trasladado todo el tráfico a él.

FAQ

How much downtime should I expect?

Para una migración gestionada, la única interrupción es la ventana de solo lectura durante la copia — las escrituras se pausan, las lecturas continúan. La ventana escala con el tamaño de los datos (ver orientación de tamaño): menos de 15 minutos para proyectos por debajo de 10 GB, más larga para los mayores. Para el runbook manual, el tiempo de inactividad es la ventana que elijas para detener las escrituras mientras vuelcas, restauras y verificas.

Can I cancel a migration?

Sí — en cualquier momento antes del corte final. Cancelar descarta el andamiaje de destino y devuelve el proyecto de origen a la normalidad; el origen nunca se modifica hasta que confirmas el cambio, así que una cancelación te deja exactamente donde empezaste.

What happens to my branches?

Cada branch se migra. Ten en cuenta que un dump-and-restore lógico aplana el historial copy-on-write: cada branch se traslada con sus datos actuales, pero la relación fork-at-LSN entre un branch hijo y su padre no se preserva — los branches de destino empiezan de cero a partir de los datos migrados en lugar de compartir páginas. Los datos están intactos; el linaje de almacenamiento compartido no.

Do my passwords and roles survive?

Los roles se recrean como parte de levantar el proyecto de destino, y los datos que poseen se trasladan. Como el runbook manual vuelca con --no-owner --no-privileges, la propiedad de los roles y los grants no los lleva el volcado — los vuelves a aplicar en el destino. Trata la paridad de rol/contraseña como algo a verificar y reestablecer después de la migración, no como automático. El flujo gestionado recrea los roles del proyecto por ti, pero se aplica la misma precaución: confirma que el rol de inicio de sesión y la contraseña de tu aplicación funcionan contra el destino antes del corte.

Do my connection strings change?

Sí — el host cambia, porque tu proyecto se mueve a un nuevo host de endpoint en la región de destino. Actualizas DATABASE_URL (y cualquier otro lugar donde el host esté codificado de forma fija) una vez, en el corte. Tus claves de API (nsk_…) tienen alcance de cuenta y no se ven afectadas por una migración de región.

Is my data encrypted in transit?

Sí. La transferencia entre regiones se realiza sobre TLS, y tanto el volcado desde el origen como la restauración en el destino usan las conexiones estándar de Postgres sslmode=require descritas en Cadenas de conexión.

Related

• Regiones — el catálogo entre el que migras.
• Proyectos — la unidad que migra en su conjunto.
• Cadenas de conexión — el formato de cable cuyo host cambia en el corte.
• Branches — los hijos copy-on-write, y cómo dump/restore afecta a su linaje.