Turso.Platform.Databases

Interact with databases in Turso.

type alias Database =
{ name : String
, databaseId : String
, hostname : String
, blockReads : Bool
, blockWrites : Bool
, regions : Array String
, primaryRegion : String
, group : String
, deleteProtection : Bool
, parent : Maybe { id : String, name : String , branchedAt : String }
}

A database in Turso. Many functions in this module return a Database.

List Databases

type alias ListArgs = { groupName : Maybe String, parentDbId : Maybe String }

Arguments for the list function.

Both group and parent are optional. Not providing them will list all databases for the given organization specified in Turso.Platform.Connection If provided, they do the following:

  • group will filter the resulting list based on the group name provided.
  • parent will filter the resulting list to databases whose parent database matches the id of the passed parent database.
type ListError
= ListErrorGroupNotFound
| ListHttpError (Error (Array Database))

Errors that can happen when attempting to list databases.

  • ListErrorGroupNotFound happens when, if a group name is provided, that group does not exist.
  • ListHttpError captures any other HTTP errors.
list :
Connection
-> ListArgs
-> Task ListError (Response ( Array Database))

List databases in your Turso organization.

When successfully, returns an Array Database of the retrieved databases.

Get a Single Database

type alias RetrieveArgs = { databaseName : String }

Arguments for the retrieve function.

  • databaseName is the name of the database you want to retrieve.
type RetrieveError
= RetrieveErrorDatabaseNotFound
| RetrieveHttpError (Error Database)

Errors that can happen when attempting to retrieve a database.

  • RetrieveErrorDatabaseNotFound happens when the passed database name does not exist in Turso.
  • RetrieveHttpError captures any other HTTP errors.
retrieve :
Connection
-> RetrieveArgs
-> Task RetrieveError (Response Database)

Retrieve a specific database by name.

When successful, returns a single Database record.

Create Databases

type alias CreateArgs = { databaseName : String, group : String }

Arguments needed to create a database.

  • group is the group the created database will be a part of. This group must already be created or else the request will fail.
  • databaseName is the name of the newly created database. The request will fail if there is already a database of the specified name created.
type alias CreateResult =
{ databaseId : String
, databaseName : String
, hostname : String
}

Results of successfully creating a database with the Turso API.

  • databaseId is the newly created databases id in Turso.
  • databaseName is the name of the newly created database. This will match the name given to the create function.
  • hostname is a value that can be used to make specific requests to that database using the Turso.Db module in this package.
type CreateError
= CreateErrorDatabaseAlreadyExists
| CreateErrorGroupNotFound
| CreateHttpError (Error CreateResult)

Errors that can happen when attempting to create a database.

  • CreateErrorDatabaseAlreadyExists happens when you're trying to create a database whose name already existing in Turso for the group you're making the database in.
  • CreateErrorGroupNotFound happens when the group you're trying to create the database for does not exist in the organization.
  • CreateHttpError captures any other HTTP errors.
create :
Connection
-> CreateArgs
-> Task CreateError (Response CreateResult)

Create a new Turso database.

Delete Databases

type alias DeleteArgs = { databaseName : String }

Arguments for the delete function.

  • databaseName is the name of the database you want to delete.
type alias DeleteResult = { databaseName : String }

Results of successfully deleting a database.

  • databaseName is the name of the deleted database. This should match the name given in the delete function.
type DeleteError
= DeleteErrorDatabaseNotFound
| DeleteHttpError (Error DeleteResult)

Errors that can happen when attempting to delete a database.

  • DeleteErrorDatabaseNotFound happens when the passed database name does not exist yet in Turso.
  • DeleteHttpError captures any other HTTP errors.
delete :
Connection
-> DeleteArgs
-> Task DeleteError (Response DeleteResult)

Delete a database in Turso.

Create Database Tokens

Create tokens for a specific database in Turso. These tokens can be used to query databases with the Turso.Db module.

type alias CreateTokenArgs =
{ databaseName : String
, expiration : Maybe String
, authorization : Maybe TokenAuthorization
, permissions : { readAttachDatabases : Array String }
}

