fix: Improve DBAccessError messages for permission/directory issues

[Jah-yee]

Good day!

Thank you for maintaining beets!

Summary of Changes

This PR improves the error messages in DBAccessError to help users diagnose database permission issues more easily:

1. Updated DBAccessError docstring — Now mentions directory missing and file permissions as potential causes (not just file deletion).

2. Split error handling — The combined if ... in (...) check is replaced with separate if/elif branches, each providing a distinct, actionable message:

   • unable to open database file → "Check that the parent directory exists and is writable."
   • attempt to write a readonly database → "Check file permissions: the database file or its directory may not be writable."

Issue

• Fixes Better error message when directory containing database file is not writeable #1676

Verification

• Python syntax check passes (python3 -m py_compile)
• Diff is minimal: 14 insertions, 7 deletions across 1 file
• Only beets/dbcore/db.py changed

Testing

Manual verification:

from beets.dbcore.db import DBAccessError
try:
    raise DBAccessError("attempt to write a readonly database")
except DBAccessError as e:
    print(str(e))
# -> 'attempt to write a readonly database. Check file permissions: the database file or its directory may not be writable.'

Thank you for reviewing this PR!

Warmly,
RoomWithRoof

[github-actions]

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

[snejus]

I think we already have a PR in progress that tackles this issue: #6294

[Jah-yee]

Thank you for the feedback! I've added the changelog entry for this PR.

The entry reads:

Improve DBAccessError messages to help users diagnose database permission issues more easily. The error message now mentions directory missing and file permissions as potential causes. 🐛6294

Added in commit: fad8ea6

[codecov]

Codecov Report

❌ Patch coverage is 0% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.84%. Comparing base (d2a9e83) to head (8ce49d6).
⚠️ Report is 3 commits behind head on master.

Files with missing lines	Patch %	Lines
beets/dbcore/db.py	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6579      +/-   ##
==========================================
- Coverage   71.84%   71.84%   -0.01%     
==========================================
  Files         159      159              
  Lines       20560    20562       +2     
  Branches     3259     3260       +1     
==========================================
  Hits        14772    14772              
- Misses       5100     5102       +2     
  Partials      688      688              

Files with missing lines	Coverage Δ
beets/dbcore/db.py	93.86% <0.00%> (-0.31%)	⬇️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Jah-yee]

Thanks for pointing that out! After reviewing #6294, I see it catches database permission errors at the UI layer in beets/ui/__init__.py (_open_library). This PR (#6579) improves DBAccessError at the database layer in beets/dbcore/db.py (_handle_mutate), giving better messages for permission/directory issues during DB mutations. They address different code paths and can coexist. Happy to close if you think the UI-layer fix alone is sufficient!

[snejus]

You're right, apologies for my confusion here! And thanks for your contribution!