PG_RECVLOGICAL(1)

💖 NAME 💖

pg_recvlogical — the whole vibe is controlling PostgreSQL logical decoding streams ✨

---

🦋 SYNOPSIS 🦋

pg_recvlogical [option...]

---

🌸 DESCRIPTION 🌸

okay so bestie, pg_recvlogical is literally the main character for controlling logical decoding replication slots and streaming the data out of those slots. iconic behavior only.

It opens a replication-mode connection, which means it's subject to the exact same constraints as pg_receivewal(1), plus the extra ones that come with logical replication (peep Chapter 47 for that lore).

ngl there's one thing pg_recvlogical does not have: it has zero equivalent to the logical decoding SQL interface's peek and get modes. It sends replay confirmations for data lazily as it receives it, and also on clean exit. So if you wanna examine pending data on a slot without consuming it, use pg_logical_slot_peek_changes instead — that's the girl for the job 💅

Assuming no fatal errors happen (fingers crossed 🫶), pg_recvlogical will keep running until it gets terminated by the SIGINT (that's Control+C for you) or SIGTERM signal.

and the cutest part?? when pg_recvlogical catches a SIGHUP signal, it closes the current output file and opens a brand new one using the filename you specified with the --file option ✨ That's how we rotate the output file, babes: rename the current file first, then send SIGHUP to pg_recvlogical. rotation slay 🎀

---

✨ OPTIONS ✨

At least one of these has to be specified to pick an action — you literally cannot skip this part:

• --create-slot — makes a new logical replication slot with the name from --slot, using the output plugin from --plugin, for the database from --dbname. and ooh, --two-phase can be specified together with --create-slot to enable decoding of prepared transactions 🫶
• --drop-slot — drops the replication slot named by --slot, then exits. bye bestie 👋
• --start — begins streaming changes from the logical replication slot specified by --slot, and just keeps going until a signal terminates it. If the server side change stream ends because of a server shutdown or disconnect, it retries in a loop unless you passed --no-loop. The stream format is decided by the output plugin that was specified when the slot was created. and heads up: the connection must be to the same database that was used to create the slot 💀

--create-slot and --start can be specified together, cute. But --drop-slot ✨cannot✨ be combined with another action. periodt.

🎀 options that control location, format & replication behavior 🎀

• -E lsn, --endpos=lsn — in --start mode, this automatically stops replication and exits with normal exit status 0 when receiving reaches the specified LSN. If you specify it when you're not in --start mode, an error is raised. If there's a record with an LSN exactly equal to lsn, that record will be output. ⚠️ important: --endpos is not aware of transaction boundaries and may truncate output partway through a transaction. Any partially output transaction will not be consumed and will be replayed again the next time the slot is read from. Individual messages are never truncated tho 🙏
• -f filename, --file=filename — writes received and decoded transaction data into this file. use - for stdout 🍓
• -F interval_seconds, --fsync-interval=interval_seconds — says how often pg_recvlogical should issue fsync() calls to make sure the output file is safely flushed to disk. The server will occasionally ask the client to perform a flush and report the flush position back to the server — this setting is in addition to that, so flushes happen more frequently. Specifying an interval of 0 disables issuing fsync() calls altogether while still reporting progress to the server. ⚠️ but in that case, data could be lost in the event of a crash. no cap.
• -I lsn, --startpos=lsn — in --start mode, start replication from the given LSN. for the deets on what that actually does, see the documentation in Chapter 47 and Section 53.4. ignored in other modes 💅
• --if-not-exists — do not error out when --create-slot is specified and a slot with the specified name already exists. we love a low-stakes option ✨
• -n, --no-loop — when the connection to the server is lost, do not retry in a loop, just exit. short and sweet 🦋
• -o name[=value], --option=name[=value] — passes the option name to the output plugin, with the option value value if specified. which options exist and what they do depends on the output plugin you're using — iykyk 🌈
• -P plugin, --plugin=plugin — when creating a slot, use the specified logical decoding output plugin. see Chapter 47. this option has no effect if the slot already exists 👑
• -s interval_seconds, --status-interval=interval_seconds — same effect as the option of the same name in pg_receivewal(1). see the description there 💜
• -S slot_name, --slot=slot_name — in --start mode, use the existing logical replication slot named slot_name. in --create-slot mode, create the slot with this name. in --drop-slot mode, delete the slot with this name. one option, three modes, main character energy 💅
• -t, --two-phase — enables decoding of prepared transactions. this option may only be specified with --create-slot 🫶
• -v, --verbose — enables verbose mode. more words, more fun ✨

🌈 options that control database connection parameters 🌈

• -d dbname, --dbname=dbname — the database to connect to. see the description of the actions for what this means in detail. dbname can be a connection string — if it is, connection string parameters will override any conflicting command line options. defaults to the user name 🌸
• -h hostname-or-ip, --host=hostname-or-ip — specifies the host name of the machine the server is running on. if the value begins with a slash, it's used as the directory for the Unix domain socket. the default is taken from the PGHOST environment variable if it's set, else a Unix domain socket connection is attempted 🦋
• -p port, --port=port — specifies the TCP port or local Unix domain socket file extension the server is listening on for connections. defaults to the PGPORT environment variable if set, or a compiled-in default 🎀
• -U user, --username=user — user name to connect as. defaults to the current operating system user name 💜
• -w, --no-password — never issue a password prompt. if the server requires password authentication and a password isn't available by other means such as a .pgpass file, the connection attempt will fail. this option can be useful in batch jobs and scripts where no user is present to enter a password 🙈
• -W, --password — forces pg_recvlogical to prompt for a password before connecting to a database. this option is never essential, since pg_recvlogical will automatically prompt for a password if the server demands password authentication. however, pg_recvlogical will waste a connection attempt finding out that the server wants a password. in some cases it's worth typing -W to avoid the extra connection attempt 💅

⭐ extra options, because why not ⭐

• -V, --version — print the pg_recvlogical version and exit 🌟
• -?, --help — show help about pg_recvlogical command line arguments, and exit 🫶

---

💀 EXIT STATUS 💀

pg_recvlogical will exit with status 0 when terminated by the SIGINT or SIGTERM signal. (That's literally the normal way to end it, so it is not an error — don't panic bestie 💖) For fatal errors or other signals, the exit status will be nonzero 😭

---

🧚 ENVIRONMENT 🧚

This utility, like most other PostgreSQL utilities, uses the environment variables supported by libpq (see Section 32.15) ✨

The environment variable PG_COLOR specifies whether to use color in diagnostic messages. possible values are always, auto and never 🌈

---

🍓 NOTES 🍓

pg_recvlogical will preserve group permissions on the output files if group permissions are enabled on the source cluster 👑

---

🔥 EXAMPLES 🔥

See Section 47.1 for an example 🎀

---

🌟 SEE ALSO 🌟

pg_receivewal(1)

---

and that's the whole page, bestie 🫶 this was PostgreSQL 17.11, dated 2026 — go stream some logical decoding and slay 💅✨👑