Materia KV

Materia is a new serverless databases offering by Clever Cloud. A whole range of services meeting the needs expressed by our customers in recent years, with an open and resilient approach. It includes deployment across multiple availability zones, compatibility with existing protocols, clients, and pay-as-you-go billing. It’s built on the FoundationDB open source transactional engine. A distributed and robust solution, notably thanks to its high simulation capacity.

Materia KV is the first publicly available product of this family. It’s a key-value database which comes with simplicity in mind. You have no instance size to choose, no storage capacity to worry about. We simply provide you with a host address, a port and a token: you’re ready to go! Once our servers send a reply message, your data is durable: it’s synchronously replicated over 3 data centers in Paris.

You don’t have to configure leaders, followers: high availability is included, by design.

ℹ️
Materia KV is in Alpha testing phase: your insights and suggestions are crucial in shaping the future of this platform. To share your feedback, please visit us at our community page. Thank you for being a part of our journey towards innovation and improvement!

Compatibility layers

We didn’t want this Materia KV to come at the cost of complex configuration, requiring the use of special clients and ORMs. That’s why we’ve developed its compatibility layers. To “talk” to it, you don’t need a special API or tools specific to Clever Cloud. You’ll be able to use it with existing solutions for DynamoDB, GraphQL or Redis. The first available layer is compatible with Redis API (and its variants as Reddict or Valkey).

Thus, you can use a Materia KV add-on with any compatible client within your applications, redis-cli or alternatives such as iredis. You can also use it with graphical interface (GUI). We tested many of them with success:

Create a Materia KV add-on

You can create a Materia KV add-on as simply as any other Clever Cloud service in the Console, following this link. Select the Alpha plan (free during testing phase), an application to link to (or none), give it a name, and you’ll get access to its dashboard giving you connection details. Environment variables shared with a linked application are listed in the Service dependencies section.

We included them with the REDIS_ format. Thus, you can just try to replace a Redis instance by Materia KV. It’s as simple as linking the new add-on, unlinking the old one and restarting your application! (Check commands you’ll need first).

You can also use clever tools to create a Materia KV add-on and set environment variables to test it with a PING command:

clever addon create kv DATABASE_NAME
source <(clever addon env addon ADDON_ID -F shell)
redis-cli -h $KV_HOST -p $KV_PORT --tls PING

Here is an example of what you can expect:

$ clever addon create kv testKV

Add-on created successfully!
ID: addon_4997cfe3-f104-4d05-9fe4-xxxxxxxxx
Real ID: kv_01HV6NCSRDxxxxxxxxxxxxxxxx
Name: testKV

/!\ The Materia KV provider is in Alpha testing phase, don't store sensitive or production grade data
You can easily use Materia KV with 'redis-cli', with such commands:
source <(clever addon env addon_4997cfe3-f104-xxxx-xxxx-xxxxxxxxx -F shell)
redis-cli -h $KV_HOST -p $KV_PORT --tls

You can also deploy Materia KV add-ons with Terraform provider (OpenTofu compatible).

ℹ️
Materia KV is in Alpha testing phase Each add-on is limited to 128 MB of storage, requests sent to the server can’t exceed 5 MB. As we fine-tune and enhance its capabilities, we advise against using the alpha release for production purposes. During alpha testing we can delete data or renew token, don’t store sensitive or production grade data.

Clever Cloud KV Explorer

Access and edit your Key-Value databases with the KV Explorer tool, it’s part of Clever Cloud’s all included experience.

Supported data types

Hash, list, set and string types are supported. For Materia KV, only string type is currently available, with other types coming soon.

An intuitive, useful interface

The interface lets you filter keys by type and perform wildcard searches (for example: *value_to_search*). Value fields are multi-line for convenience, and you can copy/paste values directly from the interface. Special attention has been paid to accessibility and keyboard navigation with shortcuts to optimize your experience.

KV Explorer Terminal

At the bottom of the page, you’ll find an integrated terminal that works like a traditional CLI client. Type your commands and press Enter to execute them. All commands are supported, including FLUSHDB and FLUSHALL. Be careful with these as they erase data!

KV Explorer is in Beta testing phase and we’ll improve it over the coming months, thanks to your feedback and suggestions.

landscape
The KV Explorer tool in the Console

Using the Redis API compatible layer

Environment variables and CLI usage

To connect to a Materia KV add-on, you need 3 parameters: the host, the port and a (biscuit based) token. You can set these parameters as environment variables by doing source <(clever addon env addon ADDON_ID -F shell). The variables set are:

  • $KV_HOST and its alias $REDIS_HOST
  • $KV_PORT and its alias $REDIS_PORT
  • $KV_TOKEN and its alias $REDIS_PASSWORD
  • $REDIS_CLI_URL
  • $REDISCLI_AUTH

You can directly use these environment variables to connect to a Materia KV add-on using redis-cli if REDISCLI_AUTH is set:

redis-cli -h $KV_HOST -p $KV_PORT --tls

