Instrucciones para la migración de MySQL → PostgreSQL#

df -h - muestra el uso del espacio en disco en un formato legible para humanos

• Asegúrese de que el espacio libre sea al menos 2 veces mayor que el tamaño de su base de datos

free -h - muestra información sobre la memoria RAM

• Se requieren al menos 4 GB de RAM para pgloader
• Si hay insuficiente memoria, la migración puede fallar con el error "Heap exhausted"

docker --version - verifica la versión de Docker

• Se requiere Docker 20.10+ para el correcto funcionamiento de todas las funciones

docker compose version - verifica la versión de Docker Compose

• Asegúrese de que compose soporte la sintaxis moderna

docker ps - muestra los contenedores en ejecución

• Deben ser visibles los contenedores mysql/postgres para acceder a los datos

curl -fSL -OJ - descarga archivos desde el servidor

• -f - finaliza silenciosamente en caso de errores del servidor
• -S - muestra errores incluso al usar -f
• -L - sigue redirecciones
• -O - guarda el archivo con el nombre del servidor
• -J - utiliza el nombre de archivo proporcionado por el servidor

pgloader_image.tar - imagen de Docker con la herramienta pgloader para la transferencia de datos alpine_image.tar - imagen ligera de Linux para operaciones con archivos

sudo mkdir -p - crea un directorio con carpetas padres

• -p previene el error si el directorio ya existe

sudo mv - mueve archivos al nuevo directorio

• Mover a /opt/SherpaAIServerNew aislará los archivos de migración de la instalación actual

docker compose stop - detiene los servicios especificados sin eliminarlos

• orchestrator - servicio principal de orquestación
• embed - servicio para trabajar con embeddings
• nginx - servidor web y proxy
• vllm - servicio de modelo de lenguaje

Dos comandos - se ejecutaron ambas versiones de la sintaxis para compatibilidad Servicios restantes - pgembeding (PostgreSQL con embeddings) y orchestrator-db (MySQL) deben seguir funcionando para acceder a los datos

docker volume list - muestra todos los volúmenes de Docker en el sistema

• DRIVER - tipo de controlador (generalmente local)
• VOLUME NAME - nombre único del volumen

El prefijo de los nombres - depende del nombre de la carpeta del proyecto:

• Para la carpeta SherpaAIServer → prefijo sherpaaiserver_
• Para la carpeta myproject → prefijo myproject_

Volúmenes principales:

• *orchestrator-mysql-data - datos de la base de datos MySQL
• *pgdata - datos de la base de datos PostgreSQL
• *storage - almacenamiento de archivos

docker run --rm - ejecuta un contenedor y lo elimina automáticamente después de la ejecución

• --rm previene la acumulación de contenedores detenidos

Montaje de volúmenes:

• -v VOLUME_NAME:/data - monta el volumen de Docker en el contenedor
• -v $(pwd)/backup_mysql:/backup - monta una carpeta local para guardar el archivo

tar czf - crea un archivo comprimido

• c - crear archivo
• z - comprimir usando gzip
• f - especificar el nombre del archivo
• -C /data . - cambia el directorio a /data antes de archivar

pgembeding - utiliza la imagen existente de PostgreSQL con herramientas

Primer volumen: sherpaaiserver_orchestrator-mysql-data

• Contiene datos de la base de datos MySQL del orquestador

• El archivo se guarda en backup_mysql/mysql_backup.tar.gzSegundo volumen: sherpaaiserver_pgdata

• Contiene datos de la base de datos PostgreSQL (si los hay)

• El archivo de respaldo se guarda en backup_pg/pg_backup.tar.gz

Primer volumen: myproject_orchestrator-mysql-data

• De manera similar, pero con el prefijo myproject_
• Utilice el nombre real de la carpeta de su proyecto

Segundo volumen: myproject_pgdata

• Datos de PostgreSQL con el prefijo correspondiente

• Crean archivos comprimidos de todos los datos del volumen de Docker
• Los archivos se guardan en los directorios locales backup_mysql y backup_pg

ls -lh - muestra información detallada sobre los archivos

• -l - formato largo
• -h - tamaños en un formato legible
• Verifique que los archivos tengan un tamaño razonable

