punimtag/viewer-frontend/GRANT_PERMISSIONS.md

Granting Database Permissions

This document describes how to grant read-only permissions to the viewer_readonly user on the main punimtag database tables.

Quick Reference

✅ WORKING METHOD (tested and confirmed):

PGPASSWORD=<choose-a-password> psql -h localhost -U punimtag -d punimtag -f grant_readonly_permissions.sql

When to Run This

Run this script when you see errors like:

• permission denied for table photos
• permission denied for table people
• permission denied for table faces
• Any other "permission denied" errors when accessing database tables

This typically happens when:

• Database tables are recreated/dropped
• Database is restored from backup
• Permissions are accidentally revoked
• Setting up a new environment

Methods

Method 1: Using punimtag user (Recommended - Tested)

PGPASSWORD=<choose-a-password> psql -h localhost -U punimtag -d punimtag -f grant_readonly_permissions.sql

Method 2: Using postgres user

PGPASSWORD=postgres_password psql -h localhost -U postgres -d punimtag -f grant_readonly_permissions.sql

Method 3: Using sudo

sudo -u postgres psql -d punimtag -f grant_readonly_permissions.sql

Method 4: Manual connection

psql -U punimtag -d punimtag

Then paste these commands:

GRANT CONNECT ON DATABASE punimtag TO viewer_readonly;
GRANT USAGE ON SCHEMA public TO viewer_readonly;
GRANT SELECT ON TABLE photos TO viewer_readonly;
GRANT SELECT ON TABLE people TO viewer_readonly;
GRANT SELECT ON TABLE faces TO viewer_readonly;
GRANT SELECT ON TABLE person_encodings TO viewer_readonly;
GRANT SELECT ON TABLE tags TO viewer_readonly;
GRANT SELECT ON TABLE phototaglinkage TO viewer_readonly;
GRANT SELECT ON TABLE photo_favorites TO viewer_readonly;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO viewer_readonly;

Verification

After granting permissions, verify they work:

1. Check permissions script:

   npm run check:permissions
   

2. Check health endpoint:

   curl http://localhost:3001/api/health
   

3. Test the website:

   • Refresh the browser
   • Photos should load without permission errors
   • Search functionality should work

What Permissions Are Granted

The script grants the following permissions to viewer_readonly:

• CONNECT on database punimtag
• USAGE on schema public
• SELECT on tables:
  • photos
  • people
  • faces
  • person_encodings
  • tags
  • phototaglinkage
  • photo_favorites
• USAGE, SELECT on all sequences in schema public
• Default privileges for future tables (optional)

Notes

• Replace <choose-a-password> with the actual password for the punimtag user (found in .env file)
• The viewer_readonly user should only have SELECT permissions (read-only)
• If you need write access, use DATABASE_URL_WRITE with a different user (viewer_write)