From 8a83ef1f11ecf019ca4574bb28efcb31c17e906a Mon Sep 17 00:00:00 2001
From: ymc9 <104139426+ymc9@users.noreply.github.com>
Date: Mon, 1 Dec 2025 14:49:17 +0800
Subject: [PATCH 1/2] doc: v3 db recipes

---
 versioned_docs/version-3.x/_components/PackageInstall.tsx  | 5 ++---
 versioned_docs/version-3.x/recipe/databases/_category_.yml | 7 +++++++
 2 files changed, 9 insertions(+), 3 deletions(-)
 create mode 100644 versioned_docs/version-3.x/recipe/databases/_category_.yml

diff --git a/versioned_docs/version-3.x/_components/PackageInstall.tsx b/versioned_docs/version-3.x/_components/PackageInstall.tsx
index 53bf8805..20dbf002 100644
--- a/versioned_docs/version-3.x/_components/PackageInstall.tsx
+++ b/versioned_docs/version-3.x/_components/PackageInstall.tsx
@@ -20,9 +20,8 @@ const PackageInstall = ({ devDependencies, dependencies }: Props) => {
             {pkgManagers.map((pkg) => (
                 <TabItem key={pkg.name} value={pkg.name} label={pkg.name}>
                     <CodeBlock language="bash">
-                        {`${devDependencies?.length ? `${pkg.command} ${pkg.dev} ${devDependencies.join(' ')}\n` : ''}${
-                            dependencies?.length ? `${pkg.command} ${dependencies.join(' ')}` : ''
-                        }`}
+                        {`${dependencies?.length ? `${pkg.command} ${dependencies.join(' ')}` : ''}
+${devDependencies?.length ? `${pkg.command} ${pkg.dev} ${devDependencies.join(' ')}\n` : ''}`}
                     </CodeBlock>
                 </TabItem>
             ))}
diff --git a/versioned_docs/version-3.x/recipe/databases/_category_.yml b/versioned_docs/version-3.x/recipe/databases/_category_.yml
new file mode 100644
index 00000000..649e74c8
--- /dev/null
+++ b/versioned_docs/version-3.x/recipe/databases/_category_.yml
@@ -0,0 +1,7 @@
+position: 1
+label: Databases
+collapsible: true
+collapsed: true
+link:
+    type: generated-index
+    title: Databases

From 67a9555246b5cbc86e36e5fb88d61faa54937dec Mon Sep 17 00:00:00 2001
From: ymc9 <104139426+ymc9@users.noreply.github.com>
Date: Mon, 1 Dec 2025 14:49:26 +0800
Subject: [PATCH 2/2] update

---
 .../version-3.x/recipe/databases/neon.md      | 43 +++++++++++++++++++
 .../version-3.x/recipe/databases/postgres.md  | 28 ++++++++++++
 .../version-3.x/recipe/databases/sqlite.md    | 24 +++++++++++
 3 files changed, 95 insertions(+)
 create mode 100644 versioned_docs/version-3.x/recipe/databases/neon.md
 create mode 100644 versioned_docs/version-3.x/recipe/databases/postgres.md
 create mode 100644 versioned_docs/version-3.x/recipe/databases/sqlite.md

diff --git a/versioned_docs/version-3.x/recipe/databases/neon.md b/versioned_docs/version-3.x/recipe/databases/neon.md
new file mode 100644
index 00000000..4004c3f2
--- /dev/null
+++ b/versioned_docs/version-3.x/recipe/databases/neon.md
@@ -0,0 +1,43 @@
+---
+sidebar_position: 3
+---
+
+import PackageInstall from '../../_components/PackageInstall';
+
+# Neon
+
+Neon can be used with the regular `pg` driver as described in the [PostgreSQL](./postgres) guide. It also provides a serverless driver that uses HTTP/WebSocket protocol which works in edge environments. This guide explains how to use the serverless driver with ZenStack.
+
+## Installing driver
+
+<PackageInstall dependencies={['@neondatabase/serverless']} />
+
+## Creating ZenStackClient
+
+```ts
+import { schema } from '@/zenstack/schema';
+import { Pool } from '@neondatabase/serverless';
+import { ZenStackClient } from '@zenstackhq/orm';
+import { PostgresDialect } from '@zenstackhq/orm/dialects/postgres';
+
+const db = new ZenStackClient(schema, {
+    dialect: new PostgresDialect({
+        pool: new Pool({
+            connectionString: process.env.DATABASE_URL,
+        }),
+    }),
+});
+```
+
+## Notes about edge runtime
+
+Edge environments are ephemeral and often only live to serve a single request. Instead of holding a global singleton client instance, you should create a new one per request. The serverless driver is designed to be used this way.
+
+```ts
+export async function handler(req: Request): Promise<Response> {
+    const db = createClient();
+    // use db...
+    await db.$disconnect();
+    return new Response('ok');
+}
+```
diff --git a/versioned_docs/version-3.x/recipe/databases/postgres.md b/versioned_docs/version-3.x/recipe/databases/postgres.md
new file mode 100644
index 00000000..15c0de24
--- /dev/null
+++ b/versioned_docs/version-3.x/recipe/databases/postgres.md
@@ -0,0 +1,28 @@
+---
+sidebar_position: 1
+---
+
+import PackageInstall from '../../_components/PackageInstall';
+
+# PostgreSQL
+
+## Installing driver
+
+<PackageInstall dependencies={['pg']} devDependencies={['@types/pg']} />
+
+## Creating ZenStackClient
+
+```ts
+import { schema } from './zenstack/schema';
+import { Pool } from 'pg';
+import { ZenStackClient } from '@zenstackhq/orm';
+import { PostgresDialect } from '@zenstackhq/orm/dialects/postgres';
+
+const db = new ZenStackClient(schema, {
+    dialect: new PostgresDialect({
+        pool: new Pool({
+            connectionString: process.env.DATABASE_URL,
+        }),
+    }),
+});
+```
diff --git a/versioned_docs/version-3.x/recipe/databases/sqlite.md b/versioned_docs/version-3.x/recipe/databases/sqlite.md
new file mode 100644
index 00000000..581e1267
--- /dev/null
+++ b/versioned_docs/version-3.x/recipe/databases/sqlite.md
@@ -0,0 +1,24 @@
+---
+sidebar_position: 2
+---
+
+import PackageInstall from '../../_components/PackageInstall';
+
+# SQLite
+
+## Installing driver
+
+<PackageInstall dependencies={['better-sqlite3']} devDependencies={['@types/better-sqlite3']} />
+
+## Creating ZenStackClient
+
+```ts
+import { schema } from './zenstack/schema';
+import SQLite from 'better-sqlite3';
+import { ZenStackClient } from '@zenstackhq/orm';
+import { SqliteDialect } from '@zenstackhq/orm/dialects/sqlite';
+
+const db = new ZenStackClient(schema, {
+    dialect: new SqliteDialect({ database: new SQLite('./dev.db') }),
+});
+```