Shuttle Shared Databases

This plugin manages databases on Shuttle and connects them to your app. A shared database is in the same cluster as other user’s databases, but it is not accessible by other users.

If you want a high performing and isolated database, consider Shuttle AWS RDS.

​

Usage

Start by adding shuttle-shared-db to the dependencies for your service. Each type of shareable database is behind its own feature flag and macro attribute path.

​

Output type

By default, you can get the connection string to the database and connect to it with your preferred library. You can also specify other return types to get rid of common boilerplate.

Depending on which type declaration is used as the output type in the macro, you might need to activate additional feature flags:

Lastly, add a macro annotaion to the Shuttle main function. Here are examples for Postgres:

// Use the connection string
#[shuttle_runtime::main]
async fn main(#[shuttle_shared_db::Postgres] conn_str: String) -> ... { ... }

// With sqlx feature flag, get a PgPool connected automatically
#[shuttle_runtime::main]
async fn main(#[shuttle_shared_db::Postgres] pool: sqlx::PgPool) -> ... { ... }

​

Parameters

Both the Postgres and MongoDB macros take the same optional parameter:

When passing in strings, you can also insert secrets from Secrets.toml using string interpolation. To insert the PASSWORD secret, pass it in like this:

#[shuttle_runtime::main]
async fn main(
    #[shuttle_shared_db::Postgres(
        local_uri = "postgres://postgres:{secrets.PASSWORD}@localhost:16695/postgres"
    )] conn_str: String,
) -> ... { ... }

The URI should be formatted according to the Postgres or MongoDB documentation, depending on which one you’re using.

If you do not specify a local_uri, then cargo-shuttle will attempt to spin up a Docker container and launch the database inside of it. For this to succeed, you must have Docker installed and you must also have started the Docker engine. If you have not used Docker before, the easiest way is to install the desktop app and then launch it in order to start the Docker engine.

​

Connection string

After deploying a project with a database macro, you can view the connection string with credentials with:

cargo shuttle resource list --show-secrets

Using the connection string, you can connect to it for manual querying, inspection, and migration. You can also export/import data using a dump tool suitable for the database of choice.

​

Example

The Shuttle poem main function below uses the #[shuttle_shared_db::Postgres] attribute macro to provision a shared Postgres database, which can be accessed using a pre-configured, authenticated sqlx Pool.

#[shuttle_runtime::main]
async fn poem(
    #[shuttle_shared_db::Postgres] pool: PgPool,
) -> ShuttlePoem<impl poem::Endpoint> {
    pool.execute(include_str!("../schema.sql"))
        .await
        .map_err(CustomError::new)?;

    let app = Route::new()
        .at("/todo", post(add))
        .at("/todo/:id", get(retrieve))
        .with(AddData::new(pool));

    Ok(app.into())
}

The full example can be found on GitHub.