src/docs/src/KV.md
The Key-Value Store API lets you store and retrieve data using key-value pairs in the cloud.
It supports various operations such as set, get, delete, list keys, increment and decrement values, and flush data. This enables you to build powerful functionality into your app, including persisting application data, caching, storing configuration settings, and much more.
Puter.js handles all the infrastructure for you, so you don't need to set up servers, handle scaling, or manage backups. And thanks to the User-Pays Model, you don't have to worry about storage, read, or write costs, as users of your application cover their own usage.
<div class="info"><strong>Need to share data across users?</strong> Each user's key-value store lives in their own account, so one user can't read another's data. To keep a single, centralized store that every user reads from and writes to, use a <a href="/Workers/">Serverless Worker</a> — its code can act on the worker owner's resources, giving all users one shared backend.</div><html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
puter.kv.set('name', 'Puter Smith').then((success) => {
puter.print(`Key-value pair created/updated: ${success}`);
});
</script>
</body>
</html>
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
(async () => {
// (1) Create a new key-value pair
await puter.kv.set('name', 'Puter Smith');
puter.print("Key-value pair 'name' created/updated
");
// (2) Retrieve the value of key 'name'
const name = await puter.kv.get('name');
puter.print(`Name is: ${name}`);
})();
</script>
</body>
</html>
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
puter.kv.incr('testIncrKey').then((newValue) => {
puter.print(`New value: ${newValue}`);
});
</script>
</body>
</html>
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
puter.kv.decr('testDecrKey').then((newValue) => {
puter.print(`New value: ${newValue}`);
});
</script>
</body>
</html>
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
(async () => {
// create a new key-value pair
await puter.kv.set('name', 'Puter Smith');
puter.print("Key-value pair 'name' created/updated
");
// delete the key 'name'
await puter.kv.del('name');
puter.print("Key-value pair 'name' deleted
");
// try to retrieve the value of key 'name'
const name = await puter.kv.get('name');
puter.print(`Name is now: ${name}`);
})();
</script>
</body>
</html>
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
(async () => {
// (1) Create a number of key-value pairs
await puter.kv.set('name', 'Puter Smith');
await puter.kv.set('age', 21);
await puter.kv.set('isCool', true);
puter.print("Key-value pairs created/updated
");
// (2) Retrieve all keys
const keys = await puter.kv.list();
puter.print(`Keys are: ${keys}
`);
// (3) Retrieve all keys and values
const key_vals = await puter.kv.list(true);
puter.print(`Keys and values are: ${(key_vals).map((key_val) => key_val.key + ' => ' + key_val.value)}
`);
// (4) Match keys with a pattern
const keys_matching_pattern = await puter.kv.list('is*');
puter.print(`Keys matching pattern are: ${keys_matching_pattern}
`);
// (5) Delete all keys (cleanup)
await puter.kv.del('name');
await puter.kv.del('age');
await puter.kv.del('isCool');
})();
</script>
</body>
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
(async () => {
// (1) Create a number of key-value pairs
await puter.kv.set('name', 'Puter Smith');
await puter.kv.set('age', 21);
await puter.kv.set('isCool', true);
puter.print("Key-value pairs created/updated
");
// (2) Rretrieve all keys
const keys = await puter.kv.list();
puter.print(`Keys are: ${keys}
`);
// (3) Flush the key-value store
await puter.kv.flush();
puter.print('Key-value store flushed
');
// (4) Retrieve all keys again, should be empty
const keys2 = await puter.kv.list();
puter.print(`Keys are now: ${keys2}
`);
})();
</script>
</body>
These Key-Value Store features are supported out of the box when using Puter.js:
puter.kv.set() - Set a key-value pairputer.kv.get() - Get a value by keyputer.kv.incr() - Increment a numeric valueputer.kv.decr() - Decrement a numeric valueputer.kv.add() - Add values to an existing keyputer.kv.remove() - Remove values by pathputer.kv.update() - Update values by pathputer.kv.del() - Delete a key-value pairputer.kv.expire() - Set key expiration in secondsputer.kv.expireAt() - Set key expiration timestampputer.kv.list() - List all keysputer.kv.flush() - Clear all dataYou can see various Puter.js Key-Value Store features in action from the following examples: