nuxt-pg

nuxt-pg

PostgreSQL database module for Nuxt with automatic transaction management

nuxt-pg provides a clean, type-safe PostgreSQL integration for Nuxt with automatic transaction context tracking. Write cleaner code by eliminating transaction parameter passing throughout your application.

Features

• Automatic Transaction Context - No need to pass transaction objects through function calls
• Lazy Initialization - Database initializes on first getPg() call, giving you full control over startup order
• DevTools Integration - Switch between database connections in Nuxt DevTools during development
• Connection Hooks - Listen for connection switch events via Nitro hooks
• Type-Safe - Full TypeScript support with proper type inference
• Connection Pooling - Built-in connection pool management with node-postgres
• Flexible Pool Configuration - Customize pool settings globally or per-connection
• Request Isolation - Transactions are automatically scoped per-request
• Graceful Shutdown - Properly closes connections on server shutdown

Installation

npm install nuxt-pg pg

Quick Start

1. Add to your nuxt.config.ts

export default defineNuxtConfig({
    modules: ['nuxt-pg'],

    nuxtPg: {
        connectionString: process.env.DATABASE_URL || '',
    },
})

2. Use in your API routes

// server/api/users/[id].get.ts
export default defineEventHandler(async (event) => {
    const db = getPg()
    const id = getRouterParam(event, 'id')

    const users = await db.query(
        'SELECT * FROM users WHERE id = $1',
        [id]
    )

    return users[0]
})

getPg() is auto-imported in all server code. The first call initializes the database connection; subsequent calls return the existing singleton.

Usage

Basic Queries

const db = getPg()

// Simple query
const users = await db.query('SELECT * FROM users')

// With parameters
const user = await db.query(
    'SELECT * FROM users WHERE email = $1',
    ['[e-mail]']
)

// With TypeScript types
interface User {
    id: string
    name: string
    email: string
}

const users = await db.query<User>(
    'SELECT * FROM users WHERE active = $1',
    [true]
)

Transactions

Automatic (Recommended)

export default defineEventHandler(async (event) => {
    const db = getPg()

    return await db.transactional(async (txn) => {
        await txn.query('INSERT INTO users (name) VALUES ($1)', ['Alice'])
        await txn.query('INSERT INTO profiles (user_id) VALUES ($1)', [userId])

        // Automatically commits on success, rolls back on error
        return { success: true }
    })
})

Manual Control

export default defineEventHandler(async (event) => {
    const db = getPg()

    await db.createTransaction()

    try {
        await db.query('INSERT INTO users ...')
        await db.query('UPDATE profiles ...')

        await db.commitTransaction()
        return { success: true }
    } catch (error) {
        await db.rollbackTransaction()
        throw error
    }
})

Context-Aware Queries

Transactions are tracked per-request — no need to pass transaction objects through your call stack:

// user.repo.ts
export class UserRepository {
    static async create(data: CreateUserData) {
        // Automatically uses the active transaction if one exists
        return getPg().query('INSERT INTO users ...', [...])
    }
}

// handler.ts
export default defineEventHandler(async (event) => {
    const db = getPg()

    return await db.transactional(async () => {
        // Both use the same transaction automatically
        await UserRepository.create({ name: 'Alice' })
        await ProfileRepository.create(userId, { bio: 'Hello' })
    })
})

Configuration

Module Options

Configure nuxt-pg under the nuxtPg key in your nuxt.config.ts:

export default defineNuxtConfig({
    modules: ['nuxt-pg'],

    nuxtPg: {
        enabled: true,                    // default: true
        connectionString: '',             // production connection string
        pool: {                           // global pool settings
            maxConnections: 30,
            minConnections: 2,
            idleTimeoutMs: 30000,
            connectionTimeoutMs: 2000,
            ssl: true,
        },
        dev: {                            // dev-only settings
            connections: {                // named connections for switching
                local: {
                    connectionString: process.env.DATABASE_URL_DEV || '',
                    pool: { ssl: false },
                },
                staging: {
                    connectionString: process.env.DATABASE_URL_STAGING || '',
                },
            },
            defaultConnection: 'local',   // which connection to use initially
        },
        devtools: {                       // devtools panel settings
            apiUrl: '',                   // remote API URL (see DevTools section)
        },
    },
})

