VB-Toml to DB migration: sync toml to DB as first step by Byron · Pull Request #12263 · gitbutlerapp/gitbutler

Byron · 2026-02-06T19:50:34Z

Sync the vb.toml file to its equivalent database representation.

Goals

backward compatibility - we keep writing the toml file, but don't read from it.
DB-backed versions of RefMetadata and VirtualBranchesHandle
Update call-sites with new types, they shouldn't notice a difference and it can be done incrementally.

Tasks

but-db
- needs savepoint to align multiple queries to different tables (or do it all in one query
- docs
but-meta
- RefMetadata uses DB version of toml snapshot
~~VirtualBranchesHandle uses DB~~ - no, it keeps using vb.toml file and but-meta is expected to auto-sync it anyway. Then the next step is to remove VirtualBranchesHandle usage from the codebase.
Plan
test GUI by hand - all fine and I saw the database sync the data correctly.

Follow-ups

remove VirtualBranchesHandle usages
make db.meta() possible, and write the database after each change. Sync the toml file on drop only, knowing well that this may write data that is going to be rolled back, and only for backward compatbility
make the cut: migrate data to clean data model and use that directly instead, cut backwards compatibility

Prompts

Look at #12263 and figure out how to best approach this transformation. The database schema of the virtual branches toml data should be human-editable, so ideally splits the data up into columns of multiple tables with foreign key connections.
Also make sure it's backwards compatible, so the virtual-branches.toml file needs to still be written and exists. If it changes and is more recent than what's in the database, the database value should be overwritten with it.

vercel · 2026-02-06T19:50:43Z

@Byron is attempting to deploy a commit to the GitButler Team on Vercel.

A member of the Team first needs to authorize it.

vercel · 2026-02-24T15:18:43Z

Deployment failed with the following error:

Creating the Deployment Timed Out.

Copilot

Pull request overview

This PR implements the first step of migrating from TOML-based virtual branches metadata to a database-backed approach. The core change synchronizes .git/gitbutler/virtual-branches.toml with an equivalent SQLite database representation while maintaining backward compatibility by continuing to write the TOML file.

Changes:

Added normalized database schema for virtual branches metadata (vb_state, vb_stacks, vb_stack_heads, vb_branch_targets tables)
Implemented bidirectional TOML↔DB synchronization with mtime+SHA256 conflict detection
Updated VirtualBranchesHandle to transparently use DB with TOML mirroring for backward compatibility

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
etc/plans/consistent-data.md	Comprehensive plan document outlining data consistency migration strategy
crates/but-db/src/table/virtual_branches.rs	New normalized database schema with savepoint-based mutation API
crates/but-db/src/table/mod.rs	Registered virtual_branches module
crates/but-db/src/lib.rs	Exported VirtualBranches types and added migration, enforced documentation
crates/but-db/src/migration.rs	Enabled foreign key enforcement in improve_concurrency
crates/but-db/src/poll.rs	Added documentation to poll types
crates/but-db/tests/db/table/virtual_branches.rs	Comprehensive tests for VB snapshot operations and FK cascades
crates/but-db/tests/db/table/mod.rs	Added virtual_branches test module
crates/but-db/tests/db/migration.rs	Updated expected schema to include VB tables
crates/but-db/tests/db/transaction.rs	Added savepoint isolation test demonstrating consistent multi-table reads
crates/but-meta/src/legacy/storage.rs	Core TOML↔DB synchronization logic with conflict resolution
crates/but-meta/src/legacy/mod.rs	Refactored to use storage module for read/write operations
crates/but-meta/src/lib.rs	Exported legacy_storage module
crates/but-meta/Cargo.toml	Added but-db, but-fs, and sha2 dependencies
crates/but-meta/tests/meta/ref_metadata_legacy.rs	Updated tests to reflect TOML mirror behavior (no longer deleted)
crates/gitbutler-stack/src/state.rs	Updated VirtualBranchesHandle to use synchronized storage
crates/gitbutler-stack/Cargo.toml	Removed but-fs dependency (moved to but-meta)
crates/gitbutler-stack/tests/mod.rs	Extensive sync behavior tests (bootstrap, recreation, newer TOML, invalid TOML, restore)
crates/gitbutler-oplog/src/oplog.rs	Added import_toml_into_db_for_restore call for oplog snapshot restoration
crates/but-db/src/table/*.rs	Added #![allow(missing_docs)] to existing table modules for consistency
Cargo.lock	Updated dependencies

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 25ab4440e0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

The idea is that we are encouraged to write docs, without being forced if it's "too obvious" what's happening.

…l` file. It also keeps track of enough state to know if the snapshot is uptodate with the vb.toml file so it can be resynced at will. Co-authored-by: Sebastian Thiel <sebastian.thiel@icloud.com>

It will be used to track tasks relates to the transition towards data-consistency, probably maintained by an agent. Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 28 out of 29 changed files in this pull request and generated 3 comments.

The source of truth is the database at least for `but-meta`, but it makes sure that the toml file stays in sync with the database and vice-versa. Adapt `but-oplog` and `VirtualBranchesHandle` to deal with database mirror correctly. Removed `toml_file_is_dirty` flag as it didn't seem useful. Co-authored-by: Sebastian Thiel <sebastian.thiel@icloud.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 40147d6a24

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Copilot reviewed 28 out of 29 changed files in this pull request and generated 1 comment.

Byron mentioned this pull request Feb 6, 2026

Takeout our skeletons for better vibes #12075

Closed

5 tasks

Byron mentioned this pull request Feb 16, 2026

Gitlab: Auto-discover and adopt MRs created on Gitlab #12341

Open

Byron force-pushed the next2 branch from da8cc87 to 7cee592 Compare February 20, 2026 11:13

github-actions Bot added the rust Pull requests that update Rust code label Feb 20, 2026

Byron force-pushed the next2 branch 6 times, most recently from e50df01 to 784c8f5 Compare February 24, 2026 14:50

Byron force-pushed the next2 branch 5 times, most recently from 78829a6 to 51b4043 Compare February 25, 2026 11:39

Byron changed the title ~~VB-Toml to DB migration~~ VB-Toml to DB migration: sync toml to DB as first step Feb 25, 2026

Byron force-pushed the next2 branch 3 times, most recently from 81721a1 to 25ab444 Compare February 25, 2026 12:33

Byron marked this pull request as ready for review February 25, 2026 12:34

Byron requested a review from krlvi as a code owner February 25, 2026 12:34

Copilot AI review requested due to automatic review settings February 25, 2026 12:34

Byron requested a review from Caleb-T-Owens as a code owner February 25, 2026 12:34

Copilot started reviewing on behalf of Byron February 25, 2026 12:34 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Feb 25, 2026

View reviewed changes

Comment thread crates/but-meta/src/legacy/storage.rs Outdated

Byron force-pushed the next2 branch from 25ab444 to 7c8a136 Compare February 25, 2026 13:28

Deny missing docs in but-db, but bail out as needed.

7a6220c

The idea is that we are encouraged to write docs, without being forced if it's "too obvious" what's happening.

chatgpt-codex-connector Bot and others added 2 commits February 25, 2026 15:32

Add but-db::virtual_branches() to capture full snapshots of a `vb.tom…

ee1b20d

…l` file. It also keeps track of enough state to know if the snapshot is uptodate with the vb.toml file so it can be resynced at will. Co-authored-by: Sebastian Thiel <sebastian.thiel@icloud.com>

Add plan about data consistency

c4a0e9e

It will be used to track tasks relates to the transition towards data-consistency, probably maintained by an agent. Co-authored-by: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 25, 2026 14:32

Byron force-pushed the next2 branch from 7c8a136 to 4f807ca Compare February 25, 2026 14:32

Copilot started reviewing on behalf of Byron February 25, 2026 14:33 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

Comment thread crates/but-meta/src/legacy/storage.rs

Comment thread crates/but-meta/src/legacy/storage.rs Outdated

Comment thread crates/but-meta/src/legacy/storage.rs Outdated

Byron force-pushed the next2 branch from 4f807ca to 40147d6 Compare February 25, 2026 15:09

Byron marked this pull request as draft February 26, 2026 06:19

Byron marked this pull request as ready for review February 26, 2026 10:04

Copilot AI review requested due to automatic review settings February 26, 2026 10:04

Copilot started reviewing on behalf of Byron February 26, 2026 10:06 View session

Byron enabled auto-merge February 26, 2026 10:09

chatgpt-codex-connector Bot reviewed Feb 26, 2026

View reviewed changes

Comment thread crates/but-meta/src/legacy/storage.rs

Comment thread crates/but-meta/src/legacy/storage.rs

Copilot AI reviewed Feb 26, 2026

View reviewed changes

Comment thread crates/but-meta/src/legacy/storage.rs

krlvi approved these changes Feb 26, 2026

View reviewed changes

Byron merged commit 1165d88 into gitbutlerapp:master Feb 26, 2026
40 of 41 checks passed

Byron mentioned this pull request Feb 27, 2026

Defer DB deserialization until after TOML freshness decision #12619

Merged

Conversation

Byron commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Goals

Tasks

Follow-ups

Prompts

Uh oh!

vercel Bot commented Feb 6, 2026

Uh oh!

vercel Bot commented Feb 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Byron commented Feb 6, 2026 •

edited

Loading