lightninglabs / lightninglabs/lndinit

migrate-db writes irreversible tombstones without verifying target backend support

Open
#81 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
37
Forks
18
Avg merge
1h 30m
Merged PRs (30d)
1

Description

**Description:**

`lndinit migrate-db` writes tombstone markers inside the source bbolt database files upon successful migration. These tombstones are permanent and cause LND to refuse to open the bbolt files with:

```
refusing to use db, it was marked with a tombstone after successful data migration
```

The problem: `lndinit` does not verify that the target LND binary actually supports the destination backend before writing these tombstones. If the LND binary was not compiled with the required build tag (e.g. `kvdb_sqlite`), the migration completes successfully but LND fails on startup with:

```
error opening sqlite graph DB: unknown database type
```

At this point the user is stuck. The sqlite files exist but LND can't use them. The bbolt files are tombstoned and LND refuses to open them. The only recovery path is restoring from a pre-migration backup. If no backup exists, the node's channel state is irrecoverably lost.

**What happened**

1. Ran `lndinit migrate-db` from bbolt to sqlite on a BTCPay Server LND node (v0.19.3-beta)
2. All five databases migrated and verified successfully (channeldb, macaroondb, decayedlogdb, walletdb, neutrinodb)
3. `lndinit` wrote tombstones into each bbolt file
4. LND failed on startup because the BTCPay LND image isn't compiled with `kvdb_sqlite`
5. LND also refused to fall back to bbolt because of the tombstones
6. Had to restore all bbolt files from a manual backup made before migration

**What should happen instead**

Any of the following would prevent data loss:

1. **Pre-flight check:** Before migrating, verify the target LND binary supports the destination backend. Fail early with a clear error if it doesn't.
2. **Revert command:** Provide `lndinit migrate-db --remove-tombstone` or `lndinit migrate-db --revert` to strip tombstones from bbolt files and restore them to a usable state.
3. **Deferred tombstone:** Don't write tombstones immediately. Instead, provide a separate `lndinit migrate-db --finalize` command that writes tombstones only after the user confirms LND started successfully on the new backend.
4. **At minimum:** Print a loud warning before writing tombstones that this operation is irreversible and the user should have a backup.

**Environment**

- lndinit: v0.1.33-beta (linux-arm64)
- LND: v0.19.3-beta (BTCPay Server Docker image, missing `kvdb_sqlite` build tag)
- Platform: Raspberry Pi 5
- Active Lightning channel with real funds at risk

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the lndinit migrate-db command and trace how destination-backend support is checked and how tombstones are written to the source bbolt files. Determine which recovery or pre-flight behavior is selected, then verify that an unsupported target cannot leave the source unusable and that the migration path reports a clear result.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, databases
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.