Capacity API

Your application often knows when a peak comes: a shop knows when a sale opens. With the capacity key of its environment it plans a boost of its own database itself. It never gets a Scaleway key: it asks Brewless, and Brewless changes the database.

Boosts come with the Business plan and up.

The capacity key#

An owner or admin switches the key on in the console: Databases, the database, Capacity key of the application, Switch on. The key is shown once, with the three variables the application reads:

BREWLESS_API_URL=https://acme.brewless.eu
BREWLESS_ENVIRONMENT=01JD…
BREWLESS_CAPACITY_KEY=bcap_…

Put them in the environment's variables (brewless env:push, or the console). New key replaces the key at once; Switch off refuses every request with it from then on.

The key reaches only the Serverless SQL Databases of its own environment, and only the boosts it asked for itself. When you switch it on, you set what a request with it may ask for, at most:

Boost hours count everything a boost holds: warming up, the window and cooling down. A boost over the end of a month counts in each month for its part there.

With brewless/laravel#

The brewless/laravel package has a CapacityClient that signs every request for you. A shop that plans a boost when an event with a sale is saved:

use Brewless\Laravel\Capacity\CapacityApi;
use Brewless\Laravel\Capacity\CapacityException;

public function saved(Event $event): void
{
    try {
        resolve(CapacityApi::class)->schedule(
            "event-{$event->id}-sale",
            $event->sale_starts_at,
            $event->sale_starts_at->addHours(2),
            min: 4,
            max: 15,
            prewarm: 15,
            cooldown: 30,
        );
    } catch (CapacityException $exception) {
        report($exception);
    }
}

When the sale moves, send the new times under the same key; when the event is cancelled, cancel the boost. Just before the start, ready() says whether the database has its minimum: tell your team when it has not, and never hold the sale back for it.

When Brewless cannot be reached#

A boost is a help, not something your application depends on. Catch the client's exceptions and go on: when Brewless or Scaleway cannot be reached, the database keeps scaling between its normal bounds as always.

The requests#

Every request goes to {BREWLESS_API_URL}/api/runtime/capacity and is signed the same way as databases per tenant: an HMAC-SHA256 with the capacity key over the method, the path, the time and the SHA-256 of the body, each on a line of its own, in three headers (X-Brewless-Environment, X-Brewless-Timestamp, X-Brewless-Signature). A request more than five minutes off is refused.

A boost asks for:

The key makes a request safe to send again: the same key with the same request gives the boost it made before (200), the same key with another request is refused (409). A boost that was cancelled and is over gives its key free: sent again, the key plans a new boost, for an event that goes ahead after all. A change with PATCH is accepted once per signature; a repeat of a boost, a later end or a cancellation may come twice.

ready is true only once Scaleway gave the database the boost's minimum.

Every answer has Cache-Control: no-store.