Key-Value Store

The Key-Value Store provides simple storage for key/value pairs. Use this to persistently store data that you'd like to retrieve through the Query tool.

For example:

Copy
1
2
3
4
5
6
7
import { kvs, WhereConditions } from '@forge/kvs';

await kvs.set('foo', 'bar');
await kvs.get('foo');
await kvs.query()
  .where('key', WhereConditions.beginsWith('fo'))
  .getMany();

To safeguard sensitive data in a more secure manner, the Key-Value Store allows for storing encrypted data via the Secret store.

Each installation of your app is subject to the Storage API's quotas and limits. See Storage quotas and Storage limits for more details.

Recommendations

When using the app storage API, we strongly recommend that you:

• only use encrypted environment variables and kvs.setSecret to store secrets or credentials in your app.
• avoid employing data models with entities that grow in an unbounded manner (in terms of depth and/or size), as this may lead to exceeding storage limits.
• avoid storing files.

Scope requirement

Using the @forge/kvs package requires the storage:app scope in your manifest file:

1
2
permissions:
  scopes:
    - storage:app

See Permissions for more information about scopes.

Data residency

The Atlassian cloud provides features that allow admins to control and verify where their Jira and Confluence data is hosted. These features support them in meeting company requirements or regulatory obligations relating to data residency.

Forge's persistent storage options use this same cloud infrastructure to store data. This allows Forge to extend similar data residency features to your app. All data stored on Forge persistent storage automatically inherit these features.

Specifically, if your app stores data on Forge persistent storage, an admin can control where that data is stored. For more details about how this works, see Data residency.

Partitioning

Data in Forge hosted storage is namespaced. The namespace includes all metadata relevant to an app's current installation. As a result:

• Only your app can read and write your stored data.
• An app can only access its data for the same environment.
• Keys or table names only need to be unique for an individual installation of your app.
• Data stored by your app for one product is not accessible from other products. For example, data stored in Jira is not accessible from Confluence or vice versa.
• Your app cannot read stored data from different sites, products, and app environments.
• Quotas and limits are not shared between individual installations of your app.

Security and durability

Data is transferred, encrypted, and stored on disk according to the Atlassian cloud’s data encryption policies. Once stored, data will persist until deleted or updated by your app.

In addition, the Atlassian Cloud backs up all persistent storage for disaster recovery.

Conflict resolution

Writes to keys using set or delete use a "last write wins" conflict resolution strategy. Writes to individual keys are atomic - For example, the value is either updated in full or not.

Supported values

The app storage API is able to persist any JSON data type except null. For example:

• arrays
• booleans
• numbers
• objects
• strings

The JavaScript storage API serializes your objects using JSON.stringify, and as such removes functions and the value undefined from any object you attempt to serialize.

Cursors

The Key-Value Store and Custom Entity Store use cursors for paginated data access. Queries (both through the Query builder and Complex Query builder) return a cursor in the results. This cursor can be provided to subsequent queries to paginate over larger data sets than you would otherwise be able to fetch.

You will have to use the same parameters as the initial query. See the example below.

1
2
// Inserts some dummy data
await kvs.set('account.1', 'account 1');
await kvs.set('account.2', 'account 2');
await kvs.set('account.3', 'account 3');
await kvs.set('account.4', 'account 4');
await kvs.set('account.5', 'account 5');
await kvs.set('user.1', 'user 1');
await kvs.set('user.2', 'user 2');
await kvs.set('user.3', 'user 3');
await kvs.set('user.4', 'user 4');

// Fetch up to 2 results, but will return "account.1" and "account.2" and a cursor to next page
const { nextCursor: firstCursor } = await kvs
    .query()
    .limit(2)
    .where('key', WhereConditions.beginsWith('account.'))
    .getMany();

// Fetch up to 2 results after the cursor, but will return "account.3" and "account.4" and a cursor to next page
const { nextCursor: secondCursor } = await kvs.query()
    .limit(2)
    .where('key', WhereConditions.beginsWith('account.'))
    .cursor(firstCursor)
    .getMany();

// Fetch up to 2 results, but will only return "account.5" and no cursor
const { nextCursor: undefinedCursor } = await kvs.query()
    .limit(2)
    .where('key', WhereConditions.beginsWith('account.'))
    .cursor(secondCursor)
    .getMany();

Key ordering

Keys are lexicographically ordered; this means, for example, that the Query builder and Complex Query builder) will return entities ordered by their key. This property can be used to group related entities or build ad-hoc indexes.

The Key-Value Store and Custom Entity Store don't support indexing of arbitrary attributes. However, it is possible to support this sort of access pattern if your keys are constructed in such a way as to support indexed reads.

Hierarchical keys can be constructed to allow for nested entities to be fetched in a single list operation such as the example below.

1
2
import { kvs, WhereConditions } from '@forge/kvs';

// Nested entities
await kvs.set('survey-responses#1#{UUID}', { });
await kvs.set('survey-responses#1#{UUID}', { });
await kvs.set('survey-responses#1#{UUID}', { });
await kvs.set('survey-responses#1#{UUID}', { });

const results = await kvs
  .query()
  .where('key', WhereConditions.beginsWith('survey-response#1#'))
  .limit(10)
  .getMany();

Data consistency

The kvs.query method used by the Key-Value Store is eventually consistent. This means that the method returns data that may be slightly out of date.

The kvs.get method, on the other hand, is strictly consistent. It will always return current data.

Legacy version

Legacy versions of the Key-Value Store and Custom Entity Store were provided through the storage module of the @forge/api package.

We will continue supporting this module. However, all future KVS and Custom Entity Store updates will only be built on modules in the current @forge/kvs package.