nuxt-hub · atinux · Dec 15, 2025 · Dec 14, 2025 · Dec 14, 2025 · Dec 14, 2025
diff --git a/docs/content/docs/2.features/0.database.md b/docs/content/docs/2.features/0.database.md
@@ -21,6 +21,7 @@ Install Drizzle ORM, Drizzle Kit, and the appropriate driver(s) for the database
     NuxtHub automatically detects your database connection using environment variables:
     - Uses `PGlite` (embedded PostgreSQL) if no environment variables are set.
     - Uses `postgres-js` driver if you set `DATABASE_URL`, `POSTGRES_URL`, or `POSTGRESQL_URL` environment variable.
+    - Use `neon-http` driver with `@neondatabase/serverless` for [Neon](https://neon.com) serverless PostgreSQL.
     ::
   :::
   :::tabs-item{label="MySQL" icon="i-simple-icons-mysql"}
@@ -780,6 +781,37 @@ This driver requires the following environment variables:
 You can find your Cloudflare account ID and create API tokens in the [Cloudflare dashboard](https://dash.cloudflare.com). The API token needs `D1:Edit` permissions.
 ::
 
+### Neon Serverless
+
+Use the `neon-http` driver to connect to [Neon](https://neon.com) serverless PostgreSQL. This driver uses HTTP protocol optimized for serverless environments.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  hub: {
+    db: {
+      dialect: 'postgresql',
+      driver: 'neon-http'
+    }
+  }
+})
+```
+
+Install the required dependency:
+
+```bash
+pnpm add @neondatabase/serverless
+```
+
+This driver requires the following environment variable:
+
+| Variable | Description |
+| --- | --- |
+| `DATABASE_URL` | Your Neon database connection string (or `POSTGRES_URL` / `POSTGRESQL_URL`) |
+
+::callout{icon="i-lucide-info"}
+You can find your Neon connection string in the [Neon dashboard](https://console.neon.tech). The connection string format is `postgresql://user:password@hostname/database`.
+::
+
 ## Migration guide
 
 ::important

