Turso.Db

Module for configuring access to a specific Turso database and sending SQL to it.

Connecting to a Database

type alias Connection =
{ httpPermission : Permission
, accessToken : String
, organizationSlug : String
, databaseName : String
, locationUrl : String
}

A Connection is required to make any requests to a Turso database.

  • httpPermission allows functions using this Connection can make HTTP requests.
  • accessToken is the token used to make requests to the specific database. A new token can be created using the Turso.Platform.Databases.createToken function, or be retrieved from the Turso account dashboard. This token is specific to the database you're attempting to access and is different than the token needed to access the Turso platform API.
  • organizationSlug is the slug of the organization the database you want to query resides in.
  • databaseUrl is the name of the database you want to connect and send queries to.
  • locationUrl is the location of the database, used to construct the correct URL. For example aws-us-west-2 is a valid location.

Run Statements

type alias Statement = { statement : String, parameters : Array Value }

A statement runs some SQL that does not expect any data back.

When inserting dynamic values into a statement, it's highly recommended to use parameters instead of adding them manually to the statement string.
execute :
Connection
-> Statement
-> Task Error (Response ( Result {}))

Execute a single SQL statement.

Turso.Db.execute connection
    { statement = "INSERT INTO users (id, name) VALUES (:user_id, :user_name)"
    , parameters = 
        [ Turso.Db.Encode.int "user_id" 1
        , Turso.Db.Encode.string "user_name" "one"
        ]
    }
transaction :
Connection
-> Array Statement
-> Task Error (Response ( Array ( Result {}))
)

Execute an Array of sql statements in a single request.

Turso.Db.transaction connection
    [ { statement = "INSERT INTO users (id, name) VALUES (:user_id, :user_name)"
      , parameters = 
        [ Turso.Db.Encode.int "user_id" 1
        , Turso.Db.Encode.string "user_name" "one"
        ]
      }
    , { statement = "INSERT INTO users (id, name) VALUES (:user_id, :user_name)"
      , parameters =
        [ Turso.Db.Encode.int "user_id" 2
        , Turso.Db.Encode.string "user_name" "two"
        ]
      }
    ]

Run Queries

type alias Query a =
{ query : String
, parameters : Array Value
, decoder : Decoder a
}

A query runs some SQL that expects some (one or more) result back.

When inserting dynamic values into a query, it's highly recommended to use parameters instead of adding them manually to the query string.
getAll :
Connection
-> Query a
-> Task Error (Response ( Result ( Array a))
)

Get all of the resulting rows from a Query.

Turso.Db.getMaybeOne
    { query = "SELECT * FROM users WHERE name = :user_name"
    , parameters = 
        [ Turso.Db.Encode.string "user_name" "John"
        ]
    , decoder = 
        Turso.Db.Decode.map2
            (\user_name user_id ->
                { name = user_name
                , id = user_id
                }
            )
            (Turso.Db.Decode.string "name")
            (Turso.Db.Decode.string "id")
    }
getOne : Connection -> Query a -> Task Error (Response (Result a))

Run a query that should return exactly one result. If this query returns zero or more than one result, it will fail.

Turso.Db.getAll
    { query = "SELECT * FROM users WHERE id = :id"
    , parameters = 
        [ Turso.Db.Encode.string "id" "b185015c-a954-48e1-b92d-c9407ee554bd"
        ]
    , decoder = 
        Turso.Db.Decode.map
            (\name ->
                { name = name
                }
            )
            (Turso.Db.Decode.string "name")
    }
getMaybeOne :
Connection
-> Query a
-> Task Error (Response ( Result ( Maybe a))
)

Run a query that should have zero or one results. If this query returns zero or more than one result, it will fail.

Turso.Db.getMaybeOne
    { query = "SELECT * FROM users WHERE name = :user_name AND id = :user_id"
    , parameters = 
        [ Turso.Db.Encode.string "user_name" "Jane"
        , Turso.Db.Encode.string "user_id" "300b989b-7549-4753-8495-49c613e83c88"
        ]
    , decoder = 
        Turso.Db.Decode.map2
            (\user_name user_id ->
                { name = user_name
                , id = user_id
                }
            )
            (Turso.Db.Decode.string "name")
            (Turso.Db.Decode.string "id")
    }

Handling Results

type Error
= HttpError (Error {})
| SqlParseError
| SqlInputError
| SqlManyStatements
| SqliteUnknownError
| ArgsInvalid
| UnknownError String

Possible errors that happen when making a request to a Turso DB. This list is not comprehensive and other errors may appear. If you encounter an error not handled here, submit a ticket in the Github repo!

  • HttpError captures any HTTP errors.
  • SqlParseError happens when the given SQL statement cannot be parsed.
  • SqlInputError happens when the given SQL has an error with one of its inputs.
  • SqlManyStatements captures when the given SQL has more than one statement. The Turso API only allows a single SQL statement in a query.
  • SqliteUnknownError happens an unknown error with SQLite
  • ArgsInvalid happens any errors involving invalid arguments.
  • UnknownError happens any other errors that may happen.
type alias Result a =
{ baton : Maybe String
, affectedRowCount : Int
, lastInsertRowId : Maybe String
, data : a
}

The result of a query.

  • baton is not used in this module, but may be used in the future. It allows making multiple requests to Turso on the same connection. This value can be safely ignored.
  • affectedRowCount is the number of rows affected by the sent SQL. If you're inserting rows, this number should equal the number of rows inserted, for example.
  • lastInsertRowId is the internal Turso ID of the last row inserted. This will be Nothing if no rows were inserted.
  • data is the data returned from the database.