Skip to content

Versioning

Bundlebase has a built-in versioning system. Every time you call commit(), a new version is created with all your changes.

Until commit() is called, any changes you have made remain in-memory and only apply to your bundle instance. To share changes, you must commit.

Committing Changes

import bundlebase as bb

bundle = await bb.create("my/data")
await bundle.attach("customers.csv")
await bundle.commit("Added customer data")

import bundlebase.sync as bb

bundle = bb.create("my/data")
bundle.attach("customers.csv")
bundle.commit("Added customer data")

COMMIT 'Added customer data'

Viewing Version and History

# Current version identifier
print(bundle.version)

# Full commit history
for entry in bundle.history():
    print(entry)

print(bundle.version)

for entry in bundle.history():
    print(entry)

SELECT * FROM bundle_info.history

or 

SHOW HISTORY

Status

View uncommitted changes in the bundle.

status = bundle.status()
print(f"Pending changes: {status.change_count}")

status = bundle.status()
print(f"Pending changes: {status.change_count}")

SELECT * FROM bundle_info.status

or

SHOW STATUS

Reset

Discard all uncommitted changes, reverting to the last committed state.

await bundle.attach("wrong_file.csv")
await bundle.reset()  # Discards the attach

bundle.attach("wrong_file.csv")
bundle.reset()  # Discards the attach

RESET

Undo

Undo the last uncommitted operation. Can be called multiple times to undo several operations, or use UNDO LAST N to undo multiple at once.

await bundle.attach("a.csv")
await bundle.attach("b.csv")
await bundle.undo()  # Undoes the attach of b.csv

bundle.attach("a.csv")
bundle.attach("b.csv")
bundle.undo()  # Undoes the attach of b.csv

UNDO
UNDO LAST 3

Verify Data

Verify the integrity of all files in the bundle by checking SHA256 hashes.

results = await bundle.verify_data()
print(results)

# Optionally update stored version metadata if hashes match
results = await bundle.verify_data(update_versions=True)

results = bundle.verify_data()
print(results)

results = bundle.verify_data(update_versions=True)

VERIFY DATA

VERIFY DATA UPDATE

Format Compatibility

Every bundle records the minimum and maximum bundlebase version required to open it. These are set automatically when a bundle is created and track the major.minor version (e.g., 0.9).

When opening a bundle:

  • If the current bundlebase version is below the bundle's minimum version, an error is returned. This means the bundle uses features that this version of bundlebase doesn't support.
  • If the current bundlebase version is above the bundle's maximum version, an error is returned with a suggestion to upgrade.

Old bundles created before version tracking was added will open without restriction.

Upgrading a Bundle

When you update bundlebase to a newer version, existing bundles may need their version range updated.

import bundlebase as bb

await bb.upgrade_bundle("/path/to/bundle")

import bundlebase.sync as bb

bb.upgrade_bundle("/path/to/bundle")

bundlebase upgrade-bundle --bundle /path/to/bundle

Use the upgrade_bundle tool with the bundle path.

This updates the bundle's min and max version to match the current bundlebase version, committing the change. The upgrade writes directly to the bundle's manifest without opening it, so it works even when the version mismatch would prevent a normal open.

Manifest System

Bundlebase uses a versioned manifest system for tracking commits:

  • Location: {data_dir}/_bundlebase/ directory
  • Format: YAML files with 5-digit version + 12-character hash
  • Example: 00001a1b2c3d4e5f6.yaml
  • Each commit can contain multiple "changes" which are the modifications to the bundle

Example commit file

author: nvoxland
message: Indexed
timestamp: 2026-01-08T07:24:18Z
changes:
  - id: 11675b7b-8aca-4187-a38d-bfda4d739e0e
    description: Attach file:///path/to/customers-0-100.csv
    operations:
      - type: definePack
        id: '56'
      - type: attachBlock
        source: file:///path/to/customers-0-100.csv
        version: 846acd3-64650a58fdd47-4308
        id: '09'
        packId: '56'