The Groups API: Platform Saga Part V

We previously learned about fetching a list of supported locations you could use with your primary, and replica database instances. In this chapter, we'll learn about the Groups API that Turso provides to manage database primary, and replica instances.

Before you continue, make sure you've read the previous chapters in this series:

#What is a Group?

You can think of a group as a physical machine that hosts all your databases (in a specific region). Each time you add locations to a group, you create a new machine in a new location with a replica all of the databases from the primary in the new location.

Turso automatically manages syncing replica databases with the primary. Since writes are routed through the primary, replica instances take milliseconds to sync.

#The Groups API

The Turso Platform API provides all of the necessary endpoints to manage groups, including adding and removing locations, as well as waking or upgrading group versions.

A Group is made up of the following properties:

uuid — The unique ID for the group (created and managed automatically).
name — The unique name of the group (provided by you).
version — The sqld version used by the group for databases.
primary — The primary location code for the group.
locations — All location codes for the group, including the primary.
archived — A boolean indicating if the group is sleeping.

#List all Groups

Using the Turso Platform API we can fetch a list of groups from the API:

curl -L https://api.turso.tech/v1/organizations/{organizationName}/groups \
  -H 'Authorization: Bearer TOKEN'

This returns a JSON of all groups for your provided organization:

{
  "groups": [
    {
      "archived": true,
      "locations": ["lhr", "ams", "bos"],
      "name": "default",
      "primary": "lhr",
      "uuid": "0a28102d-6906-11ee-8553-eaa7715aeaf2",
      "version": "v0.24.2"
    }
  ]
}

#Create a Group

To create a group, you'll need to provide a name, a primary location code, and optionally the SQLite extensions you want to enable.

The following request creates a group called default in the primary location lhr:

curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/groups' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "default",
      "location": "lhr"
  }'

This will return the newly created group as JSON:

{
  "group": {
    "archived": false,
    "locations": ["lhr"],
    "name": "default",
    "primary": "lhr",
    "uuid": "bb0a4383-5ed5-4dda-83d6-59f793f289e1",
    "version": "v0.24.2"
  }
}

You'll need to be on a paid plan to create more than one group, otherwise you'll see an error from the API indicating you've reached the limit:

{
  "code": "group_quota_exceeded",
  "error": "maximum group count of 1 reached"
}

#Retrieve a Group

To retrieve a specific group, you'll need to provide the group name:

curl -L 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}' \
  -H 'Authorization: Bearer TOKEN'

The response will contain the group as JSON:

{
  "group": {
    "archived": false,
    "locations": ["lhr"],
    "name": "default",
    "primary": "lhr",
    "uuid": "bb0a4383-5ed5-4dda-83d6-59f793f289e1",
    "version": "v0.24.2"
  }
}

#Update a Group version

You can update the version of databases in the group to use the latest libSQL version:

curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}/update' \
  -H 'Authorization: Bearer TOKEN'

This operation causes some amount of downtime to occur during the update process. The version of libSQL server is taken from the latest built docker image.

If successful, the response body will be empty but return a 200 status code. Failed updates will return an error message.

#Delete a Group

You can delete a group using the Turso Platform API using just the name:

curl -L -X DELETE 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}' \
  -H 'Authorization: Bearer TOKEN'

This will immediately delete the group, including all databases.

The response will contain the deleted group as JSON:

{
  "group": {
    "archived": false,
    "locations": ["lhr"],
    "name": "default",
    "primary": "lhr",
    "uuid": "bb0a4383-5ed5-4dda-83d6-59f793f289e1",
    "version": "v0.24.2"
  }
}

#Transfer a Group

You can transfer a group from organization to another organization using the Turso Platform API:

curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}/transfer' \
  -H 'Authorization: Bearer TOKEN' \
  -d '{
      "organization": "new-organization-name"
  }'

You might want to do this if you have an existing group on a personal account, and want to transfer it to an organization account your team can manage.

The response will contain the transferred group as JSON:

{
  "archived": true,
  "locations": ["lhr", "ams", "bos"],
  "name": "default",
  "primary": "lhr",
  "uuid": "0a28102d-6906-11ee-8553-eaa7715aeaf2",
  "version": "v0.23.7"
}

If you attempt to transfer a group to an organization that already has a group with the same name, you'll receive an error:

{
  "code": "",
  "error": "group with name default already exists in new organization"
}

#Add Location to a Group

You can add a location to a group using the Turso Platform API that will create a new replica in the new location of all databases belonging to the group:

curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}/locations/{location}' \
-H 'Authorization: Bearer TOKEN'

The {location} in the request URL is a valid three digit location code. If you provide an invalid location code, you will get an error:

{
  "error": "Invalid location code"
}

#Remove Location from a Group

You can remove a location from a group using the Turso Platform API that will remove the replica in the location of all databases belonging to the group:

curl -L -X DELETE 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}/locations/{location}' \
  -H 'Authorization: Bearer TOKEN'

The {location} in the request URL is a valid three digit location code.

#Group Tokens

A Group Token is a JSON Web Token (JWT) that you can use to connect to ALL databases in the group. This is extremely useful when working with multitenancy and multi-db schemas.

#Create Token

You can create a Group Token using the Turso Platform API:

curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}/auth/tokens' \
  -H 'Authorization: Bearer TOKEN'

This will return a response that contains the token:

{
  "jwt": "TOKEN"
}

Tokens by default never expire, and cannot be retrieved again.

#Create an expiring access token

You can create a Group Token that expires after a certain amount of time. For example, to expire a token in 2 weeks, 1 day, and 30 minutes, we can pass that as a value to the query string expiration:

curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}/auth/tokens?expiration=2w1d30m' \
  -H 'Authorization: Bearer TOKEN'

#Create a read-only access token

Tokens by default enable full-access to databases, but you can create a read-only token by passing the query string authorization, and the access type required:

curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}/auth/tokens?authorization=read-only' \
  -H 'Authorization: Bearer TOKEN'

#Create a token with specific permissions

You can create a Group Token with specific permissions by passing permissions to the body of a request as JSON. This is useful if you're using the ATTACH statement with one database to read from others — learn more.

For example, to create a token that can only read from databases db1, db2, and db3:

curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}/auth/tokens' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "permissions": {
        "read_attach": {
          "databases": ["db1", "db2", "db3"]
        }
      }
  }'

#Invalidate Tokens

Should a token become compromised, or you no longer need it, you will need to invalidate all tokens created for the group using the API:

curl -L -X POST 'https://api.turso.tech/v1/organizations/{organizationName}/groups/{groupName}/auth/rotate' \
  -H 'Authorization: Bearer TOKEN'

You will need to create a new token, and update any libSQL clients to use the new token.

That's it! You know have all of the knowledge required to create organizations, groups, query locations, and replicate databases within groups globally using the Turso Platform API.

In the next chapter, we will learn how to create databases inside a group from scratch, or by uploading a dump of SQLite file.