When enabled is false, the module is entirely stripped — no aliases, runtime config, server imports, or hooks are registered. The only exception is the DevTools tab when devtools.apiUrl is set.

Pool Options

Option	Type	Default	Description
maxConnections	number	30	Maximum number of clients in the pool
minConnections	number	2	Minimum number of clients to maintain
idleTimeoutMs	number	30000	Time (ms) a client can be idle before being closed
connectionTimeoutMs	number	2000	Time (ms) to wait for a connection before timing out
ssl	boolean	true	Enable SSL connection

Pool settings defined per-connection in dev.connections are merged with (and override) the global pool settings.

DevTools Integration

In dev mode, nuxt-pg adds a NuxtPG tab to Nuxt DevTools that lets you switch between named database connections on the fly.

Setup

Define multiple connections under dev.connections:

nuxtPg: {
    connectionString: process.env.DATABASE_URL || '',
    dev: {
        connections: {
            local: {
                connectionString: process.env.DATABASE_URL_DEV || '',
                pool: { ssl: false },
            },
            staging: {
                connectionString: process.env.DATABASE_URL_STAGING || '',
            },
            production: {
                connectionString: process.env.DATABASE_URL || '',
            },
        },
        defaultConnection: 'local',
    },
}

The DevTools panel appears automatically. Click any connection to switch — the module waits for active transactions to complete, swaps the connection pool, and resumes.

Remote DevTools (Monorepo)

In a monorepo where multiple Nuxt apps share a single API project, you can show the connection switcher in all apps without initializing a database in each one:

// main-app/nuxt.config.ts, dashboard/nuxt.config.ts, etc.
export default defineNuxtConfig({
    modules: ['nuxt-pg'],

    nuxtPg: {
        enabled: false,
        devtools: {
            apiUrl: 'http://localhost:3000',  // your API project's dev URL
        },
    },
})

With enabled: false and devtools.apiUrl set, the module only registers the DevTools tab pointing at the remote API — nothing else is loaded.

Connection Switch Hooks

When a database connection is switched (via DevTools or programmatically), nuxt-pg emits Nitro hooks you can listen to:

Hook	Payload	When
nuxtpg:connection:before-switch	{ from, to }	Before the pool shutdown begins
nuxtpg:connection:switched	{ from, to }	After a successful switch
nuxtpg:connection:switch-error	{ from, to, error }	On switch failure

Listening to Hooks

// server/plugins/on-db-switch.ts
export default defineNitroPlugin((nitroApp) => {
    nitroApp.hooks.hook('nuxtpg:connection:switched', ({ from, to }) => {
        console.log(`Database switched from "${from}" to "${to}"`)
        // Invalidate caches, re-seed data, notify services, etc.
    })

    nitroApp.hooks.hook('nuxtpg:connection:switch-error', ({ from, to, error }) => {
        console.error(`Failed to switch from "${from}" to "${to}":`, error.message)
    })
})

Hook Payload Types

import type {
    NuxtPgConnectionSwitchPayload,
    NuxtPgConnectionSwitchErrorPayload,
    NuxtPgHooks,
} from 'nuxt-pg'

API Reference

getPg()

Returns the database service singleton. Auto-imported in all server code.

On first call, reads runtime config, initializes the connection pool, and registers a shutdown hook. Subsequent calls return the existing instance.

Method	Description
query<T>(sql, params?)	Execute a SQL query. Uses the active transaction if one exists.
createTransaction(timeoutMs?)	Start a new transaction in the current request context.
commitTransaction()	Commit the active transaction.
rollbackTransaction()	Rollback the active transaction.
transactional<T>(fn, timeoutMs?)	Execute a function within a transaction with automatic commit/rollback.
isHealthy()	Check if the connection pool is healthy.
shutdown()	Gracefully shutdown the database service.

How It Works

nuxt-pg automatically enables Nitro's asyncContext to track database transactions across async boundaries. When you start a transaction, it's stored in the request context and automatically used by all subsequent queries in that request:

// Without nuxt-pg (manual transaction passing)
await userService.create(data, transaction)
await profileService.create(profileData, transaction)

// With nuxt-pg (automatic context tracking)
await userService.create(data)
await profileService.create(profileData)

Requirements

• Nuxt 3.0+
• Node.js 18+
• PostgreSQL 12+
• pg as a peer dependency

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Credits

Built with:

• node-postgres (pg)
• Nuxt
• h3