Introduction
Laravel Cloud allows you to create Redis-compatible key-value stores and attach them to your application’s environments directly from the Laravel Cloud dashboard.
KV store serves multiple purposes within your Laravel application. They can function as your application’s cache, a backend for storing queued jobs, or for managing sessions. Additionally, you have the option to interact directly with the key-value store by utilizing the Redis API.
Laravel Valkey
Laravel Valkey is a fully-managed, Redis-compatible KV store and cache for your application. Laravel Valkey comes in various sizes (starting at 250mb), is more performant and cheaper than industry averages, and can scale automatically.
Laravel Valkey is currently in Developer Preview.
Creating a Laravel Valkey cache
To attach a Laravel Valkey cache to an environment, click “Cache” on your environment’s canvas. Laravel Cloud will prompt you to select the cache you would like to attach to the environment or to create a new cache. When creating a new cache, select “Laravel Valkey” as your cache type.
Once the cache has been attached to an environment, you will need to redeploy the environment in order for the changes to take effect.
Visit the pricing docs for information on cache sizes and limits on message sizes.
Connecting to Laravel Valkey
From your application
When a cache is attached to an environment, Laravel Cloud will automatically inject the environment variables needed by the Laravel application to interact with the cache via the Cache facade, including the CACHE_STORE, REDIS_HOST, and REDIS_PASSWORD variables. You may view these environment variables in your environment’s General Settings.
From your local machine
To connect to Laravel Valkey from your local machine, click the ”…” icon next to the cache card in your environment’s canvas dashboard, then click “View credentials”.
The cache credentials modal window will provide you with the credentials needed to connect to your cache, as well as a command-line instruction to connect to your Redis cache server.
You may connect using a client that supports TLS and SNI, but note that some database management tools are incompatible with this connection process.
Editing and resizing your cache
You may edit and resize a Laravel Valkey cache via your organization’s “Resources” page. From the “Resources” page, navigate to the “Caches” tab and click the ”…” icon for the cache you would like to edit or resize. Then, click “Edit settings”.
Detaching and deleting your cache
If a KV Store is no longer needed in your project, you can detach it from your application canvas.
Detaching a KV store does not delete the store. As KV Stores can be shared across many applications, you cannot directly delete a KV store from your application, only detach it.KV Stores are billed for their availability, regardless of whether they are in use by an application. To permanently delete a KV store, you should visit your organization’s “Resources” page. Auto-upgrade
Laravel Valkey has hard limits on usage, such as commands per second and message size. When these limits are reached, your cache may experience performance degradation or stop accepting new requests.
Laravel Cloud offers an automatic upgrade feature for Laravel Valkey, ensuring your cache continues to operate smoothly as your usage grows. You can enable or disable this feature at any time.
How auto-upgrades work
- Provisioning & Configuration: When you create or update a cache with auto-upgrade enabled, Laravel Cloud provisions the cache and configures its auto-upgrade settings.
- Monitoring: Laravel Cloud continuously monitors your cache’s usage. If your cache approaches its usage limits, the system prepares to upgrade.
- Notifications: When a threshold is reached or an upgrade is triggered, Laravel Cloud will send you an alert notification.
- Seamless Upgrade: The upgrade is performed automatically in the background, with no downtime for your application. Your cache is moved to the next available size.
After an upgrade, billing is adjusted to reflect the new cache size. See the pricing documentation for details.
Monitoring cache metrics
You may view metrics such as storage usage, throughput, and hit / miss ratio for Laravel Valkey via your organization’s “Resources” page. From the “Resources” page, navigate to the “Caches” tab and click the ”…” icon for an available cache. Then, click “View metrics”.
Redis by Upstash
Laravel Cloud offers an alternative KV store through a partnership with Upstash.
Redis by Upstash caches offer the following functionalities:
- Multiple cache sizes, from 250MB to 500GB.
- Auto-upgrades.
- Metrics and monitoring.
To create a Redis by Upstash cache, head over to your canvas and click “Cache” and select “Create new cache”. Under “Cache type”, select Redis by Upstash.
Troubleshooting
Handling transient connection errors
As part of normal business operation (feature updates, security updates, etc.), your cache may restart. This may cause transient errors with some PHP clients, such as Error while reading line from the server or read error on connection to tls.
These are expected because a TCP connection cannot survive a server restart.
To mitigate this, we recommend your application:
- Catches transient errors.
- Automatically reconnects to the cache through a new, healthy connection.
We recommend you follow the best practices listed here.
Connection force-closed
For the safety of your cache, we enforce a maximum limit on the size of the messages to your cache. If a client sends a message that exceeds this limit, we will treat it as a protocol violation and immediately force-close the TCP connection.
Because the server drops the connection, your client won’t receive a standard error response. Instead, it will register a low-level network error, such as:
Error while reading line from the server (PHP)Error: read ECONNRESET (Node.js)Connection reset by peer (Python/Java)
To resolve this, you must reduce the message size or upgrade your cache size.
