D1 multi tenant improvements and test coverage

.github/workflows/build-hono-example.yml

@@ -19,6 +19,10 @@ on:
             - ".github/workflows/build-hono-example.yml" # This file
     workflow_dispatch:
 
+concurrency:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+    cancel-in-progress: true
+
 jobs:
     build:
         runs-on: ubuntu-latest

.github/workflows/build-opennextjs-example.yml

@@ -19,6 +19,10 @@ on:
             - ".github/workflows/build-example.yml" # This file
     workflow_dispatch:
 
+concurrency:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+    cancel-in-progress: true
+
 jobs:
     build:
         runs-on: ubuntu-latest

.github/workflows/build-opennextjs-org-d1-multi-tenancy-example.yml

@@ -19,6 +19,10 @@ on:
             - ".github/workflows/build-opennextjs-org-d1-multi-tenancy-example.yml" # This file
     workflow_dispatch:
 
+concurrency:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+    cancel-in-progress: true
+
 jobs:
     build:
         runs-on: ubuntu-latest

.github/workflows/build.yml

@@ -7,6 +7,10 @@ on:
         branches: [main]
     workflow_dispatch:
 
+concurrency:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+    cancel-in-progress: true
+
 jobs:
     build:
         runs-on: ubuntu-latest

.github/workflows/cli-build.yml

@@ -7,6 +7,10 @@ on:
     pull_request:
         paths: ["cli/**"]
 
+concurrency:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+    cancel-in-progress: true
+
 jobs:
     build:
         runs-on: ubuntu-latest

.github/workflows/cli-test.yml

@@ -7,6 +7,10 @@ on:
     pull_request:
         paths: ["cli/**"]
 
+concurrency:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+    cancel-in-progress: true
+
 jobs:
     test:
         runs-on: ubuntu-latest

.github/workflows/continuous-releases.yml

@@ -6,6 +6,10 @@ on:
         branches: [main]
     workflow_dispatch:
 
+concurrency:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+    cancel-in-progress: true
+
 permissions: {}
 
 jobs:

.github/workflows/test.yml

@@ -0,0 +1,140 @@
+name: Test Suite
+
+on:
+    push:
+        branches:
+          - main
+          - "feat/d1-multi-tenancy"
+    pull_request:
+        branches:
+          - main
+          - "feat/d1-multi-tenancy"
+    workflow_dispatch:
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    unit-tests:
+        name: Unit & Integration Tests (Node ${{ matrix.node-version }})
+        runs-on: ubuntu-latest
+
+        strategy:
+            fail-fast: false
+            matrix:
+                node-version: ["20", "22", "24"]
+
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Setup Node.js ${{ matrix.node-version }}
+              uses: actions/setup-node@v4
+              with:
+                  node-version: ${{ matrix.node-version }}
+
+            - name: Setup pnpm
+              uses: pnpm/action-setup@v4
+              with:
+                  version: 10.10.0
+                  run_install: false
+
+            - name: Get pnpm store directory
+              shell: bash
+              run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+            - name: Cache pnpm dependencies
+              uses: actions/cache@v4
+              with:
+                  path: ${{ env.STORE_PATH }}
+                  key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+                  restore-keys: |
+                      ${{ runner.os }}-pnpm-
+
+            - name: Install dependencies
+              run: pnpm install
+
+            - name: Run tests
+              run: pnpm test
+
+            - name: Run tests with coverage
+              run: pnpm test:coverage
+              if: matrix.node-version == '22'
+
+    typecheck:
+        name: Typecheck
+        runs-on: ubuntu-latest
+
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "22"
+
+            - name: Setup pnpm
+              uses: pnpm/action-setup@v4
+              with:
+                  version: 10.10.0
+                  run_install: false
+
+            - name: Install dependencies
+              run: pnpm install
+
+            - name: Typecheck
+              run: pnpm typecheck
+
+    sharding-scenarios:
+        name: Sharding Scenarios
+        runs-on: ubuntu-latest
+        strategy:
+            fail-fast: false
+            matrix:
+                scenario:
+                    - name: "Multi-DB Sharding"
+                      test-filter: "sharding-multi-db"
+                    - name: "Integration Sharding"
+                      test-filter: "integration-sharding"
+                    - name: "Shard Cache"
+                      test-filter: "shard-cache"
+                    - name: "ID Generator & Routing"
+                      test-filter: "id-generator"
+                    - name: "Schema Detection"
+                      test-filter: "schema-detection"
+                    - name: "D1 Utils"
+                      test-filter: "d1-utils"
+                    - name: "Plugin Index"
+                      test-filter: "__tests__/index"
+
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "24"
+
+            - name: Setup pnpm
+              uses: pnpm/action-setup@v4
+              with:
+                  version: 10.10.0
+                  run_install: false
+
+            - name: Get pnpm store directory
+              shell: bash
+              run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+            - name: Cache pnpm dependencies
+              uses: actions/cache@v4
+              with:
+                  path: ${{ env.STORE_PATH }}
+                  key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+                  restore-keys: |
+                      ${{ runner.os }}-pnpm-
+
+            - name: Install dependencies
+              run: pnpm install
+
+            - name: "Run: ${{ matrix.scenario.name }}"
+              run: npx vitest run --reporter=verbose ${{ matrix.scenario.test-filter }}

