@earth-app/collegedb 1.0.8 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # CollegeDB
 
-_Cloudflare D1 Horizontal Sharding Router_
+Universal Database Horizontal Sharding Router
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![GitHub Issues](https://img.shields.io/github/issues/earth-app/CollegeDB)](https://github.com/earth-app/CollegeDB/issues)
@@ -8,7 +8,7 @@ _Cloudflare D1 Horizontal Sharding Router_
 [![GitHub License](https://img.shields.io/github/license/earth-app/CollegeDB)](LICENSE)
 ![NPM Version](https://img.shields.io/npm/v/%40earth-app%2Fcollegedb)
 
-A TypeScript library for **true horizontal scaling** of SQLite-style databases on Cloudflare using D1 and KV. CollegeDB distributes your data across multiple D1 databases, with each table's records split by primary key across different database instances.
+A TypeScript library for **true horizontal scaling** of SQLite-style databases primarily for Cloudflare using D1 and KV, with additional provider adapters for Redis/Valkey KV and PostgreSQL/MySQL/SQLite SQL backends. CollegeDB distributes your data across multiple database shards, with each table's records split by primary key across different database instances.
 
 CollegeDB implements **data distribution** where a single logical table is physically stored across multiple D1 databases:
 
@@ -46,6 +46,7 @@ CollegeDB provides a sharding layer on top of Cloudflare D1 databases, enabling
 - **Scale horizontally** by distributing table data across multiple D1 instances
 - **Route queries automatically** based on primary key mappings
 - **Maintain consistency** with KV-based shard mapping
+- **Run on multiple providers** through `KVStorage` and `SQLDatabase` contracts
 - **Optimize for geography** with location-aware shard allocation
 - **Monitor and rebalance** shard distribution
 - **Handle migrations** between shards seamlessly
@@ -53,6 +54,7 @@ CollegeDB provides a sharding layer on top of Cloudflare D1 databases, enabling
 ## 📦 Features
 
 - **🔀 Automatic Query Routing**: Primary key → shard mapping using Cloudflare KV
+- **🧩 Provider Adapters (v1.1.0)**: Redis/Valkey KV + PostgreSQL/MySQL/SQLite SQL adapters while preserving Cloudflare compatibility
 - **🎯 Multiple Allocation Strategies**: Round-robin, random, hash-based, and location-aware distribution
 - **🔄 Mixed Strategy Support**: Different strategies for reads vs writes (e.g., location for writes, hash for reads)
 - **📊 Shard Coordination**: Durable Objects for allocation and statistics
@@ -62,6 +64,58 @@ CollegeDB provides a sharding layer on top of Cloudflare D1 databases, enabling
 - **⚡ High Performance**: Optimized for Cloudflare Workers runtime
 - **🔧 TypeScript First**: Full type safety and excellent DX
 
+## Benchmark Suite
+
+CollegeDB includes a comprehensive benchmark suite covering real-world latency across provider combinations and Cloudflare Worker routing paths.
+
+### Matrix
+
+| Scenario Key      | Scenario                         | What Happens                                                                                        | Workload Per Run                                                       |
+| ----------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| basic_crud        | Basic CRUD round-trip            | Insert, read, update, and delete a user via routed queries.                                         | 20 iterations; 4 routed SQL ops per iteration                          |
+| advanced_usage    | Advanced lookup workflow         | Writes user+post, adds lookup aliases, then validates join and alias-based lookup.                  | 15 iterations; ~5 routed SQL ops + KV lookup-key updates per iteration |
+| migration_mapping | Migration-style mapping creation | Inserts legacy records on a fixed shard, then builds shard mappings in batch and validates routing. | 10 iterations; 20 legacy records mapped per iteration                  |
+| bulk_crud         | Bulk CRUD pressure               | Performs bulk inserts, half updates, and full delete sweep, then validates shard-wide totals.       | 7 iterations; 160 inserts + 80 updates + 160 deletes per iteration     |
+| indexing          | Indexed query scan               | Creates an index on posts(user_id) and repeatedly queries the indexed path.                         | 15 iterations after warmup dataset build                               |
+
+Real-world latency benchmarks across provider combinations (`average / p95`):
+
+| Combination     | Basic CRUD          | Advanced Operations | Migration           | Bulk CRUD             | Indexing             | Overall Avg |
+| --------------- | ------------------- | ------------------- | ------------------- | --------------------- | -------------------- | ----------- |
+| cloudflare      | 13.14 ms / 16.50 ms | 4.43 ms / 9.65 ms   | 27.68 ms / 30.69 ms | 156.30 ms / 163.76 ms | 67.17 ms / 106.63 ms | 28.40 ms    |
+| postgres+redis  | 2.77 ms / 3.90 ms   | 3.11 ms / 4.64 ms   | 6.55 ms / 8.07 ms   | 42.33 ms / 80.67 ms   | 0.34 ms / 0.61 ms    | 5.87 ms     |
+| postgres+valkey | 1.65 ms / 2.23 ms   | 2.10 ms / 2.82 ms   | 5.60 ms / 6.05 ms   | 33.13 ms / 43.69 ms   | 0.30 ms / 0.46 ms    | 4.64 ms     |
+| mysql+redis     | 5.11 ms / 8.38 ms   | 5.45 ms / 8.51 ms   | 27.41 ms / 61.56 ms | 92.70 ms / 139.70 ms  | 0.49 ms / 1.22 ms    | 13.91 ms    |
+| mysql+valkey    | 4.99 ms / 6.66 ms   | 4.21 ms / 6.42 ms   | 21.68 ms / 27.20 ms | 87.67 ms / 109.44 ms  | 0.55 ms / 1.92 ms    | 12.54 ms    |
+| mariadb+redis   | 2.64 ms / 5.90 ms   | 3.02 ms / 7.55 ms   | 6.48 ms / 7.66 ms   | 46.99 ms / 58.08 ms   | 0.37 ms / 1.08 ms    | 6.29 ms     |
+| mariadb+valkey  | 2.34 ms / 4.58 ms   | 2.91 ms / 5.69 ms   | 5.73 ms / 7.35 ms   | 45.04 ms / 61.42 ms   | 0.36 ms / 0.79 ms    | 5.96 ms     |
+| sqlite+redis    | 2.21 ms / 3.84 ms   | 2.43 ms / 3.14 ms   | 10.49 ms / 17.31 ms | 140.85 ms / 184.48 ms | 0.07 ms / 0.14 ms    | 15.87 ms    |
+| sqlite+valkey   | 1.36 ms / 1.80 ms   | 2.06 ms / 2.70 ms   | 6.36 ms / 8.77 ms   | 121.13 ms / 156.31 ms | 0.06 ms / 0.14 ms    | 13.42 ms    |
+
+### Overview
+
+CollegeDB includes an integration benchmark suite covering both local provider matrices and Cloudflare Worker routing paths.
+
+Top-level benchmark scenarios:
+
+- `basic_crud`: insert/read/update/delete round-trip routing
+- `advanced_usage`: join + multi-key lookup behavior
+- `migration_mapping`: batch mapping creation for existing keys
+- `bulk_crud`: high-volume insert/update/delete flow
+- `indexing`: indexed query latency under warm data
+- `metadata_fetch`: schema/metadata query latency
+- `pragma_or_info`: provider-specific pragma/info query latency
+- `counting`: shard-wide aggregate counting
+- `shard_fanout`: all-shards fanout query aggregation
+- `reassignment`: shard reassignment and routed-read validation
+
+Benchmark reports include:
+
+- an interpretation guide (`How To Read This Report`)
+- a benchmark catalog with per-run workload details
+- a compact overall matrix (passed/failed/skipped + overall average)
+- split scenario matrices for core workload latency and introspection/routing latency
+
 ## Installation
 
 ```bash
@@ -70,6 +124,129 @@ bun add @earth-app/collegedb
 npm install @earth-app/collegedb
 ```
 
+## Provider Adapters
+
+CollegeDB can run with either native Cloudflare bindings or custom providers as long as they match the exported `KVStorage` and `SQLDatabase` interfaces.
+
+Supported adapters:
+
+- `createRedisKVProvider`
+- `createValkeyKVProvider`
+- `createPostgresSQLProvider`
+- `createMySQLSQLProvider`
+- `createSQLiteSQLProvider`
+- `createHyperdrivePostgresProvider`
+- `createHyperdriveMySQLProvider`
+
+```typescript
+import { createClient as createRedisClient } from 'redis';
+import { Pool } from 'pg';
+import { createPostgresSQLProvider, createRedisKVProvider, initialize, run, type CollegeDBConfig } from '@earth-app/collegedb';
+
+const redisClient = createRedisClient({ url: process.env.REDIS_URL });
+const pgPool = new Pool({ connectionString: process.env.POSTGRES_URL });
+
+const config: CollegeDBConfig = {
+	kv: createRedisKVProvider(redisClient),
+	shards: {
+		'pg-east': createPostgresSQLProvider(pgPool)
+	},
+	strategy: 'hash',
+	disableAutoMigration: true
+};
+
+async function bootstrap() {
+	await redisClient.connect();
+	initialize(config);
+	await run('user-1', 'INSERT INTO users (id, name) VALUES (?, ?)', ['user-1', 'Taylor']);
+}
+
+bootstrap().catch(console.error);
+```
+
+For Hyperdrive-backed SQL connections, use `createHyperdrivePostgresProvider` or `createHyperdriveMySQLProvider` with your database client factory.
+
+For a complete non-Cloudflare setup, see `examples/provider-sandbox.ts`.
+
+## Sandbox Benchmarks (Docker Compose)
+
+CollegeDB ships with an integration sandbox runner that benchmarks real latency across provider combinations.
+
+Requirements:
+
+- Docker + Docker Compose plugin
+- Bun
+- Wrangler (installed as a dev dependency and invoked by scripts)
+
+The Cloudflare benchmark path runs against the dedicated sandbox worker:
+
+- Worker entry: `sandbox/worker.ts`
+- Wrangler config: `sandbox/wrangler.jsonc`
+
+Main commands:
+
+```bash
+# Run full SQL x KV matrix plus Cloudflare local benchmark
+bun run test:sandbox
+
+# Run full SQL x KV matrix only
+bun run test:sandbox:all
+
+# Run Cloudflare local benchmark only (wrangler dev --local)
+bun run test:sandbox:cloudflare
+```
+
+Provider filters:
+
+```bash
+# One SQL provider against both KV providers
+bun run test:sandbox:mysql
+bun run test:sandbox:postgres
+bun run test:sandbox:mariadb
+bun run test:sandbox:sqlite
+
+# One KV provider against all SQL providers
+bun run test:sandbox:redis
+bun run test:sandbox:valkey
+
+# Explicit pairwise combinations
+bun run test:sandbox:postgres+redis
+bun run test:sandbox:postgres+valkey
+bun run test:sandbox:mysql+redis
+bun run test:sandbox:mysql+valkey
+bun run test:sandbox:mariadb+redis
+bun run test:sandbox:mariadb+valkey
+bun run test:sandbox:sqlite+redis
+bun run test:sandbox:sqlite+valkey
+```
+
+Output behavior:
+
+- Every run writes a timestamped Markdown report to `sandbox/results/`
+- `sandbox/results/latest.md` is always updated to the newest report
+- The runner prints the report in-terminal using Bun's Markdown renderer with ANSI formatting
+- `test:sandbox` produces a matrix for all SQL x KV combinations; filtered commands produce matrix subsets
+
+Benchmark coverage includes:
+
+- basic CRUD
+- advanced lookup/routing workflows
+- migration-style mapping creation
+- bulk CRUD
+- indexing queries
+- metadata fetch
+- pragma/info queries (provider-specific)
+- counting across shards
+- shard fanout aggregation
+- shard reassignment workflow
+
+How to read benchmark rows:
+
+- Latency cells are formatted as `average / p95` in milliseconds.
+- `FAILED` means the scenario returned an error.
+- `N/A` means the scenario was intentionally skipped in that environment.
+- Use the detailed section for full `avg`, `p50`, `p95`, `min`, `max`, and sample count (`n`).
+
 ## Basic Usage
 
 ```typescript
@@ -88,7 +265,7 @@ collegedb(
 	},
 	async () => {
 		// Create schema on new shards only (existing shards auto-detected)
-		await createSchema(env['db-new-shard']);
+		await createSchema(env['db-new-shard'], 'CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT, email TEXT)');
 
 		// Insert data (automatically routed to appropriate shard)
 		await run('user-123', 'INSERT INTO users (id, name, email) VALUES (?, ?, ?)', ['user-123', 'Johnson', 'alice@example.com']);
@@ -222,8 +399,6 @@ collegedb(
 
 ### Adding Lookup Keys to Existing Mappings
 
-s
-
 ```typescript
 const mapper = new KVShardMapper(env.KV);
 
@@ -535,7 +710,7 @@ for (const [table, pkColumn] of Object.entries(customIntegration)) {
 | ------------------------------------------ | ---------------------------------------------------------------- | -------------------------- |
 | `collegedb(config, callback)`              | Initialize CollegeDB, then run a callback                        | `CollegeDBConfig, () => T` |
 | `initialize(config)`                       | Initialize CollegeDB with configuration                          | `CollegeDBConfig`          |
-| `createSchema(d1)`                         | Create database schema on a D1 instance                          | `D1Database`               |
+| `createSchema(db, schema)`                 | Create schema on a shard database                                | `SQLDatabase, string`      |
 | `prepare(key, sql)`                        | Prepare a SQL statement for execution                            | `string, string`           |
 | `run(key, sql, bindings)`                  | Execute a SQL query with primary key routing                     | `string, string, any[]`    |
 | `first(key, sql, bindings)`                | Execute a SQL query and return first result                      | `string, string, any[]`    |
@@ -552,17 +727,31 @@ for (const [table, pkColumn] of Object.entries(customIntegration)) {
 | `getDatabaseSizeForShard(shard)`           | Get size of a specific shard in bytes                            | `string`                   |
 | `flush()`                                  | Clear all shard mappings (development only)                      | `void`                     |
 
+### Provider Adapter Functions
+
+| Function                                                   | Description                                                          | Parameters                                               |
+| ---------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------- |
+| `createRedisKVProvider(client, options?)`                  | Adapt a Redis client to CollegeDB's `KVStorage` contract             | `RedisLikeClient, { scanCount?: number }`                |
+| `createValkeyKVProvider(client, options?)`                 | Adapt a Valkey client to CollegeDB's `KVStorage` contract            | `RedisLikeClient, { scanCount?: number }`                |
+| `createPostgresSQLProvider(client)`                        | Adapt a PostgreSQL client/pool to `SQLDatabase`                      | `PostgresClientLike`                                     |
+| `createMySQLSQLProvider(client)`                           | Adapt a MySQL/MariaDB client to `SQLDatabase`                        | `MySQLClientLike`                                        |
+| `createSQLiteSQLProvider(client)`                          | Adapt a SQLite client to `SQLDatabase`                               | `SQLiteClientLike`                                       |
+| `createHyperdrivePostgresProvider(binding, clientFactory)` | Create a PostgreSQL `SQLDatabase` adapter using a Hyperdrive binding | `HyperdriveBindingLike, HyperdrivePostgresClientFactory` |
+| `createHyperdriveMySQLProvider(binding, clientFactory)`    | Create a MySQL `SQLDatabase` adapter using a Hyperdrive binding      | `HyperdriveBindingLike, HyperdriveMySQLClientFactory`    |
+| `isKVStorage(value)`                                       | Runtime guard for `KVStorage`                                        | `unknown`                                                |
+| `isSQLDatabase(value)`                                     | Runtime guard for `SQLDatabase`                                      | `unknown`                                                |
+
 ### Drop-in Replacement Functions
 
 | Function                                  | Description                                    | Parameters                     |
 | ----------------------------------------- | ---------------------------------------------- | ------------------------------ |
-| `autoDetectAndMigrate(d1, shard, config)` | Automatically detect and migrate existing data | `D1Database, string, config`   |
-| `checkMigrationNeeded(d1, shard, config)` | Check if database needs migration              | `D1Database, string, config`   |
-| `validateTableForSharding(d1, table)`     | Check if table is suitable for sharding        | `D1Database, string`           |
-| `discoverExistingPrimaryKeys(d1, table)`  | Find all primary keys in existing table        | `D1Database, string`           |
-| `integrateExistingDatabase(d1, shard)`    | Complete drop-in integration of existing DB    | `D1Database, string, mapper`   |
+| `autoDetectAndMigrate(d1, shard, config)` | Automatically detect and migrate existing data | `SQLDatabase, string, config`  |
+| `checkMigrationNeeded(d1, shard, config)` | Check if database needs migration              | `SQLDatabase, string, config`  |
+| `validateTableForSharding(d1, table)`     | Check if table is suitable for sharding        | `SQLDatabase, string`          |
+| `discoverExistingPrimaryKeys(d1, table)`  | Find all primary keys in existing table        | `SQLDatabase, string`          |
+| `integrateExistingDatabase(d1, shard)`    | Complete drop-in integration of existing DB    | `SQLDatabase, string, mapper`  |
 | `createMappingsForExistingKeys(keys)`     | Create shard mappings for existing keys        | `string[], string[], strategy` |
-| `listTables(d1)`                          | Get list of tables in database                 | `D1Database`                   |
+| `listTables(d1)`                          | Get list of tables in database                 | `SQLDatabase`                  |
 | `clearMigrationCache()`                   | Clear automatic migration cache                | `void`                         |
 
 ### Error Handling
@@ -645,15 +834,19 @@ The main configuration interface supports both single strategies and mixed strat
 
 ```typescript
 interface CollegeDBConfig {
-	kv: KVNamespace;
+	kv: KVStorage;
 	coordinator?: DurableObjectNamespace;
-	shards: Record<string, D1Database>;
+	shards: Record<string, SQLDatabase>;
 	strategy?: ShardingStrategy | MixedShardingStrategy;
 	targetRegion?: D1Region;
 	shardLocations?: Record<string, ShardLocation>;
 	disableAutoMigration?: boolean; // Default: false
 	hashShardMappings?: boolean; // Default: true
 	maxDatabaseSize?: number; // Default: undefined (no limit)
+	mappingCacheTtlMs?: number; // Default: 30000
+	knownShardsCacheTtlMs?: number; // Default: 10000
+	sizeCacheTtlMs?: number; // Default: 30000
+	migrationConcurrency?: number; // Default: 25
 }
 ```
 
@@ -706,7 +899,7 @@ const mixedStrategyConfig: CollegeDBConfig = {
 
 ### Database Size Management
 
-CollegeDB supports automatic size-based shard exclusion to prevent individual shards from becoming too large. This feature helps maintain optimal performance and prevents hitting D1 storage limits.
+CollegeDB supports automatic size-based shard exclusion to prevent individual shards from becoming too large. This feature helps maintain optimal performance and prevents hitting database storage limits.
 
 #### Configuration
 
@@ -782,12 +975,12 @@ const config: CollegeDBConfig = {
 // "Excluded 2 shards due to size limits: db-east, db-central"
 ```
 
-#### Performance Impact
+#### Size-Limit Performance Impact
 
 - **Size Check Frequency**: Only performed during new allocations (not on reads)
 - **Query Efficiency**: Uses fast SQLite pragmas (microsecond execution time)
 - **Parallel Execution**: Size checks run concurrently across all shards
-- **Caching**: No caching implemented to ensure accurate real-time limits
+- **Caching**: Size checks are cached in-memory (controlled by `sizeCacheTtlMs`, default `30000`)
 
 ### Types
 
@@ -796,6 +989,10 @@ CollegeDB exports TypeScript types for better development experience and type sa
 | Type                    | Description                    | Example                                             |
 | ----------------------- | ------------------------------ | --------------------------------------------------- |
 | `CollegeDBConfig`       | Main configuration object      | `{ kv, shards, strategy }`                          |
+| `KVStorage`             | Provider-agnostic KV contract  | `createRedisKVProvider(redisClient)`                |
+| `SQLDatabase`           | Provider-agnostic SQL contract | `createPostgresSQLProvider(pgPool)`                 |
+| `QueryResult`           | Standard query response shape  | `{ success, results, meta }`                        |
+| `QueryResultMeta`       | Query execution metadata       | `{ duration, changes?, last_row_id? }`              |
 | `ShardingStrategy`      | Single strategy options        | `'hash' \| 'location' \| 'round-robin' \| 'random'` |
 | `MixedShardingStrategy` | Mixed strategy configuration   | `{ read: 'hash', write: 'location' }`               |
 | `OperationType`         | Database operation types       | `'read' \| 'write'`                                 |
@@ -918,81 +1115,127 @@ wrangler d1 create collegedb-central
 wrangler kv namespace create "KV"
 ```
 
-### 3. Configure wrangler.toml
-
-```toml
-[[d1_databases]]
-binding = "db-east"
-database_name = "collegedb-east"
-database_id = "your-database-id"
+### 3. Configure wrangler.jsonc
 
-[[d1_databases]]
-binding = "db-west"
-database_name = "collegedb-west"
-database_id = "your-database-id"
-
-[[kv_namespaces]]
-binding = "KV"
-id = "your-kv-namespace-id"
-
-[[durable_objects.bindings]]
-name = "ShardCoordinator"
-class_name = "ShardCoordinator"
+```jsonc
+{
+	"$schema": "./node_modules/wrangler/config-schema.json",
+	"name": "collegedb-app",
+	"main": "src/index.ts",
+	"compatibility_date": "2026-04-15",
+	"d1_databases": [
+		{
+			"binding": "db-east",
+			"database_name": "collegedb-east",
+			"database_id": "your-east-database-id"
+		},
+		{
+			"binding": "db-west",
+			"database_name": "collegedb-west",
+			"database_id": "your-west-database-id"
+		}
+	],
+	"kv_namespaces": [
+		{
+			"binding": "KV",
+			"id": "your-kv-namespace-id",
+			"preview_id": "your-kv-preview-id"
+		}
+	],
+	"durable_objects": {
+		"bindings": [
+			{
+				"name": "ShardCoordinator",
+				"class_name": "ShardCoordinator"
+			}
+		]
+	},
+	"migrations": [
+		{
+			"tag": "v1",
+			"new_sqlite_classes": ["ShardCoordinator"]
+		}
+	]
+}
 ```
 
-#### Complete wrangler.toml with ShardCoordinator
-
-```toml
-name = "collegedb-app"
-main = "src/index.ts"
-compatibility_date = "2024-08-10"
-
-# D1 Database bindings
-[[d1_databases]]
-binding = "db-east"
-database_name = "collegedb-east"
-database_id = "your-east-database-id"
-
-[[d1_databases]]
-binding = "db-west"
-database_name = "collegedb-west"
-database_id = "your-west-database-id"
-
-[[d1_databases]]
-binding = "db-central"
-database_name = "collegedb-central"
-database_id = "your-central-database-id"
-
-# KV namespace for shard mappings
-[[kv_namespaces]]
-binding = "KV"
-id = "your-kv-namespace-id"
-preview_id = "your-kv-preview-id" # For local development
-
-# Durable Object for shard coordination
-[[durable_objects.bindings]]
-name = "ShardCoordinator"
-class_name = "ShardCoordinator"
-
-# Environment-specific configurations
-[env.production]
-[[env.production.d1_databases]]
-binding = "db-east"
-database_name = "collegedb-prod-east"
-database_id = "your-prod-east-id"
-
-[[env.production.d1_databases]]
-binding = "db-west"
-database_name = "collegedb-prod-west"
-database_id = "your-prod-west-id"
-
-[[env.production.kv_namespaces]]
-binding = "KV"
-id = "your-prod-kv-namespace-id"
+#### Complete wrangler.jsonc with ShardCoordinator
 
-[[env.production.durable_objects.bindings]]
-name = "ShardCoordinator"
-class_name = "ShardCoordinator"
+```jsonc
+{
+	"$schema": "./node_modules/wrangler/config-schema.json",
+	"name": "collegedb-app",
+	"main": "src/index.ts",
+	"compatibility_date": "2026-04-15",
+	"d1_databases": [
+		{
+			"binding": "db-east",
+			"database_name": "collegedb-east",
+			"database_id": "your-east-database-id"
+		},
+		{
+			"binding": "db-west",
+			"database_name": "collegedb-west",
+			"database_id": "your-west-database-id"
+		},
+		{
+			"binding": "db-central",
+			"database_name": "collegedb-central",
+			"database_id": "your-central-database-id"
+		}
+	],
+	"kv_namespaces": [
+		{
+			"binding": "KV",
+			"id": "your-kv-namespace-id",
+			"preview_id": "your-kv-preview-id"
+		}
+	],
+	"durable_objects": {
+		"bindings": [
+			{
+				"name": "ShardCoordinator",
+				"class_name": "ShardCoordinator"
+			}
+		]
+	},
+	"migrations": [
+		{
+			"tag": "v1",
+			"new_sqlite_classes": ["ShardCoordinator"]
+		}
+	],
+	"env": {
+		"production": {
+			"d1_databases": [
+				{
+					"binding": "db-east",
+					"database_name": "collegedb-prod-east",
+					"database_id": "your-prod-east-id"
+				},
+				{
+					"binding": "db-west",
+					"database_name": "collegedb-prod-west",
+					"database_id": "your-prod-west-id"
+				}
+			],
+			"kv_namespaces": [
+				{
+					"binding": "KV",
+					"id": "your-prod-kv-namespace-id"
+				}
+			],
+			"durable_objects": {
+				"bindings": [
+					{
+						"name": "ShardCoordinator",
+						"class_name": "ShardCoordinator"
+					}
+				]
+			}
+		}
+	}
+}
 ```
 
 ### 3.1. Worker Script Setup (Required for ShardCoordinator)
@@ -1762,19 +2005,25 @@ CollegeDB includes an optional **ShardCoordinator** Durable Object that provides
 
 #### Durable Object Setup
 
-First, configure the Durable Object in your `wrangler.toml`:
-
-```toml
-[[durable_objects.bindings]]
-name = "ShardCoordinator"
-class_name = "ShardCoordinator"
+First, configure the Durable Object in your `wrangler.jsonc`:
 
-# Export the ShardCoordinator class
-[durable_objects.bindings.script_name]
-# If using modules format
-[[durable_objects.bindings]]
-name = "ShardCoordinator"
-class_name = "ShardCoordinator"
+```jsonc
+{
+	"durable_objects": {
+		"bindings": [
+			{
+				"name": "ShardCoordinator",
+				"class_name": "ShardCoordinator"
+			}
+		]
+	},
+	"migrations": [
+		{
+			"tag": "v1",
+			"new_sqlite_classes": ["ShardCoordinator"]
+		}
+	]
+}
 ```
 
 #### Basic Usage with ShardCoordinator

package/dist/durable.d.ts

@@ -7,10 +7,14 @@
  *
  * @example
  * ```typescript
- * // In wrangler.toml:
- * [[durable_objects.bindings]]
- * name = "ShardCoordinator"
- * class_name = "ShardCoordinator"
+ * // In wrangler.jsonc:
+ * // {
+ * //   "durable_objects": {
+ * //     "bindings": [
+ * //       { "name": "ShardCoordinator", "class_name": "ShardCoordinator" }
+ * //     ]
+ * //   }
+ * // }
  *
  * // Usage in a Worker:
  * const coordinatorId = env.ShardCoordinator.idFromName('default');

package/dist/durable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durable.d.ts","sourceRoot":"","sources":["../src/durable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAIpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAgB;IAC5B;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAqB;IAElC;;;OAGG;gBACS,KAAK,EAAE,kBAAkB;IAIrC;;;;;;;;;;OAUG;YACW,QAAQ;IAYtB;;;;;;;;;;OAUG;YACW,SAAS;IAIvB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAgChD;;;;;;OAMG;YACW,gBAAgB;IAO9B;;;;;;;;;OASG;YACW,cAAc;IA4B5B;;;;;;;;;OASG;YACW,iBAAiB;IA6B/B;;;;;;OAMG;YACW,cAAc;IAQ5B;;;;;;;;OAQG;YACW,iBAAiB;IA+B/B;;;;;;;;;;;;;;;OAeG;YACW,mBAAmB;IAsCjC;;;;;;;;;;OAUG;YACW,WAAW;IAOzB;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAmBvB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,WAAW;IAgGnB;;;;;;;;;;;OAWG;IACG,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASvD;;;;;;;;;;;OAWG;IACG,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQvD"}
+{"version":3,"file":"durable.d.ts","sourceRoot":"","sources":["../src/durable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAIpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAgB;IAC5B;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAqB;IAElC;;;OAGG;gBACS,KAAK,EAAE,kBAAkB;IAIrC;;;;;;;;;;OAUG;YACW,QAAQ;IAYtB;;;;;;;;;;OAUG;YACW,SAAS;IAIvB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAgChD;;;;;;OAMG;YACW,gBAAgB;IAO9B;;;;;;;;;OASG;YACW,cAAc;IA4B5B;;;;;;;;;OASG;YACW,iBAAiB;IA6B/B;;;;;;OAMG;YACW,cAAc;IAQ5B;;;;;;;;OAQG;YACW,iBAAiB;IA+B/B;;;;;;;;;;;;;;;OAeG;YACW,mBAAmB;IAsCjC;;;;;;;;;;OAUG;YACW,WAAW;IAOzB;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAmBvB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,WAAW;IAgGnB;;;;;;;;;;;OAWG;IACG,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASvD;;;;;;;;;;;OAWG;IACG,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQvD"}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { all, allAllShards, allShard, collegedb, createSchema, first, firstAllSh
 export { ShardCoordinator } from './durable.js';
 export { CollegeDBError } from './errors.js';
 export { KVShardMapper } from './kvmap.js';
+export { createHyperdriveMySQLProvider, createHyperdrivePostgresProvider, createMySQLProvider as createMySQLSQLProvider, createPostgreSQLProvider as createPostgresSQLProvider, createRedisKVProvider, createSQLiteProvider as createSQLiteSQLProvider, createValkeyKVProvider, isKVStorage, isSQLDatabase, type HyperdriveBindingLike, type HyperdriveMySQLClientFactory, type HyperdrivePostgresClientFactory, type MySQLClientLike, type PostgresClientLike, type RedisLikeClient, type SQLiteClientLike } from './providers.js';
 export { autoDetectAndMigrate, checkMigrationNeeded, clearMigrationCache, clearShardMigrationCache, createMappingsForExistingKeys, createSchemaAcrossShards, discoverExistingPrimaryKeys, discoverExistingRecordsWithColumns, dropSchema, integrateExistingDatabase, listTables, migrateRecord, schemaExists, validateTableForSharding, type IntegrationOptions, type IntegrationResult, type ValidationResult } from './migrations.js';
-export type { CollegeDBConfig, D1Region, Env, MixedShardingStrategy, OperationType, ShardCoordinatorState, ShardLocation, ShardMapping, ShardStats, ShardingStrategy } from './types.js';
+export type { CollegeDBConfig, D1Region, Env, KVListResult, KVStorage, MixedShardingStrategy, OperationType, PreparedStatement, QueryResult, QueryResultMeta, SQLDatabase, ShardCoordinatorState, ShardLocation, ShardMapping, ShardStats, ShardingStrategy } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACN,GAAG,EACH,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,KAAK,EACL,cAAc,EACd,UAAU,EACV,KAAK,EACL,sBAAsB,EACtB,uBAAuB,EACvB,aAAa,EACb,UAAU,EACV,eAAe,EACf,eAAe,EACf,OAAO,EACP,aAAa,EACb,WAAW,EACX,GAAG,EACH,YAAY,EACZ,QAAQ,EACR,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,EACxB,2BAA2B,EAC3B,kCAAkC,EAClC,UAAU,EACV,yBAAyB,EACzB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACX,eAAe,EACf,QAAQ,EACR,GAAG,EACH,qBAAqB,EACrB,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACN,GAAG,EACH,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,KAAK,EACL,cAAc,EACd,UAAU,EACV,KAAK,EACL,sBAAsB,EACtB,uBAAuB,EACvB,aAAa,EACb,UAAU,EACV,eAAe,EACf,eAAe,EACf,OAAO,EACP,aAAa,EACb,WAAW,EACX,GAAG,EACH,YAAY,EACZ,QAAQ,EACR,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,EACN,6BAA6B,EAC7B,gCAAgC,EAChC,mBAAmB,IAAI,sBAAsB,EAC7C,wBAAwB,IAAI,yBAAyB,EACrD,qBAAqB,EACrB,oBAAoB,IAAI,uBAAuB,EAC/C,sBAAsB,EACtB,WAAW,EACX,aAAa,EACb,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,EACjC,KAAK,+BAA+B,EACpC,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACN,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,6BAA6B,EAC7B,wBAAwB,EACxB,2BAA2B,EAC3B,kCAAkC,EAClC,UAAU,EACV,yBAAyB,EACzB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACX,eAAe,EACf,QAAQ,EACR,GAAG,EACH,YAAY,EACZ,SAAS,EACT,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,eAAe,EACf,WAAW,EACX,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,MAAM,YAAY,CAAC"}