NuxtHub

NuxtHub provides the easiest way to add database persistence to your authentication. Enable NuxtHub and this module generates and manages your database schema.

Features

• Auto Schema Generation - Tables for users, sessions, accounts created automatically
• Plugin-Aware - Schema updates when you add plugins like twoFactor, passkey
• Multi-Dialect - SQLite, PostgreSQL, or MySQL
• Multi-Cloud - Deploy to Cloudflare, Vercel, or self-hosted infrastructure
• Secondary Storage - Optional KV storage for session caching
• Zero Config Migrations - Use npx nuxt db migrate for production

Setup

pnpm add @nuxthub/core@^0.10.5

export default defineNuxtConfig({
  modules: [
    '@nuxthub/core',
    '@onmax/nuxt-better-auth'
  ],

  hub: {
    db: 'sqlite' // 'sqlite' | 'postgresql' | 'mysql'
  }
})

Configuration Options

The hub.db option accepts a string shorthand or full object:

export default defineNuxtConfig({
  hub: {
    db: 'sqlite' // shorthand: 'sqlite' | 'postgresql' | 'mysql'
    // or full object:
    // db: { dialect: 'postgresql', /* additional options */ }
  }
})

Secondary Storage (KV)

Enable KV storage for faster session lookups:

export default defineNuxtConfig({
  hub: {
    db: 'sqlite',
    kv: true
  },

  auth: {
    secondaryStorage: true
  }
})

Sessions are cached in NuxtHub KV, reducing database queries.

Production Migrations

NuxtHub handles migrations automatically in most deployments. For manual control:

Manual Migration

If you need to run migrations manually:

# Generate migrations from schema changes
npx nuxt db generate

# Apply pending migrations
npx nuxt db migrate

CI/CD Integration

Add to your GitHub Actions workflow:

- name: Run migrations
  run: npx nuxt db migrate
  env:
    NUXT_HUB_PROJECT_KEY: ${{ secrets.NUXTHUB_PROJECT_KEY }}

Schema Generation Details

The module analyzes your server/auth.config.ts at build time:

1. Reads plugins from your config
2. Generates Drizzle schema matching your dialect
3. Injects into NuxtHub via hub:db:schema:extend hook

Accessing the Database

With NuxtHub, you get access to the Drizzle database instance in your server config:

import { defineServerAuth } from '@onmax/nuxt-better-auth/config'

export default defineServerAuth(({ db }) => ({
  // db is the Drizzle instance from NuxtHub
}))

Creating Custom Tables with Foreign Keys

Create application tables that reference auth tables by importing schema from hub:db. NuxtHub automatically merges your custom schemas with Better Auth tables.

import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
import { schema } from '@nuxthub/db'

export const posts = sqliteTable('posts', {
  id: text('id').primaryKey(),
  title: text('title').notNull(),
  authorId: text('author_id').notNull()
    .references(() => schema.user.id),
  createdAt: integer('created_at', { mode: 'timestamp' })
    .$defaultFn(() => new Date()),
})

Available Auth Tables

Reference these tables via the schema object:

• schema.user - User accounts
• schema.session - Active sessions
• schema.account - OAuth provider accounts
• schema.verification - Email verification tokens
• Plugin tables: schema.passkey, schema.twoFactor, etc. (based on enabled plugins)

ID Type Matching

Match your auth table ID types in foreign keys:

• SQLite/MySQL: Use text() or varchar()
• PostgreSQL with UUID: Use uuid() when advanced.database.generateId = 'uuid'

Migrations

Generate and apply migrations after schema changes:

npx nuxt db generate  # Generate migrations
npx nuxt db migrate   # Apply (automatic in dev)

Adding Columns to Auth Tables

To add fields to existing auth tables (e.g., role on user), use Better Auth's additionalFields instead of custom schemas.