Key-value store

Rocketlane provides a built-in Key-Value store that lets your app persist data in a simple, flexible way—no external database required.

You can use the Key-Value store to:

Save and retrieve settings
Store counters, flags, timestamps, and structured data
Persist user-specific or app-wide state
Perform lightweight data manipulation (increment, push, remove)

Scoping Options

The key-value store supports two scopes:

Scope	Description
App-Specific	Data is isolated to your app and installation. Ideal for tenant-level config, preferences, or logs.
Global	Data is shared across all installations of your app. Use with care for system-level flags or analytics.

Let's deep dive into each below.

App-Specific Key-Value Store

Use these methods to store data specific to the current app installation.

Basic Operations

// Store a value
await r.kv.setAppValue({
  key: 'user_preferences',
  value: { theme: 'dark', notifications: true },
  ttlInSeconds: 86400, // Optional expiration (24 hours)
  setIf: 'not_exist'    // Optional condition: only set if key doesn't exist
});

// Retrieve a value
const preferences = await r.kv.getAppValue('user_preferences');

// Delete a value
await r.kv.deleteAppValue('user_preferences');

// Retrieve all app-specific values
const allValues = await r.kv.getAllAppValues();

JSON Field Operations

You can manipulate nested fields in stored JSON objects:

await r.kv.setAppJsonValue('user_preferences', 'theme', 'light');
await r.kv.incrementAppJsonValue('stats', 'count');
await r.kv.pushAppJsonValue('history', 'events', { type: 'login', timestamp: Date.now() });
await r.kv.removeAppJsonValue('user_preferences', 'notifications');

Global Key-Value Store

Use these methods when you need to store data that’s shared across all installations of your app.

Basic Operations

// Store a global value
await r.kv.setGlobalValue({
  key: 'system_settings',
  value: { maintenance: false },
  ttlInSeconds: 3600,    // Optional expiration (1 hour)
  setIf: 'exist'         // Optional condition: only set if key already exists
});

// Retrieve a global value
const settings = await r.kv.getGlobalValue('system_settings');

// Delete a global value
await r.kv.deleteGlobalValue('system_settings');

// Retrieve all global values
const allGlobalValues = await r.kv.getAllGlobalValues();

JSON Field Operations

await r.kv.setGlobalJsonValue('system_settings', 'maintenance', true);
await r.kv.incrementGlobalJsonValue('global_stats', 'visitor_count');
await r.kv.pushGlobalJsonValue('audit_log', 'entries', { action: 'config_change', timestamp: Date.now() });
await r.kv.removeGlobalJsonValue('system_settings', 'deprecated_feature');

Notes & Best Practices

All keys are strings.
Stored values can be primitives, arrays, or objects.
Use TTL (ttlInSeconds) to auto-expire temporary data.
Use setIf: 'exist' or setIf: 'not_exist' to avoid overwrites or race conditions.
For large-scale analytics or querying, consider offloading to an external database.