Materia KV is also compatible with alternatives such as iredis.

Fish shell users

If you use the Fish shell, you can use the following command to set the environment variables:

clever addon env ADDON_ID -F shell | source
ℹ️
By default, Materia KV uses TLS on the 6379 port. You can use non-TLS connections on the 6378 port for testing purposes.

Clever KV

We’re exploring how Clever Tools can natively support Materia KV and helps you to manage such add-ons without any additional software or configuration. We’ve enabled the clever kv command in a testing branch available here. You can download it as a binary and only need the KV_TOKEN environment variable to be set to use it, or target a specific add-on with the --addon option.

Demos and examples

We’ve prepared a few examples to help you get started with Materia KV:

Supported types and commands

During this alpha stage, we don’t provide 100% compatibility with the Redis API. Currently supported value types are:

  • String

Find below the list of currently supported commands:

Commands
Description
APPENDIf key already exists and is a string, this command appends the value at the end of the string. If key doesn’t exist it is created and set as an empty string, so APPEND will be similar to SET in this special case.
AUTHAuthenticate the current connection using the biscuit token as password.
CLIENT IDReturns the ID of the current connection. A connection ID has is never repeated and is monotonically incremental.
COMMANDReturn an array with details about every supported command.
COMMAND DOCSReturn documentary information about commands. By default, the reply includes all the server’s commands. You can use the optional command-name argument to specify the names of one or more commands. The reply includes a map for each returned command.
COMMAND INFOReturns an array reply of details about multiple Materia KV commands. Same result format as COMMAND except you can specify which commands get returned. If you request details about non-existing commands, their return position will be nil.
COMMAND LISTReturn an array of the server’s command names.
DBSIZEReturn the number of keys in the currently-selected database.
DECRDecrements the number stored at key by one. If the key doesn’t exist, it is set to 0 before performing the operation. An error is returned if key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64-bit signed integers.
DECRBYDecrements the number stored at key by the given decrement. If the key doesn’t exist, it is set to 0 before performing the operation. An error is returned if key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64-bit signed integers.
DELRemoves the specified key. A key is ignored if it doesn’t exist.
EXISTSReturns if key exists.
EXPIRESet a key time to live in seconds. After the timeout has expired, the key will be automatically deleted. The time to live can be updated using the EXPIRE command or cleared using the PERSIST command.
FLUSHALLDelete all the keys of all the existing databases, not just the currently selected one. This command never fails.
FLUSHDBDelete all the keys of the currently selected DB. This command never fails.
GETGet the value of key. If the key doesn’t exist the special value nil is returned. An error is returned if the value stored at key is not a string, because GET only handles string values.
GETBITReturns the bit value at offset in the string value stored at key.
GETRANGEReturns the substring of the string value stored at key, determined by the offsets start and end (both are inclusive). Negative offsets can be used in order to provide an offset starting from the end of the string. So -1 means the last character, -2 the penultimate and so forth.
HELLOSwitch to a different protocol, optionally authenticating and setting the connection’s name, or provide a contextual client report. It always replies with a list of current server and connection properties.
INCRIncrements the number stored at key by one. If the key doesn’t exist, it is set to 0 before performing the operation. An error is returned if key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64-bit signed integers.
INCRBYIncrements the number stored at key by the given increment. If the key doesn’t exist, it is set to 0 before performing the operation. An error is returned if key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64-bit signed integers.
INFOThe INFO command returns information and statistics about the server in a format that is simple to parse by computers and easy to read by humans.
KEYSReturns all keys matching pattern, can be *
MGETReturns the values of all specified keys. For every key that doesn’t hold a string value or doesn’t exist, the special value nil is returned. Because of this, the operation never fails.
MSETSets the given keys to their respective values. MSET replaces existing values with new values, just as regular SET. MSET is atomic, so all given keys are set at once. It is not possible for clients to see that some keys were updated while others are unchanged.
PERSISTRemove the existing time to live associated with the key.
PEXPIRESet a key time to live in milliseconds. After the timeout has expired, the key will be automatically deleted. The time to live can be updated using the PEXPIRE command or cleared using the PERSIST command.
PINGReturns PONG if no argument is provided, otherwise return a copy of the argument as a bulk.
PTTLRReturns the remaining time to live of a key, in milliseconds.
SCANIncrementally iterate over a collection of elements. It is a cursor based iterator, this means that at every call of the command, the server returns an updated cursor that the user needs to use as the cursor argument in the next call. An iteration starts when the cursor is set to 0, and terminates when the cursor returned by the server is 0.
SETSet key to hold the string value. If key already holds a value, it is overwritten, regardless of its type.
SETBITSets or clears the bit at offset in the string value stored at key.
STRLENReturns the length of the string value stored at key. An error is returned when key holds a non-string value.
TTLReturns the remaining time to live of a key, in seconds.
TYPEReturns the string representation of the type of the value stored at key. Can be: hash, list or string.
Last updated on

Did this documentation help you ?