pg_xlog_replay_resume() considered armed and dangerous

Hi,

I think it's quite confusing that a function named
pg_xlog_replay_resume() can cause a node to be promoted.

That this is happened is kind of documented in the recovery.conf section
of the manual:
"The intended use of the pause setting is to allow queries to be executed
against the database to check if this recovery target is the most
desirable point for recovery. The paused state can be resumed by using
pg_xlog_replay_resume() (see Table 9-69), which then causes recovery to
end. If this recovery target is not the desired stopping point, then
shut down the server, change the recovery target settings to a later
target and restart to continue recovery."

But it's not mentioned at all in the section about the functions:
http://www.postgresql.org/docs/devel/static/functions-admin.html#FUNCTIONS-RECOVERY-CONTROL-TABLE

Promotion only happens when a node is paused due to a recovery target
setting, and not when it's stopped due to pg_xlog_replay_pause().

I think this, at the very least, needs a big caveat in the documentation
of the resume function. But a different API would probably be
better. I'd actually argue that for now pg_xlog_replay_resume() should
refuse to work if paused due to a recovery target. Promotion should be
done via the normal promotion methods.

Greetings,

Andres Freund

-- Andres Freund                       http://www.2ndQuadrant.com/PostgreSQL Development, 24x7 Support, Training &
Services