tar -tzf - muestra el contenido del archivo sin descomprimir

• -t - lista el contenido
• -z - descomprimir usando gzip
• -f - especificar el nombre del archivo
• | head -20 - muestra los primeros 20 archivos

Recomendación: Asegúrese de que los archivos no estén vacíos y contengan los archivos de base de datos esperados

tar -xvzf - descomprime el archivo

• -x - extraer
• -v - salida detallada
• -z - descomprimir usando gzip
• -f - especificar el nombre del archivo

Subcomando para seleccionar el archivo:

• ls client_files_*.tgz - encuentra todos los archivos comprimidos de client-files
• sort -V - ordena por versión (1.0, 1.1, 2.0, etc.)
• tail -n 1 - toma el último (el más reciente) archivo

Resultado: Se crea una carpeta pgloader con herramientas de migración

cd pgloader - cambia a la carpeta con herramientas de migración

• Todos los comandos posteriores se ejecutan desde este directorio
• Contiene scripts y configuraciones para pgloader

./load_pgloader.sh - script para cargar la imagen de Docker

• Importa pgloader_image.tar en el daemon de Docker local
• Después de la ejecución, la imagen estará disponible como pgloader:latest
• Puede tardar unos minutos dependiendo del tamaño de la imagen

./run.sh build - construye el contenedor de Docker para la migración

• Crea un contenedor basado en la imagen de pgloader cargada
• Configura todas las dependencias y herramientas necesarias
• Después de la construcción, el contenedor está listo para ejecutar la migración

MIGRATE_MYSQL - URI de conexión a la base de datos MySQL de origen

• Formato: mysql://username:password@host:port/database
• Utilizado por pgloader para leer datos

MIGRATE_PG - URI de conexión a la base de datos PostgreSQL de destino

• Formato: postgres://username:password@host:port/database
• Debe estar disponible para escribir datos

DUMP_ / RESTORE_ ** - parámetros opcionales para crear/restaurar volcados

• Útiles para depuración o migración por etapas

Parámetros de MySQL:

• Host: 91.206.149.183 (servidor externo)
• Puerto: 3306 (estándar para MySQL)
• Base: orchestrator
• Usuario: root (con todos los permisos)

Parámetros de PostgreSQL:

• Host: el mismo servidor
• Puerto: 5432 (estándar para PostgreSQL)
• Base: postgres (base de datos del sistema)
• Usuario: postgres (administrador)

Importante: Las contraseñas deben tomarse del config.ini existente

./run.sh dry-run - simulación de la migración sin cambios

• Se conecta a ambas bases de datos
• Analiza la estructura y los datos
• Muestra el plan de migración y posibles problemas
• No realiza ningún cambio en PostgreSQL

Verifica:

• Disponibilidad y corrección de las conexiones
• Compatibilidad de tipos de datos MySQL → PostgreSQL
• Existencia de todas las tablas y relaciones
• Volumen de datos esperado para la transferencia

Recomendación: Siempre realice una ejecución de prueba antes de la migración real

./run.sh migrate - realiza la migración real de datos

• Crea el esquema orchestrator en PostgreSQL
• Transfiere la estructura de las tablas con conversión de tipos
• Copia todos los datos de MySQL a PostgreSQL
• Crea índices y restricciones de integridad

Etapas de ejecución:

1. Verificación de conexiones y permisos
2. Creación del esquema de la base de datos
3. Migración de la estructura (tablas, tipos de datos)
4. Transferencia de datos con optimización del rendimiento
5. Creación de índices y restricciones

Importante: El proceso puede ser largo para bases de datos grandes

./run.sh rmi - elimina la imagen de Docker pgloader

• Libera espacio en disco
• Elimina imágenes y contenedores temporales
• Opcional - se puede dejar para reutilización

cd .. - regresa al directorio padre

• Sale de la carpeta pgloader
• Regresa a la raíz del proyecto SherpaAIServer

Recomendación: Realice la limpieza solo después de una finalización y prueba exitosa de la migración

docker load -i - importa una imagen de Docker desde un archivo tar

• -i - leer desde un archivo tar guardado localmente
• Carga la imagen en el daemon de Docker local

Alpine Linux - distribución de Linux minimalista

