PGCOPYDB SNAPSHOT(1)

📦
version 0.18 · 6 versions
, in ubuntu stonking

💖 PGCOPYDB SNAPSHOT(1) 💖

okay so bestie, welcome to section 1 of the manual — this is the pgcopydb snapshot page, and it's genuinely one of my faves because it's SO straightforward. she connects, she exports, she dips. icon behaviour fr fr. ✨

🌸 NAME 🌸

pgcopydb snapshot — pgcopydb snapshot

pgcopydb snapshot — Create and export a snapshot on the source database

The way that pgcopydb snapshot works is: it connects to your source database and runs a SQL query to export a snapshot. That snapshot? It gets printed on stdout AND written into a file, because that's where the other pgcopydb commands go looking for it. no cap. 🫶

   pgcopydb snapshot: Create and export a snapshot on the source database
   usage: pgcopydb snapshot  --source ...

     --source                      Postgres URI to the source database
     --dir                         Work directory to use
     --follow                      Implement logical decoding to replay changes
     --plugin                      Output plugin to use (pgoutput, test_decoding, wal2json)
     --wal2json-numeric-as-string  Print numeric data type as string when using wal2json output plugin
     --slot-name                   Use this Postgres replication slot name

✨ OPTIONS ✨

These are the options you get with pgcopydb snapshot, and yes, I'm giving you all of them, no gatekeeping 💅

  • --source — the connection string for your source Postgres instance. peep the Postgres docs for connection strings <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING> if you want the full tea. short version: both the quoted form "host=... dbname=..." and the URI form postgres://user@host:5432/dbname are supported. pick your fighter 🎀
  • --dir — during normal operations pgcopydb creates a LOT of temporary files, because it's tracking sub-processes progress and it's lowkey a little overachiever about it. those temp files live in the directory you pick here, or they default to ${TMPDIR}/pgcopydb when the environment variable is set, or otherwise to /tmp/pgcopydb. 🧚
  • --follow — when you pass --follow, pgcopydb implements Change Data Capture as detailed in the manual page for pgcopydb follow <#id7>, running in parallel to the main copy database steps. the replication slot gets created with the Postgres replication protocol command CREATE_REPLICATION_SLOT, which then exports the snapshot being used in that command. main character energy, honestly 👑
  • --plugin — the logical decoding output plugin to use. the default is pgoutput <https://www.postgresql.org/docs/current/protocol-logical-replication.html>, which is built right into PostgreSQL core (since Postgres 10) and needs ZERO extension installation on the source server. obsessed. ✨ you can also use test_decoding <https://www.postgresql.org/docs/current/test-decoding.html> or wal2json <https://github.com/eulerto/wal2json/> — both are still supported for backwards compatibility. 🦋
  • --wal2json-numeric-as-string — when you're using the wal2json output plugin, you can pass this option to tell wal2json to output numeric values as strings, which prevents some precision loss. so important. ⭐ heads up though: you need a wal2json plugin version on the source database that supports the --numeric-data-types-as-string option to be able to use this. and see also the docs for wal2json <https://github.com/eulerto/wal2json/pull/255> about this option for the details 👀
  • --slot-name — the logical decoding slot name to use.
  • --verbose — bump up the current verbosity. default level is INFO. in ascending order, pgcopydb knows about these verbosity levels: FATAL, ERROR, WARN, INFO, NOTICE, DEBUG, TRACE. 🌈
  • --debug — set current verbosity to DEBUG level.
  • --trace — set current verbosity to TRACE level.
  • --quiet — set current verbosity to ERROR level. 🤫

🌿 ENVIRONMENT 🌿

  • PGCOPYDB_SOURCE_PGURI — connection string to the source Postgres instance. when --source is ommitted from the command line, then this environment variable is used. she's the backup plan and she delivers 💜
  • PGCOPYDB_OUTPUT_PLUGIN — logical decoding output plugin to use. when --plugin is omitted from the command line, then this environment variable is used.
  • PGCOPYDB_WAL2JSON_NUMERIC_AS_STRING — when it's true (or yes, or on, or 1 — same input as a Postgres boolean, so whatever flavour of truth you vibe with) then pgcopydb uses the wal2json option --numeric-data-types-as-string when using the wal2json output plugin. and when --wal2json-numeric-as-string is ommitted from the command line, then this environment variable is used. periodt. 💅

🎀 EXAMPLES 🎀

Create a snapshot on the source database in the background:

$ pgcopydb snapshot &
[1] 72938
17:31:52 72938 INFO  Running pgcopydb version 0.7.13.gcbf2d16.dirty from "/Users/dim/dev/PostgreSQL/pgcopydb/./src/bin/pgcopydb/pgcopydb"
17:31:52 72938 INFO  Using work dir "/var/folders/d7/zzxmgs9s16gdxxcm0hs0sssw0000gn/T//pgcopydb"
17:31:52 72938 INFO  Removing the stale pid file "/var/folders/d7/zzxmgs9s16gdxxcm0hs0sssw0000gn/T//pgcopydb/pgcopydb.aux.pid"
17:31:52 72938 INFO  Work directory "/var/folders/d7/zzxmgs9s16gdxxcm0hs0sssw0000gn/T//pgcopydb" already exists
17:31:52 72938 INFO  Exported snapshot "00000003-000CB5FE-1" from the source database
00000003-000CB5FE-1

And when the process is done, stop maintaining the snapshot in the background:

$ kill %1
17:31:56 72938 INFO  Asked to terminate, aborting
[1]+  Done                    pgcopydb snapshot

🦋 AUTHOR 🦋

Dimitri Fontaine

2022-2024, Dimitri Fontaine

okay that's the whole page bestie, you ate it up fr fr 💅✨

made with love, pgcopydb version 0.18, dated Jun 28, 2026 — that's the tea, see you in the next manpage 🫶🎀

📦 where this page comes from