Delegate `rusqlite::Connection` persister to transaction persister

[ValuedMammal]

Currently, the rusqlite connection persister and transaction persister are entirely different implementations, even though the connection persister just creates a new transaction, does what the transaction persister does, and then commits.

Originally posted on bitcoindevkit/bdk#1863

[evanlinjin]

@ValuedMammal could you expand on what you are proposing to be done? Thanks

[ValuedMammal]

Certainly. It would be better to delegate the implementation of WalletPersister on rusqlite::Connection to the existing implementation for rusqlite::Transaction. This does a few things: 1) Avoids code duplication, 2) Centralizes the logic, and 3) Makes maintenance easier.

You can refactor the Connection implementation to use the Transaction implementation like this:

#[cfg(feature = "rusqlite")]
impl WalletPersister for bdk_chain::rusqlite::Connection {
    type Error = bdk_chain::rusqlite::Error;

    fn initialize(persister: &mut Self) -> Result<ChangeSet, Self::Error> {
        let mut db_tx = persister.transaction()?;
        let changeset = <bdk_chain::rusqlite::Transaction as WalletPersister>::initialize(&mut db_tx)?;
        db_tx.commit()?;
        Ok(changeset)
    }

    fn persist(persister: &mut Self, changeset: &ChangeSet) -> Result<(), Self::Error> {
        let mut db_tx = persister.transaction()?;
        <bdk_chain::rusqlite::Transaction as WalletPersister>::persist(&mut db_tx, changeset)?;
        db_tx.commit()
    }
}

1. Avoid Code Duplication

Both WalletPersister implementations for Connection and Transaction were manually performing similar steps (initializing tables, reading/writing data). Duplicated code increases the risk of inconsistencies and bugs. If you need to fix a bug or update the logic, you must remember to change it everywhere it appears.

By delegating the Connection implementation to the Transaction implementation, you only have one place to maintain the core logic. This reduces the chance of errors and makes your code cleaner.

2. Centralizing the Logic

When logic is centralized, it’s easier to understand, test, and reason about. Encapsulation also makes it easier to change the implementation details without affecting code that uses it. By having the Transaction implementation as the single source of truth for SQLite operations, you encapsulate all of the details there. The Connection implementation simply delegates, so users don’t need to know or care about the details — they just use the interface.

3. Ease of Maintenance

Code that is easy to maintain saves developer time and reduces the likelihood of introducing bugs during updates. If you need to change how wallet data is persisted (e.g., add a migration, change schema, fix a bug), you only need to update the logic in one place—the Transaction implementation. All code paths that use Connection automatically benefit from the fix, making future maintenance much simpler and safer.

Summary:
Delegating the Connection implementation to the Transaction implementation makes your code DRY (Don’t Repeat Yourself), keeps the database logic in one place, and makes future changes easier and less error-prone.

---

Ok but the rusqlite Connection and Transaction types are two different things. So what is the reasoning for "delegating" the implementation of WalletPersister for one type (the connection) to the other (the transaction)?

While rusqlite::Connection and rusqlite::Transaction are distinct types, in practice, all database modifications and reads that need atomicity and consistency should happen inside a transaction. A Transaction is always created from a Connection, and it provides a safe, rollback-able context for database operations.

Delegating the WalletPersister implementation for Connection to the one for Transaction means:

Consistency:
All wallet persistence logic (table creation, reading, writing) is guaranteed to run inside a transaction, ensuring atomicity and preventing partial updates.

Reuse:
The actual logic for interacting with the database is the same, whether you start with a Connection or a Transaction. By delegating, you avoid duplicating this logic and ensure both entry points behave identically.

Ergonomics:
Users can call persistence methods on either a Connection or a Transaction, but under the hood, the logic is unified and always uses the safest approach.

Summary:
Even though the types are different, the operations you want (atomic, consistent, safe persistence) are best implemented once for Transaction, and the Connection implementation simply creates a transaction and delegates.