• Tamaño de la imagen ~5-10 MB (en comparación con Ubuntu ~100+ MB)
• Contiene solo las herramientas necesarias (cp, ls, tar, etc.)
• Ideal para operaciones con archivos en contenedores

Uso: Para copiar datos entre volúmenes de Docker

docker volume create - crea un nuevo volumen de Docker nombrado

• aiserver-storage - nombre para el nuevo volumen
• El volumen se crea vacío y listo para usar

Características del volumen:

• Gestionado automáticamente por Docker
• Accesible para todos los contenedores en el host
• Se conserva al reiniciar el daemon de Docker
• Soporta operaciones de snapshot y backup

Propósito: Almacenamiento de archivos de Sherpa AIServer (descargas, caché, logs, etc.)

docker volume list - verificación reiterada de la lista de volúmenes

• Asegurarse de que todos los volúmenes estén disponibles
• Verificar la corrección de los nombres antes de copiar datos

Importante: Comparar con los resultados de la primera verificación

• Asegúrese de que los volúmenes no hayan sido eliminados accidentalmente
• Verifique la disponibilidad de todos los datos necesarios

docker run --rm - inicia un contenedor temporal de Alpine

• --rm - el contenedor se eliminará después de la ejecución

Montaje de volúmenes:

• -v STORAGE_DATA:/from - el volumen fuente se monta en /from
• -v aiserver-storage:/to - el volumen de destino se monta en /to

ash -c - ejecuta un comando en el shell de Alpine

• ash - Almquist shell (ligero)
• -c - ejecutar el comando

cp -av /from/. /to/ - copia todos los archivos

• -a - modo de archivo (mantiene permisos, propietarios, marcas de tiempo)
• -v - salida detallada
• /from/. - copia el contenido, no la carpeta /from
• /to/ - en el directorio de destino

Ejemplo de reemplazo: STORAGE_DATA → sherpaaiserver_storage

docker run --rm -v aiserver-storage:/data alpine ls -la /data

• Verifica el contenido del nuevo volumen
• ls -la muestra todos los archivos con permisos y tamaños
• Asegurarse de que los archivos se hayan copiado correctamente

docker run --rm -v STORAGE_DATA:/data alpine du -sh /data

• Verifica el tamaño del volumen fuente
• du -sh - uso de disco, resumen, formato legible por humanos
• Comparamos tamaños para verificar la integridad de la copia

Expectativas:

• La cantidad de archivos debe coincidir
• Los tamaños deben ser aproximadamente iguales
• La estructura de directorios debe ser idéntica

Si los tamaños difieren: Verifique los registros de copia en busca de errores

• ls client_files_*.tgz - encuentra todos los archivos de archivo
• sort -V - ordena versiones de forma natural (1.0 < 1.1 < 1.10)
• tail -n 1 - selecciona el archivo más reciente
• tar -xvzf - descomprime el archivo mostrando el contenido

Resultado esperado: Se creará un directorio sh_scripts/ con scripts ejecutables y otros archivos necesarios.

• chmod +x *.sh - establece permisos de ejecución para todos los scripts de shell
• Esto es necesario para ejecutar los scripts en las siguientes etapas de la instalación

1. Carga todas las imágenes de Docker desde los archivos .tar.gz descargados
2. Importa las imágenes en el registro local de Docker
3. Verifica el éxito de la carga

1. Descomprime el modelo Whisper para reconocimiento de voz
2. Descomprime el modelo BGE Reranker para mejorar la búsqueda
3. Descomprime modelos para generación de embeddings
4. Crea los directorios necesarios
5. Verifica el éxito de la descompresión

1. Descomprime el modelo Llama 3 para modelado de lenguaje
2. Elimina el prefijo model-store/ de las rutas de los archivos
3. Coloca los archivos directamente en el directorio de modelos
4. Verifica el contenido después de la descompresión

docker compose up -d - inicia los servicios en segundo plano

• -d - modo desconectado (ejecución en segundo plano)
• Inicia todos los servicios del docker-compose.yml
• Incluye PostgreSQL 17 en el contenedor aiserver-pg

Importante:

• La base de datos antigua debe seguir funcionando
• La nueva versión se inicia en otro puerto (5433)
• El proceso de inicialización puede tardar varios minutos

