Iterate your project

When your project is live in Tinybird Cloud, it's time to iterate on it to improve performance, fix bugs, or add new features.

Tinybird makes it easy to iterate your data project like any other software project.

1

Set up a Git repo

Create your Tinybird project in a Git repository to follow standard development practices, such as working in feature branches, using pull requests, and running CI pipelines to validate and deploy changes.

When you create a project using tb create, Tinybird generates CI templates you can use in GitHub and GitLab to automate testing and deployment. By default, the templates build your project and create a preview deployment when opening a pull request. Merging the pull request promotes the deployment to live. Learn more about Tinybird CI workflows.

The following is an example of a Git repository structure for an application containing all Tinybird resources in a tinybird folder:

my-app/
├─ public/
│  ├─ index.html
├─ src/
│  ├─ App.js
│  └─ ...
├─ package.json
├─ package-lock.json or yarn.lock
├─ README.md
├─ .gitignore
├─ tinybird/
│  ├─ datasources/
│  ├─ endpoints/
│  ├─ materializations/
│  ├─ ...
2

Edit your project

Create a new git branch in your project. Start Tinybird Local and build your project in watch mode:

git switch -c your-branch-name
tb local start
tb build --watch

As you make changes to your project, Tinybird prints the results in the terminal.

From within the build session, you can run other commands, like tb token ls to get a list of available tokens that you can use in your calls.

tb > token ls

** Tokens:
--------------------------------------------------------------------------------
id: <token_id>
name: <token_name>
token: <token_value>
--------------------------------------------------------------------------------
id: <token_id>
name: <token_name>
token: <token_value>
--------------------------------------------------------------------------------
3

Test your project locally

There are several ways of generating test data for your local project:

  • Use tb mock in a separate terminal to send test data to your data source.
  • Add test data to the /fixtures folder and re-run tb build --watch.
  • Call the local Events API endpoint using a generator, for example Mockingbird.

Run tb endpoint ls to get a list of available endpoints which you can call.

tb endpoint ls
** Pipes:
----------------------------------------------------------------------------------------------
name: user_actions_line_chart
updated at: 2025-01-15 09:10:04
nodes: 1
url: http://localhost:80/v0/pipes/user_actions_line_chart.json?org_id=1&token=<redacted_token>
----------------------------------------------------------------------------------------------

As you call the endpoints, you can see errors and warnings in the console. Use this information to debug your datafiles.

If you use the Cursor editor, you can use the tb create --cursor command to create a .cursorrules file with Tinybird rules.

4

Create a test suite

Once your project builds correctly, you can generate a test suite using tb test:

# Create a YAML test file inside /tests
tb test create user_action_insights_widget

Customize the tests to fit your needs.

5

Create a merge request

Commit your changes to Git and create a pull request. If you're using the Tinybird CI templates, this triggers the Tinybird CI pipeline, which builds the project, runs the test suite, and creates a preview deployment in Tinybird Cloud.

New errors might appear when you create a deployment in Tinybird Cloud. Use the information in the console to debug your datafiles. For example, if you're updating an existing project, you might need to use the FORWARD_QUERY statement in your datasource file.

You can use the --check flag to validate the deployment before creating it:

tb deployment create --check
6

Promote your deployment to live

After your preview deployment succeeds in Tinybird Cloud, return to your pull request and merge it. This triggers the Tinybird CD pipeline, which promotes the deployment to live.

You can now access your updated resources in Tinybird Cloud.

Next steps

Updated