Connect Nuxt to Postgres on Neon

Create a Neon project with the Neon CLI or the Console.

neon login
neon projects create --name my-app

1. Create a Nuxt project if you do not have one, then change into its directory. The scaffolder is interactive (it asks about the template, package manager, git, and modules); for CI or an AI agent, pass those as flags to run non-interactively. See Create a Nuxt Project for details. The CLI commands in the next step run from this directory.

   # Interactive (human):
   npm create nuxt@latest my-app && cd my-app
   
   # Non-interactive (CI / AI agents):
   npm create nuxt@latest my-app -- --template minimal --packageManager npm --no-gitInit --modules "" && cd my-app

2. Add a Postgres driver. This guide's examples use the Neon serverless driver, which suits serverless and edge deployments; for long-lived servers, pg or postgres.js are recommended. See Choosing your connection method.npm install @neondatabase/serverlessnpm install postgresnpm install pg

Get your DATABASE_URL into a .env file the app can read.

neon link                    # connects this directory to your project (writes .neon)
neon env pull --file .env    # writes DATABASE_URL from your default branch into .env

DATABASE_URL="postgresql://<user>:<password>@<endpoint_hostname>.neon.tech/<dbname>?sslmode=require&channel_binding=require"

The connection string is a server-side secret, so query it from Nitro server code, which reads process.env.DATABASE_URL directly (no runtimeConfig needed).

This example uses the Neon serverless driver (@neondatabase/serverless). Create a server utility that holds the database client:

import { neon } from '@neondatabase/serverless';

export const sql = neon(process.env.DATABASE_URL!);

Then use it in a server API route. Files in server/utils/ are auto-imported, so sql is available without an import:

export default defineEventHandler(async () => {
  const [row] = await sql`SELECT version()`;
  return row;
});

Start the dev server:

npm run dev

Then open localhost:3000/api/version. The route returns your Postgres version, confirming the connection:

{ "version": "PostgreSQL 18.4 on aarch64-unknown-linux-gnu, compiled by gcc ..." }