logoStacktape docs


Upstash RedisWork in progress
Work in progress

Overview and basic concepts

  • Redis is a fast, NoSQL in-memory data store that can provide sub-millisecond latency.

  • Upstash provides Redis as a serverless service. This enables users to leverage Redis without the need for paying and managing their own servers.

  • Upstash uses Per-Request pricing so you do NOT need to pay for the servers/instances and you only pay for request you make.

  • Low latency data, ease of use, and pay-per-request pricing makes Upstash a perfect choice for the Jamstack and Serverless world.

When to use

Advantages

  • REST API - access your database using simple REST API
  • Secure - with option to enable TLS out of the box
  • High availability - with option to enable multizone replication
  • Pay-per-request - pay only for what you use. Refer to Upstash pricing
  • Scalable

Disadvantages

  • Separate billing - Even though Stacktape seamlessly integrates Upstash Redis to your stacks, you still need to manage your billing separately.

Provider configuration

  • You must have an Upstash account. To create one, head over to Upstash registration page.

  • You need following to configure the provider:

    • Email address of your Upstash account (accountEmail).
    • API Key associated with the account (apiKey).
  • You can obtain API Key in Upstash account management console.

  • The recommended way to store your credentials is to use secrets.

Copy

providerConfig:
upstash:
accountEmail: xxxxx.yyyy@example.com
apiKey: $Secret('upstash-api-key')
resources:
myUpstash:
type: upstash-redis

Basic usage

Copy

providerConfig:
upstash:
accountEmail: xxxxx.yyyy@example.com
apiKey: $Secret('upstash-api-key')
resources:
myUpstash:
type: upstash-redis
myFunction:
type: function
properties:
packaging:
type: stacktape-lambda-buildpack
properties:
entryfilePath: lambdas/upstash.ts
environment:
- name: UPSTASH_REDIS_REST_URL
value: $ResourceParam('myUpstash', 'restUrl')
- name: UPSTASH_REDIS_REST_TOKEN
value: $ResourceParam('myUpstash', 'restToken')

Copy

import upstash from '@upstash/redis';
const redis = upstash({ url: process.env.UPSTASH_REDIS_REST_URL, token: process.env.UPSTASH_REDIS_REST_TOKEN });
export default async (event) => {
// write data
let { data, error } = await redis.set('key1', 'value1');
// read data
({ data, error } = await redis.get('key1'));
console.log(data);
if (error) {
throw error;
}
};

Code of myFunction function

UpstashRedis  API reference
type
Required

No description

Type: string "upstash-redis"

properties.enableMultizoneReplication

Enables multizone replication to improve availability

Type: boolean

  • When enabled the data is replicated to multiple availability zones.
  • Enabling multi zone replication will increase per-request-cost to $0.4 per 100K requests (from original $0.2).
  • For more information refer to Upstash docs.

Once multizone replication is enabled, it cannot be disabled

properties.enableTls

Enables encryption of data traffic

Type: boolean

  • If you enable TLS on existing database, the database will experience a downtime about 1-2 seconds (NO data will be lost).
  • Enabling TLS can cause performance downgrade. If high throughput is essential for your app, consider reading this thread before using TLS.

Once TLS is enabled, it cannot be disabled.

properties.enableStrongConsistency

Enables strong consistency for the databse

Type: boolean

  • Strong consistency can only be enabled during database creation.
  • When strong consistency is enabled, persistence to disk and replication to the majority of replicas are performed before returning response to the client.
  • Enabling strong consistency mode may increase the latency of writes.
  • For more information refer to Upstash docs
overrides

Overrides one or more properties of the specified child resource.

Type: Object

  • Child resources are specified using their cloudformation logical id (e.g. MyBucketBucket).
  • To see all configurable child resources for given Stacktape resource, use stacktape stack-info --detailed command.
  • To see the list of properties that can be overridden, refer to AWS Cloudformation docs.

Deployment region

Currently Upstash Redis supports only following regions:

  • us-east-1
  • us-west-1
  • eu-west-1
  • ap-northeast-1

If you are deploying your stack in some other region, Stacktape will try to deploy the database in the region geographically closest to the region of your stack.

Enable TLS

  • If you enable TLS on existing database, the database will experience a downtime about 1-2 seconds (NO data will be lost).
  • Enabling TLS can cause performance downgrade. If high throughput is essential for your app, consider reading this thread before using TLS.

Once TLS is enabled, it cannot be disabled.

Copy

providerConfig:
upstash:
accountEmail: xxxxx.yyyy@example.com
apiKey: $Secret('upstash-api-key')
resources:
myUpstash:
type: upstash-redis
properties:
enableTls: true

Enable multizone replication

  • When enabled the data is replicated to multiple availability zones.
  • Enabling multi zone replication will increase per-request-cost to $0.4 per 100K requests (from original $0.2).
  • For more information refer to Upstash docs.

Once multizone replication is enabled, it cannot be disabled

Copy

providerConfig:
upstash:
accountEmail: xxxxx.yyyy@example.com
apiKey: $Secret('upstash-api-key')
resources:
myUpstash:
type: upstash-redis
properties:
enableMultizoneReplication: true

Enable strong consistency

  • Strong consistency can only be enabled during database creation.
  • When strong consistency is enabled, persistence to disk and replication to the majority of replicas are performed before returning response to the client.
  • Enabling strong consistency mode may increase the latency of writes.
  • For more information refer to Upstash docs

Copy

providerConfig:
upstash:
accountEmail: xxxxx.yyyy@example.com
apiKey: $Secret('upstash-api-key')
resources:
myUpstash:
type: upstash-redis
properties:
enableStrongConsistency: true

Referenceable parameters

The following parameters can be easily referenced using $ResourceParam directive directive.

To learn more about referencing parameters, refer to referencing parameters.

host
  • Hostname (address) of the Upstash Redis database.

  • Usage: $ResourceParam('<<resource-name>>', 'host')
port
  • Port of the Upstash Redis database.

  • Usage: $ResourceParam('<<resource-name>>', 'port')
password
  • Autogenerated password that can be used to authenticate towards the database.

  • Usage: $ResourceParam('<<resource-name>>', 'password')
restToken
  • Rest token which can be used when reading/writing from/to the database using the REST API

  • Usage: $ResourceParam('<<resource-name>>', 'restToken')
readOnlyRestToken
  • Rest token which can be used only for reading from the database using the REST API

  • Usage: $ResourceParam('<<resource-name>>', 'readOnlyRestToken')
restUrl
  • Rest URL which can be used when communicating with the database using the REST API

  • Usage: $ResourceParam('<<resource-name>>', 'restUrl')
redisUrl
  • Standard redis url (including password) which can be used for connecting using cli.

  • Usage: $ResourceParam('<<resource-name>>', 'redisUrl')
Need help? Ask a question on SlackDiscord or info@stacktape.com.