Beaver2.5.0 syalia-srl/beaver

Opening a 1.x file

Before this desk, the shop ran a small script on beaver 1.3, and its file still has the old settings and threads. Beaver 1.x named its tables beaver_dicts, beaver_lists and so on; 2.x names them __beaver_dicts__, __beaver_lists__. Here is a small file in the 1.x layout, built by hand with sqlite3 the way 1.x wrote it:

import json
import sqlite3

old = sqlite3.connect("old-desk.db")
old.execute(
    "CREATE TABLE beaver_dicts (dict_name TEXT NOT NULL, key TEXT NOT NULL,"
    " value TEXT NOT NULL, expires_at REAL, PRIMARY KEY (dict_name, key))"
)
old.execute(
    "CREATE TABLE beaver_lists (list_name TEXT NOT NULL, item_order REAL NOT NULL,"
    " item_value TEXT NOT NULL, PRIMARY KEY (list_name, item_order))"
)
old.executemany(
    "INSERT INTO beaver_dicts VALUES (?, ?, ?, NULL)",
    [
        ("__metadata__", "version", json.dumps("1.3.0")),
        ("settings", "shop", json.dumps("Spoke & Chain")),
        ("settings", "hours", json.dumps({"open": 9, "close": 18})),
    ],
)
old.executemany(
    "INSERT INTO beaver_lists VALUES (?, ?, ?)",
    [("thread:T-0042", 1.0, json.dumps("My bell is broken")), ("thread:T-0042", 2.0, json.dumps("Fixed in store"))],
)
old.commit()
old.close()

Beaver refuses it#

A 2.x reader that ignored the old tables would see an empty database, and the first write would start a new dataset beside the old one, with nothing failing. So 2.x refuses to open a 1.x file, with BeaverLegacySchemaError:

from beaver import BeaverDB, BeaverLegacySchemaError

try:
    BeaverDB("old-desk.db")
except BeaverLegacySchemaError as e:
    print(str(e).splitlines()[0])
    print(str(e).splitlines()[1])
Database 'old-desk.db' was created by beaver 1.3.0 and cannot be opened by beaver 2.x.
  legacy tables found: beaver_dicts, beaver_lists

The same holds for a file newer than the running beaver. Beaver records its schema version in SQLite's user_version, and a file written by a later, incompatible release fails with BeaverIncompatibleSchemaError, of which the legacy error is a kind:

from beaver import BeaverIncompatibleSchemaError

future = sqlite3.connect("future.db")
future.execute("PRAGMA user_version = 99")
future.close()
try:
    BeaverDB("future.db")
except BeaverIncompatibleSchemaError as e:
    print(type(e).__name__, "|", str(e).splitlines()[0])
BeaverIncompatibleSchemaError | Database user_version is 99; this beaver only understands up to 1. The database was written by a newer beaver release.

Migrating#

beaver migrate copies a 1.x file into a new 2.x file. It opens the source read-only, and never writes to it, so a failed migration leaves the original as it was. --dry-run reports what it would copy and writes nothing:

import subprocess
import sys
from pathlib import Path

beaver_cli = str(Path(sys.executable).parent / "beaver")
print(subprocess.run([beaver_cli, "migrate", "old-desk.db", "--dry-run"], capture_output=True, text=True).stdout)
source:      old-desk.db  (beaver 1.3.0)
destination: (dry run — nothing written)

dicts (1):
  settings                                               2 rows

lists (ordering regenerated REAL -> fractional index) (1):
  thread:T-0042                                          2 rows

total rows would migrate: 4

Without it, the copy goes to old-desk.db.migrated, or to --output. List positions are renumbered, because 2.x keeps them as fractional keys:

run = subprocess.run([beaver_cli, "migrate", "old-desk.db", "-o", "old-desk-2x.db"], capture_output=True, text=True)
print(run.stdout)

with BeaverDB("old-desk-2x.db") as db:
    print(db.dict("settings")["hours"], list(db.list("thread:T-0042")))
source:      old-desk.db  (beaver 1.3.0)
destination: old-desk-2x.db

dicts (1):
  settings                                               2 rows

lists (ordering regenerated REAL -> fractional index) (1):
  thread:T-0042                                          2 rows

total rows migrated: 4

The original is untouched. To adopt the migrated copy:
  mv old-desk.db old-desk.db.1x-backup
  mv old-desk-2x.db old-desk.db
Keep the backup until you have verified the migration.

{'open': 9, 'close': 18} ['My bell is broken', 'Fixed in store']

Adopting the copy is then two renames, which the command prints. If a 1.x file was already opened by an early 2.x release that did not refuse it, it holds both schemas, the old data and a new set written beside it. The report calls that a split brain and lists the rows of each side, and the migration does not merge them: deciding which side is right is for a person.

From Python#

The command is a thin layer over beaver.migrate: plan_migration(path) for the dry run, and migrate_database(source, destination), a coroutine, for the copy. Both return a MigrationReport with the counts per collection, and format_report() prints it as above.

from beaver.migrate import plan_migration

report = plan_migration("old-desk.db")
print(type(report).__name__, report.legacy_version, report.dicts, report.lists)
MigrationReport 1.3.0 {'settings': 2} {'thread:T-0042': 2}

The program#

A startup check for the desk: open the file, and if it is a 1.x one, say what to do instead of failing with a traceback.

examples/open_or_explain.py · L1–26
import sys

from beaver import BeaverDB, BeaverIncompatibleSchemaError, BeaverLegacySchemaError
from beaver.migrate import plan_migration

def open_desk(path: str) -> BeaverDB | None:
    try:
        return BeaverDB(path)
    except BeaverLegacySchemaError:
        report = plan_migration(path)
        rows = sum(report.dicts.values()) + sum(report.lists.values())
        print(f"{path} is a beaver {report.legacy_version} file with {rows} rows.")
        print(f"Run: beaver migrate {path} --output {path}.2x")
    except BeaverIncompatibleSchemaError as e:
        print(f"{path} was written by a newer beaver: {e}")
    return None

def main():
    path = sys.argv[1] if len(sys.argv) > 1 else "helpdesk.db"
    db = open_desk(path)
    if db is not None:
        with db:
            print(f"{path} is ready, {len(db.dict('settings'))} settings")

if __name__ == "__main__":
    main()
helpdesk.db is ready, 0 settings
Last updated 2026-11-10 · Edit this pageBeaver is MIT-licensed. Made by Syalia.