Interface CollegeDBConfig

Whether a read that finds no mapping should record one.

When false a read resolves a shard and returns it without writing to KV, so looking up a key that has no row costs no KV write and leaves no mapping behind. Writes always record their mapping.

Shard coordinator Durable Object

Enable debug logging for development and troubleshooting

Disable automatic migration detection and background migration (useful for testing)

Whether to hash shard mapping keys with SHA-256 for security and privacy. When enabled, primary keys are hashed before storing in KV, protecting sensitive data like emails from being visible in KV keys.

Primary-key column per table, used by the query planner to recover the routing key from a statement. Tables absent from the map use id.

In-memory TTL for known shard list cache.

Key-value provider for storing shard mappings

Whether a mapping miss should also probe the legacy multi-key record.

Every writer since 1.0.3 stores a single-key record for each lookup key alongside the multi-key record, so this second read cannot succeed for data this version wrote and doubles the KV cost of every true miss. Enable it only while migrating mappings written before 1.0.3.

In-memory TTL for primary key to shard mapping cache.

Maximum database size in bytes. When set, shards that exceed this size are excluded from new allocations (existing mappings remain intact).

When omitted, size-based filtering is disabled to avoid extra sizing queries. This significantly reduces routing latency for write-heavy workloads.

Concurrency limit for migration mapping operations.

Per-phase timing observer. When set, CollegeDB reports the cost of hashing, each KV round trip, shard selection, coordinator calls, and SQL execution. Unset, the instrumentation allocates nothing.

What the query planner does with a statement whose routing key it cannot prove.

• throw - reject the call and point the caller at the explicit-key API.
• fanout - run the statement on every shard.

throw is the default because a mis-routed write lands a row where no reader will look, while a thrown error is visible immediately.

How a primary key is resolved to a shard.

• computed - derive the shard from the key with rendezvous hashing and consult KV only for keys that were explicitly reassigned or placed by an older algorithm. Removes one KV read per operation and one KV write per new key.
• kv - read the mapping from KV, allocating and recording on a miss.

Only meaningful for the hash strategy. round-robin and random are not functions of the key, and location depends on the requesting region rather than the key, so all three force kv.

Defaults to computed for the hash strategy on a deployment CollegeDB has not seen before, and to kv when existing mappings are detected, so an upgrade never starts computing placements for keys another algorithm placed. Call rebalance() to migrate such a deployment.

Geographic locations of each shard (required for location strategy)

Available SQL shard providers

In-memory TTL for shard size checks when maxDatabaseSize is enabled.

Default shard allocation strategy (can be single strategy or mixed strategy object)

Target region for location-based sharding

Extends the lifetime of CollegeDB's background work past the current request. Pass ctx.waitUntil from a Worker: without it, the background known-shard sync and auto-migration started by initialize are cancelled when the request that triggered them ends.