docker logs aiserver - muestra los logs del contenedor

• Sigue el proceso de inicialización de PostgreSQL
• Busca mensajes sobre el inicio exitoso y la aplicación de migraciones
• Se puede interrumpir con Ctrl+C

docker ps | grep aiserver - verifica el estado

• docker ps - muestra los contenedores en ejecución
• grep aiserver - filtra por nombre
• Debe mostrar el contenedor aiserver-pg en estado Up

docker compose stop - detiene los servicios especificados

• Se ejecutan ambas versiones de la sintaxis por compatibilidad
• Se detienen todos los servicios de Sherpa AIServer excepto la base de datos

Servicios detenidos:

• aiserver - servidor web principal
• aiserver-code_interpreter - intérprete de código
• aiserver-llm-server - modelo de lenguaje
• aiserver-embed - servicio de embeddings
• aiserver-whisper - servicio de reconocimiento de voz
• aiserver-bge_reranker - servicio de ranking

Resultado: Solo aiserver-pg (nueva PostgreSQL) sigue funcionando

Paso 1: Crear un volcado de la base de datos antigua

• docker exec -t postgres - ejecuta el comando en el contenedor postgres (versión 16)
• pg_dump -U postgres -d postgres -Fc - crea un volcado en formato especial
• -Fc - formato especial comprimido (mejor para bases de datos grandes)
• Se guarda en /tmp/postgres.dump dentro del contenedor

Paso 2: Copiar el volcado al host

• docker cp postgres:/tmp/postgres.dump ./postgres.dump
• Transfiere el volcado del contenedor al disco local
• Necesario para la transferencia entre contenedores

Paso 3: Eliminar la base de datos antigua en el nuevo contenedor

• Se conecta a la base de datos del sistema template1
• Elimina la base de datos existente postgres (si existe)

Paso 4: Crear una nueva base de datos

• Crea una base de datos postgres limpia en el contenedor aiserver-pg

Paso 5: Crear extensiones

• embedding - extensión para embeddings vectoriales
• uuid-ossp - generación de UUID (necesaria para algunas tablas)

Paso 6: Copiar el volcado al nuevo contenedor

• Operación inversa de copia
• Coloca el volcado en el contenedor aiserver-pg

Paso 7: Restaurar los datos

• pg_restore - restaura desde el volcado en formato especial
• -t - asigna TTY para el progreso
• Crea automáticamente tablas, índices y datos

docker exec -it aiserver-pg psql -U postgres -d postgres

• Se conecta a PostgreSQL en modo interactivo
• -it - terminal interactivo
• -U postgres - usuario postgres
• -d postgres - base de datos postgres

\dt orchestrator.* - muestra todas las tablas en el esquema orchestrator

• \dt - lista de tablas
• orchestrator.* - filtro por esquema

SELECT ... FROM pg_stat_user_tables - estadísticas sobre las tablas

• n_tup_ins - número de filas insertadas (número aproximado de registros)
• La ordenación descendente muestra las tablas más grandes

\dx - muestra las extensiones instaladas

• Deben ser visibles embedding y uuid-ossp

\q - salir de psql

tail -f migrate.log - sigue los logs en tiempo real

• -f - seguir (se actualiza al agregar nuevas líneas)
• Muestra el progreso de la migración de pgloader
• Busca errores o advertencias

docker stats - monitorea el uso de recursos de los contenedores

• Muestra CPU, memoria, red, disco para todos los contenedores
• Útil para rastrear la carga en el sistema
• Interrumpir con Ctrl+C

* Cuenta el número total de registros en todas las tablas del orchestrator
* `watch` - utilidad para ejecutar comandos periódicamente
* `-n 30` - intervalo de 30 segundos

**Uso:** Mantener estos comandos en terminales separados durante la migración

</details>

### Finalización de la migración

**Después de completar con éxito todos los pasos:**

1. **Iniciar todos los servicios de Sherpa AI Server**
2. **Realizar pruebas finales del sistema**
3. **Eliminar archivos temporales y contenedores antiguos** (si es necesario)

> **Recomendación:** Guarde los registros de migración y los archivos de configuración para futuras referencias.