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 ( Result ( Data {}))
)
(Response ( Result ( Data {}))
)

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 ( Result ( Array ( Data {}))
))
(Response ( Result ( Array ( Data {}))
))

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 ( Result ( Data ( Array a))
))
(Response ( Result ( Data ( 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 ( Result ( Data a))
)
(Response ( Result ( Data 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 ( Result ( Maybe ( Data a))
))
(Response ( Result ( Maybe ( Data 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")
    }

Getting Results

type alias Result a = { baton : Maybe String, result : a }

The result of a single query sent to Turso.

  • baton is a value that is not used in this module. If supported in the future, it'd allow for multiple queries or statements to be run using the same database connection.
  • data is the data result of running the query. These are captured by the Data a type in this module.
type alias Data a =
{ affectedRowCount : Int
, lastInsertRowId : Maybe String
, data : a
}

The data returned from a query or statement sent to the database.

  • affectedRowCount will return the amount of rows affected by the query or statement. For example, if you run the execute function with a DELETE statement, the returned affectedRowcount would indicate the number of rows deleted.
  • lastInsertedRowId will return the id of the last inserted row. This id is the Turso internal representation of the row that was inserted. This will be Nothing if no rows were inserted as part of the query.
  • data is the data that was decoded from the given query. If you are running statements (using execute or transaction), no data will be returned.