Almost every backend developer has built, is building, or will build a multi-tenant SaaS application at some point in their career.

The multi-tenancy approach is often simpler than single-tenancy for app developers because they can manage customer data across a common architecture, whether that’s in a shared database schema or separate databases entirely.

Tinybird is a backend platform for developers to build fast APIs over large-scale data. If you are using Tinybird to build a SaaS application, you’ll probably find yourself wanting to create a multi-tenant architecture.

This post will explain the 3 different approaches to multi-tenancy in Tinybird, when to use each one, and links to in-depth blogs on the two approaches we most recommend.

Option 1: Row-level security

Maybe the simplest way to implement multi-tenancy with Tinybird is to store all customer data in one Data Source in a single Workspace. You collect all the data from all of your tenants into a single Data Source with a shared schema. 

The upside here is that you only have to manage one Data Source, and you wouldn’t need to join many different tables together if you want to run internal analytics across many different clients. It’s as simple as it gets to set up and maintain.

The downside is that you won’t have the flexibility you would have with other approaches, especially when it comes to schema management. This approach won’t work if you need to use a different table schema for different clients, as when regional data privacy laws might require you to store PII differently for clients in various locations. You wouldn’t be able to support clients with different data locality needs.

How to create multi-tenancy with one Tinybird Data Source

Tinybird supports multi-tenancy in a single Data Source through the use of row-level security. Every client that uses published Tinybird APIs will require a unique authorization token to access those endpoints. Tinybird allows you to augment the read permission scopes of these tokens with a simple column-based SQL expression, kind of like a ``WHERE`` clause.

For example, if you have a column called ``tenant_id`` in your multi-tenant Data Source, you could modify the Data Source read permission scope of a client’s authorization token. For example, the token for Tenant 1337 would include the statement ``tenant_id = 1337``. In this way, each tenant’s SaaS experience will be powered by endpoints that only read the rows in the Data Source containing data that belongs to them.

If you’d like to take the shared Data Source approach, you can check out this more detailed blog on how to do row-level security in Tinybird.

Option 2: One Workspace, Multiple Data Sources

Shared Data Sources won’t work for every application, so the next logical step would be to use multiple Data Sources in a single Workspace. With this approach, you would send data for each tenant into its own separate data source.

There’s a lot of upside to this approach. First, you can define a unique schema for any tenant, giving you more flexibility to respond to the needs of that particular client. Second, it’s much easier to modify or delete data for a specific tenant. If, for example, a client churns and you need to delete their data, you can just drop the Data Source.

You’ll also most likely benefit from faster APIs. If you’re writing SQL queries on top of one large table, filtering and aggregating will slow down as that table grows. If you run your queries over smaller, tenant-specific tables, the APIs they support should be snappier, which makes for a better UX.

The downside here compared to the shared data source approach is that you add a bit of complexity. Now you’re managing multiple Data Sources, which means you need to be cognizant of where you send data from the application level. It also doesn’t give you the flexibility to support tenants with different data locality requirements, because all data in a Workspace will still be hosted in the selected region for that Workspace. If that’s the case, you might have to split your tenants into Workspaces on different regional clusters, which again adds a bit of complexity.

How to create multi-tenancy in a shared Tinybird Workspace

The basic approach here is to ingest all your tenant data into a common landing Data Source. From there, you can create Pipes that filter in only data belonging to a specific tenant.

This approach leverages the power of Materialized Views in Tinybird.

You can materialize those Pipes into new Data Sources, one for each tenant. As new data hits the landing Data Source, these tenant-specific Data Sources will automatically update.

You have the added bonus of being able to define some additional prefilters and pre-aggregations in the materialized Pipes if your use case allows it. This will speed up your queries and endpoints later on.

Then as you build your APIs, you can simply duplicate your .pipe files, programmatically replacing the Data Source name in their SQL.

If you’d like to pursue the per-tenant Data Source approach, you can check out this more detailed blog on how to achieve that.

Option 3: Multiple Workspaces, One Data Source Each

In theory, the final way you can create multi-tenant SaaS on Tinybird is by splitting each tenant’s data into its own separate Workspace with a single Data Source in each Workspace.

In practice, we don’t recommend this approach. It doesn’t offer much value over Option 2, and it requires that you maintain one Workspace per tenant (or more, if you use Workspaces to create development, staging, test environments, etc.). The number of Workspaces can become quite cumbersome.

That said, there are a few benefits. You can allow each tenant to choose where their data is hosted, since each Workspace is created on a specific host, and you could even invite your users to work directly in the Tinybird workspace without any risk of leaking other tenants’ data.

In almost every case, we recommend that you avoid this option, but if you have ideas or questions about it, we’d love to chat with you in Slack!

Choose your multi-tenancy path

So you have options for how you approach multi-tenancy with Tinybird. Each option is a valid and useful approach with its own set of pros and cons. Choose the one that works best for you, and for your clients.