> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powersync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust SDK (alpha)

> Use PowerSync in Rust apps.

<Warning>
  This SDK is currently in [**alpha**](/resources/feature-status), intended for external testing and public feedback. Expect breaking changes and instability as development continues.
</Warning>

<CardGroup cols={3}>
  <Card title="PowerSync SDK on crates.io" icon="cube" href="https://crates.io/crates/powersync">
    The SDK is distributed via crates.io
  </Card>

  <Card title="Source Code" icon="github" href="https://github.com/powersync-ja/powersync-native/">
    Refer to the `powersync-native` repo on GitHub
  </Card>

  <Card title="API Reference" icon="book" href="https://docs.rs/powersync/latest/powersync/">
    Full API reference for the SDK
  </Card>

  <Card title="Example Projects" icon="code" href="/intro/examples#rust-alpha">
    Gallery of example projects/demo apps built with Rust and PowerSync
  </Card>

  <Card title="Changelog" icon="megaphone" href="https://github.com/powersync-ja/powersync-native/blob/main/CHANGELOG.md">
    Changelog for the SDK
  </Card>
</CardGroup>

### SDK Features

* **Real-time streaming of database changes**: Changes made by one user are instantly streamed to all other users with access to that data. This keeps clients automatically in sync without manual polling or refresh logic.
* **Direct access to a local SQLite database**: Data is stored locally, so apps can read and write instantly without network calls. This enables offline support and faster user interactions.
* **Asynchronous background execution**: The SDK performs database operations in the background to avoid blocking the application’s main thread. This means that apps stay responsive, even during heavy data activity.
* **Query subscriptions for live updates**: The SDK supports query subscriptions that automatically push real-time updates to client applications as data changes, keeping your UI reactive and up to date.
* **Automatic schema management**: PowerSync syncs schemaless data and applies a client-defined schema using SQLite views. This architecture means that PowerSync SDKs can handle schema changes gracefully without requiring explicit migrations on the client-side.

## Installation

Add the [PowerSync SDK](https://central.sonatype.com/artifact/com.powersync/core) to your project by adding the following to your `Cargo.toml` file:

```shell theme={null}
cargo add powersync
```

## Getting Started

**Prerequisites**: To sync data between your client-side app and your backend source database, you must have completed the necessary setup for PowerSync, which includes connecting your source database to the PowerSync Service and deploying Sync Streams (or legacy Sync Rules) (steps 1-4 in the [Setup Guide](/intro/setup-guide)).

### 1. Define the Client-Side Schema

The first step is to define the client-side schema, which refers to the schema for the managed SQLite database exposed by the PowerSync Client SDKs, that your app can read from and write to. The client-side schema is typically mainly derived from your backend source database schema and your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)), but can also include other tables such as local-only tables. Note that schema migrations are not required on the SQLite database due to the schemaless nature of the [PowerSync protocol](/architecture/powersync-protocol): schemaless data is synced to the client-side SQLite database, and the client-side schema is then applied to that data using *SQLite views* to allow for structured querying of the data. The schema is applied when the local PowerSync database is constructed (as we'll show in the next step).

<Tip>
  **Generate schema automatically**

  In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance and click the **Connect** button in the top bar to generate the client-side schema in your preferred language. The schema will be generated based off your Sync Streams/Rules.

  Similar functionality exists in the [CLI](/tools/cli).

  **Note:** The generated schema will not include an `id` column, as the client SDK automatically creates an `id` column of type `text`. Consequently, it is not necessary to specify an `id` column in your schema. For additional information on IDs, refer to [Client ID](/sync/advanced/client-id).
</Tip>

The types available are `text`, `integer` and `real`. These should map directly to the values produced by your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)). If a value doesn't match, it is cast automatically. For details on how backend source database types are mapped to the SQLite types, see [Types](/sync/types).

**Example**:

```Rust src/schema.rs theme={null}
use powersync::schema::{Column, Schema, Table};

pub fn app_schema() -> Schema {
    let mut schema = Schema::default();
    let todos = Table::create(
        "todos",
        vec![
            Column::text("list_id"),
            Column::text("created_at"),
            Column::text("completed_at"),
            Column::text("description"),
            Column::integer("completed"),
            Column::text("created_by"),
            Column::text("completed_by"),
        ],
        |_| {},
    );

    let lists = Table::create(
        "lists",
        vec![
            Column::text("created_at"),
            Column::text("name"),
            Column::text("owner_id"),
        ],
        |_| {},
    );

    schema.tables.push(todos);
    schema.tables.push(lists);
    schema
}
```

