How to deploy a Cursor app with PostgreSQL

To deploy a Cursor app with PostgreSQL, run the application on a host, create a database, connect it through a server-side DATABASE_URL, and apply your schema migrations. Cursor's agent can do this through Lizard CLI. After deployment, check the public URL and confirm that a record survives a fresh browser session and a redeploy.

This guide is for a Next.js application you already run locally. It uses Lizard for the app and Managed Postgres for the database. You can use the prompts in Cursor's desktop agent, inspect its plan, and let it run the steps you approve.

What needs to move off your laptop?

Consider a task app: you add a task, mark it done, and come back later. Publishing the page is only part of deploying it. The server must reach the database, the tables must exist, and new requests must read the saved data.

Your local database and .env.local file do not move with a GitHub push. Decide which data you need to keep. A fresh database is suitable for a new app; moving an existing database needs a separate export and import plan.

1. Check the production build in Cursor

Open the application folder in Cursor. Ask the agent to inspect the project before changing its deployment settings:

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.

A development server can work while the production build fails. For a standard Next.js Node.js deployment, the build uses next build and the server uses next start. Static export and standalone output need different launch settings. Follow the Next.js deployment guide for the configuration your app uses.

Keep the lockfile in source control. Keep database credentials out of it. A variable such as NEXT_PUBLIC_DATABASE_URL would expose a secret to the browser: Next.js includes NEXT_PUBLIC_* values in client JavaScript at build time. Use a server-only DATABASE_URL. Next.js environment-variable docs explain the distinction.

2. Give Cursor the current deployment instructions

Cursor's agent can run terminal commands. Install Lizard CLI in Cursor's terminal if it is not already available:

npm install -g @lizard-build/cli

Then ask the agent to run and read:

lizard skills get core --json

The command returns the guide that matches the installed CLI. This workflow uses the CLI directly; you do not need to configure an MCP server. If Lizard requests authentication, complete the sign-in link before continuing.

Paste this deployment prompt into 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.

The coding agent guide contains the full commands for both source paths. Keep that guide available while reviewing the agent's work.

3. Connect Postgres before the first deploy

A service can build successfully and then fail on its first database request. Configure the connection before starting that first build or release.

For a new service named web in the intended linked project, with the app at the GitHub repository root, the connection step looks like this. Replace YOUR_ORG/YOUR_REPO with your repository:

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

Reuse an existing service or database when that is the intended target. The example assumes the new database is named postgres. If Lizard returns another name, use it in the reference. The single quotes keep your shell from interpreting ${{...}}.

--no-deploy leaves time to configure the database, migration command, and other required settings. For a monorepo or another branch, also set the app directory and branch before deploying. See Managed Postgres for connection details.

If you have no GitHub remote, the agent can create an empty service and upload the local source with lizard up. For a GitHub service, use its GitHub deployment flow for later updates: lizard up changes the service to uploaded source. The two paths are separate choices.

4. Apply the schema your app expects

Creating PostgreSQL does not create your app's tables. A connection error and a missing-table error need different fixes.

Use the migration tool already in the project. For Prisma projects with committed migration files, prisma migrate deploy applies pending migrations in production. Prisma recommends running it through the deployment process. It does not generate Prisma Client, so the build still needs any generation step your project requires. Prisma's deployment docs cover that setup.

Have Cursor configure the service's preDeployCommand with the reviewed migration command. Ensure the built image contains the migration files, the required CLI package, and its configuration. If the migration needs a database connection, that connection must be available when the command runs. Avoid a development reset command against data you need to keep.

Next.js can also read data while building a page. A database connection configured for the running server does not prove that a build-time query will succeed. Ask Cursor to check when each query runs and use the rendering behavior the page needs. The Next.js self-hosting guide covers runtime and build-time behavior.

5. Verify saved data at the public URL

Read the deployment result and open its HTTPS URL. Test the feature that needs Postgres, rather than stopping after the home page loads.

For a task app, use this sequence:

1. Create a task with a name you can recognize, such as deployment-check-0909.
2. Reload the page and confirm the task appears.
3. Open a private browser window, sign in to the same account if needed, and check the task again. This helps catch apps that only save to browser storage.
4. Deploy a small code change through the same source path. Confirm the task still exists and that you can update it.

Adapt the check to your app: a booking, note, or form submission can serve the same purpose. Use test data and check that each account can access only its own records before inviting users.

If a check fails, give Cursor the failed action and ask it to inspect the service logs:

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

The first command reads build logs; the second reads application logs. Keep the logs reference open for filters and troubleshooting.

Why does a Cursor app work locally but fail after deployment?

The deployed app may have different variables, a new database, or a different start command. Match the symptom to the relevant check:

Ask the agent to fix the cause shown in the logs. Repeated deployments with the same configuration will not fix a missing variable or table.

How much does it cost to host the app and Postgres?

Lizard uses pay as you go with no monthly subscription. New accounts receive $10 in free credits, valid for 31 days. Purchased credits do not expire. Resource usage draws from your account balance; the top-up screen shows any payment fee before you confirm. See current rates and payment terms.

The application and Managed Postgres both consume resources. Lizard uses billing only for active resources, with charges for CPU, memory, storage, and outbound traffic under the plan's terms. Stopping an app does not stop a separate database, and retained volume storage can still incur charges.

Measure the app and database together under the load you expect. A trial credit is a way to test the deployment; it is not a promise of permanent free hosting or a fixed monthly cost for every app.

Questions before you deploy

Do I need to export my app from Cursor?

For a local project, your source files are already in the project folder. Deploy that code through a connected GitHub repository or local upload. Check that the source includes the files needed to build and run it.

Does a Cursor subscription pay for Lizard hosting?

No. Cursor and Lizard are separate services. This workflow uses Cursor to operate Lizard CLI; the Lizard account pays for the deployed app and database under its own plan.

Can I keep my existing PostgreSQL database?

Yes, if the deployed server can reach it and its connection settings meet the database provider's requirements. Configure the server-side connection string, check network access, and run the same application tests. You do not need to create another database just to use this workflow.

Do I need a custom domain before deploying?

Start by checking the public address Lizard returns for your web service. Once it works, follow the custom domain instructions to connect your hostname and verify the DNS records. If your app uses login callbacks, update those URLs too.

Open your project in Cursor and start with the preparation prompt above. For the exact deployment sequence, use the coding agent guide.