Branches¶

What's a Branch?¶

Branches are isolated, temporary copies of your Tinybird project and the resources it contains (including Data Sources, Pipes, API Endpoints). They are inspired by Git branches, allowing you to make changes and develop new features, then merge those changes back into the Workspace.

What should you use Branches for?¶

Use Branches to develop new features without affecting production or other developers. Tinybird Branches mirror the intent behind Git branches, and you can use them for the same reasons.

Branches are temporary, rather than long lived, so they're ideal for building new features and prototyping. Remove Branches when their work is complete, either merged or deleted.

Common uses for Branches include:

• Designing new Data Sources or Pipes.
• Iterating the schema of a Data Source.
• Testing the backfill strategy of a new Data Source.
• Changing the output of a Pipe.
• Modifying API Endpoint query parameters.

Data in Branches¶

Creating a Branch copies all the resources from the Workspace to the new Branch, but it doesn't copy all the production data.

When creating a Branch, you can select to copy a segment of data from production into the new Branch. This duplicates the latest active partition up to a maximum of 50 GB of data from all production Data Sources, and attaches the copies to the new Branch Data Sources. This data is a copy and is physically separate from the production data. This means you can ingest or drop data from the Branch and production data isn't affected. If you select not to copy data, the new Branch contains no data, and you need to ingest data into the Branch Data Sources. When you delete a Branch, the Branch data is also deleted.

There is a soft limit on the number of Branches you can create per Workspace. Contact Tinybird at support@tinybird.co if you need to increase this limit.

Branch users¶

When you create a Branch, Tinybird adds all Workspace users to the new Branch with their current roles. If you don't see a user in the Branch, it's probably because the user joined the Workspace after creating the Branch.

Adding or removing members is only available in main Branch.

Branch Tokens¶

When creating a new Branch, all Tokens from the Workspace mirror in the new Branch. These are new Tokens that are completely independent of the production Tokens, but with the same names and scopes. This means you can delete or update the scopes of the Tokens in the new Branch without affecting production.

Create a Branch¶

You can create a Branch via the Tinybird UI, Tinybird CLI, or automatically as part of your CI/CD process.

Using the Tinybird UI¶

To create a new Branch with the Tinybird UI, select the Branch dropdown in the top bar near main, and select New Branch. Type the Branch name and select the Create Branch button.

Using the Tinybird CLI¶

To create a new Branch with the Tinybird CLI, use the tb branch create command. See the tb branch Command Reference for more information.

Using a pull request¶

To create a new Branch with a Pull Request (PR), push your local feature branch to your Git provider and open a new PR. The CI/CD actions should sync the branch from your PR to Tinybird.

Delete a Branch¶

You can delete a Branch via the Tinybird UI, Tinybird CLI, or automatically as part of your CI/CD process.

Using the Tinybird UI¶

To delete a Branch with the Tinybird UI, select the Branch you want to delete in the top bar. Then select Settings and from that menu select Advanced Settings. Verify you have selected the correct Branch and select the red Delete Branch button. You must verify this operation and select Delete again.

Using the Tinybird CLI¶

To delete a Branch with the Tinybird CLI, use the tb branch rm command. See the tb branch Command Reference for more information.

Using a pull request¶

To delete a Branch from a Pull Request (PR), close or merge the associated PR in your Git provider. The automated CI/CD actions delete the Branch from Tinybird.

Limitations¶

JOIN Engine Data Sources

Data Sources using the JOIN Engine aren't fully supported in Branches.

You can create a Branch with JOIN Engine Data Sources, but the data isn't copied into the new Branch.