src/backend/doc/extensions/builtins/data.md

Extensions - the data extension

The data extension can be imported in custom extensions for access to the database and key-value store.

You can import these from 'data':

• db - Puter's main SQL database
• kv - A persistent key-value store
• cache - In-memory kv.js store

const { db, kv, cache } = extension.import('data');

Database (db)

Don't forget to import it first!

const { db } = extension.import('data');

db.read

Usage:

const rows = await db.read('SELECT * FROM apps WHERE `name` = ?', [
    'editor'
]);

db.write

Usage:

const {
    insertId,        // internal ID of new row (if this is an INSERT)
    anyRowsAffected, // true if 1 or more rows were affected
} = await db.write(
    // A query like INSERT, UPDATE, DELETE, etc...
    'INSERT INTO example_table (a, b, c) VALUES (?, ?, ?)',
    // Parameters (all user input should go here)
    [
        "Value for column a",
        "Value for column b",
        "Value for column c",
    ]
);

Persistent KV Store (kv)

Don't forget to import it first!

const { kv } = extension.import('data');

kv.get({ key })

// Short-Form (like kv.js)
const someValue = kv.get('some-key');

// Long-Form (the `puter-kvstore` driver interface)
const someValue = kv.get({ key: 'some-key' });

kv.set({ key, value })

await kv.set('some-key', 'some value');

// or...

await kv.set({
    key: 'some-key',
    value: 'some value',
});

kv.expire({ key, ttl })

This key will persist for 20 minutes, even if the server restarts.

kv.expire({
    key: 'some-key',
    ttl: 1000 * 60 * 20, // 20 minutes
});

kv.expireAt({ key, timestamp })

The following example expires a key 1 second before "the apocalypse". (don't worry, KV won't break in 2038)

kv.expireAt(
    key: 'some-key',
    // Expires Jan 19 2038 3:14:07 GMT
    timestamp: 2147483647,
);

In-Memory Cache (cache)

Don't forget to import it first!

const { cache } = extension.import('data');

The in-memory cache is provided by kv.js. Below is a simple example. For comprehensive documentation, see the kv.js repository's readme.

const { cache } = extension.require('data');

cache.set('some-key', 'some value');
const value = cache.get('some-key'); // some value

// This value only exists for 5 minutes
cache.set('temporary', 'abcdefg', { EX: 5 * 60 });

cache.incr('qwerty'); // cache.get('qwerty') is now: 1
cache.incr('qwerty'); // cache.get('qwerty') is now: 2