Llevar una aplicación NestJS con TypeORM a producción implica resolver un problema frecuente: ¿cómo ejecutar migraciones en un entorno donde las variables de ambiente y las dependencias funcionan de forma diferente? Aquí se aborda paso a paso la configuración necesaria para que el CLI de TypeORM se conecte correctamente a la base de datos en Heroku, desde la creación del archivo de configuración hasta la ejecución exitosa de migraciones y la validación de endpoints protegidos.
¿Por qué TypeORM necesita una configuración especial para producción?
TypeORM mantiene tres conexiones posibles en un proyecto típico: la del módulo de la aplicación, una conexión nativa con el driver oficial y la que utiliza el CLI para ejecutar migraciones. En desarrollo, la configuración suele darse mediante variables de ambiente individuales como host, puerto y contraseña. Sin embargo, en producción la conexión llega en una sola variable llamada DATABASE_URL [01:01].
El problema es que no se puede simplemente asignar una variable de ambiente a otra dentro del archivo .env. Por eso, TypeORM ofrece la posibilidad de usar un archivo JavaScript llamado ormconfig.js, donde se puede acceder de forma programática a process.env.DATABASE_URL y pasarla como la URL de conexión [02:27].
¿Cómo se estructura el archivo ormconfig.js?
El archivo exporta un objeto con la configuración de conexión. Lo esencial es indicar el tipo de base de datos (en este caso postgres), y asignar la URL directamente desde la variable de entorno [03:07]:
javascript
module.exports = {
type: 'postgres',
url: process.env.DATABASE_URL,
synchronize: false,
logging: false,
entities: ['src/**/.entity.ts'],
migrations: ['src/database/migrations/.ts'],
cli: {
migrationsDir: 'src/database/migrations',
},
};
- synchronize debe estar en
false para evitar cambios automáticos en el esquema.
- logging puede activarse con una variable de ambiente si se necesita depurar.
- Las rutas de entities y migrations se definen en formato de array.
- La propiedad
cli.migrationsDir indica dónde se generan las migraciones.
Una vez creado este archivo, las variables individuales de conexión en el .env deben comentarse para evitar conflictos [04:55].
¿Qué errores comunes aparecen al correr migraciones en Heroku?
El primer intento de ejecutar heroku run npm run migrations:run suele fallar porque ts-node no se encuentra en el entorno productivo [06:25]. Esto ocurre porque ts-node está listado como dependencia de desarrollo. Heroku instala las devDependencies solo durante el build y luego las elimina.
La solución es mover tanto ts-node como typescript a las dependencias de producción, ya que las migraciones están escritas en TypeScript y necesitan ser interpretadas [07:15].
¿Cómo conviven dos configuraciones de TypeORM?
Para desarrollo se mantiene la configuración original que usa ts-node directamente. Para producción se crea una configuración paralela que ejecuta con Node [08:00]:
{
"typeorm:prod": "node --require ts-node/register ./node_modules/typeorm/cli.js",
"migrations:prod": "npm run typeorm:prod -- migration:run"
}
- El comando
migrations:prod utiliza la configuración typeorm:prod.
- El comando de drop no se habilita en producción por seguridad.
- Es explícito en su nombre para evitar confusiones con los comandos de desarrollo.
El segundo error frecuente es la falta de configuración SSL [09:48]. Heroku requiere una propiedad ssl en la conexión. Al agregarla en ormconfig.js con ssl: { rejectUnauthorized: false }, la conexión se establece correctamente.
¿Cómo validar que todo funciona en el entorno productivo?
Una vez ejecutadas las migraciones con éxito [10:55], se pueden probar los endpoints directamente. En este caso se crearon marcas, categorías y usuarios utilizando endpoints sin protección, y luego se validó la autenticación con JWT [12:10]:
- Un administrador puede crear productos tras autenticarse y obtener un token.
- Un cliente recibe un error de rol al intentar crear productos.
- Un token alterado devuelve error de autorización.
- El endpoint público de obtener productos funciona sin token [14:02].
Heroku proporciona una instancia de Postgres con plan gratuito para desarrollo. Para datos productivos reales, es recomendable evaluar planes con backups y mayor estabilidad [14:35].
Una mejora importante es automatizar la ejecución de migraciones con integración continua. Cada vez que se hace push a master, un pipeline puede verificar si hay migraciones pendientes y ejecutarlas automáticamente, ya que TypeORM mantiene una tabla interna que registra qué migraciones se han corrido [15:05]. Heroku ofrece herramientas para configurar este flujo, aunque también es válido mantener el control manual si se prefiere mayor supervisión sobre cada release.
