Skip to content

surreal cloud

/

Commands

surreal cloud catalog

surreal cloud catalog browses the platform catalogues: the regions, Earth residencies, instance types, versions and billing countries SurrealDB Cloud offers. These are the slugs instance create and instance update expect.

Usage
surreal cloud catalog <COMMAND> [OPTIONS]
CommandPurpose
regionsList the regions instances can be deployed in
residenciesList where SurrealDB Earth instances can keep their data
instance-typesList the instance types available on the platform
storage-typesList the storage instance types available on the platform
instance-versionsList the SurrealDB versions instances can run
billing-countriesList the countries billing details can be registered in

These are nouns rather than list verbs, because a catalogue has exactly one thing you can do with it. None takes a positional argument, none takes --org, and none carries any flag beyond the list presentation flags.

Important

These lists are global. What an organisation may actually deploy is narrower, and org plans is the organisation-scoped answer - the one to trust before a create.

List the regions instances can be deployed in.

Usage
surreal cloud catalog regions [OPTIONS]

This command takes no positional arguments and no options of its own. Column ids are slug and description, with flag under --wide.

surreal cloud catalog regions
Output
SLUG        DESCRIPTION
aws-euw1    Europe (Ireland)
aws-use1    US East (N. Virginia)
aws-usw2    US West (Oregon)
Just the slugs
surreal cloud catalog regions --columns slug --no-header

The slug is what --region accepts. The list holds the cloud regions for dedicated instances. SurrealDB Earth is not one of them: --region earth deploys an Earth instance, and is the default.

List where SurrealDB Earth instances can keep their data.

Usage
surreal cloud catalog residencies [OPTIONS]

This command takes no positional arguments and no options of its own. Column ids are name, label, default and locations, with slug and description under --wide.

surreal cloud catalog residencies
Output
NAME   RESIDENCY       DEFAULT  LOCATIONS
eu     European Union  false    weur, eeur
us     United States   false    wnam, enam
world  Worldwide       true     wnam, enam, weur, eeur, apac, oc

The name is what instance deploy --residency accepts, and locations lists the values its --location-hint accepts with that residency. A residency cannot be changed after the instance is deployed.

List the instance types available on the platform.

Usage
surreal cloud catalog instance-types [OPTIONS]

This command takes no positional arguments and no options of its own. Column ids are slug, category, cpu, memory, units, price_hour, storage and enabled, with display_name, restricted and description under --wide.

surreal cloud catalog instance-types
Cheapest first
surreal cloud catalog instance-types --sort price_hour

The slug is what --type accepts. Prices stay in integer minor units under --json.

The enabled column is left unset here, because whether a type is available to you is a property of your organisation's plan rather than of the platform - check org plans, or price a specific combination with instance estimate.

List the storage instance types available on the platform.

Usage
surreal cloud catalog storage-types [OPTIONS]

This command takes no positional arguments and no options of its own. The columns are the same as instance-types.

surreal cloud catalog storage-types

An empty list is a success, and says why on stderr:

No storage instance types are offered. Distributed storage may not be available here.

List the SurrealDB versions instances can run.

Usage
surreal cloud catalog instance-versions [OPTIONS]

This command takes no positional arguments and no options of its own. The single column id is version.

surreal cloud catalog instance-versions
The version an update would move to
surreal cloud catalog instance-versions --limit 1 --no-header

The API's own order is newest-first and is left alone. --sort version sorts as strings, so 3.10.0 would come before 3.9.0 - prefer the default order when you want the newest release.

An empty list should not happen, and says so:

The API returned no versions, which should not happen. Try again, or report it.

List the countries billing details can be registered in.

Usage
surreal cloud catalog billing-countries [OPTIONS]

This command takes no positional arguments and no options of its own. Column ids are code and name.

surreal cloud catalog billing-countries
Check one country is supported
surreal cloud catalog billing-countries --json | jq -e '.[] | select(.code == "IE")' > /dev/null

Was this page helpful?