PG_RECVLOGICAL(1)

📦 version 18.6, in opensuse-leap 16.0

💖 PG_RECVLOGICAL 💖

okay bestie, so you know how PostgreSQL can literally stream the changes happening in your database like it's a live feed? yeah. this is the little command-line icon that drives that. it's called pg_recvlogical and it lives in the PostgreSQL 18.6 Documentation, and no cap, it's lowkey the main character of logical decoding. 🎀

✨ NAME ✨

pg_recvlogical — control PostgreSQL logical decoding streams. that's it. that's the job. slay. 💅

🌸 SYNOPSIS 🌸

pg_recvlogical [option...]

like, you just hand it options. it does the rest. periodt. 🦋

💜 DESCRIPTION 💜

so here's the tea. pg_recvlogical does two big things: it controls logical decoding replication slots, and it streams data out of those replication slots. both. at once. versatile queen. 👑

it makes a replication-mode connection, which means it's bound by the same rules as pg_receivewal(1), plus all the extra rules that come with logical replication (peep Chapter 47 if you wanna go deep, iykyk).

here's a thing you should know fr fr: pg_recvlogical has no equivalent to the logical decoding SQL interface's peek and get modes. instead, it sends replay confirmations for data lazily as it receives it, and also on clean exit. so if you just wanna look at what's pending on a slot without eating it? use pg_logical_slot_peek_changes. don't come for pg_recvlogical's plate. 🙈

as long as no fatal errors show up, pg_recvlogical will literally just run until something kills it — specifically the SIGINT signal (that's Control+C for you and me 💀) or the SIGTERM signal.

and when pg_recvlogical catches a SIGHUP signal? it closes the current output file and opens a brand new one using the filename you gave it with the --file option. the way that works is iconic actually — you rename the current file first, then send the SIGHUP, and boom 💥: log rotation. chef's kiss. 🍓

✨ OPTIONS ✨

heads up bestie: you gotta give at least one of the action options below, or we're not going anywhere.

🎀 the actions (pick at least one, okay?)

  • --create-slot — makes a brand new logical replication slot. the name comes from --slot, the output plugin comes from --plugin, and the database comes from --dbname. for this action, --slot and --dbname are required. you can also throw in --enable-two-phase and --enable-failover here if you're feeling fancy. ✨
  • --drop-slot — yeets the replication slot named by --slot, then exits. --slot is required for this one. bye boo 👋
  • --start — begins streaming changes from the logical replication slot named by --slot, and keeps going until a signal ends it. if the server-side change stream ends because of a server shutdown or a disconnect, it'll retry in a loop — unless you passed --no-loop. --slot, --dbname and --file are all required for this action. the stream format? determined by whatever output plugin was used when the slot was created. and the connection must be to the same database that was used to create the slot. no switching up. 🚫

you can combine --create-slot and --start. but --drop-slot? that one cannot be combined with another action. it's a solo act. 🎤

💅 output location, format & other replication behavior

  • -E lsn, --endpos=lsn — in --start mode, automatically stop replication and exit with normal exit status 0 once receiving reaches the specified LSN. if you specify this while not in --start mode, an error gets raised, sorry babe. if there's a record with an LSN exactly equal to lsn, that record will be output. ⚠️ warning though: --endpos is not aware of transaction boundaries and may truncate output partway through a transaction. any partially output transaction won't be consumed and will be replayed again the next time the slot is read from. individual messages, however, are never truncated.
  • --enable-failover — enables the slot to be synchronized to the standbys. this option may only be specified with --create-slot.
  • -f filename, --file=filename — writes received and decoded transaction data into this file. use - for stdout. this parameter is required for --start.
  • -F interval_seconds, --fsync-interval=interval_seconds — 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 you flush more often. setting an interval of 0 disables issuing fsync() calls altogether — while still reporting progress to the server. in that case, data could be lost in the event of a crash. 💀
  • -I lsn, --startpos=lsn — in --start mode, start replication from the given LSN. for details on what that actually does, check Chapter 47 and Section 54.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. be chill about it. 😌
  • -n, --no-loop — when the connection to the server is lost, don't retry in a loop, just exit. no dramatic comebacks.
  • -o name[=value], --option=name[=value] — passes the option name to the output plugin, along with the option value if one is specified. which options exist and what they do depends entirely on the output plugin you're using. your plugin, your rules.
  • -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. sorry, it's already got a personality.
  • -s interval_seconds, --status-interval=interval_seconds — same effect as the option of the same name in pg_receivewal(1). go read the description over there, bestie.
  • -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. this parameter is required for any of actions.
  • -t, --enable-two-phase, --two-phase (deprecated) — enables decoding of prepared transactions. this option may only be specified with --create-slot.
  • -v, --verbose — enables verbose mode. give us the details, we love details. 🗣️

🌈 database connection parameters

  • -d dbname, --dbname=dbname — the database to connect to. check the descriptions of the actions to see what this means in detail. dbname can be a connection string. if it is, connection string parameters will override any conflicting command line options. this parameter is required for --create-slot and --start.
  • -h hostname-or-ip, --host=hostname-or-ip — 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 comes from the PGHOST environment variable if it's set — otherwise a Unix domain socket connection is attempted.
  • -p port, --port=port — the TCP port, or the local Unix domain socket file extension, that the server is listening on for connections. defaults to the PGPORT environment variable if set, or a compiled-in default.
  • -U user, --username=user — the 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 no password is available by other means — like a .pgpass file — the connection attempt will fail. super useful in batch jobs and scripts where there's nobody around to type a password. 🤖
  • -W, --password — force 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 auth. but here's the thing: without it, pg_recvlogical wastes a whole connection attempt just finding out the server wants a password. sometimes it's worth typing -W to skip that extra attempt. 💅

⭐ the extra lil options

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

🦋 EXIT STATUS 🦋

pg_recvlogical exits with status 0 when it's terminated by the SIGINT or SIGTERM signal. and bestie, that's the normal way to end it — so it is not an error, okay? don't feel bad. 💖

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. it's respectful like that. 🫶

🍓 EXAMPLES 🍓

see Section 47.1 for an example.

👑 SEE ALSO 👑

pg_receivewal(1)

and that's the whole vibe, bestie 💖 go forth and decode logically. this was the pg_recvlogical page from PostgreSQL 18.6, dated 2026 — mwah, take care of her, she's iconic. 🎀✨🦋

📦 where this page comes from