Cómo desplegar una app de Cursor con PostgreSQL

Para desplegar una app de Cursor con PostgreSQL, ejecuta la aplicación en un host, crea una base de datos, conéctala mediante un DATABASE_URL del lado del servidor y aplica las migraciones de tu esquema. El agente de Cursor puede hacerlo mediante Lizard CLI. Después del despliegue, comprueba la URL pública y confirma que un registro se conserve tras una sesión nueva del navegador y un nuevo despliegue.

Esta guía es para una aplicación Next.js que ya ejecutas localmente. Usa Lizard para la app y Managed Postgres para la base de datos. Puedes usar los prompts en el agente de escritorio de Cursor, revisar su plan y dejar que ejecute los pasos que apruebes.

¿Qué debe salir de tu portátil?

Piensa en una app de tareas: agregas una tarea, la marcas como hecha y vuelves más tarde. Publicar la página es solo una parte del despliegue. El servidor debe poder acceder a la base de datos, las tablas deben existir y las nuevas solicitudes deben leer los datos guardados.

Tu base de datos local y el archivo .env.local no se mueven con un push a GitHub. Decide qué datos necesitas conservar. Una base de datos nueva sirve para una app nueva; mover una base de datos existente requiere un plan aparte de exportación e importación.

1. Comprueba la compilación de producción en Cursor

Abre la carpeta de la aplicación en Cursor. Pide al agente que inspeccione el proyecto antes de cambiar su configuración de despliegue:

Prepare this Next.js app for deployment with PostgreSQL. Read its package.json,
lockfile, Next.js configuration, database client, and migration files.

Run the existing checks and production build using this project's package
manager. Identify the start command, port, required environment-variable
names, and production migration command. Do not print secret values.

Check whether any page queries the database during the build. Explain what
must be available at build time and what the app can read at request time.
Show any fixes needed before deploying.

Un servidor de desarrollo puede funcionar mientras la compilación de producción falla. Para un despliegue estándar de Next.js con Node.js, la compilación usa next build y el servidor usa next start. La exportación estática y la salida standalone necesitan configuraciones de inicio distintas. Sigue la guía de despliegue de Next.js para la configuración que usa tu app.

Mantén el lockfile en el control de código fuente. Mantén fuera de él las credenciales de la base de datos. Una variable como NEXT_PUBLIC_DATABASE_URL expondría un secreto al navegador: Next.js incluye los valores NEXT_PUBLIC_* en el JavaScript del cliente en tiempo de compilación. Usa un DATABASE_URL solo para el servidor. La documentación de variables de entorno de Next.js explica la diferencia.

2. Dale a Cursor las instrucciones actuales de despliegue

El agente de Cursor puede ejecutar comandos de terminal. Instala Lizard CLI en la terminal de Cursor si todavía no está disponible:

npm install -g @lizard-build/cli

Luego pídele al agente que ejecute y lea:

lizard skills get core --json

El comando devuelve la guía que coincide con la CLI instalada. Este flujo de trabajo usa la CLI directamente; no necesitas configurar un servidor MCP. Si Lizard solicita autenticación, completa el enlace de inicio de sesión antes de continuar.

Pega este prompt de despliegue en Cursor:

Deploy this app with Lizard and Managed Postgres. First read the full output
of `lizard skills get core --json`. Check the current project link and git
remote, then show me the target project, service, region, and resources.
Wait for approval before creating resources or changing a live service.

If this app has a GitHub remote, connect that repository without starting
the first build. If it has no GitHub remote, use local source upload.

Create or select the intended database. Set DATABASE_URL on the app service
using a reference to that database's actual name. Configure the app's other
required variables and its reviewed production migration command before
deploying. Keep secret values out of the chat and repository.

Use the build settings this project needs. Read build and runtime logs,
check the final deployment status, and return the public URL. Test the
app's database-backed action and report what passed or failed.

La guía del agente de programación contiene los comandos completos para ambas rutas de origen. Mantén esa guía a mano mientras revisas el trabajo del agente.

3. Conecta Postgres antes del primer despliegue

Un servicio puede compilar correctamente y luego fallar en su primera solicitud a la base de datos. Configura la conexión antes de iniciar esa primera compilación o publicación.

Para un servicio nuevo llamado web en el proyecto vinculado previsto, con la app en la raíz del repositorio de GitHub, el paso de conexión se ve así. Sustituye YOUR_ORG/YOUR_REPO por tu repositorio:

lizard add --repo YOUR_ORG/YOUR_REPO --name web --no-deploy --json
lizard add postgres --json
lizard secrets set DATABASE_URL='${{postgres.DATABASE_URL}}' --service web --json

Reutiliza un servicio o una base de datos existentes cuando ese sea el destino previsto. El ejemplo supone que la nueva base de datos se llama postgres. Si Lizard devuelve otro nombre, úsalo en la referencia. Las comillas simples evitan que tu shell interprete ${{...}}.

--no-deploy deja tiempo para configurar la base de datos, el comando de migración y otros ajustes necesarios. Para un monorepo u otra rama, configura también el directorio de la app y la rama antes de desplegar. Consulta Managed Postgres para ver los detalles de conexión.

Si no tienes un remoto de GitHub, el agente puede crear un servicio vacío y subir el código fuente local con lizard up. Para un servicio de GitHub, usa su flujo de despliegue con GitHub para las actualizaciones posteriores: lizard up cambia el servicio a código fuente subido. Las dos rutas son opciones separadas.

