Database Adapters
Database Adapters
@websideproject/nuxt-auto-api supports multiple database engines through a unified adapter layer. Each adapter normalizes engine-specific behavior like transactions, batch operations, and mutation count parsing.
Supported Engines
| Engine | Package | Transactions | Returning | Native Batch |
|---|---|---|---|---|
better-sqlite3 | better-sqlite3 | db.transaction() | Yes | No |
postgres | pg / postgres | db.transaction() | Yes | No |
mysql | mysql2 | db.transaction() | No | No |
d1 | Cloudflare D1 | db.batch() | Yes | Yes |
turso | @libsql/client | db.batch() | Yes | Yes |
planetscale | @planetscale/database | db.transaction() | No | No |
Setup
Using initializeDatabase
The recommended way to initialize the database is with initializeDatabase() in a server plugin:
// server/plugins/database.ts
import { drizzle } from 'drizzle-orm/better-sqlite3'
import Database from 'better-sqlite3'
import { initializeDatabase } from '@websideproject/nuxt-auto-api/database'
import * as schema from '../database/schema'
export default defineNitroPlugin(() => {
const sqlite = new Database('sqlite.db')
const db = drizzle(sqlite, { schema })
initializeDatabase(db, 'better-sqlite3')
})
Postgres
import { drizzle } from 'drizzle-orm/node-postgres'
import { Pool } from 'pg'
import { initializeDatabase } from '@websideproject/nuxt-auto-api/database'
export default defineNitroPlugin(() => {
const pool = new Pool({ connectionString: process.env.DATABASE_URL })
const db = drizzle(pool, { schema })
initializeDatabase(db, 'postgres')
})
Cloudflare D1
import { drizzle } from 'drizzle-orm/d1'
import { initializeDatabase } from '@websideproject/nuxt-auto-api/database'
export default defineNitroPlugin(() => {
const db = drizzle(env.DB, { schema })
initializeDatabase(db, 'd1')
})
Turso / LibSQL
import { drizzle } from 'drizzle-orm/libsql'
import { createClient } from '@libsql/client'
import { initializeDatabase } from '@websideproject/nuxt-auto-api/database'
export default defineNitroPlugin(() => {
const client = createClient({
url: process.env.TURSO_DATABASE_URL!,
authToken: process.env.TURSO_AUTH_TOKEN,
})
const db = drizzle(client, { schema })
initializeDatabase(db, 'turso')
})
Configuration
Set the engine in nuxt.config.ts:
export default defineNuxtConfig({
autoApi: {
database: {
client: 'better-sqlite3', // or 'postgres', 'mysql', 'd1', 'turso', 'planetscale'
},
},
})
Using the Adapter Directly
The adapter is available in HandlerContext and from the getDatabaseAdapter() helper:
import { getDatabaseAdapter } from '@websideproject/nuxt-auto-api/database'
// In a server handler
const adapter = getDatabaseAdapter()
// Run atomic operations (transaction or batch depending on engine)
const result = await adapter.atomic(async ({ tx }) => {
await tx.insert(users).values({ name: 'Alice' })
await tx.insert(posts).values({ title: 'Hello', userId: 1 })
return 'done'
})
// Check engine capabilities
if (adapter.supportsReturning) {
const [created] = await db.insert(users).values(data).returning()
}
// Parse mutation counts
const result = await db.delete(posts).where(eq(posts.draft, true))
const deleted = adapter.getMutationCount(result)
Adapter API
interface DatabaseAdapter {
engine: DatabaseEngine // Engine identifier
db: any // Drizzle database instance
atomic<T>(fn): Promise<T> // Run operations atomically
getMutationCount(result): number // Parse affected rows
supportsReturning: boolean // Does the engine support RETURNING?
supportsNativeBatch: boolean // Does the engine use batch() instead of transaction()?
}
Backward Compatibility
If you are using the legacy globalThis.__autoApiDb pattern, it still works. The system will automatically wrap it in a default SQLite adapter with a deprecation warning. To silence the warning, switch to initializeDatabase().
// Legacy (still works, deprecated)
globalThis.__autoApiDb = db
// Recommended
initializeDatabase(db, 'better-sqlite3')
Plugin System
The plugin system provides a structured architecture for extending @websideproject/nuxt-auto-api. Plugins can hook into both the build-time module setup and the server-side runtime pipeline.
Custom Endpoints
@websideproject/nuxt-auto-api provides two approaches for building custom server endpoints that integrate with the auto-api pipeline: createEndpoint() for full pipeline integration, and standalone helpers for lightweight use in regular Nitro handlers.
