Suggestion: Keep SQLight and "No DB True" Backwards Compatibility in Future Versions

[webboty]

Beads in version 0.49.6 is a great app.
While the switch to dolt (in v0.50+) may make sense for certain applications, i recommend to keep a backward compatibility to SQLight in future versions.

Why - it is widely supported by many OS.
It is super easy to set up and works flawless.

This makes beads a strong option in many use cases where simple beads features are an advantage.

Removing SQLight creates a setup dependency issue hell, making beads NOT the first option to choose in simple scenarios anymore.

In other words beads is LOT LESS attractive to be used without SQLight support.

[aaronaston]

Upgrading seemed to blow me up - "setup dependency issue hell"?

[dhabedank]

The biggest issue I've run into was simply that most community tools for viewing tasks in beads have become non-functional. Such is the nature of things, but it is a pain point.

Appreciate the progress being made on this project through. Quite a valuable tool. Thank you.

[iqdoctor]

Silent migration to Dolt is a pain.
Suddenly, after downloading the new version, I realized that all projects needed to be migrated immediately.

Is there an official guide for agents on how to migrate?

[iqdoctor]

Actual migration behavior (from current code)

1. Events are selected without ORDER BY.
2. Events are imported via map iteration (for issueID, events := range data.eventsMap), so insertion order is non-deterministic.
3. Migration writes one new Dolt commit at migration time (acceptable by itself).
4. issues.metadata is not included in migration SELECT/INSERT.
5. dependencies.metadata and thread_id are not included in migration SELECT/INSERT.
6. Comments are not explicitly migrated from comments table in this path (migration relies on events path).
7. Additional issue fields present in Dolt schema are not migrated in this path (closed_by_session, spec_id, wisp_type).
8. Dependencies are conditionally skipped if depends_on_id is not found in local target issues during import; this can drop valid external references.

---

upd 2026-02-26 issue #2085 fixed in PR #2125 fix(migrate): deterministic SQLite->Dolt fidelity + dependency/comment preservation

[iqdoctor]

Goal/Mission: Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

[ubuntupunk]

My two cents on the dolt upgrade. Once upon a time, there was just git, then along came beads, the git level issues tracker that was dependency aware. On its own astonishing. It worked famously with a simple sqlite db, doing one thing great, tracking issues at git level, but the developers wanted it to be something more like a memory graph, and there was this other similar project called dolt, which claims to be the git of databases (the name should be a tipoff here?), and so, the complexity grew and grew until, nothing worked anymore, I am seriously considering whether to just fork Beads in version 0.49.6 is a great app, because introducing dolt just isn't aligning with what beads is supposed to be doing, tracking issues? Its now a project that just bloats git style commands (bd commands plus dolt commands plus git commands = command hell) and provides stuff like version control for our already version controlled environment, please just ask why would we want a server running with its own git-style version control, if you're already working inside a git repo? I can't for for the life of me make head or tail of the project as it stands, with reams and reams of sloppy documentation, what are the expected use cases? its the exact opposite of do one thing well. Why it even provides support for gastown, with yet more places for the project to break? And is the long term plan to replace git? I say lets fork, at least until the objectives are clear, and yes, there are quite a few memory projects out there?

[iqdoctor]

If you look at the bd command line interface, it is very good, and well designed, fast and reliable. Hundreds of tickets in GitHub for the operational work of agents are too much, and a lightweight solution came in very handy. and beads must be compared with other issue managment systems, not from the top of version control systems. Interesting here is the synchronization of tasks in branches via jsonl.

as well as the concept itself that the list of open tasks directly depends on the brunch - not an obvious, but very interesting idea. do not link the ticket to the branch, but simply create it inside the branch and merge it with it. this is real know-how.

what code is behind it is secondary until the abstractions start leaking, see:
The Law of Leaky Abstractions by Joel

Believe Beads version 0.49.6 will remain the pinnacle of stability for a long time and sufficient for many projects.

I will try to make an effort to make the migration smoother, but for now I have returned all my projects to 0.49.6.

After all, closed and accumulated tickets are also in some way a useful knowledge base for the project.
And now dolt still leak.

[peterkc]

