Keyv Files

keyv@6.1.0 — 2026-10-06

First stable release of Keyv v6, published to npm's latest tag.

All 20 published packages release in lockstep at 6.1.0; there is no 6.0.0. @keyv/website is private and not published.

Coming from v5? Follow the v5 to v6 migration guide, or point your coding agent at https://keyv.org/skills/migrate. v5 stays in maintenance; install it with keyv@5.

⚠ BREAKING CHANGES

These are changes since 6.0.0-rc.1. Coming from v5, start with the migration guide.

• keyv, adapters: the namespace separator option is namespaceSeparator on every adapter that joins the namespace and the key, and it defaults to ::; keySeparator and keyPrefixSeparator are gone (d0bc310, [#2189]) Migration from rc.1: rename the option. To keep reading namespaced data rc.1 wrote, set namespaceSeparator: ':' on the memory and bridge adapters, @keyv/etcd, @keyv/dynamo, @keyv/cloudflare-kv and @keyv/valkey. @keyv/redis already used :: in rc.1. Migration from v5: v5's Keyv also prefixed every key with <namespace>:, so the setting depends on the adapter. A default v5 @keyv/redis setup stored keyv::keyv:foo, which v6 reads with new Keyv(new KeyvRedis(uri, { namespaceSeparator: '::keyv:' }), { namespace: 'keyv' }). If you used createKeyv(), set only the same namespace. For other adapters, see The Default keyv Namespace Was Removed.
• keyv: throwOnErrors is removed; a failed call returns a fallback value when an error listener is attached and rejects when none is (860dba7, [#2155]) Migration: remove throwOnErrors, and attach an error listener if you want fallback values instead of rejections.
• keyv: a namespace set on the storage adapter is used when Keyv has none (c6e88e7, [#2156]) Migration: data rc.1 wrote in that setup has no namespace; remove the adapter's namespace to keep reading it, or let it refill.
• keyv: a namespaced clear() fails instead of wiping a store it can't list (790eb3c, [#2186]) Migration: give the store keys() or iterator(), or call clear() on a Keyv instance without a namespace to empty it.
• keyv: writes fail when an encryption adapter is set and serialization is off; rc.1 stored those values unencrypted (b73ee16, [#2176]) Migration: keep serialization on, which is the default, when you use encryption.
• postgres, sqlite, mongo, dynamo, cloudflare-kv, etcd: keys that start with <namespace>: are stored as given instead of being treated as already prefixed (9dec04c, [#2159]) Migration: entries rc.1 wrote under such keys read as missing; write them again.
• encrypt-node, encrypt-web: @keyv/encrypt-node accepts only AES-GCM, AES-CCM and ChaCha20-Poly1305 with base64, base64url or hex output, and @keyv/encrypt-web accepts only AES-GCM; AES-CBC is removed (b06ec8b, [#2187]) Migration: the defaults are unchanged; re-encrypt values written with any other algorithm or encoding before you upgrade.
• dynamo: keys written without a TTL no longer expire, and sixHoursInMilliseconds is removed (476761d, [#2161]) Migration: set Keyv's ttl option for a default expiry, as in new Keyv(store, { ttl: 6 * 60 * 60 * 1000 }).
• etcd: the lease property is removed, and the store ttl applies to each key from its own write (6ba3096, [#2160]) Migration: remove code that reads or sets store.lease.
• etcd: without a namespace, clear() and iterator() only touch entries Keyv wrote without a namespace (8a77946, [#2173]) Migration: set noNamespaceAffectsAll: true for the rc.1 behavior, and namespaceSeparator: ':' while etcd still holds namespaced rc.1 entries.
• memcache: clear() only removes the store's own entries, and values rc.1 wrote read as missing (12415c5, [#2179]) Migration: let the cache refill; set noNamespaceAffectsAll: true on a store without a namespace to flush the whole server.
• bigmap: setting storeSize keeps every entry and no longer emits clear (b80b44d, [#2178]) Migration: call clear() yourself if you resized the map to empty it.

Features

• add the keyv-migrate agent skill, which upgrades a project from Keyv v4 or v5 to v6; it is published at https://keyv.org/skills/migrate (bae30d5, [#2171])

bash npx skills add jaredwray/keyv --skill keyv-migrate

• add a namespaceSeparator option to every adapter that joins the namespace and the key; it defaults to :: (d0bc310, [#2189])

```ts import Keyv from 'keyv'; import KeyvEtcd from '@keyv/etcd';

// Read keys written with the old ':' separator const keyv = new Keyv(new KeyvEtcd('etcd://localhost:2379', { namespaceSeparator: ':' }), { namespace: 'keyv' }); ```

Bug Fixes

• keyv: promise-based stores without async methods go through KeyvBridgeAdapter (9c82ca3, [#2157])
• keyv: the sanitizer strips patterns until none remain (3462350, [#2158])
• keyv, postgres: fractional TTLs no longer fail writes, and postgres disconnect() releases the pool it connected with (82daf5d, [#2168])
• postgres, sqlite: a clearExpiredInterval over 24.8 days no longer runs cleanup every millisecond (920ad81, [#2164])
• cloudflare-kv: keys with a TTL of 60 seconds or less are removed by KV (ce6efce, [#2162])
• etcd: the value envelope uses Keyv's JSON serializer, so Buffer and BigInt values round-trip (9010961, [#2041])
• etcd: setMany() reports failed writes as false (c8133f7, [#2172])
• memcache: keys memcached can't store now work, and rejected writes return false (365eeba, [#2174])
• mongo: add a v6 migration script so documents v5 wrote stay readable (4068b0a, [#2152])
• mongo: GridFS reads the newest revision, and delete() removes every revision (8101af5, [#2163])
• mysql: tables get a primary key on (namespace, id), and existing tables are migrated on connect (1bb5d90, [#2165])
• mysql: the primary-key migration keeps primary keys you added and finds generated invisible ones (fbbb044, [#2170])
• mysql, postgres: the v6 migration scripts ship in the package and run with npx tsx (8ede7f4, [#2150])
• mysql, valkey: keyv is a peer dependency instead of a bundled copy (2c72abe, [#2149])
• postgres: the migration script drops the legacy primary key first, deleteMany() runs as one statement, and SQL NULL reads as undefined (aa692eb, [#2064])
• redis: createKeyv() accepts cluster and sentinel options, replacing the client removes the old client's listeners, and missing values are undefined (cab81d2, [#2062])
• redis: concurrent operations during the handshake share one connect instead of failing (bb35d2b, [#2105])
• redis: connectionTimeout covers the handshake, and timed-out connects close their sockets (00a48ba, [#2108])
• redis: createKeyvNonBlocking() stops reconnecting to a server that is down (0575171, [#2167])
• redis: clear() and iterator() match the namespace literally, not as a glob pattern (b91b8bf, [#2185])
• sqlite: converting a v5 table runs in a transaction, and the sqlite3 driver no longer hangs after a failed statement (90630ee, [#2063])
• valkey: reads return undefined, never null (2435715, [#2065])
• valkey: clear() removes only its own namespace, not namespaces that share its prefix (4d369be, [#2147])
• valkey: clear(), iterator() and useSets work in cluster mode (a4326e9, [#2166])

Documentation

• keyv.org moves to the Docula modern template, and the v5 docs are archived at https://keyv.org/v5/ (52f692d, [#2066])
• how to keep reading data written by v5, with each adapter's stored key layout (df63ef6, [#2151])
• encryption: use a random secret as the key, or derive one with PBKDF2 (b5eeec9, [#2188])
• postgres, redis: TLS how-tos for Amazon RDS for PostgreSQL and Redis Cloud (bda7916, [#2194])
• migration guide and skill corrections (13c683e, [#2169]; f1bb9e3, [#2175]; bec33f4, [#2177])

Internal

• npm releases are staged and approved with 2FA, with provenance and an Aikido scan gate; stable v6 releases stage under latest (#2057, [#2124], [#2148])
• runtime dependency upgrades: @redis/client 6.2.1, mongodb 7.6.0, mysql2 3.24.2, pg 8.23.0, better-sqlite3 13.0.3, memcache 1.10.0, AWS SDK DynamoDB 3.1121.0, msgpackr 2.1.0, lz4-napi 2.10.0, hookified 3.0.3 (#2083–#2092)

Contributors

• @jaredwray (99)

Full List of Changes

• etcd - fix: Use Keyv default serializer for value envelope by @jaredwray in [#2041]
• mono - chore: defense - stage npm publishes with Aikido gate by @jaredwray in [#2057]
• website - docs: migrate to Docula 2 modern template and archive v5 by @jaredwray in [#2066]
• redis - refactor: v6 client swap, API docs, and test uniformity by @jaredwray in [#2062]
• postgres - fix: v6 release review (migration, API docs, events) by @jaredwray in [#2064]
• sqlite - fix: harden v6 sqlite adapter, docs, and tests by @jaredwray in [#2063]
• valkey - refactor: v6 review cleanup for docs, tests, and events by @jaredwray in [#2065]
• redis - fix: share in-flight connect so concurrent ops are not dropped by @jaredwray in [#2105]
• redis - fix: Abort timed-out Redis connects without leaking sockets by @jaredwray in [#2108]
• mono - chore: release concurrency group + v5 staged publishing docs by @jaredwray in [#2124]
• valkey - fix: clear() only removes keys in the exact namespace by @jaredwray in [#2147]
• mono - fix: stage stable v6 releases under latest, not v6-lts by @jaredwray in [#2148]
• mono - fix: declare keyv as a peer dependency of mysql and valkey by @jaredwray in [#2149]
• mono - fix: make the mysql and postgres v6 migration scripts runnable by @jaredwray in [#2150]
• mono - docs: explain how to keep reading data written by v5 by @jaredwray in [#2151]
• mongo - fix: add a v6 migration script so v5 documents stay readable by @jaredwray in [#2152]
• keyv - fix: follow the EventEmitter error rule and remove throwOnErrors by @jaredwray in [#2155]
• keyv - fix: keep a namespace set on the storage adapter by @jaredwray in [#2156]
• keyv - fix: route promise-based stores without async methods through the bridge by @jaredwray in [#2157]
• keyv - fix: strip sanitizer patterns until none remain by @jaredwray in [#2158]
• mono - fix: keys that start with the namespace no longer collide by @jaredwray in [#2159]
• etcd - fix: default ttl applies per key and keeps working after the first lease expires by @jaredwray in [#2160]
• dynamo - fix: clear() removes every scan page and keys without a ttl no longer expire by @jaredwray in [#2161]
• cloudflare-kv - fix: keys with a ttl of 60 seconds or less are removed by KV by @jaredwray in [#2162]
• mongo - fix: GridFS reads the newest value and delete removes every revision by @jaredwray in [#2163]
• mono - fix: a clearExpiredInterval over 24.8 days no longer runs cleanup every millisecond by @jaredwray in [#2164]
• mysql - fix: tables get a primary key on (namespace, id) by @jaredwray in [#2165]
• valkey - fix: clear, iterator and useSets work in cluster mode by @jaredwray in [#2166]
• redis - fix: createKeyvNonBlocking stops reconnecting, and failed connects stop adding listeners by @jaredwray in [#2167]
• mono - fix: fractional TTLs no longer fail writes, and postgres disconnect releases the pool it connected with by @jaredwray in [#2168]
• mono - docs: drop the removed useKeyPrefix option from dynamo and cloudflare-kv examples by @jaredwray in [#2169]
• mysql - fix: Primary key migration keeps owner keys, replaces prefix keys, and finds hidden generated keys by @jaredwray in [#2170]
• etcd - fix: setMany reports failed writes as false by @jaredwray in [#2172]
• etcd - fix: Without a namespace, clear() and iterator() only touch Keyv's own entries by @jaredwray in [#2173]
• mono - feat: Add keyv-migrate agent skill at keyv.org/skills/migrate and fix stale v6 docs by @jaredwray in [#2171]
• memcache - fix: Keys memcached can't store now work, and rejected writes return false by @jaredwray in [#2174]
• mono - docs: Correct old delete results and etcd clear() in the migration skill by @jaredwray in [#2175]
• keyv - fix: writes fail with an error when encryption is set without serialization by @jaredwray in [#2176]
• skills - docs: bound the Redis "every key" range to @keyv/redis 2.7 through 3.0 by @jaredwray in [#2177]
• bigmap - fix: Changing storeSize or storeHashFunction keeps every entry by @jaredwray in [#2178]
• memcache - fix: clear() only removes the store's own entries by @jaredwray in [#2179]
• redis - fix: clear() and iterator() match the namespace literally by @jaredwray in [#2185]
• keyv - fix: a namespaced clear() fails instead of wiping a store it can't scope by @jaredwray in [#2186]
• mono - fix: authenticated ciphers only, bridge setMany() results, serializer __proto__ by @jaredwray in [#2187]
• mono - docs: use a random secret as the encryption key, or derive one with PBKDF2 by @jaredwray in [#2188]
• mono - feat: namespaceSeparator on every adapter, defaulting to :: by @jaredwray in [#2189]
• mono - docs: Amazon RDS for PostgreSQL and Redis Cloud how-tos by @jaredwray in [#2194]
• mono - chore: Release v6.1.0 by @jaredwray in [#2192]
• …plus 51 dependency, tooling, CI, test and repo-maintenance PRs; see the full diff.

Full diff: https://github.com/jaredwray/keyv/compare/v6.0.0-rc.1...v6.1.0