Managing Key Value Stores On Cloud

With Spin Key Value Store support in Fermyon Cloud, you can persist non-relational data generated by your Spin beyond application invocations. Fermyon Cloud will provision and manage the database on your behalf, letting Fermyon Cloud do the heavy lifting for you. To learn more about the Spin Key Value Store SDK, please visit the API guide.

This tutorial will focus primarily on linking your Spin applications to Fermyon Cloud Key Value Stores. To learn more how to configure business login within a Spin application to access key value data, please visit the Spin Key Value tutorial. Fermyon Cloud supports linking Spin applications to storage objects such as SQL databases and key value stores. Links connect your Spin application to a Fermyon Cloud managed store via an associated label. That label is scoped to only the Spin application you are linking. This enables developers to abstractly declare that their application should have access to a key value stores, while giving them the ability to dynamically change which key value store it uses at any point. For an in depth review of these concepts, please visit the links and labels conceptual article

Please check that you have Spin CLI v2.0 or greater, and cloud plugin v0.7.0 or greater installed.

Creating a New Spin Application

If you already have a Spin application, you can skip this step. If you do not have a Spin application locally you will need to create one.

Grant Key Value Store Permission

To tell Spin that we want to use a key value store, we only need to grant key value store permission to a component in the application’s manifest (the spin.toml file) by supplying a label. For example:

[component.example]
key_value_stores = ["mylabel"]

The new database file (sqlite_key_value.db) is created in your application’s .spin folder when you run this Spin application. The database persists across Spin application invocations and updates. The key value store is empty to start.

Creating a Key Value Store in Fermyon Cloud

You have two options to create your key value store (both are equally valid):

  • Option A: Create a key value store during spin cloud deploy, using an automatically generated default or specifying a custom name.
  • Option B : Create a key value store before deploying an application with the spin cloud kv create command. For example, spin cloud kv create finance-database creates a key value store called finance-database inside your Fermyon Cloud account. Then you can link this store to your application with spin cloud link kv or during spin deploy.

Please follow whichever approach is most relevant to your needs.

Creating Key Value Stores Via spin cloud deploy

When you first spin cloud deploy your application (with the key_value_stores configuration, as shown above), Fermyon Cloud will prompt you to either create a new key value store or use an existing one for your Cloud application.

The new key value store is initially empty. You can seed it preliminary values using spin cloud kv set.

  1. Find the name of your Cloud key value store. To do this, run the following command:
$ spin cloud kv list
+--------------------------------------------+
| App              Label     Key Value Store |
+============================================+
| example          mylabel   gentle-lemon    |
+--------------------------------------------+

Note: The contents of the Cloud Key Value Store is completely unrelated to the local Key Value Store, and must be prepared separately.

Congratulations, you now have an application and key value store running on Fermyon Cloud.

Explicitly Create A Database Via spin cloud kv create

  1. You can create your key value store using the following command:
$ spin cloud kv create mykv
Key value store  "mykv" created

Note: The contents of the Cloud Key Value Store is completely unrelated to the local Key Value Store, and must be prepared separately.

Now you can deploy your application and select mykv as the resource you would like to link your application to: 

$ spin deploy
Uploading todo-app version 0.1.0-r234fe5a4 to Fermyon Cloud...
Deploying...
App "todo-app" accesses a kv store labeled "default"
Would you like to link an existing key value store or create a new key value store?:
> Use an existing key value store and link app to it
  Create a new key value store and link the app to it

Since we chose to link to an existing database, spin deploy asks us which database we would like to link this app’s “default” label to:

Which database would you like to link to todo-app using the label "default":
> mykv

Congratulations, you’ve now deployed an application to Fermyon Cloud that’s linked to a key value store.

Viewing Linked Stores and Labels

If you would like to see the key value stores you’ve created and the linked applications, you can run the following command:

$ spin cloud kv list
+---------------------------------------------------------------+
| App                          Label         Key Value Store    |
+===============================================================+
| example                      default       mykv               |
+---------------------------------------------------------------+

Deleting the Cloud Key Value Store

Warning: using the delete subcommand is permanent.

You can delete your default key value store with the following command:

$ spin cloud kv delete inspirational-pig
The action is irreversible.
Please type "inspirational-pig" for confirmation: inspirational-pig
Deleting kv ...
KV "inspirational-pig" deleted

Next Steps

  • Visit FAQ for frequently asked questions.