Whether you want to run SELECT or INSERT statements, or any other number of commands on your database via SQL, the HTTP query endpoint allows you to do it.

Authorization

Every request sent to a StarbaseDB instance must pass in an Authorization Bearer token with a token value matching the value defined in your wrangler.toml file where the variable name is AUTHORIZATION_TOKEN. For any request that does not have a matching token value, the request will automatically be denied and cannot pass into the storage layer of your database.

An example cURL including the Bearer token can be seen below.

Copycurl --location 'https://starbasedb.YOUR-IDENTIFIER.workers.dev/query' \
--header 'Authorization: Bearer ABC123' \
--header 'Content-Type: application/json' \
--data '{
    "sql": "SELECT 1+1;",
    "params": []
}'

Run Query

Executing an arbitrary SQL query against your database is easy. You can pass in any legal SQLite command into the sql parameter of your POST body and it will respond with the databases result, or an error explaining what went wrong.

Copycurl --location 'https://starbasedb.YOUR-IDENTIFIER.workers.dev/query' \
--header 'Authorization: Bearer ABC123' \
--header 'Content-Type: application/json' \
--data '{
    "sql": "INSERT INTO orders (user_id, order_date, amount) VALUES (1, '\''2024-12-01'\'', 50.75);",
    "params": []
}'

Query with Parameters

When you need to execute a SQL statement in a sanitized manner, you should utilize the params body parameter in the POST endpoint. This allows for the database engine to properly sanitize and replace values from the array, into the SQL statement to be executed in a safe way.

To indicate where each item from the params array should be placed, it will match the order in which the ? characters appear in the sql parameter value.

Copycurl --location 'https://starbasedb.YOUR-IDENTIFIER.workers.dev/query' \
--header 'Authorization: Bearer ABC123' \
--header 'Content-Type: application/json' \
--data '{
    "sql": "INSERT INTO orders (user_id, order_date, amount) VALUES (?, ?, ?);",
    "params": [1, '\''2024-12-01'\'', 50.75]
}'