<Note>
  **Note**: No need to declare a primary key `id` column, as PowerSync will automatically create this.
</Note>

### 2. Instantiate the PowerSync Database

Next, you need to instantiate the PowerSync database. PowerSync streams changes from your backend source database into the client-side SQLite database, based on your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)). In your client-side app, you can read from and write to the local SQLite database, whether the user is online or offline.

#### Process setup

PowerSync is based on SQLite, and statically links the [PowerSync SQLite core extension](https://github.com/powersync-ja/powersync-sqlite-core), which needs to be enabled for the process before the SDK can be used. The SDK offers a utility to register the extension, and we recommend calling it early in `main()`:

```Rust lib/main.rs theme={null}
use powersync::env::PowerSyncEnvironment;

mod schema;

fn main() {
    PowerSyncEnvironment::powersync_auto_extension()
        .expect("could not load PowerSync core extension");

    // TODO: Start database and your app
}
```

#### Database setup

For maximum flexibility, the PowerSync Rust SDK can be configured with different asynchronous runtimes and HTTP clients used to connect to the PowerSync Service.
These dependencies can be configured through the [`PowerSyncEnvironment`](https://docs.rs/powersync/latest/powersync/env/struct.PowerSyncEnvironment.html)
struct, which wraps:

1. An HTTP client (implement the `powersync::http::HttpClient` trait). When enabling the `reqwest` feature on
   the `powersync` crate, that trait is implemented for `reqwest::Client`.
2. An asynchronous pool giving out leases to SQLite connections.
3. A timer implementation allowing the sync client to implement delayed retries on connection errors.
   This is typically provided by async runtimes like Tokio.

To configure PowerSync, begin by configuring a connection pool:

<Tabs>
  <Tab title="Default setup">
    Use `ConnectionPool::open` to open a database file with multiple connections configured with WAL mode:

    ```Rust theme={null}
    use powersync::{ConnectionPool, error::PowerSyncError};
    use powersync::env::PowerSyncEnvironment;

    fn open_pool() -> Result<ConnectionPool, PowerSyncError>{
        ConnectionPool::open("database.db")
    }
    ```
  </Tab>

  <Tab title="In-memory connection">
    ```Rust theme={null}
    use powersync::ConnectionPool;
    use powersync::env::PowerSyncEnvironment;
    use powersync::error::PowerSyncError;
    use rusqlite::Connection;

    fn open_pool() -> Result<ConnectionPool, PowerSyncError> {
        let connection = Connection::open_in_memory()?;
        Ok(ConnectionPool::single_connection(connection))
    }
    ```
  </Tab>
</Tabs>

Next, create a database and start asynchronous tasks used by the sync client when connecting.
To be compatible with different executors, the SDK uses a model based on long-lived actors instead of
spawning tasks dynamically. All asynchronous processes are exposed through `PowerSyncDatabase::async_tasks()`,
these tasks must be spawned before connecting.

<Tabs>
  <Tab title="Tokio">
    Ensure you depend on `powersync` with the `tokio` feature enabled.

    ```Rust theme={null}
    #[tokio::main]
    async fn main() {
        PowerSyncEnvironment::powersync_auto_extension()
            .expect("could not load PowerSync core extension");

        let pool = open_pool().expect("open pool");
        let env = PowerSyncEnvironment::custom(
            reqwest::Client::new(),
            pool,
            PowerSyncEnvironment::tokio_timer(),
        );

        let db = PowerSyncDatabase::new(env, schema::app_schema());
        db.async_tasks().spawn_with_tokio();
    }
    ```
  </Tab>

  <Tab title="smol">
    Ensure you depend on `powersync` with the `smol` feature enabled.

    ```Rust theme={null}
    async fn start_app() {
        let pool = open_pool().expect("open pool");
        let env = PowerSyncEnvironment::custom(
            reqwest::Client::new(),
            pool,
            // Use the async_io crate to implement timers in PowerSync
            PowerSyncEnvironment::async_io_timer(),
        );

        let db = PowerSyncDatabase::new(env, schema::app_schema());
        // TODO: Use a custom multi-threaded executor instead of the default
        let tasks = db.async_tasks().spawn_with(smol::spawn);
        for task in tasks {
            // The task will automatically stop once the database is dropped, but we
            // want to keep it running until then.
            task.detach();
        }
    }

    fn main() {
        PowerSyncEnvironment::powersync_auto_extension()
            .expect("could not load PowerSync core extension");
        smol::block_on(start_app());
    }
    ```
  </Tab>

  <Tab title="Other">
    PowerSync is executor-agnostic and supports all async Rust runtimes. You need to provide:

    1. A future that delays execution by scheduling its waker through a timer.
    2. A way to spawn futures as a task that is polled independently.

    PowerSync uses the [`Timer`](https://docs.rs/powersync/latest/powersync/env/trait.Timer.html)
    trait for timers, it can be installed by creating a `PowerSyncEnvironment` with `PowerSyncEnvironment::custom`
    and passing your custom timer implementation.

    Spawning tasks is only necessary once after opening the database. All tasks necessary for the sync
    client are exposed through `PowerSyncDatabase::async_tasks`. You can spawn these by providing
    a function turning these futures into independent tasks via `AsyncDatabaseTasks::spawn_with`.
  </Tab>
</Tabs>

Finally, instruct PowerSync to sync data from your backend:

```Rust theme={null}
// MyBackendConnector is defined in the next step...
db.connect(SyncOptions::new(MyBackendConnector {
    db: db.clone(),
})).await;
```

<Tip>
  **Note**: This section assumes you want to use PowerSync to sync your backend source database with SQLite in your app. If you only want to use PowerSync to manage your local SQLite database without sync, instantiate the PowerSync database without calling `connect()` and refer to our [Local-Only](/client-sdks/advanced/local-only-usage) guide.
</Tip>

### 3. Integrate with Your Backend

Create a connector to integrate with your backend. The PowerSync backend connector provides the connection between your application backend and the PowerSync managed database. It is used to:

1. Retrieve an auth token to connect to the PowerSync instance.
2. Upload client-side writes to your backend API. Any writes that are made to the SQLite database are placed into an upload queue by the PowerSync Client SDK and automatically uploaded to your app backend (where you apply those changes to the backend source database) when the user is connected.

Accordingly, the connector must implement two methods:

1. `fetch_credentials` - This method is automatically invoked by the PowerSync Client SDK to obtain authentication credentials. The SDK caches credentials internally and only calls this method when needed (e.g. on initial connection or when the token is near expiry). See [When `fetchCredentials()` is Called](/configuration/app-backend/client-side-integration#when-fetchcredentials-is-called) for details, and [Authentication Setup](/configuration/auth/overview) for instructions on how the credentials should be generated.
2. `upload_data` - This method will be automatically invoked by the PowerSync Client SDK whenever it needs to upload client-side writes to your app's backend API. You need to implement how those writes are processed and uploaded in this method. See [When `uploadData()` is Called](/configuration/app-backend/client-side-integration#when-uploaddata-is-called) for details on triggers, throttling, and retry behavior, and [Writing Client Changes](/handling-writes/writing-client-changes) for considerations on the app backend implementation.

**Example**:

```Rust theme={null}
struct MyBackendConnector {
    db: PowerSyncDatabase,
}

#[async_trait]
impl BackendConnector for MyBackendConnector {
    async fn fetch_credentials(&self) -> Result<PowerSyncCredentials, PowerSyncError> {
        // implement fetchCredentials to obtain the necessary credentials to connect to your backend
        // See an example implementation in https://github.com/powersync-ja/powersync-native/blob/508193b0822b8dad1a534a16462e2fcd36a9ac68/examples/egui_todolist/src/database.rs#L119-L133

        Ok(PowerSyncCredentials {
            endpoint: "[Your PowerSync instance URL or self-hosted endpoint]".to_string(),
            // Use a development token (see Authentication Setup https://docs.powersync.com/configuration/auth/development-tokens) to get up and running quickly
            token: "An authentication token".to_string(),
        })
    }

    async fn upload_data(&self) -> Result<(), PowerSyncError> {
        // Implement uploadData to send local changes to your backend service
        // You can omit this method if you only want to sync data from the server to the client
        // See an example implementation under Usage Examples (sub-page)
        // See https://docs.powersync.com/handling-writes/writing-client-changes for considerations.
        let  mut local_writes = self.db.crud_transactions();
        while let Some(tx) = local_writes.try_next().await? {
            todo!("Inspect tx.crud for local writes that need to be uploaded to your backend");
            tx.complete().await?;
        }

        Ok(())
    }
}
```

## Using PowerSync: CRUD functions

Once the PowerSync instance is configured you can start using the SQLite DB functions.

The most commonly used CRUD functions to interact with your SQLite data are:

* [reader](#reads) - run statements reading from the database.
* [writer](/client-sdks/reference/kotlin#querying-items-powersync-getall) - execute a read query every time source tables are modified.
* [writer](#mutations) - write to the database.

### Reads

To obtain a connection suitable for reads, call and await `PowerSyncDatabase::reader()`.
The returned connection leased can be used as a `rusqlite::Connection` to run queries.

```Rust theme={null}
async fn find(db: &PowerSyncDatabase, id: &str) -> Result<(), PowerSyncError> {
    let reader = db.reader().await?;
    let mut stmt = reader.prepare("SELECT * FROM lists WHERE id = ?")?;
    let mut rows = stmt.query(params![id])?;
    while let Some(row) = rows.next()? {
        let id: String = row.get("id")?;
        let name: String = row.get("name")?;

        println!("Found todo list: {id}, {name}");
    }
}
```

### Watching Queries

The `watch_statement` method executes a read query whenever a change to a dependent table is made.

```Rust theme={null}
async fn watch_pending_lists(db: &PowerSyncDatabase) -> Result<(), PowerSyncError> {
    let stream = db.watch_statement(
        "SELECT * FROM lists WHERE state = ?".to_string(),
        params!["pending"],
        |stmt, params| {
            let mut rows = stmt.query(params)?;
            let mut mapped = vec![];

            while let Some(row) = rows.next()? {
                mapped.push(() /* TODO: Read row into list struct */)
            }

            Ok(mapped)
        },
    );
    let mut stream = pin!(stream);

    // Note: The stream is never-ending, so you probably want to call this in an independent async
    // task.
    while let Some(event) = stream.try_next().await? {
        // Update UI to display rows
    }
    Ok(())
}
```

### Mutations

Local writes on tables are automatically captured with triggers. To obtain a connection suitable for
writes, use the `PowerSyncDatabase::writer` method:

The `execute` method executes a write query (INSERT, UPDATE, DELETE) and returns the results (if any).

```Rust theme={null}
async fn insert_customer(
    db: &PowerSyncDatabase,
    name: &str,
    email: &str,
) -> Result<(), PowerSyncError> {
    let writer = db.writer().await?;
    writer.execute(
        "INSERT INTO customers (id, name, email) VALUES (uuid(), ?, ?)",
        params![name, email],
    )?;
    Ok(())
}
```

If you're looking for transactions, use the [`transaction`](https://docs.rs/rusqlite/latest/rusqlite/struct.Connection.html#method.transaction)
method from `rusqlite` on `writer`.

## Configure Logging

The Rust SDK uses the `log` crate internally, so you can configure it with any backend, e.g. with
`env_logger`:

```Rust theme={null}
fn main() {
    env_logger::init();
    // ...
}
```

## Additional Usage Examples

For more usage examples including accessing connection status, monitoring sync progress, and waiting for initial sync, see the [Usage Examples](/client-sdks/usage-examples) page.

## ORM / SQL Library Support

The Rust SDK does not currently support any higher-level SQL libraries, but we're investigating
support for Diesel and sqlx.
Please reach out to us if you're interested in these or other integrations.

## Troubleshooting

See [Troubleshooting](/debugging/troubleshooting) for pointers to debug common issues.

## Supported Platforms

See [Supported Platforms -> Rust SDK](/resources/supported-platforms#rust-sdk).

## Upgrading the SDK

To update the PowerSync SDK, run `cargo update powersync` or manually update to the
[latest version](https://crates.io/crates/powersync/versions).