Stop timeout advice is confusing

[dchandekstark]

Please clarify the advice in the Dockerfile regarding stop timeout:

# An additional setting that is recommended for all users regardless of this
# value is the runtime "--stop-timeout" (or your orchestrator/runtime's
# equivalent) for controlling how long to wait between sending the defined
# STOPSIGNAL and sending SIGKILL (which is likely to cause data corruption).
#
# The default in most runtimes (such as Docker) is 10 seconds, and the
# documentation at https://www.postgresql.org/docs/12/server-start.html notes
# that even 90 seconds may not be long enough in many instances.

The referenced PG documentation mentions the time to become ready, not shut down. The PG shut down doc (at least for v12) doesn't mention the 90 second issue. Also, if this comment is in fact accurate/important, may I suggest putting it in the "how to use this image" doc?

[wglambert]

https://www.postgresql.org/docs/12/server-start.html#:~:text=consider%20carefully%20the%20timeout%20setting

Consider carefully the timeout setting. systemd has a default timeout of 90 seconds as of this writing and will kill a process that does not notify readiness within that time. But a PostgreSQL server that might have to perform crash recovery at startup could take much longer to become ready. The suggested value of 0 disables the timeout logic.

It's not necessarily a "90 second issue" so much as even at 90 seconds the docs say it might not be long enough. I imagine the grace period length is really just dependent on the host's environmental factors such as disk speed and amount of data in transit at the start of the signal being sent

It's talking specifically about Docker here though and how Docker has a default grace period of 10 seconds. Similar discussions #544 #184

[tianon]

I think our intention with pointing to that specific document was just as an example of a critical database operation that might take up to 90 seconds to complete (so if you tried to stop the server during that operation, it would potentially need at least that long before you kill it if you don't want to risk data loss).

There's not a really great document to link to about "smart" vs "fast" (or about shutting down the server in general), but doing Ctrl-F for "smart" on https://www.postgresql.org/docs/12/app-pg-ctl.html has a little bit.

[dchandekstark]

@tianon That's fair. Thanks for addressing my concern. Please consider adding this information to "how to use" since it seems quite relevant there? Otherwise, feel free to close this issue.

[tianon]

It's difficult to balance our limited space on the Hub description with the sheer amount of things we could document there. 😬 🙈

I'm glad we got it explained well enough for you to understand! Hopefully this thread can serve as a good reference for other folks in the future. 👍