How to Restore Lost Contacts from a LineageOS Phone

One day I ran my phone's battery down all the way to 0%, until it switched itself off. When I rebooted, of my hundreds of contacts only about a dozen were left (those stored on the SIM card I suspect).
Of course my last backup was way too old, and I don't have any online accounts either.
Ouch.
But somehow I couldn't quite believe they were just gone. So I started scouring the web for advice, and this is what I found (after filtering out all the bullshit advertisment for spyware apps that magically fix your phone):

  1. adb must be functional on your computer and enabled on your phone (Settings => System => Developer Options (possibly you need to enable those first) => Android Debugging)
  2. If not stated otherwise, everything happens on your computer's command prompt a.k.a. terminal from now on. I am assuming a Linux machine; if you use something else, please figure out how to adapt the commands. adb is definitely available for all major platforms.
    It is best to create a dedicated directory first and change into that.
  3. Run adb root - this will put the adb daemon in automatic root mode. On the Android device we need to be root all the time for this.
  4. Run adb shell find / -iname '*contact*' -o -iname '*.vcf' 2>/dev/null
  5. Save the output; maybe copy-paste it to a file; of course Linux users will know how to change the previous command to save everything to a file directly ;-)
  6. Now comes the tricky bit: we need to pull the files that interest us, but adb pull does not extract the full path and will happily overwrite existing files. There's different ways to tackle this, but for me this was the quickest: go through the output manually and adb pull the directories or single files that might be of interest: mostly those that end in .db and .vcf. Check before and after every pull that nothing gets overwritten. If it would, it's possible to pull to a different filename, e.g.:
    adb pull /mnt/runtime/read/emulated/0/00002.vcf 00002-copy.vcf
  7. If you found a .vcf file that contains your lost contacts you're almost there and can skip the next step (unlikely because AFAIK Android/LineageOS does not store contacts in this format).
  8. If you found a contacts2.db that contains your lost contacts it's probably best to convert it to .vcf with this script (still works on LineageOS 15.1 / Android 8.1.0).
  9. Now just move the file back to your phone's storage, go to your Contacts app and "Import contacts from .vcf file".
  10. You can also look at contacts2.db with one of many applications on your computer or your phone, e.g. SQLiteViewer.

This happened on a Oneplus 3 (A3003) running LineageOS 15.1-20190222-NIGHTLY-oneplus3 / Android 8.1.0

Lesson learned: Take automated backups for your phone, too!