Arguments needed to create a database token.

  • databaseName is the name of the database you want to create the token for.
  • expiration field is a string representing when the token expires. This must resemble the following format: 2w1d30m. If not provided, the token will never expire.
  • authorization value specifies what type of actions the token will be able to take on the database. The default value is FullAccess. See the TokenAuthorization type for more options.
  • permissions record has one field: readAttachDatabases. Providing an array of database ids which this token is allowed to attach to a SQL statement with the ATTACH keyword. If not required, an empty array ([]) can be provided as the value.
type TokenAuthorization
= FullAccess
| ReadOnly

Represents the type of access a token is allowed to have for the database.

  • FullAccess allows reading and writing data to the database.
  • ReadOnly only allows queries to read data from the database.
type alias CreateTokenResult = { jwt : String }

Results of successfully creating token for a database.

  • jwt is a String representing the created JWT (JavaScipt Web Token).
createToken :
Connection
-> CreateTokenArgs
-> Task (Error CreateTokenResult)
(Response CreateTokenResult)

Create a token for operating on a database in Turso.

Invalidate Database Tokens

type alias InvalidateTokensArgs = { databaseName : String }

Arguments needed to invalidate all tokens for a database.

  • databaseName is the database you want to invalid the tokens for.
type InvalidateTokensError
= InvalidateTokensErrorDatabaseNotFound
| InvalidateTokensHttpError (Error {})

Errors that can happen when attempting to invalidate a databases tokens.

  • InvalidateTokensErrorDatabaseNotFound happens when the passed database name does not exist yet in Turso.
  • InvalidateTokensHttpError captures any other HTTP errors.
invalidateTokens :
Connection
-> InvalidateTokensArgs
-> Task InvalidateTokensError (Response {})

Invalidate all tokens for the given database name.

When successfull, will invalidate all tokens for the given database, but returns no values.

Get Database Usage

type alias UsageArgs =
{ databaseName : String
, from : Maybe String
, to : Maybe String
}

Arguments for the usage function.

  • databaseName is the name of the database you want to get usage information for
  • from is the first date you want to get usage for.
  • to is the last date you want to get usage for.

Both from and to must be ISO 8601 strings.
type alias UsageStats =
{ rowsRead : Int
, rowsWritten : Int
, storageBytes : Int
, bytesSynced : Int
}

The specific stats for an individual database.
type alias UsageResult =
{ databaseId : String
, totalUsage : UsageStats
, instances : Array { databaseInstanceId : String, usage : UsageStats }
}

The results of getting usage information for a database.

  • databaseId is the id of the database you're getting usage for
  • totaUsage is sum of all of the UsageStats from all instances of the given database.
  • instances is the usage for each specific instance of the database.
type UsageError
= UsageErrorInvalidQueryParameter
| UsageErrorDatabaseNotFound
| UsageHttpError (Error UsageResult)

Errors that can happen when attempting to retrieve usage information for a database.

  • UsageErrorInvalidQueryParameter happens when the passed from or to values are not valid ISO 8601 strings.
  • UsageErrorDatabaseNotFound happens when the passed database name does not exist yet in Turso.
  • RetrieveHttpError captures any other HTTP errors.
usage :
Connection
-> UsageArgs
-> Task UsageError (Response UsageResult)

Get the usage information for a given database.

Get Database Stats

type alias StatsArgs = { databaseName : String }

Arguments for the stats function.

  • databaseName is the name of the database you want to get stats for.
type alias StatsResult =
{ topQueries : Array { query : String, rowsRead : Int , rowsWritten : Int }
}

The results of getting stats for a database.

  • topQueries is an array of the queries who have done the most reading and writing of rows for the database.
type StatsError
= StatsErrorDatabaseNotFound
| StatsHttpError (Error StatsResult)

Errors that can happen when attempting to retrieve stats for a database.

  • StatsErrorDatabaseNotFound happens when the passed database name does not exist in Turso.
  • StatsHttpError captures any other HTTP errors.
stats :
Connection
-> StatsArgs
-> Task StatsError (Response StatsResult)

Get stats for a given database.