Merge pull request #15 from tinybirdco/manum/fwd-796-define-cloud-branch-creation-in-tinybird-config

Allow to set branch mode in tinybird.config.json

Author: manumartinm

CHANGELOG.md

@@ -5,11 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
-
-### Added
-- Professional repository baseline:
-  - CI workflow with lint, type checks, tests, and secret scanning gates.
-  - `pre-commit` with `ruff`, `mypy`, and `gitleaks`.
-  - `Makefile`, `CODEOWNERS`, and PR template.
-  - Initial `SECURITY.md` and packaging metadata improvements.
+## [0.1.11] - 2026-06-15
+
+### Changed
+
+- Relaxed bundled `tinybird` CLI dependency to `>=4.6.0,<4.7.0` to avoid resolution failures while keeping the SDK on the `4.6.x` line.
+- Updated branch data config handling to use `branch_data_mode`; legacy `branch_data_on_create` now triggers an explicit migration error.
+- `branch_data_mode` now only accepts `last_partition` as a user-facing value.
+- In `dev_mode=local`, branch data mode warnings are now shown only when `branch_data_mode` is explicitly set in `tinybird.config.json`.
+- `tinybird branch create` and `tinybird branch clear` now show a deprecation warning (instead of failing) when `--ignore-datasource` is passed, then continue by ignoring that flag.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tinybird-sdk"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for Tinybird Forward"
 readme = "README.md"
 license = "MIT"