4. Aplica el esquema que espera tu app

Crear PostgreSQL no crea las tablas de tu app. Un error de conexión y un error por falta de tabla requieren soluciones distintas.

Usa la herramienta de migración que ya esté en el proyecto. Para proyectos de Prisma con archivos de migración confirmados, prisma migrate deploy aplica las migraciones pendientes en producción. Prisma recomienda ejecutarlo mediante el proceso de despliegue. No genera Prisma Client, así que la compilación sigue necesitando cualquier paso de generación que requiera tu proyecto. La documentación de despliegue de Prisma cubre esa configuración.

Pide a Cursor que configure el preDeployCommand del servicio con el comando de migración revisado. Asegúrate de que la imagen compilada incluya los archivos de migración, el paquete CLI necesario y su configuración. Si la migración necesita una conexión a la base de datos, esa conexión debe estar disponible cuando se ejecute el comando. Evita un comando de restablecimiento de desarrollo sobre datos que necesites conservar.

Next.js también puede leer datos al compilar una página. Una conexión a la base de datos configurada para el servidor en ejecución no demuestra que una consulta en tiempo de compilación vaya a funcionar. Pide a Cursor que compruebe cuándo se ejecuta cada consulta y que use el comportamiento de renderizado que necesita la página. La guía de self-hosting de Next.js cubre el comportamiento en tiempo de ejecución y en tiempo de compilación.

5. Verifica los datos guardados en la URL pública

Lee el resultado del despliegue y abre su URL HTTPS. Prueba la funcionalidad que necesita Postgres, en lugar de detenerte cuando cargue la página de inicio.

Para una app de tareas, usa esta secuencia:

1. Crea una tarea con un nombre que puedas reconocer, como deployment-check-0909.
2. Recarga la página y confirma que la tarea aparece.
3. Abre una ventana privada del navegador, inicia sesión en la misma cuenta si hace falta y vuelve a comprobar la tarea. Esto ayuda a detectar apps que solo guardan en el almacenamiento del navegador.
4. Despliega un pequeño cambio de código mediante la misma ruta de origen. Confirma que la tarea sigue existiendo y que puedes actualizarla.

Adapta la comprobación a tu app: una reserva, nota o envío de formulario puede servir para lo mismo. Usa datos de prueba y comprueba que cada cuenta solo pueda acceder a sus propios registros antes de invitar a usuarios.

Si una comprobación falla, dale a Cursor la acción fallida y pídele que inspeccione los logs del servicio:

lizard logs --build --service web --json
lizard logs --service web --json
lizard ps --json

El primer comando lee los logs de compilación; el segundo lee los logs de la aplicación. Mantén abierta la referencia de logs para filtros y solución de problemas.

¿Por qué una app de Cursor funciona localmente pero falla después del despliegue?

La app desplegada puede tener variables distintas, una base de datos nueva o un comando de inicio diferente. Relaciona el síntoma con la comprobación pertinente:

Pide al agente que corrija la causa que muestran los logs. Los despliegues repetidos con la misma configuración no corregirán una variable o tabla que falta.

¿Cuánto cuesta alojar la app y Postgres?

Lizard usa pay as you go sin suscripción mensual. Las cuentas nuevas reciben $10 en créditos gratis, válidos durante 31 días. Los créditos comprados no caducan. El uso de recursos se descuenta del saldo de tu cuenta; la pantalla de recarga muestra cualquier comisión de pago antes de confirmar. Consulta las tarifas actuales y condiciones de pago.

Tanto la aplicación como Managed Postgres consumen recursos. Lizard usa facturación solo para recursos activos, con cargos por CPU, memoria, almacenamiento y tráfico saliente según las condiciones del plan. Detener una app no detiene una base de datos independiente, y el almacenamiento de volúmenes retenidos puede seguir generando cargos.

Mide la app y la base de datos juntas bajo la carga que esperas. Un crédito de prueba es una forma de probar el despliegue; no es una promesa de hosting gratis permanente ni de un costo mensual fijo para todas las apps.

Preguntas antes de desplegar

¿Necesito exportar mi app desde Cursor?

Para un proyecto local, tus archivos fuente ya están en la carpeta del proyecto. Despliega ese código mediante un repositorio de GitHub conectado o una subida local. Comprueba que el código fuente incluya los archivos necesarios para compilarlo y ejecutarlo.

¿Una suscripción de Cursor paga el hosting de Lizard?

No. Cursor y Lizard son servicios independientes. Este flujo de trabajo usa Cursor para operar Lizard CLI; la cuenta de Lizard paga la app desplegada y la base de datos según su propio plan.

¿Puedo conservar mi base de datos PostgreSQL existente?

Sí, si el servidor desplegado puede acceder a ella y su configuración de conexión cumple los requisitos del proveedor de base de datos. Configura la cadena de conexión del lado del servidor, comprueba el acceso de red y ejecuta las mismas pruebas de la aplicación. No necesitas crear otra base de datos solo para usar este flujo de trabajo.

¿Necesito un dominio personalizado antes de desplegar?

Empieza comprobando la dirección pública que Lizard devuelve para tu servicio web. Cuando funcione, sigue las instrucciones de dominio personalizado para conectar tu hostname y verificar los registros DNS. Si tu app usa callbacks de inicio de sesión, actualiza también esas URLs.

Abre tu proyecto en Cursor y empieza con el prompt de preparación anterior. Para la secuencia exacta de despliegue, usa la guía del agente de programación.