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

Name passed to idFromName when the router reaches the coordinator. Deployments that split their keys into groups can give each group its own scope and coordinator object. A scope change starts from an empty allocation ledger.

Enable debug logging for development and troubleshooting

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

Decides whether a shard may take new keys, after shardState and maxDatabaseSize have had their say. Return false to keep a shard out; a throw or rejection fails the operation with ELIGIBILITY_FAILED and never counts as eligible.

With a kv-mapped strategy it runs for each new key (operation: 'allocate'), because the chosen shard is stored as a mapping. With computed placement it runs when a snapshot is published (operation: 'publish'), at a cold start and in publishEligibility(), and the result becomes a topology epoch. It never affects a read or an existing key. When no shard is eligible, allocation throws NO_ELIGIBLE_SHARD. Under computed placement a process that finds an existing manifest and no eligible shard publishes nothing, keeps serving reads from the epochs it has and refuses every write with NO_ELIGIBLE_SHARD.

Re-initializing does not compare this function, so a changed predicate takes effect through publishEligibility() or the next cold start.

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.

Partition of the journal, for deployments that share one journal database.

Shard binding that holds the migration journal.

reassignShard, rebalance and recoverMigrations need it once there is more than one shard, and throw JOURNAL_NOT_CONFIGURED without it. A single-shard config falls back to its only shard. When set, router-issued inserts and upserts also check the shard-local tombstone, so a stale caller cannot recreate a row on a shard the key has left.

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.

Under computed placement, a write to a key whose owner changed in an earlier topology change also probes this column to find the shard that holds the row, so a table with another key column must be listed here.

In-memory TTL for known shard list cache.

Key-value provider for storing shard mappings

Per-call time limit for KV reads and writes. A call that runs longer rejects with KV_TIMEOUT; it never resolves as "not found". The underlying call is not cancelled.

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.

A shard whose size cannot be read is not excluded: the limit applies only where it can be measured. With debug set, the first failure per shard is logged.

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 kv. Set computed to opt in.

Geographic locations of each shard (required for location strategy)

Available SQL shard providers

Known facts per shard binding. id is the physical database id that session bookmarks are keyed by; a read that supplies bookmarks for a binding with no id throws BOOKMARK_IDENTITY_UNVERIFIED.

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.