Mason's additions to the documentation and error handling

Author: danolivo

docs/managing/read_only.md

@@ -1,48 +1,82 @@
 # Using Spock in Read-Only Mode
 
-Spock supports operating a cluster in read-only mode.  Read-only status is managed using a GUC (Grand Unified Configuration) parameter named `spock.readonly`. This parameter can be set to enable or disable the read-only mode. Read-only mode restricts non-superusers to read-only operations, while superusers can still perform both read and write operations regardless of the setting.
+Spock supports operating a node in read-only mode. Read-only status is managed using a GUC parameter named `spock.readonly`, which can be set to one of three values:
 
-The flag is at cluster level: either all databases are read-only or all databases
-are read-write (the usual setting).
+| Value   | Description |
+|---------|-------------|
+| `off`   | No restrictions. All users may write. This is the default. |
+| `local` | Non-superuser local sessions are read-only. Replicated writes from apply workers are still permitted, so inbound replication continues normally. Superusers may still perform write operations. (The legacy alias `user` is accepted for backward compatibility.) |
+| `all`   | Non-superuser local sessions and apply workers are blocked from writing. Superusers may still perform write operations. Use this mode when you need to stop both local application writes and inbound replication. |
 
-Read-only mode is implemented by filtering SQL statements:
+The setting is at cluster level: either all databases are read-only or all
+databases are read-write (the usual setting).
 
-- `SELECT` statements are allowed if they don't call functions that write.
-- DML (`INSERT`, `UPDATE`, `DELETE`) and DDL statements including `TRUNCATE` are forbidden entirely.
-- DCL statements `GRANT` and `REVOKE` are also forbidden.
+Read-only mode is enforced by setting PostgreSQL's `transaction_read_only` flag for affected sessions. This means that any statement that would modify data — including DML (`INSERT`, `UPDATE`, `DELETE`), DDL, `TRUNCATE`, and DCL (`GRANT`, `REVOKE`) — will be rejected by PostgreSQL's standard read-only transaction checks.
 
-This means that the databases are in read-only mode at SQL level: however, the
-checkpointer, background writer, walwriter, and the autovacuum launcher are still
-running. This means that the database files are not read-only and that in some
-cases the database may still write to disk.
+The databases are in read-only mode at the SQL level: however, the checkpointer,
+background writer, walwriter, and the autovacuum launcher are still running. This
+means that the database files are not read-only and that in some cases the
+database may still write to disk.
 
 ## Setting Read-Only Mode
 
-You can control read-only mode with the Spock parameter `spock.readonly`; only a superuser can modify this setting. When the cluster is set to read-only mode, non-superusers will be restricted to read-only operations, while superusers will still be able to perform read and write operations regardless of the setting.
-
-This value can be changed using the `ALTER SYSTEM` command.
+Only a superuser can modify the `spock.readonly` parameter. The value can be changed using the `ALTER SYSTEM` command:
 
 ```sql
-ALTER SYSTEM SET spock.readonly = 'on';
+-- Block non-superuser local writes; inbound replication continues
+ALTER SYSTEM SET spock.readonly = 'local';
+SELECT pg_reload_conf();
+
+-- Block all non-superuser writes including replication
+ALTER SYSTEM SET spock.readonly = 'all';
+SELECT pg_reload_conf();
+
+-- Restore normal operation
+ALTER SYSTEM SET spock.readonly = 'off';
 SELECT pg_reload_conf();
 ```
 
-To set the cluster to read-only mode for a session, use the `SET` command. Here are the steps:
+To set the mode for the current session only:
 
 ```sql
-SET spock.readonly TO on;
+SET spock.readonly TO local;
 ```
 
-To query the current status of the cluster, you can use the following SQL command:
+To query the current status:
 
 ```sql
 SHOW spock.readonly;
 ```
 
-This command will return on if the cluster is in read-only mode and off if it is not.
+## Superuser writes and outbound replication
+
+In both `local` and `all` modes, superusers are exempt from the read-only
+restriction and may perform write operations. **The readonly setting has no
+effect on the walsender (outbound replication).** Any writes made by a
+superuser are captured in WAL and will be replicated outbound to other nodes
+in the cluster, regardless of the readonly mode.
+
+To perform repair operations that should **not** replicate to other nodes, use
+[`spock.repair_mode()`](../spock_functions/index.md) to suppress outbound
+replication of DML/DDL statements:
+
+```sql
+BEGIN;
+SELECT spock.repair_mode(true);
+
+-- Perform repair DML/DDL here...
+
+SELECT spock.repair_mode(false);
+COMMIT;
+```
+
+## Behavior of `all` mode
+
+In `all` mode, apply workers detect the setting and stop consuming inbound WAL.
+When the mode is switched back to `off` or `local`, replication resumes from
+where it left off — no data is lost.
 
 Notes:
  - Only superusers can set and unset the `spock.readonly` parameter.
- - When the cluster is in read-only mode, only non-superusers are restricted to read-only operations. Superusers can continue to perform both read and write operations.
- - By using a GUC parameter, you can easily manage the cluster's read-only status through standard PostgreSQL configuration mechanisms.
+ - By using a GUC parameter, you can easily manage the node's read-only status through standard PostgreSQL configuration mechanisms.
 

src/spock_apply.c

@@ -2434,7 +2434,7 @@ replication_handler(StringInfo s)
 	char		action = pq_getmsgbyte(s);
 
 	if (spock_readonly == READONLY_ALL)
-		elog(PANIC, "SPOCK %s: cluster is in read-only mode, not performing replication",
+		elog(FATAL, "SPOCK %s: cluster is in read-only mode, not performing replication",
 			 MySubscription->name);
 
 	memset(&errcallback_arg, 0, sizeof(struct ActionErrCallbackArg));