How Readwyn writes to a Kobo safely
Readwyn writes to a Kobo’s database only when you apply a Readwyn → Device sync, and only over USB. Device → Readwyn only reads it. For a write, it backs the database up to your Mac first, puts every change into one transaction that it checks before and after the commit, and restores the backup if the last check fails.
Plugging in a Kobo, counting the changes and building a preview never write anything. The database is opened through a connection that can’t write, and nothing changes until you click the apply button of a review, for example “Apply 7 changes”.
The rules for every write
These rules cover everything Readwyn writes to the database: highlights, notes, reading values, saved words and collections.
- Before each write, Readwyn copies
KoboReader.sqliteinto a folder on your Mac named after the time. Nothing extra lands on the Kobo. - Everything goes into one transaction. Before committing it, Readwyn reads the rows back and checks them.
- The Kobo’s database keeps recent changes in a separate
-walfile, and the Kobo expects a clean database when it leaves USB mode. So after the commit, Readwyn folds that file into the database, leaves no-walor-shmfile behind, and checks the rows a second time through a fresh connection. - If the Kobo has book files that aren’t in its database yet, it’s still adding books, and Readwyn writes nothing until it’s done. This happens straight after a send. Apply a Readwyn → Device sync then and Readwyn stops with “The Kobo is still adding books. Eject it, let it finish, and connect it again.” Device → Readwyn works as usual in the meantime.
- Readwyn reaches the database only through the mounted volume, and the Kobo leaves it alone while it’s in USB mode.
The backups are in ~/Library/Application Support/readwyn/kobo-backups/. Settings › E-readers has a “Backups” section with the note “Before every write, Readwyn saves a copy of the e-reader’s database on this Mac.” Its button, “Show backups in Finder”, opens the folder. After a write, the message at the foot of the Sync screen ends with “The device database is backed up.”
Book files and the device ID
Sending a book doesn’t touch the database at all. “Send to device” writes only the book file, and the Kobo adds the book itself when it leaves USB mode. “Remove from device” deletes nothing but the book file, so it needs no backup either.
The one other file Readwyn writes is .readwyn/device-id, which tells it which Kobo this is. It’s written at the first applied sync or send: first to a temporary file, then renamed into place and read back to check it.
Ejecting during a write
“Eject device” waits for a write to finish, for at most 30 seconds. Click it mid-write and an alert says “Readwyn is still writing to the Kobo”, with “Wait” and “Stop and eject”. “Wait” just closes the alert, while “Stop and eject” ejects as soon as the write is done. If the write ends first, the alert closes by itself.
Tested on a copy of a real Kobo
The writes were checked in a virtual machine, on a copy of a Kobo Libra Colour’s storage. A highlight with a note written from the Mac matched the form of the Kobo’s own rows, and the table grew by exactly one row. A Readwyn → Device sync wrote 15 ratings. A My Words sync added two new words and didn’t duplicate one the Kobo already had in another case. Every run of SQLite’s PRAGMA integrity_check gave ok, and no -wal or -shm file was left on the Kobo afterwards.
When your library is on another Mac
If your libraries live on another Mac, the Kobo still works with the Mac it’s plugged into. That Mac copies the files the sync needs, the other Mac runs the sync on the copy, and the changed files come back. Before it writes them, the Mac with the Kobo backs up the database and checks that it hasn’t changed since the copy was taken.