Skip to main content

Slots and tags

tip

If you used SQD Cloud before the slots and tags update, you may want to take a look at the Changelog, including its Backwards compatibility section.

Starting with @subsquid/cli>=3.0.0 SQD Cloud is using a new deployment system based on the following concepts:

  • Slots: Given a squid name and an organization, slot name uniquely identifies a squid deployment.

    • Slots are identified by short strings. They directly replace versions from the old workflow, which were identified by numbers.
    • You can specify a slot on deployment or omit it. In the latter case the Cloud will create a new slot with a random identifier.
    • Deploying to an already occupied slot will result in updating the initial deployment.

  • Tags: A way to label deployments.

    Tags rules:

    • Each tag can be assigned to only one deployment among those that have the same name + organization. Assigning an existing tag moves it.
    • Multiple tags can be assigned to any one deployment.

    Tags uses:

    • Each tag added to the slot adds a new custom endpoint.
    • You can address deployments by their tags to perform various operations, including redeployment.

Both tags and slots can be specified in squid manifest as well as via command line, giving rise to a variety of possible workflows. Let's take a look at a few common scenarios.

Zero-downtime updates​

info

The functionality in this section mirrors the now-deprecated production aliases.

As you develop your squid you will sometimes need to re-sync it from scratch. With tags you can do this without a maintenance downtime.

Here is how to prepare your squid on its initial deployment:

  1. Go to your squid project (or the EVM template if you just want something to test this with) and open the squid manifest (squid.yaml by default). Remove any deployment references:

    • version: (old)
    • slot: (new)
    • tag: (new)

    This is needed because we'll let the Cloud auto generate a slot identifier for us. The top of your manifest file should look something like this:

    manifestVersion: subsquid.io/v0.1
    name: my-squid
    description: 'The very first...

  2. Deploy the squid with sqd deploy . while in the project folder. Once complete, you’ll see a message like this:

    =================================================
    A new squid my-org/my-squid@fj0anc has been successfully created
    =================================================

    fj0anc is the slot name that Cloud automatically assigned to your squid deployment. Here's how this deployment looks like in the app:

    First squid

    At this stage you can already access your deployment's API via a slot-based URL. However, that API will go down if we reset the deployment's database. Instead, let us use a tag-based URL that can be redirected to an API of another deployment.

  3. Assign a tag to your deployment:

    sqd tags add production -n my-squid -s fj0anc

    This assigns the production tag to the deployment, making the API accessible via:

    https://my-org.squids.live/my-squid:production/api/graphql

    Use this URL to access the API in your frontend app.

Now, let's say you've made some changes to your codebase and need to re-sync your squid from scratch. Follow these steps:

  1. Make one more deployment of your squid. For that you can just re-run sqd deploy .: since no slot, version or tag is supplied in the manifest, the Cloud will automatically create a new slot for you. Your Cloud deployments might now look like this:

    Second squid

  2. Wait for your new deployment to sync, then test its API using its slot-based (canonical) URL:

    https://my-org.squids.live/my-squid@u293zi/api/graphql

  3. When you're ready to switch, simply reassign the production tag to the new deployment:

    sqd tags add production -n my-squid -s u293zi

    The tag-based URL will now point to the new deployment, u293zi, with the switch typically taking just a few seconds.

  4. Finally, if you no longer need the old deployment, remove it by slot:

    sqd rm -n my-squid -s fj0anc

Multiple major versions​

One common scenario occurs when you release a breaking change and need to maintain several major versions of your API. With tags, you can keep all these major versions under the same squid name.

Let’s say you’ve introduced a breaking change to the squid from the previous example. Deploy your new version as follows:

sqd deploy .
# then, assuming that the new deployment got slot f69x40
sqd tags add production-v1 -n my-squid -s f69x40

Alternatively, you can use the --add-tag option of sqd deploy to do the same thing without having to handle the autogenerated slot name:

sqd deploy . --add-tag production-v1

This will produce exactly the same result. Here's how it may look like in the Cloud app:

Two major versions

Now you have two independent APIs accessible by tag-based URLs and you can perform zero-downtime updates on each.

Development workflows​

In the previous section we considered the situation when multiple tags are used to denote major versions of the API. However, the exact same approach can be used to separate, for example, development from production:

Development and production

When working on your development deployment, you’ll likely need to perform a variety of operations on it, frequently and without the concern of downtime. For that, all Squid CLI commands allow addressing deployments by tag. For example, to access logs of your development deployment use

sqd logs -n my-squid -t development

This command allows you to pull logs directly from the deployment tagged development, without needing to remember or specify the slot name.

Moreover, you can update your development-tagged deployment without having to know its slot name:

sqd deploy . -t development

It's even possible to ensure that whenever you deploy from the current directory, the deployment goes to the slot tagged development. Simply add the following line to squid.yaml:

tag: development

This may serve as a safeguard, preventing accidental deployments to production or the creation of unintended deployments.

Next steps​

Now that you've seen how slots and tags can help you with some common tasks, you may want to use them to design new workflows uniquely suitable for the needs of your project. Here are some resources that may help you with that:

  • Squid CLI documentation, particularly the sqd deploy page. Most of it is also available via

    sqd deploy --help

    All the flags you can use to refer to deployments and to disable protective user prompts are described there.

  • The detailed changelog that (for now) doubles as the reference documentation page. It describes the new system by comparing it to the old one that was based on versions and production aliases.

  • If you used the old system or witnessed the migration of your organization, you may want to take a look at the Backwards compatibility section of the changelog.