.gitignore

@@ -5,4 +5,6 @@ node_modules
 dist
 pnpm-lock.yaml
 bun.lock
-*.log
+*.log
+.wrangler
+coverage

README.md

@@ -19,6 +19,7 @@ Demo implementations are available in the [`examples/`](./examples/) directory f
 - 🚀 **Hyperdrive Support**: Connect to Postgres and MySQL databases through Cloudflare Hyperdrive.
 - 🔌 **KV Storage Integration**: Optionally use Cloudflare KV for secondary storage (e.g., session caching).
 - 📁 **R2 File Storage**: Upload, download, and manage user files with Cloudflare R2 object storage and database tracking.
+- 🏢 **D1 Multi-Tenancy**: Automatic tenant database creation with Universal ID-based sharding for optimal performance.
 - 📍 **Automatic Geolocation Tracking**: Enrich user sessions with location data derived from Cloudflare.
 - 🌐 **Cloudflare IP Detection**: Utilize Cloudflare's IP detection headers out-of-the-box.
 - 🔍 **Rich Client-Side Context**: Access timezone, city, country, region, and more via the client plugin.
@@ -34,7 +35,7 @@ Demo implementations are available in the [`examples/`](./examples/) directory f
 - [x] R2
 - [ ] Cloudflare Images
 - [ ] Durable Objects
-- [ ] D1 Multi-Tenancy
+- [x] D1 Multi-Tenancy with Universal ID-based Sharding
 
 **CLI:**
 
@@ -67,6 +68,8 @@ Demo implementations are available in the [`examples/`](./examples/) directory f
     - [7. Initialize the Client](#7-initialize-the-client)
 - [Usage Examples](#usage-examples)
     - [Accessing Geolocation Data](#accessing-geolocation-data)
+- [D1 Multi-Tenancy with Universal ID Sharding](./docs/d1-multi-tenancy-universal-ids.md)
+- [D1 Multi-Tenancy Plugin Integration Guide](./docs/d1-multi-tenancy-plugins.md)
 - [R2 File Storage Guide](./docs/r2.md)
 - [License](#license)
 - [Contributing](#contributing)
@@ -339,6 +342,15 @@ For integrating the generated `auth.schema.ts` with your existing Drizzle schema
 
 If you provide a KV namespace in the `withCloudflare` configuration (as shown in `src/auth/index.ts`), it will be used as [Secondary Storage](https://www.better-auth.com/docs/concepts/database#secondary-storage) by Better Auth. This is typically used for caching or storing session data that doesn't need to reside in your primary database.
 
+When D1 multi-tenancy is configured, the same KV namespace (or a dedicated one passed as `multiTenancy.kv`) is also used as a **persistent L2 backing store for the shard cache**. This means the `shardHash → databaseId` mapping survives Worker cold starts and is shared across all Worker instances, eliminating the tenant-table re-hydration query on startup.
+
+```typescript
+multiTenancy: {
+    // ... other options
+    kv: env.KV, // uses this KV for the shard cache; falls back to top-level kv if omitted
+},
+```
+
 Ensure your KV namespace (e.g., `USER_SESSIONS`) is correctly bound in your `wrangler.toml` file.
 
 ### 6. Set Up API Routes