4 * Copyright (c) 2010-2025, PostgreSQL Global Development Group
5 * src/bin/pg_upgrade/pg_upgrade.h
16/* For now, pg_upgrade does not use common/logging.c; use our own pg_fatal */
19/* Use port in the private/dynamic port number range */
20 #define DEF_PGUPORT 50432
22 #define MAX_STRING 1024
23 #define QUERY_ALLOC 8192
25 #define MESSAGE_WIDTH 62
27 #define GET_MAJOR_VERSION(v) ((v) / 100)
29/* contains both global db information and CREATE DATABASE commands */
30 #define GLOBALS_DUMP_FILE "pg_upgrade_dump_globals.sql"
31 #define DB_DUMP_FILE_MASK "pg_upgrade_dump_%u.custom"
34 * Base directories that include all the files generated internally, from the
35 * root path of the new cluster. The paths are dynamically built as of
36 * BASE_OUTPUTDIR/$timestamp/{LOG_OUTPUTDIR,DUMP_OUTPUTDIR} to ensure their
37 * uniqueness in each run.
39 #define BASE_OUTPUTDIR "pg_upgrade_output.d"
40 #define LOG_OUTPUTDIR "log"
41 #define DUMP_OUTPUTDIR "dump"
43 #define DB_DUMP_LOG_FILE_MASK "pg_upgrade_dump_%u.log"
44 #define SERVER_LOG_FILE "pg_upgrade_server.log"
45 #define UTILITY_LOG_FILE "pg_upgrade_utility.log"
46 #define INTERNAL_LOG_FILE "pg_upgrade_internal.log"
51 * WIN32 files do not accept writes from multiple processes
53 * On Win32, we can't send both pg_upgrade output and command output to the
54 * same file because we get the error: "The process cannot access the file
55 * because it is being used by another process." so send the pg_ctl
56 * command-line output to a new file, rather than into the server log file.
57 * Ideally we could use UTILITY_LOG_FILE for this, but some Windows platforms
58 * keep the pg_ctl output file open by the running postmaster, even after
61 * We could use the Windows pgwin32_open() flags to allow shared file
62 * writes but is unclear how all other tools would use those flags, so
63 * we just avoid it and log a little differently on Windows; we adjust
64 * the error message appropriately.
67 #define SERVER_START_LOG_FILE SERVER_LOG_FILE
68 #define SERVER_STOP_LOG_FILE SERVER_LOG_FILE
70#define SERVER_START_LOG_FILE "pg_upgrade_server_start.log"
72 * "pg_ctl start" keeps SERVER_START_LOG_FILE and SERVER_LOG_FILE open
73 * while the server is running, so we use UTILITY_LOG_FILE for "pg_ctl
76#define SERVER_STOP_LOG_FILE UTILITY_LOG_FILE
81 #define pg_mv_file rename
82 #define PATH_SEPARATOR '/'
83 #define PATH_QUOTE '\''
84 #define RM_CMD "rm -f"
85 #define RMDIR_CMD "rm -rf"
86 #define SCRIPT_PREFIX "./"
87 #define SCRIPT_EXT "sh"
88 #define ECHO_QUOTE "'"
91#define pg_mv_file pgrename
92#define PATH_SEPARATOR '\\'
94/* @ prefix disables command echo in .bat files */
95#define RM_CMD "@DEL /q"
96#define RMDIR_CMD "@RMDIR /s/q"
97#define SCRIPT_PREFIX ""
98#define SCRIPT_EXT "bat"
100#define ECHO_BLANK "."
105 * The format of visibility map was changed with this 9.6 commit.
107 #define VISIBILITY_MAP_FROZEN_BIT_CAT_VER 201603011
110 * pg_multixact format changed in 9.3 commit 0ac5ad5134f2769ccbaefec73844f85,
111 * ("Improve concurrency of foreign key locking") which also updated catalog
112 * version to this value. pg_upgrade behavior depends on whether old and new
113 * server versions are both newer than this, or only the new one is.
115 #define MULTIXACT_FORMATCHANGE_CAT_VER 201301231
118 * large object chunk size added to pg_controldata,
119 * commit 5f93c37805e7485488480916b4585e098d3cc883
121 #define LARGE_OBJECT_SIZE_PG_CONTROL_VER 942
124 * change in JSONB format during 9.4 beta
126 #define JSONB_FORMAT_CHANGE_CAT_VER 201409291
129 * The control file was changed to have the default char signedness,
130 * commit 44fe30fdab6746a287163e7cc093fd36cda8eb92
132 #define DEFAULT_CHAR_SIGNEDNESS_CAT_VER 202502212
135 * Each relation is represented by a relinfo structure.
139 /* Can't use NAMEDATALEN; not guaranteed to be same on client */
140 char *nspname; /* namespace name */
141 char *relname; /* relation name */
142 Oid reloid; /* relation OID */
143 RelFileNumber relfilenumber; /* relation file number */
144 Oid indtable; /* if index, OID of its table, else 0 */
145 Oid toastheap; /* if toast table, OID of base table, else 0 */
146 char *tablespace; /* tablespace path; "" for cluster default */
147 bool nsp_alloc; /* should nspname be freed? */
148 bool tblsp_alloc; /* should tablespace be freed? */
158 * Structure to store logical replication slot information.
162 char *slotname; /* slot name */
163 char *plugin; /* plugin */
164 bool two_phase; /* can the slot decode 2PC? */
165 bool caught_up; /* has the slot caught up to latest changes? */
166 bool invalid; /* if true, the slot is unusable */
167 bool failover; /* is the slot designated to be synced to the
168 * physical standby? */
173 int nslots; /* number of logical slot infos */
174 LogicalSlotInfo *slots; /* array of logical slot infos */
178 * The following structure represents a relation mapping.
182 const char *old_tablespace;
183 const char *new_tablespace;
184 const char *old_tablespace_suffix;
185 const char *new_tablespace_suffix;
187 RelFileNumber relfilenumber;
188 /* the rest are used only for logging and error reporting */
189 char *nspname; /* namespaces */
194 * Structure to store database information
198 Oid db_oid; /* oid of the database */
199 char *db_name; /* database name */
200 char db_tablespace[MAXPGPATH]; /* database default tablespace
202 RelInfoArr rel_arr; /* array of all user relinfos */
203 LogicalSlotInfoArr slot_arr; /* array of all LogicalSlotInfo */
207 * Locale information about a database.
213 char db_collprovider;
220 DbInfo *dbs; /* array of db infos */
221 int ndbs; /* number of db infos */
225 * The following structure is used to hold pg_control information.
226 * Rather than using the backend's control structure we use our own
227 * structure to avoid pg_control version issues between releases.
233 char nextxlogfile[25];
234 uint32 chkpnt_nxtxid;
235 uint32 chkpnt_nxtepoch;
236 uint32 chkpnt_nxtoid;
237 uint32 chkpnt_nxtmulti;
238 uint32 chkpnt_nxtmxoff;
239 uint32 chkpnt_oldstMulti;
240 uint32 chkpnt_oldstxid;
251 bool float8_pass_by_value;
252 uint32 data_checksum_version;
253 bool default_char_signedness;
257 * Enumeration to denote transfer modes
263 TRANSFER_MODE_COPY_FILE_RANGE,
269 * Enumeration to denote pg_log modes
274 PG_STATUS, /* these messages do not get a newline added */
275 PG_REPORT_NONL, /* these too */
285 * information about each cluster
289 ControlData controldata; /* pg_control information */
290 DbLocaleInfo *template0; /* template0 locale info */
291 DbInfoArr dbarr; /* dbinfos array */
292 char *pgdata; /* pathname for cluster's $PGDATA directory */
293 char *pgconfig; /* pathname for cluster's config file
295 char *bindir; /* pathname for cluster's executable directory */
296 char *pgopts; /* options to pass to the server, like pg_ctl
298 char *sockdir; /* directory for Unix Domain socket, if any */
299 unsigned short port; /* port number where postmaster is waiting */
300 uint32 major_version; /* PG_VERSION of cluster */
301 char major_version_str[64]; /* string PG_VERSION of cluster */
302 uint32 bin_version; /* version returned from pg_ctl */
303 char **tablespaces; /* tablespace directories */
305 const char *tablespace_suffix; /* directory specification */
306 int nsubs; /* number of subscriptions */
307 bool sub_retain_dead_tuples; /* whether a subscription enables
308 * retain_dead_tuples. */
317 FILE *internal; /* internal log FILE */
318 bool verbose; /* true -> be verbose in messages */
319 bool retain; /* retain log files on success */
320 /* Set of internal directories for output files */
321 char *rootdir; /* Root directory, aka pg_upgrade_output.d */
322 char *basedir; /* Base output directory, with timestamp */
323 char *dumpdir; /* Dumps */
324 char *logdir; /* Log files */
325 bool isatty; /* is stdout a tty */
334 bool check; /* check clusters only, don't change any data */
335 bool live_check; /* check clusters only, old server is running */
336 bool do_sync; /* flush changes to disk */
337 transferMode transfer_mode; /* copy files or link them? */
338 int jobs; /* number of processes/threads to use */
339 char *socketdir; /* directory to use for Unix sockets */
341 bool do_statistics; /* carry over statistics from old cluster */
342 int char_signedness; /* default char signedness: -1 for initial
343 * value, 1 for "signed" and 0 for
358 const char *progname; /* complete pathname for this program */
359 char *user; /* username for clusters */
360 bool user_specified; /* user specified on command-line */
361 LibraryInfo *libraries; /* loadable libraries */
363 ClusterInfo *running_cluster;
367/* Function signature for data type check version hook */
368 typedef bool (*DataTypesUsageVersionCheck) (ClusterInfo *cluster);
373extern LogOpts log_opts;
374extern UserOpts user_opts;
375extern ClusterInfo old_cluster,
377extern OSInfo os_info;
382void output_check_banner(void);
383void check_and_dump_old_cluster(void);
384void check_new_cluster(void);
385void report_clusters_compatible(void);
386void issue_warnings_and_set_wal_level(void);
387void output_completion_banner(char *deletion_script_file_name);
388void check_cluster_versions(void);
389void check_cluster_compatibility(void);
390void create_script_for_old_cluster_deletion(char **deletion_script_file_name);
395void get_control_data(ClusterInfo *cluster);
396void check_control_data(ControlData *oldctrl, ControlData *newctrl);
397void disable_old_cluster(transferMode transfer_mode);
402void generate_old_dump(void);
407 #define EXEC_PSQL_ARGS "--echo-queries --set ON_ERROR_STOP=on --no-psqlrc --dbname=template1"
409 bool exec_prog(const char *log_filename, const char *opt_log_file,
410 bool report_error, bool exit_on_error, const char *fmt,...) pg_attribute_printf(5, 6);
411void verify_directories(void);
412bool pid_lock_file_exists(const char *datadir);
417void cloneFile(const char *src, const char *dst,
418 const char *schemaName, const char *relName);
419void copyFile(const char *src, const char *dst,
420 const char *schemaName, const char *relName);
421void copyFileByRange(const char *src, const char *dst,
422 const char *schemaName, const char *relName);
423void linkFile(const char *src, const char *dst,
424 const char *schemaName, const char *relName);
425void rewriteVisibilityMap(const char *fromfile, const char *tofile,
426 const char *schemaName, const char *relName);
427void check_file_clone(void);
428void check_copy_file_range(void);
429void check_hard_link(transferMode transfer_mode);
431/* fopen_priv() is no longer different from fopen() */
432 #define fopen_priv(path, mode) fopen(path, mode)
436void get_loadable_libraries(void);
437void check_loadable_libraries(void);
441FileNameMap *gen_db_file_maps(DbInfo *old_db,
442 DbInfo *new_db, int *nmaps, const char *old_pgdata,
443 const char *new_pgdata);
444void get_db_rel_and_slot_infos(ClusterInfo *cluster);
445int count_old_cluster_logical_slots(void);
446void get_subscription_info(ClusterInfo *cluster);
450void parseCommandLine(int argc, char *argv[]);
451void adjust_data_dir(ClusterInfo *cluster);
452void get_sock_dir(ClusterInfo *cluster);
456void transfer_all_new_tablespaces(DbInfoArr *old_db_arr,
457 DbInfoArr *new_db_arr, char *old_pgdata, char *new_pgdata);
458void transfer_all_new_dbs(DbInfoArr *old_db_arr,
459 DbInfoArr *new_db_arr, char *old_pgdata, char *new_pgdata,
460 char *old_tablespace, char *new_tablespace);
464void init_tablespaces(void);
469PGconn *connectToServer(ClusterInfo *cluster, const char *db_name);
470 PGresult *executeQueryOrDie(PGconn *conn, const char *fmt,...) pg_attribute_printf(2, 3);
472char *cluster_conn_opts(ClusterInfo *cluster);
474bool start_postmaster(ClusterInfo *cluster, bool report_and_exit_on_error);
475void stop_postmaster(bool in_atexit);
476uint32 get_major_server_version(ClusterInfo *cluster);
477void check_pghost_envvar(void);
482char *quote_identifier(const char *s);
483int get_user_info(char **user_name_p);
485 void report_status(eLogType type, const char *fmt,...) pg_attribute_printf(2, 3);
486 void pg_log(eLogType type, const char *fmt,...) pg_attribute_printf(2, 3);
487 pg_noreturn void pg_fatal(const char *fmt,...) pg_attribute_printf(1, 2);
488void end_progress_output(void);
489void cleanup_output_dirs(void);
490 void prep_status(const char *fmt,...) pg_attribute_printf(1, 2);
491 void prep_status_progress(const char *fmt,...) pg_attribute_printf(1, 2);
492unsigned int str2uint(const char *str);
497bool jsonb_9_4_check_applicable(ClusterInfo *cluster);
498void old_9_6_invalidate_hash_indexes(ClusterInfo *cluster,
501void report_extension_updates(ClusterInfo *cluster);
504 void parallel_exec_prog(const char *log_file, const char *opt_log_file,
505 const char *fmt,...) pg_attribute_printf(3, 4);
506void parallel_transfer_all_new_dbs(DbInfoArr *old_db_arr, DbInfoArr *new_db_arr,
507 char *old_pgdata, char *new_pgdata,
508 char *old_tablespace, char *new_tablespace);
509bool reap_child(bool wait_for_child);
513 typedef void (*UpgradeTaskProcessCB) (DbInfo *dbinfo, PGresult *res, void *arg);
515/* struct definition is private to task.c */
516 typedef struct UpgradeTask UpgradeTask;
518UpgradeTask *upgrade_task_create(void);
519void upgrade_task_add_step(UpgradeTask *task, const char *query,
520 UpgradeTaskProcessCB process_cb, bool free_result,
522void upgrade_task_run(const UpgradeTask *task, const ClusterInfo *cluster);
523void upgrade_task_free(UpgradeTask *task);
525/* convenient type for common private data needed by several tasks */
529 char path[MAXPGPATH];