PhotoStructure + SQLite = :heart:

PhotoStructure uses SQLite to store your PhotoStructure library metadata and to manage synchronization state.


SQLite is an open source, embedded, and extremely popular database engine. If PhotoStructure for Desktops used a different database engine (say, PostgreSQL), the installer would need to be 2-4x larger than it is currently (~100Mb), and memory requirements would increase as well.

SQLite + remote filesystems = :skull_and_crossbones:

One small limitation with SQLite is that its write-ahead log and shared memory file, both used to coordinate multiple concurrent processes, must be stored on a local disk.

If you store your PhotoStructure Library on a remote filesystem, like SMB (windows file sharing) or AFP, or NFS, PhotoStructure has to do some fancy footwork to make SQLite happy.

Enter forceLocalDbReplica

If PhotoStructure determines that your library is on a remote volume, or is running on Docker, or the forceLocalDbReplica setting (or PS_FORCE_LOCAL_DB_REPLICA environment variable) is true:

  1. PhotoStructure will copy your library database to a subdirectory in your cacheDir*, and

  2. use this “local db replica” as the working database.

  3. The local db replica is then periodically copied back to the remote library.

* the cacheDir defaults to /ps/tmp on Docker, ~/Library/Caches/PhotoStructure on macOS, and $LOCALAPPDATA/PhotoStructure on Windows. The subdirectory is called local-db-LIBRARYUUID. LIBRARYUUID is stored in .photostructure/.library-uid.json.

Why do I care?

If PhotoStructure doesn’t accurately determine that your volume is a remote filesystem, you may see SQLITE_READONLY or similar errors, and need to set forceLocalDbReplica=true manually.

If you’re using bi-directional backup software, you may find it easier to configure your backup software to exclude your cacheDir, and set forceLocalDbReplica=true manually to avoid sync bugs.

1 Like