Synchronous Commit
By the end of this page you will know what synchronous_commit = off trades, exactly what a crash can cost you, and how to see how many commits a server answered early.
synchronous_commit is PostgreSQL's setting, with PostgreSQL's five values and context (a user setting: any session sets it for itself). By default a commit answers the client once its record is on disk. A session that sets it off gets its answer as soon as the commit is written to the log, without waiting for the flush, which saves the flush's latency on every commit.
Examples on this page use this table:
CREATE TABLE events (id BIGINT PRIMARY KEY, payload TEXT);
The setting
SHOW synchronous_commit;
SET synchronous_commit = off;
SHOW synchronous_commit;
RESET synchronous_commit;
| Value | What a commit does on one node |
|---|---|
on (default) | Waits for its log flush. |
local | The same as on. |
remote_write | The same as on on one node. |
remote_apply | The same as on on one node. |
off | Answers before its log flush. |
On a single node there is no remote to wait for, so the four values that wait are identical. On a cluster a commit answers once its group's quorum has the vote round durable, and the read fence makes it visible to the next read, under every value but off. PostgreSQL's boolean spellings read as on and off (true, false, yes, no, 1, 0, in any case). Any other value is refused with 22023 and the list of values:
ERROR: invalid value for parameter "synchronous_commit": "maybe"
HINT: Available values: local, remote_write, remote_apply, on, off.
The setting lasts for the session, or for the transaction with SET LOCAL; RESET, RESET ALL and DISCARD ALL return it to on, and a rolled-back SET is undone.
BEGIN;
SET LOCAL synchronous_commit = off;
INSERT INTO events VALUES (1, 'this commit does not wait for the flush');
COMMIT;
SHOW synchronous_commit;
SELECT set_config('synchronous_commit', 'off', false);
INSERT INTO events VALUES (2, 'and neither does this one');
RESET synchronous_commit;
SELECT count(*) FROM events;
What a crash can cost
An early answer changes when the log is flushed, never what a read sees. The rows are visible to every session as soon as the commit answers, exactly as the same commit would be after waiting.
If the machine stops before the flush, the commits answered in that window are lost. They are lost whole: a transaction that cannot be replayed in full is dropped in full, never half of it, and the database comes back consistent. The window is one flush epoch of the log, so the most a crash loses is the last few commits of the sessions that set off; the commits of every session that did not are never in it.
The setting is the session's own. One session's off never makes another session's commit early.
Two settings with one name
[storage.wal] synchronous_commit in the config file is the server's switch for whether any commit waits. It is on by default. A session's off takes effect only while that key is on; with the key off, no commit waits, so none is early; the session still reads its value back and it changes nothing.
Counting early commits
Every commit answered before its log flush is counted once on /metrics as scramdb_async_commits_total: one autocommit statement is one commit, an explicit transaction is one commit however many statements it holds, and a rollback or a read is none. A server that never counts any has no session running with off, which is what to check before relying on the durability of a commit. See Observability.