Hi @Sega2,
I can help with this. Welcome to Lakebase branching. As the earlier reply mentioned, Lakebase branches use copy-on-write technology rather than Git-style merging, so the workflow for promoting changes is a bit different from what you might expect. Let me explain how it works and the recommended approach.
HOW LAKEBASE BRANCHING WORKS
Lakebase branches operate in a parent-child hierarchy. When you create a branch (for example, "dev" from "prod"), it inherits the schema and data from its parent but shares the underlying storage through pointers. Only the data you actually modify gets written separately, which makes branch creation instant and storage-efficient.
The important thing to understand is that changes in a child branch do not affect its parent, and changes in a parent do not automatically appear in children. This isolation is by design so you can safely experiment.
PROMOTING CHANGES FROM DEV TO PROD
Currently, Lakebase does not have a built-in "merge" or "promote" operation that pushes child branch changes up to the parent. The branch reset feature only works in one direction: parent to child (it resets the child to match the parent's current state).
To move changes from your dev branch to the prod (main) branch, the recommended approach is to use standard database migration tools to apply the same schema changes to your parent branch. The workflow looks like this:
1. Create your dev branch from the main branch
2. Develop and test your schema changes on the dev branch (for example, adding a column as you described)
3. Capture those changes as migration scripts (SQL ALTER statements, etc.)
4. Apply those same migration scripts directly against the main branch
5. Optionally delete or reset the dev branch when done
For your specific example where you added a column on the dev branch, you would run that same ALTER TABLE ... ADD COLUMN statement against your main branch connection.
RECOMMENDED MIGRATION TOOLS
Since Lakebase is PostgreSQL-compatible, you can use any standard PostgreSQL migration tool to manage and apply schema changes consistently. Popular options include:
- Flyway (https://flywaydb.org) - versioned SQL migration files
- Liquibase (https://www.liquibase.com) - XML/SQL/YAML changelog-based migrations
- Alembic (https://alembic.sqlalchemy.org) - Python-based, great if you use SQLAlchemy
- sqitch (https://sqitch.org) - dependency-aware, scriptable migrations
- pgAdmin or psql - for simple manual changes, you can run ALTER statements directly
The key idea is to write your schema changes as repeatable migration scripts. Test them on your dev branch first, then apply the same scripts to the main branch.
PRACTICAL EXAMPLE
Suppose you created a dev branch and added a column:
-- Connected to the dev branch
ALTER TABLE my_schema.my_table ADD COLUMN new_field VARCHAR(100);
After verifying everything works on dev, connect to the main branch and run:
-- Connected to the main branch
ALTER TABLE my_schema.my_table ADD COLUMN new_field VARCHAR(100);
If you are using a migration tool like Flyway, you would have a migration file like V2__add_new_field.sql containing that ALTER statement, and you would run flyway migrate against each branch's connection string.
BRANCH RESET (PARENT TO CHILD)
One more thing worth knowing: when you want to refresh your dev branch with the latest production data, you can use Branch Reset. This instantly updates the child branch to match its parent's current state using copy-on-write. You can do this from the UI by clicking the menu next to your branch name and selecting the reset option. Keep in mind that any local changes on the child branch are lost during a reset.
PROTECTING YOUR PRODUCTION BRANCH
Lakebase also supports Protected Branches, which prevent accidental changes and block deletion and reset operations on critical branches. Consider marking your main/production branch as protected to add an extra layer of safety.
KEY DOCUMENTATION
- Lakebase branching overview: https://docs.databricks.com/en/oltp/projects/branches.html
- Managing branches (create, reset, delete): https://docs.databricks.com/en/oltp/projects/manage-branches.html
- Protected branches: https://docs.databricks.com/en/oltp/projects/protected-branches.html
- Lakebase overview: https://docs.databricks.com/en/oltp/index.html
Hope this clears things up. The short answer is: write your schema changes as migration scripts, test them on the dev branch, then apply those same scripts to the main branch. Lakebase branching gives you a safe, isolated environment for development and testing, and standard database migration tooling handles the promotion step.
* This reply used an agent system I built to research and draft this response based on the wide set of documentation I have available and previous memory. I personally review the draft for any obvious issues and for monitoring system reliability and update it when I detect any drift, but there is still a small chance that something is inaccurate, especially if you are experimenting with brand new features.
