Environments¶
What is an Environment?¶
An Environment is a snapshot of a Workspace. Environments are temporary copies of the Workspace and are perfect for testing and experimenting. They enable you to experiment with new Data Sources, updated schemas, and new API Endpoint features, without affecting the Data Project in production.
What can I use Environments for?¶
Since Environments are ephemeral in nature, they are ideal for prototyping, CI/CD workflows, and release previews. Environments enable you to iterate Data Projects without touching your production environment.
Environments are a great tool for things like:
Testing new Data Sources and schemas.
Designing with new Pipes and Nodes with exploratory SQL.
Prototyping new API Endpoints and query parameters.
Creating snapshots of production data for regression testing.
How do Environments work?¶
Main Environment¶
With Environments, a “main” Environment is provided and represents the Data Project in production. Additional Environments are created by making a copy of the “main” Environment.
Creating Environments¶
You can create and manage Environments using the UI and CLI. See below for examples of creating, switching between, and deleting Environments. By default, three Environments can be created per Workspace. Contact us at support@tinybird.co if you need to increase this limit.
There is an option to protect the main Environment from changes made with the UI. See the Protecting main Environment from UI updates section below for more information.
When creating a new Environment, you can choose a data branching strategy depending on the use case: attach all the data you have in production, just the last partition, use fixtures, or don’t add any data at all.
Note that new Environments created from main can not ingest data directly from Connectors. If you need to add data to a non-main Environment, you can use the Data Sources API using an Auth Token associated with the target Environment.
Environments and CI/CD¶
Since Environments are based on making copies of production Workspaces, they readily integrate with CI/CD workflows. By integrating Workspaces with Git, CI workflows can now create a release candidate when updates are merged. These workflows also support applying API Endpoint and custom tests, and preparing resources needed for CD. To learn more about integrating Tinybird into CI/CD pipelines, see this guide.
Environment members¶
When a new Environment is created, the Workspace members of the main Environment are assigned to the new Environment, along with their current roles. Since the new Environment is completely independent of the main Environment, members management is also independent. You can update the membership details in either Environment without affecting the other.
Environment Auth Tokens¶
When a new Environment is created, new Auth Tokens with the same scopes of the main Environment Tokens are created and added to the new Environment. These are different Tokens and completely independent of the main Environment Tokens.
Protecting main Environment from UI updates¶
Since the main Environment is intended to be the production environment, there is an option to protect it from changes made with the UI. Changes such as creating, editing, or deleting resources such as Data Sources, Pipes, Nodes, API Endpoints, and Auth Tokens.
Protecting the main Environment is recommended if you have synced your Data Project with Git. Once integrated with Git, the intent is to have your Git repository be the source of truth for what is in production. Therefore it is important to apply Data Project changes to the Git repository and use CI workflows to keep main Environment resources in sync.
To protect the main Environment, select “Setting”, then “Advanced Settings” and click the “Protect main Environment” checkbox. This can be unchecked at any time.
Managing Environments with the UI¶
In this section, we’ll cover how Environments are created, selected, and deleted with the UI.
Creating Environments¶
At the top of the Tinybird UI you’ll see the “main” Environment dropdown box. To create a new Environment, expand the dropdown menu and click the “New Environment” + icon.
This will open the Environment configuration dialog box. Every Environment is assigned a name, and you can set that by typing into the “Name” box. When creating an Environment, you can start with just the Data Source schemas, or copy all data from the current data partitions.
Selecting an Environment¶
The currently selected Environment is displayed in the Environment dropdown box. To change Environments, expand that menu and select the Environment you want to switch to.
Deleting Environment¶
To delete an Environment, switch to that Environment, then select “Settings” , then select “Advanced settings” , then click the “Delete Environment” button. This action can not be undone.
Managing Environments with the CLI¶
Creating Environments¶
To create a new Environment from the CLI, you can use the following command, replacing {NAME} with what name you want to assign to it:
tb env create {NAME} --wait
You can choose to create the Environment with no data as above or use a flag to select the data branching strategy. See tb env create --help for more info.
Selecting an Environment¶
To see the currently selected Environment, use the following command:
tb env current
To see a list of Environments, use the following command:
tb env ls
To switch to a different Environment, use this command, replacing {NAME} with the name of the Environment to load:
tb env use {NAME}
Deleting Environment¶
To delete an Environment, use the following command:
tb env rm {NAME}
You will be prompted to confirm that you want to delete the currently selected Environment. Use with care since this deletion can not be undone. If you are scripting/automating Environment management, this prompt can be skipped if you include the --yes option. This action can not be performed on the main Environment, since that would be equivalent to deleting the Workspace.