diff --git a/src/db/lib/client.ts b/src/db/lib/client.ts
@@ -19,6 +19,13 @@ export async function createDrizzleClient(config: ResolvedDatabaseConfig, hubDir
     pkg = 'drizzle-orm/postgres-js'
     const { drizzle } = await import(pkg)
     return drizzle({ client })
+  } else if (driver === 'neon-http') {
+    const clientPkg = '@neondatabase/serverless'
+    const { neon } = await import(clientPkg)
+    const sql = neon(connection.url)
+    pkg = 'drizzle-orm/neon-http'
+    const { drizzle } = await import(pkg)
+    return drizzle(sql)
   } else if (driver === 'libsql') {
     pkg = 'drizzle-orm/libsql'
   } else if (driver === 'mysql2') {

diff --git a/src/db/setup.ts b/src/db/setup.ts
@@ -61,6 +61,9 @@ export async function resolveDatabaseConfig(nuxt: Nuxt, hub: HubConfig): Promise
     }
     case 'postgresql': {
       config.connection = defu(config.connection, { url: process.env.POSTGRES_URL || process.env.POSTGRESQL_URL || process.env.DATABASE_URL || '' })
+      if (config.driver && ['neon-http', 'postgres-js'].includes(config.driver) && !config.connection.url) {
+        throw new Error(`\`${config.driver}\` driver requires \`DATABASE_URL\`, \`POSTGRES_URL\`, or \`POSTGRESQL_URL\` environment variable`)
+      }
       if (config.connection.url) {
         config.driver ||= 'postgres-js'
         break
@@ -103,6 +106,8 @@ export async function setupDatabase(nuxt: Nuxt, hub: HubConfig, deps: Record<str
   }
   if (driver === 'postgres-js' && !deps['postgres']) {
     logWhenReady(nuxt, 'Please run `npx nypm i postgres` to use PostgreSQL as database.', 'error')
+  } else if (driver === 'neon-http' && !deps['@neondatabase/serverless']) {
+    logWhenReady(nuxt, 'Please run `npx nypm i @neondatabase/serverless` to use Neon serverless database.', 'error')
   } else if (driver === 'pglite' && !deps['@electric-sql/pglite']) {
     logWhenReady(nuxt, 'Please run `npx nypm i @electric-sql/pglite` to use PGlite as database.', 'error')
   } else if (driver === 'mysql2' && !deps.mysql2) {
@@ -268,7 +273,16 @@ const db = drizzle({ client, schema });
 export { db, schema }
 `
   }
+  if (driver === 'neon-http') {
+    drizzleOrmContent = `import { neon } from '@neondatabase/serverless'
+import { drizzle } from 'drizzle-orm/neon-http'
+import * as schema from './db/schema.mjs'
 
+const sql = neon(${connection.connectionString})
+const db = drizzle(sql, { schema })
+export { db, schema }
+`
+  }
   if (driver === 'd1') {
     // D1 requires lazy binding access - bindings only available in request context on CF Workers
     drizzleOrmContent = `import { drizzle } from 'drizzle-orm/d1'

diff --git a/src/types/config.ts b/src/types/config.ts
@@ -156,10 +156,10 @@ export type DatabaseConfig = {
    * Database driver (optional, auto-detected if not provided)
    *
    * SQLite drivers: 'better-sqlite3', 'libsql', 'bun-sqlite', 'd1', 'd1-http'
-   * PostgreSQL drivers: 'postgres-js', 'pglite'
+   * PostgreSQL drivers: 'postgres-js', 'pglite', 'neon-http'
    * MySQL drivers: 'mysql2'
    */
-  driver?: 'better-sqlite3' | 'libsql' | 'bun-sqlite' | 'd1' | 'd1-http' | 'postgres-js' | 'pglite' | 'mysql2'
+  driver?: 'better-sqlite3' | 'libsql' | 'bun-sqlite' | 'd1' | 'd1-http' | 'postgres-js' | 'pglite' | 'neon-http' | 'mysql2'
   /**
    * Database connection configuration
    */
@@ -183,7 +183,7 @@ export type DatabaseConfig = {
 
 export type ResolvedDatabaseConfig = DatabaseConfig & {
   dialect: 'sqlite' | 'postgresql' | 'mysql'
-  driver: 'better-sqlite3' | 'libsql' | 'bun-sqlite' | 'd1' | 'd1-http' | 'postgres-js' | 'pglite' | 'mysql2'
+  driver: 'better-sqlite3' | 'libsql' | 'bun-sqlite' | 'd1' | 'd1-http' | 'postgres-js' | 'pglite' | 'neon-http' | 'mysql2'
   connection: DatabaseConnection
   migrationsDirs: string[]
   queriesPaths: string[]

diff --git a/test/database.config.test.ts b/test/database.config.test.ts
@@ -237,6 +237,55 @@ describe('resolveDatabaseConfig', () => {
         driver: 'custom-postgres'
       })
     })
+
+    it('should use neon-http driver when explicitly set', async () => {
+      process.env.DATABASE_URL = 'postgresql://user:pass@localhost:5432/db'
+
+      const nuxt = createMockNuxt()
+      const hub = createBaseHubConfig({
+        dialect: 'postgresql',
+        driver: 'neon-http'
+      })
+
+      const result = await resolveDatabaseConfig(nuxt, hub)
+
+      expect(result).toMatchObject({
+        dialect: 'postgresql',
+        driver: 'neon-http',
+        connection: {
+          url: 'postgresql://user:pass@localhost:5432/db'
+        }
+      })
+    })
+
+    it('should not use neon-http driver automatically', async () => {
+      process.env.DATABASE_URL = 'postgresql://user:pass@localhost:5432/db'
+
+      const nuxt = createMockNuxt()
+      const hub = createBaseHubConfig('postgresql')
+
+      const result = await resolveDatabaseConfig(nuxt, hub)
+
+      expect(result).toMatchObject({
+        dialect: 'postgresql',
+        driver: 'postgres-js',
+        connection: {
+          url: 'postgresql://user:pass@localhost:5432/db'
+        }
+      })
+    })
+
+    it('should throw error when DATABASE_URL is not set for neon-http', async () => {
+      const nuxt = createMockNuxt()
+      const hub = createBaseHubConfig({
+        dialect: 'postgresql',
+        driver: 'neon-http'
+      })
+
+      await expect(resolveDatabaseConfig(nuxt, hub)).rejects.toThrow(
+        'Neon HTTP driver requires DATABASE_URL, POSTGRES_URL, or POSTGRESQL_URL environment variable'
+      )
+    })
   })
 
   describe('MySQL dialect', () => {