Skip to main content

Read Scaling

💡Preview Feature

This is a preview feature. Preview features may be operationally incomplete and may offer limited backward compatibility.

Read-only data applications and business intelligence tools that serve multiple concurrent end users but connect to MotherDuck with a single MotherDuck user account can see poor performance due to resource contention. This is because, by default, MotherDuck assigns all client instances of DuckDB that connect to MotherDuck with the same account to a single DuckDB instance running in the cloud (“duckling”). To solve this problem, applications can create and use a Read Scaling Token to connect to MotherDuck and transparently access up to 4X compute resources to better handle concurrent query workloads generated by end users. The result is an improved end user experience and read performance for your applications!

With read scaling tokens, MotherDuck accounts now support scaling up to 4 replicas of your database that can be read concurrently. When connecting with a read scaling token, each concurrent end user connects to a read scaling replica of the database that is served by its own duckling.

With read scaling enabled, your flock of ducklings grows to ensure each concurrent end user is served by its own duckling, up to the concurrency limit of 4. Beyond this limit, applications can gracefully degrade by having multiple end users be served by the same duckling, while still maintaining affinity between end user and duckling.

Understanding read scaling tokens​

MotherDuck offers a special type of personal access token called a *Read Scaling Token. This token enables scalable read operations while restricting write capabilities. Here’s a breakdown of how it works:

Creating a read scaling token​

You can generate a read scaling token through the MotherDuck UI. When generating an access token, select "read scaling token" as the token type.

Permissions and limitations​

A read scaling token grants permission for read operations, such as querying tables, but restricts write operations, including:

  • Updating tables
  • Creating new databases
  • Attaching or detaching databases

How a DuckDB client uses read scaling tokens​

When a DuckDB client connects to MotherDuck with a read scaling token:

  • It is assigned to one of the read scaling replicas for the user account.
  • This is in addition to the standard read-write "duckling" that is used without a scaling token.

These replicas are eventually consistent, meaning data from read operations may briefly lag behind the latest writes. This design supports scaling but does not guarantee real-time access to live data.

Scaling and Replicas​

  • The flock of read scaling replicas can grow to a maximum size of 4.
  • Each replica operates independently to handle concurrent read operations.

Session affinity with session_hint​

To enhance replica affinity, the DuckDB connection string supports the session_hint parameter:

  • Clients with the same session_hint value are assigned to the same replica.
  • This parameter can be set to the ID of a user session, a user ID, or a hashed value for privacy.

By leveraging read scaling tokens and session_hint, you can efficiently scale read operations and group user sessions to optimize performance.

Best Practices​

Some prescriptions to get the best user experience out of MotherDuck read scaling features in the present:

Provision your flock based on number of concurrent end users​

Assigning each end user their own duckling leverages DuckDB’s strengths on a single user workload and will provide an optimal user experience. In practice, applications may choose to accept some graceful degradation due to co-location of multiple users on a duckling in order to bound costs. This can be done by configuring a maximum size for the flock of read replicas based on an expected number of concurrent end users. While we expect the current limit of 4 to support many use cases, we also anticipate that limit to increase over time, enabling further scale out for applications that require it.

Use local resources where it makes sense​

WASM allows applications to run a client instance of DuckDB and connect to MotherDuck in the browser. Shifting processing to the client will make better use of local resources, and may scale better to a large number of end users compared to distributing that processing over a relatively small number of ducklings.

Maintain end user affinity with ducklings​

Running all queries for a given end user on the same duckling improves user experience due to several factors: query performance benefits from caching, users see more consistent views of data across queries, and there is some measure of isolation between users. To that end, applications should use the session hint mechanism to implement user affinity. In particular, deriving the session hint from end user identity results in all client instances of DuckDB created for a given end user being assigned to the same read replica.