# Shuttle Turso

This plugin allows services to connect to a Turso database. Turso is an edge-hosted distributed database based on libSQL, a SQLite fork.

## Usage

**IMPORTANT**: Currently Shuttle isn't able to provision a database for you (yet). This means you will have to create an account on their [website](https://turso.tech/) and follow the few steps required to create a database and create a token to access it.

Add `shuttle-turso` to the dependencies for your service by running `cargo add shuttle-turso`.
This resource will be provided by adding the `shuttle_turso::Turso` attribute to your Shuttle `main` decorated function.

It returns a `libsql_client::Client`. When running locally it will instantiate a local SQLite database of the name of your service instead of connecting to your edge database.

If you want to connect to a remote database when running locally, you can specify the `local_addr` parameter. In that case, the token will be read from your `Secrets.dev.toml` file.

### Example

In the case of an Axum server, your main function will look like this:

```rust
use libsql_client::client::Client;
use shuttle_axum::ShuttleAxum;

#[shuttle_runtime::main]
async fn app(#[shuttle_turso::Turso(addr="libsql://my-turso-db-name.turso.io", token="{secrets.DB_TURSO_TOKEN}")] client: Client) -> ShuttleAxum { }
```

### Parameters

| Parameter  | Type        | Default | Description                                                                                                                                        |
| ---------- | ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| addr       | str         | `""`    | URL of the database to connect to. If `libsql://` is missing at the beginning, it will be automatically added.                                     |
| token      | str         | `""`    | The value of the token to authenticate against the Turso database. You can use string interpolation to read a secret from your `Secret.toml` file. |
| local_addr | Option<str> | `None`  | The URL to use when running your service locally. If not provided, this will default to a local file named `<service name>.db`                     |