As active contributors working on the doctor/storage layer (PRs #2089, #2093), a few data points:

v0.56.1 addresses the "leaky abstraction" surface significantly. Embedded mode was removed entirely — beads is now server-only. This eliminates the CGO build requirement, the embedded vs server mode split, and the nil-pointer crash class reported in #2072. One mode, one code path.

The migration gaps @iqdoctor cataloged in #2085 are real. The non-deterministic event ordering and missing fields (metadata, thread_id, closed_by_session) are concrete issues worth fixing upstream.

On the "too many modes" problem — this was arguably the root cause of most issues in this thread. Embedded mode, server mode, SQLite fallback, and JSONL sync each multiplied the test matrix and made changes risky. Server-only is a better foundation going forward.

On forking v0.49.6 — this is a viable option for projects that don't need SQL queries, dependency graph analysis, or multi-agent collaboration. SQLite+JSONL was genuinely simpler and stable for straightforward issue tracking. The trade-off is real: Dolt unlocks capabilities that SQLite can't provide, but not every project needs them.

For anyone still on v0.55.4: upgrading to v0.56.1 resolves the SIGSEGV crashes (#2072), the doctor false positives (#1981), and removes the CGO dependency.

[iqdoctor]

The migration gaps @iqdoctor cataloged in #2085 are real. The non-deterministic event ordering and missing fields (metadata, thread_id, closed_by_session) are concrete issues worth fixing upstream.

And now that the Dolt storage layer is mostly stabilized in v0.56.x, and the issues of non-deterministic and incomplete migrations have been largely resolved in PR #2125 fix(migrate): deterministic SQLite->Dolt fidelity + dependency/comment preservation

It's time to expand on your statement:

The trade-off is real: Dolt unlocks capabilities that SQLite can't provide, but not every project needs them.

I'd like to discuss and understand what specific capabilities the Dolt database architecture unlocks. Please share your thoughts.

[peterkc]

@iqdoctor Great question. And it connects to @ubuntupunk's point about "why Dolt when you already have git" — so I'll address both.

The short answer: git versions files, Dolt versions rows. They're complementary, not redundant. You can't SELECT * FROM issues WHERE status='open' AND priority < 3 against a git repo without parsing files first. You can't run SQL aggregations over markdown or JSON without a query engine. Dolt gives you a relational database where every mutation is versioned — git semantics applied to structured data, not source code.

Here's what I've seen from running Dolt in production across 3 projects (1,287 issues, 42K+ trace events):

1. Concurrent multi-agent writes. This was the forcing function for me. With SQLite, concurrent agent sessions hit WAL contention — one writer blocks others. My setup runs multiple Claude Code sessions against a shared Dolt server (launchctl-managed, port 3309), and concurrent writes just work. If you're running a single agent per project, this doesn't matter.

2. Data archaeology via version history. Dolt commits every mutation, so dolt_log and dolt_diff give you "what was the state of issue X last Tuesday?" without manual snapshots. I have 97 commits in my traces DB alone. For issue tracking, this means you can trace when a status changed, who changed it, and what else changed in the same commit — useful for debugging agent behavior. Git could track a SQLite file, but diffing binary blobs gives you nothing useful.

3. SQL views over operational data. I run 4 analytical views over my traces database (event timelines, session summaries, tool call patterns, usage stats). SQLite supports views too, but Dolt's server mode means these queries don't block the agents doing writes.

4. dolt push/dolt pull for remote sync. Same semantics as git — push your issue database to a remote, pull on another machine. Not something SQLite offers natively (you'd need to ship the file and handle merge conflicts yourself).

What Dolt doesn't yet unlock (but could):

• Branch-per-feature issue isolation (Dolt supports SQL branches, beads doesn't use them yet)
• Schema diff tracking for migration auditing
• Three-way merge for conflict resolution on concurrent edits

The honest trade-off: Capabilities 1-2 matter for multi-agent/multi-session workflows. If you're running one agent on one project, v0.49.6 SQLite is genuinely simpler and sufficient. The Dolt value scales with the complexity of your agent orchestration — not every project needs a versioned relational store, but when you do, bolting it onto git+SQLite is harder than starting with Dolt.

[iqdoctor]

And finally, what does @steveyegge have to say?

[duckpuppy]

My two cents... since upgrading to beads 0.58.0 from 0.49, beads has been completely broken. No repos migrate. Dolt is running - bd dolt status shows the PID and port number, but every beads command just errors with Error: failed to open database: dolt circuit breaker is open: server appears down, failing fast (cooldown 30s). Been that way for a day now. I can't migrate and I've been searching for a way to revert to the SQLite DB backend without downgrading, but I think after a day of lost work I'll have to downgrade to get moving again.

[peterkc]

@duckpuppy The circuit breaker error has a specific fix. The breaker state lives in a file at /tmp/beads-dolt-circuit-<port>.json — once tripped, every bd invocation fails immediately for 30 seconds, then allows one probe. If that probe also fails, the cycle repeats indefinitely.

Immediate unblock:

rm /tmp/beads-dolt-circuit-*.json
bd dolt stop
bd dolt start
bd list

If bd list still fails after that, the likely cause is a port mismatch. There was a regression in DefaultConfig (fixed in PR #2313) where bd commands would try to connect on a different port than the one the server actually started on. bd dolt status checks the PID file, not the TCP socket, so it reports "running" even when the port is wrong.

To verify:

bd dolt status                          # note the port
cat .beads/metadata.json | jq .         # check dolt_server_port
lsof -i :<port> | grep dolt            # confirm something is actually listening

If the ports don't match, or nothing is listening, bd dolt stop && bd dolt start after clearing the circuit breaker file should resolve it.

On the v0.49 → v0.58 jump specifically: v0.58 removed the SQLite backend entirely. If your projects still have SQLite databases, the migration path depends on what version created them — there's a scripts/migrate-jsonl-to-dolt.sh script for pre-0.50 JSONL-only projects. For projects that were on 0.50-0.57 with SQLite, the auto-migration should have run on first command, but if the Dolt server never connected successfully, that migration never completed.

Running bd doctor --fix after the server is confirmed up would be the next diagnostic step — it handles fresh-clone scenarios and version mismatches.

[duckpuppy]

bd dolt test, bd dolt status and bd dolt show all reported positive results. The ports matched, and deleting the circuit breaker file didn't fix anything. It just kept giving me the circuit breaker error. I've gone back to 0.49.6. 0.58.0 had performed a partial migration which caused DB issues, so I ended up doing a fresh bd init from scratch again in the project I was working on - but things are working again. Maybe I'll try to upgrade again when things are more stable.

[webboty]

FYI ... steve has decided to not support the old model (SQLight) anymore and focuses on the DOLT version.
Dolt is superior in terms of functionality.

Complexity and overhead would be to big for 2 different concepts.

As on my own part I will be using beads with dolt every now and then.

But for simpler solutions I will switch to another FORK of beads maintained by another gentleman:
https://github.com/Dicklesworthstone/beads_rust

Alternatively we just maintain the 0.49 version in a own fork ourself.

[peterkc]

Working on an extensible fork. Will share soon. 😉

[nmelo]

Late to this thread but relevant data point: I maintain Beadbox, a native desktop GUI for beads. We went through the same Dolt transition and survived it because we wrap the bd CLI for all data access rather than reading SQLite or JSONL directly. When Dolt landed, nothing broke on our side.

If you're looking for a working GUI with current beads (v0.57+): real-time sync, epic trees, dependency visualization, multi-workspace. Runs on macOS, Linux, and Windows.

brew tap beadbox/cask && brew install --cask beadbox or grab the binary at beadbox.app

[w3dev33]

For those sticking with bd 0.49.x (SQLite) — which as several people noted here is genuinely stable and sufficient for straightforward issue tracking — there's a lightweight Tauri desktop GUI available:

Beads Task-Issue Tracker — wraps the bd CLI, provides a dashboard with filtering/sorting, issue details, comments, dependency visualization, and real-time file watching. Runs on macOS (DMG) and Linux.

Compatible with both bd 0.49.x and beads_rust (br).

It won't solve the Dolt migration debate, but if 0.49.6 or br does what you need and you want a GUI on top of it, it's there.

[iqdoctor]

See: Beads v0.62.0 — Standalone & The Road to 1.0 #2757
Release: https://github.com/gastownhall/beads/releases

We're actively targeting Beads v1.0.0. The gate is embedded Dolt — running Dolt in-process without a separate server. This matters because standalone users should get a zero-config experience: bd init, bd create, done. No server to manage.

[iqdoctor]

See: Beads feels painful to use #2938

My note in #2938:

Beads 0.49.6 is the pinnacle of system stability evolution.

And I'm still waiting for version 1.X.6, where no new features are added, and existing ones are only stabilized over several consecutive patches.

Even though I made a modest contribution to stabilizing the SQLite => Dolt migration process, in:

fix(migrate): deterministic SQLite->Dolt fidelity + dependency/comment preservation #2125

I still don't risk migrating my production projects to the Dolt version.

Collaborator @maphew Responce:

Ensure upgradeability across beads releases #3061

[iqdoctor]

Ensure upgradeability across beads releases #3061

Who is brave enough to migrate their production to the latest beads?