Development socket

While nuxt dev runs, the module can serve the PGlite of your server config over TCP. Drivers, ORMs, migration tools and psql connect to it as they would to any Postgres server, so your code needs no PGlite-specific branch.

export default defineNuxtConfig({
  pglite: {
    socket: { port: 5433 }, // or `true` for a free port
  },
})

✔ PGlite socket listening at postgres://postgres@127.0.0.1:5433/postgres (DATABASE_URL)

pglite.socket is an option of its own, next to server and client, and only runs in nuxt dev. It is created in the Nuxt process from your server config, whether or not server.enabled is, so it survives server reloads; a change to the config file restarts Nuxt.

Finding the URL

The URL is available in three ways:

• DATABASE_URL: set to the socket's URL when it is still unset, so a real database configured in your environment always wins. socket.env and socket.provider change what is exported, see below.
• useRuntimeConfig().pglite.url: on the server, for code that should not read process.env.
• The terminal: the URL is printed when the socket starts, with the variables it exported. Pin port so that tools outside Nuxt can rely on it.

Environment variables

socket.env decides what the socket exports: a name for the URL ('DATABASE_URL', the default), false for nothing, or a map whose values are functions of the URL or strings exported as is.

export default defineNuxtConfig({
  pglite: {
    socket: { port: 5433, env: 'PGLITE_URL' }, // `env: false` exports nothing
  },
})

export default defineNuxtConfig({
  pglite: {
    socket: {
      port: 5433,
      env: {
        DATABASE_URL: (url: string) => url,
        DATABASE_POOL_URL: (url: string) => `${url}?pool=true`,
        DB_DRIVER: 'pg',
      },
    },
  },
})

Provider presets

DATABASE_URL covers most hosts and tools. Some platforms provision the database themselves and set variables of their own, and code written for them reads those. Presets exist for those platforms: socket.provider exports the platform's variables in place of DATABASE_URL, so that code reaches the socket unchanged.

export default defineNuxtConfig({
  pglite: {
    socket: { port: 5433, provider: 'netlify' },
  },
})

netlify is the first preset. env is merged over it, to add a variable or replace one of its values.

When a variable is taken

Each variable is set only while still unset, so a real database configured in your environment always wins. Once the dev server is up, a warning names each variable that does not hold the socket's value: one set before the module ran (a .env file, your shell), or overwritten after it, for example by another module's own database emulation. Disable the other emulation, or unset the variable, to reach PGlite.

The variables exported are listed when the socket starts, in the DevTools tab, and passed to socket actions as env.

Connecting

The socket speaks the Postgres protocol, so use the driver you would use in production.

// server/utils/db.ts
import { drizzle } from 'drizzle-orm/node-postgres'

import { relations } from '../database/relations'

export function useDB() {
  return drizzle(process.env.DATABASE_URL!, { relations })
}

// server/utils/db.ts
import pg from 'pg'

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })

export function useDB() {
  return pool
}

// server/utils/db.ts
import postgres from 'postgres'

const sql = postgres(process.env.DATABASE_URL!)

export function useDB() {
  return sql
}

Tools outside the app

Tools that run in their own process reach the same database through the pinned port:

import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  schema: './server/database/schema.ts',
  out: './server/database/migrations',
  dialect: 'postgresql',
  dbCredentials: {
    url: 'postgres://postgres@127.0.0.1:5433/postgres',
  },
})

psql postgres://postgres@127.0.0.1:5433/postgres

With nuxt dev running, drizzle-kit studio, drizzle-kit check, drizzle-kit push or psql work against PGlite. When your schema lives in migration files, let init apply them rather than pushing: see Migrations. To launch a tool from Nuxt DevTools with the variables filled in, use a socket action. A test suite, which runs without nuxt dev, gets a socket of its own from nuxt-pglite/testing, in front of a database built from the same config, with the same variables.

Server instance and socket together

The socket's instance holds the configured data directory, and PGlite allows one instance per directory. With both the server side and the socket enabled, connect to the socket from your routes too (that is what the snippets above do), rather than calling usePGlite(), which refuses the directory the socket serves. See Advanced for the alternative.

If PGlite is only your development database, disable the server side altogether: see PGlite in dev, Postgres in prod.