@@ -9,7 +9,7 @@ authors = [
 ]
 requires-python = ">=3.11"
 dependencies = [
-    "tinybird==4.6.0",
+    "tinybird>=4.6.0,<4.7.0",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",

src/tinybird_sdk/api/__init__.py

@@ -13,6 +13,7 @@
 )
 from .branches import (
     TinybirdBranch,
+    CreateBranchOptions,
     BranchApiConfig,
     BranchApiError,
     create_branch,

src/tinybird_sdk/api/branches.py

@@ -1,15 +1,13 @@
 from __future__ import annotations
 
 import time
-from dataclasses import asdict
-from dataclasses import dataclass
+from dataclasses import asdict, dataclass
 from typing import Any
 from urllib.parse import urlencode
 
+from ..cli.config_types import BranchDataMode
 from .fetcher import tinybird_fetch
 
-LAST_PARTITION = "last_partition"
-
 
 @dataclass(frozen=True, slots=True)
 class BranchApiConfig:
@@ -25,6 +23,11 @@ class TinybirdBranch:
     token: str | None = None
 
 
+@dataclass(frozen=True, slots=True)
+class CreateBranchOptions:
+    branch_data_mode: BranchDataMode | None = None
+
+
 class BranchApiError(Exception):
     def __init__(self, message: str, status: int, body: Any = None):
         super().__init__(message)
@@ -68,9 +71,14 @@ def _poll_job(
     raise BranchApiError(f"Job '{job_id}' timed out after {max_attempts} attempts", 408)
 
 
-def create_branch(config: BranchApiConfig | dict[str, Any], name: str) -> TinybirdBranch:
+def create_branch(
+    config: BranchApiConfig | dict[str, Any], name: str, options: CreateBranchOptions | None = None
+) -> TinybirdBranch:
     normalized = config if isinstance(config, BranchApiConfig) else BranchApiConfig(**config)
-    url = f"{normalized.base_url.rstrip('/')}/v1/environments?{urlencode({'name': name})}"
+    params = {"name": name}
+    if options and options.branch_data_mode:
+        params["data"] = options.branch_data_mode
+    url = f"{normalized.base_url.rstrip('/')}/v1/environments?{urlencode(params)}"
     response = tinybird_fetch(url, method="POST", headers=_headers(normalized.token))
 
     if not response.ok:
@@ -152,19 +160,23 @@ def branch_exists(config: BranchApiConfig | dict[str, Any], name: str) -> bool:
     return any(branch.name == name for branch in branches)
 
 
-def get_or_create_branch(config: BranchApiConfig | dict[str, Any], name: str) -> dict[str, Any]:
+def get_or_create_branch(
+    config: BranchApiConfig | dict[str, Any], name: str, options: CreateBranchOptions | None = None
+) -> dict[str, Any]:
     normalized = config if isinstance(config, BranchApiConfig) else BranchApiConfig(**config)
     try:
         branch = get_branch(normalized, name)
         return {**asdict(branch), "was_created": False}
     except BranchApiError as error:
         if error.status == 404:
-            branch = create_branch(normalized, name)
+            branch = create_branch(normalized, name, options=options)
             return {**asdict(branch), "was_created": True}
         raise
 
 
-def clear_branch(config: BranchApiConfig | dict[str, Any], name: str) -> TinybirdBranch:
+def clear_branch(
+    config: BranchApiConfig | dict[str, Any], name: str, options: CreateBranchOptions | None = None
+) -> TinybirdBranch:
     normalized = config if isinstance(config, BranchApiConfig) else BranchApiConfig(**config)
     delete_branch(normalized, name)
-    return create_branch(normalized, name)
+    return create_branch(normalized, name, options=options)

src/tinybird_sdk/cli/commands/build.py

@@ -5,7 +5,7 @@
 import time
 from typing import Any
 
-from ...api.branches import get_or_create_branch
+from ...api.branches import CreateBranchOptions, get_or_create_branch
 from ...api.build import build_to_tinybird
 from ...api.dashboard import get_branch_dashboard_url, get_local_dashboard_url
 from ...api.local import (
@@ -138,9 +138,14 @@ def run_build(options: BuildCommandOptions | dict[str, Any] | None = None) -> Bu
 
         if not normalized.token_override:
             try:
+                branch_options = None
+                branch_value = config.get("branch_data_mode")
+                if branch_value and config.get("dev_mode") != "local":
+                    branch_options = CreateBranchOptions(branch_data_mode=branch_value)
                 branch = get_or_create_branch(
                     {"base_url": config["base_url"], "token": config["token"]},
                     config["tinybird_branch"],
+                    options=branch_options,
                 )
                 if not branch.get("token"):
                     return BuildCommandResult(

src/tinybird_sdk/cli/commands/clear.py

@@ -5,7 +5,7 @@
 import time
 from typing import Any
 
-from ...api.branches import clear_branch
+from ...api.branches import CreateBranchOptions, clear_branch
 from ...api.local import clear_local_workspace, get_local_tokens, get_local_workspace_name
 from ..config import load_config_async
 
@@ -60,8 +60,15 @@ def run_clear(options: ClearCommandOptions | dict[str, Any] | None = None) -> Cl
                 duration_ms=int(time.time() * 1000) - start,
             )
 
+        branch_options = None
+        branch_value = config.get("branch_data_mode")
+        if branch_value and config.get("dev_mode") != "local":
+            branch_options = CreateBranchOptions(branch_data_mode=branch_value)
+
         clear_branch(
-            {"base_url": config["base_url"], "token": config["token"]}, config["tinybird_branch"]
+            {"base_url": config["base_url"], "token": config["token"]},
+            config["tinybird_branch"],
+            options=branch_options,
         )
         return ClearResult(
             success=True,

src/tinybird_sdk/cli/commands/preview.py

@@ -5,7 +5,7 @@
 import time
 from typing import Any
 
-from ...api.branches import create_branch, delete_branch, get_branch
+from ...api.branches import CreateBranchOptions, create_branch, delete_branch, get_branch
 from ...api.build import build_to_tinybird
 from ...api.deploy import deploy_to_main
 from ...api.local import LocalNotRunningError, get_local_tokens, get_or_create_local_workspace
@@ -151,8 +151,14 @@ def run_preview(
         except Exception:
             pass
 
+        branch_options = None
+        branch_value = config.get("branch_data_mode")
+        if branch_value and config.get("dev_mode") != "local":
+            branch_options = CreateBranchOptions(branch_data_mode=branch_value)
         branch = create_branch(
-            {"base_url": config["base_url"], "token": config["token"]}, preview_branch_name
+            {"base_url": config["base_url"], "token": config["token"]},
+            preview_branch_name,
+            options=branch_options,
         )
     except Exception as error:
         return PreviewCommandResult(

src/tinybird_sdk/cli/config.py

@@ -8,7 +8,12 @@
 from typing import Any
 
 from .config_loader import load_config_file
-from .config_types import DevMode, TinybirdConfig
+from .config_types import (
+    BRANCH_DATA_MODE_VALUES,
+    BranchDataModeEnum,
+    DevMode,
+    TinybirdConfig,
+)
 from .git import get_current_git_branch, get_tinybird_branch_name, is_main_branch
 
 DEFAULT_BASE_URL = "https://api.tinybird.co"
@@ -34,6 +39,27 @@ class ResolvedConfig:
     tinybird_branch: str | None
     is_main_branch: bool
     dev_mode: DevMode
+    branch_data_mode: str | None
+
+
+def _resolve_branch_data_mode(raw: dict[str, Any]) -> tuple[str | None, bool]:
+    if "branch_data_on_create" in raw:
+        raise ValueError("`branch_data_on_create` has been renamed to `branch_data_mode`.")
+
+    value = raw.get("branch_data_mode")
+    if value is None:
+        return BranchDataModeEnum.LAST_PARTITION.value, False
+    if not isinstance(value, str):
+        raise ValueError("branch_data_mode must be a string.")
+
+    mode = value.strip().lower()
+    if not mode:
+        return BranchDataModeEnum.LAST_PARTITION.value, False
+    if mode not in BRANCH_DATA_MODE_VALUES:
+        raise ValueError(
+            f"Invalid branch_data_mode '{value}'. Allowed values are: {', '.join(BRANCH_DATA_MODE_VALUES)}."
+        )
+    return mode, True
 
 
 def load_env_files(directory: str) -> None:
@@ -176,6 +202,14 @@ def _resolve_config(config: TinybirdConfig, config_path: str) -> ResolvedConfig:
         or DEFAULT_BASE_URL
     )
 
+    branch_data_mode, branch_data_mode_explicit = _resolve_branch_data_mode(asdict(config))
+    dev_mode = config.dev_mode or "branch"
+    if branch_data_mode_explicit and branch_data_mode and dev_mode == "local":
+        print(
+            "Warning: branch_data_mode is set in tinybird.config.json but dev_mode='local'. "
+            "Branch data settings only apply to cloud branches."
+        )
+
     return ResolvedConfig(
         include=include,
         token=token,
@@ -185,7 +219,8 @@ def _resolve_config(config: TinybirdConfig, config_path: str) -> ResolvedConfig:
         git_branch=get_current_git_branch(),
         tinybird_branch=get_tinybird_branch_name(),
         is_main_branch=is_main_branch(),
-        dev_mode=config.dev_mode or "branch",
+        dev_mode=dev_mode,
+        branch_data_mode=branch_data_mode,
     )
 
 

src/tinybird_sdk/cli/config_types.py

@@ -1,9 +1,16 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from enum import StrEnum
 from typing import Literal
 
 DevMode = Literal["branch", "local"]
+BranchDataMode = Literal["last_partition"]
+BRANCH_DATA_MODE_VALUES: tuple[str, ...] = ("last_partition",)
+
+
+class BranchDataModeEnum(StrEnum):
+    LAST_PARTITION = "last_partition"
 
 
 @dataclass(frozen=True, slots=True)
@@ -13,3 +20,4 @@ class TinybirdConfig:
     token: str | None = None
     base_url: str | None = None
     dev_mode: DevMode | None = None
+    branch_data_mode: str | None = None

src/tinybird_sdk/client/base.py

@@ -4,7 +4,7 @@
 from typing import Any, cast
 
 from ..api.api import TinybirdApi, TinybirdApiError
-from ..api.branches import get_or_create_branch
+from ..api.branches import CreateBranchOptions, get_or_create_branch
 from ..cli.config import load_config_async
 from .preview import get_preview_branch_name, is_preview_environment
 from .tokens import TokensNamespace
@@ -159,12 +159,18 @@ def _resolve_branch_context(self) -> ClientContext:
                 )
 
             branch_name = config["tinybird_branch"]
+            branch_options = None
+            branch_value = config.get("branch_data_mode")
+            if branch_value and config.get("dev_mode") != "local":
+                branch_options = CreateBranchOptions(branch_data_mode=branch_value)
+
             branch = get_or_create_branch(
                 {
                     "base_url": self._config["base_url"],
                     "token": self._config["token"],
                 },
                 branch_name,
+                options=branch_options,
             )
 
             if not branch.get("token"):