--- a/database/init/users.sql	Sun Apr 10 17:41:24 2022 -0400
+++ b/database/init/users.sql	Sun Apr 10 19:36:29 2022 -0400
@@ -1,14 +1,55 @@
 -- Database user initialization.
 -- Needs to be done as database superuser.
 --
--- The users:
---    swallowtail_admin: owns the database tables
---    swallowtail_writer: has write access
---    swallowtail: has readonly access to everything
+-- We create the following database-level users:
+--    swallowtail_owner: owns the database tables
+--    swallowtail_admin: used by administrator scripts
+--    swallowtail_writer: has write access for ordinary operations
+--    swallowtail_reader: has readonly access to everything
 --    swallowtail_public: cannot see confidential PRs
+--    swallowtail_uops: has access to the Swallowtail user table
+--
+-- These are intended to be accessed by Unix-level users as follows:
+--    swallowtail_owner: Swallowtail-level core administrators
+--    swallowtail_admin: Swallowtail-level administrators
+--    swallowtail_writer: all developers (used by edit-pr and browse-pr)
+--    swallowtail_reader: all developers (used by query-pr)
+--    swallowtail_public: the web server interface (used by query-pr)
+--    swallowtail_uops: the logged-in web server interface
+--
+-- The following principles underlie this:
+--
+-- 1. All the database tables are created by and owned by
+-- swallowtail_owner; for safety, nothing routine connects as this
+-- database user. Administrators may connect by hand to fix the
+-- database if it breaks, or to apply schema changes for Swallowtail
+-- updates, or to adjust the configuration tables, or for other
+-- similar purposes.
+--
+-- 2. The tables behind administrative functions are only accessible
+-- to the swallowtail_admin user. This is more to prevent accidents
+-- than because developers with access to the other users are
+-- distrusted.
+--
+-- 3. All developers have full write access to all bugs via edit-pr,
+-- which connects as the swallowtail_writer user. We don't make a
+-- separate database user for every developer/Unix user because that's
+-- pointless. We trust developers not to trash the database on
+-- purpose.
+--
+-- 4. The query-pr script connects as the swallowtail_reader user,
+-- which has no write access to anything. This is to prevent accidents.
+-- It is thus theoretically possible to grant some Unix users read but
+-- not write access, but I hope we never have to do that.
+--
+-- 5. When running via the web interface (and passed the --paranoid
+-- option), query-pr connects as the swallowtail_public user. This
+-- prevents it (via restricted views) from seeing confidential PRs.
 --
 
+create user swallowtail_owner;
 create user swallowtail_admin;
 create user swallowtail_writer;
-create user swallowtail;
+create user swallowtail_reader;
 create user swallowtail_public;
+create user swallowtail_uops;