PostgreSQL Source Code  git master
pg_upgrade.h
Go to the documentation of this file.
1 /*
2  * pg_upgrade.h
3  *
4  * Copyright (c) 2010-2024, PostgreSQL Global Development Group
5  * src/bin/pg_upgrade/pg_upgrade.h
6  */
7 
8 #include <unistd.h>
9 #include <assert.h>
10 #include <sys/stat.h>
11 #include <sys/time.h>
12 
13 #include "common/relpath.h"
14 #include "libpq-fe.h"
15 
16 /* For now, pg_upgrade does not use common/logging.c; use our own pg_fatal */
17 #undef pg_fatal
18 
19 /* Use port in the private/dynamic port number range */
20 #define DEF_PGUPORT 50432
21 
22 #define MAX_STRING 1024
23 #define QUERY_ALLOC 8192
24 
25 #define MESSAGE_WIDTH 62
26 
27 #define GET_MAJOR_VERSION(v) ((v) / 100)
28 
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"
32 
33 /*
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.
38  */
39 #define BASE_OUTPUTDIR "pg_upgrade_output.d"
40 #define LOG_OUTPUTDIR "log"
41 #define DUMP_OUTPUTDIR "dump"
42 
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"
47 
48 extern char *output_files[];
49 
50 /*
51  * WIN32 files do not accept writes from multiple processes
52  *
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
59  * pg_ctl exits.
60  *
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.
65  */
66 #ifndef WIN32
67 #define SERVER_START_LOG_FILE SERVER_LOG_FILE
68 #define SERVER_STOP_LOG_FILE SERVER_LOG_FILE
69 #else
70 #define SERVER_START_LOG_FILE "pg_upgrade_server_start.log"
71 /*
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
74  * stop".
75  */
76 #define SERVER_STOP_LOG_FILE UTILITY_LOG_FILE
77 #endif
78 
79 
80 #ifndef WIN32
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 "'"
89 #define ECHO_BLANK ""
90 #else
91 #define pg_mv_file pgrename
92 #define PATH_SEPARATOR '\\'
93 #define PATH_QUOTE '"'
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"
99 #define EXE_EXT ".exe"
100 #define ECHO_QUOTE ""
101 #define ECHO_BLANK "."
102 #endif
103 
104 
105 /*
106  * The format of visibility map was changed with this 9.6 commit.
107  */
108 #define VISIBILITY_MAP_FROZEN_BIT_CAT_VER 201603011
109 
110 /*
111  * pg_multixact format changed in 9.3 commit 0ac5ad5134f2769ccbaefec73844f85,
112  * ("Improve concurrency of foreign key locking") which also updated catalog
113  * version to this value. pg_upgrade behavior depends on whether old and new
114  * server versions are both newer than this, or only the new one is.
115  */
116 #define MULTIXACT_FORMATCHANGE_CAT_VER 201301231
117 
118 /*
119  * large object chunk size added to pg_controldata,
120  * commit 5f93c37805e7485488480916b4585e098d3cc883
121  */
122 #define LARGE_OBJECT_SIZE_PG_CONTROL_VER 942
123 
124 /*
125  * change in JSONB format during 9.4 beta
126  */
127 #define JSONB_FORMAT_CHANGE_CAT_VER 201409291
128 
129 
130 /*
131  * Each relation is represented by a relinfo structure.
132  */
133 typedef struct
134 {
135  /* Can't use NAMEDATALEN; not guaranteed to be same on client */
136  char *nspname; /* namespace name */
137  char *relname; /* relation name */
138  Oid reloid; /* relation OID */
139  RelFileNumber relfilenumber; /* relation file number */
140  Oid indtable; /* if index, OID of its table, else 0 */
141  Oid toastheap; /* if toast table, OID of base table, else 0 */
142  char *tablespace; /* tablespace path; "" for cluster default */
143  bool nsp_alloc; /* should nspname be freed? */
144  bool tblsp_alloc; /* should tablespace be freed? */
145 } RelInfo;
146 
147 typedef struct
148 {
149  RelInfo *rels;
150  int nrels;
151 } RelInfoArr;
152 
153 /*
154  * Structure to store logical replication slot information.
155  */
156 typedef struct
157 {
158  char *slotname; /* slot name */
159  char *plugin; /* plugin */
160  bool two_phase; /* can the slot decode 2PC? */
161  bool caught_up; /* has the slot caught up to latest changes? */
162  bool invalid; /* if true, the slot is unusable */
163  bool failover; /* is the slot designated to be synced to the
164  * physical standby? */
165 } LogicalSlotInfo;
166 
167 typedef struct
168 {
169  int nslots; /* number of logical slot infos */
170  LogicalSlotInfo *slots; /* array of logical slot infos */
171 } LogicalSlotInfoArr;
172 
173 /*
174  * The following structure represents a relation mapping.
175  */
176 typedef struct
177 {
178  const char *old_tablespace;
179  const char *new_tablespace;
180  const char *old_tablespace_suffix;
181  const char *new_tablespace_suffix;
182  Oid db_oid;
183  RelFileNumber relfilenumber;
184  /* the rest are used only for logging and error reporting */
185  char *nspname; /* namespaces */
186  char *relname;
187 } FileNameMap;
188 
189 /*
190  * Structure to store database information
191  */
192 typedef struct
193 {
194  Oid db_oid; /* oid of the database */
195  char *db_name; /* database name */
196  char db_tablespace[MAXPGPATH]; /* database default tablespace
197  * path */
198  RelInfoArr rel_arr; /* array of all user relinfos */
199  LogicalSlotInfoArr slot_arr; /* array of all LogicalSlotInfo */
200  int nsubs; /* number of subscriptions */
201 } DbInfo;
202 
203 /*
204  * Locale information about a database.
205  */
206 typedef struct
207 {
208  char *db_collate;
209  char *db_ctype;
210  char db_collprovider;
211  char *db_iculocale;
212  int db_encoding;
213 } DbLocaleInfo;
214 
215 typedef struct
216 {
217  DbInfo *dbs; /* array of db infos */
218  int ndbs; /* number of db infos */
219 } DbInfoArr;
220 
221 /*
222  * The following structure is used to hold pg_control information.
223  * Rather than using the backend's control structure we use our own
224  * structure to avoid pg_control version issues between releases.
225  */
226 typedef struct
227 {
228  uint32 ctrl_ver;
229  uint32 cat_ver;
230  char nextxlogfile[25];
231  uint32 chkpnt_nxtxid;
232  uint32 chkpnt_nxtepoch;
233  uint32 chkpnt_nxtoid;
234  uint32 chkpnt_nxtmulti;
235  uint32 chkpnt_nxtmxoff;
236  uint32 chkpnt_oldstMulti;
237  uint32 chkpnt_oldstxid;
238  uint32 align;
239  uint32 blocksz;
240  uint32 largesz;
241  uint32 walsz;
242  uint32 walseg;
243  uint32 ident;
244  uint32 index;
245  uint32 toast;
246  uint32 large_object;
247  bool date_is_int;
248  bool float8_pass_by_value;
249  uint32 data_checksum_version;
250 } ControlData;
251 
252 /*
253  * Enumeration to denote transfer modes
254  */
255 typedef enum
256 {
257  TRANSFER_MODE_CLONE,
258  TRANSFER_MODE_COPY,
259  TRANSFER_MODE_LINK,
260 } transferMode;
261 
262 /*
263  * Enumeration to denote pg_log modes
264  */
265 typedef enum
266 {
267  PG_VERBOSE,
268  PG_STATUS, /* these messages do not get a newline added */
269  PG_REPORT_NONL, /* these too */
270  PG_REPORT,
271  PG_WARNING,
272  PG_FATAL,
273 } eLogType;
274 
275 
276 /*
277  * cluster
278  *
279  * information about each cluster
280  */
281 typedef struct
282 {
283  ControlData controldata; /* pg_control information */
284  DbLocaleInfo *template0; /* template0 locale info */
285  DbInfoArr dbarr; /* dbinfos array */
286  char *pgdata; /* pathname for cluster's $PGDATA directory */
287  char *pgconfig; /* pathname for cluster's config file
288  * directory */
289  char *bindir; /* pathname for cluster's executable directory */
290  char *pgopts; /* options to pass to the server, like pg_ctl
291  * -o */
292  char *sockdir; /* directory for Unix Domain socket, if any */
293  unsigned short port; /* port number where postmaster is waiting */
294  uint32 major_version; /* PG_VERSION of cluster */
295  char major_version_str[64]; /* string PG_VERSION of cluster */
296  uint32 bin_version; /* version returned from pg_ctl */
297  const char *tablespace_suffix; /* directory specification */
298 } ClusterInfo;
299 
300 
301 /*
302  * LogOpts
303 */
304 typedef struct
305 {
306  FILE *internal; /* internal log FILE */
307  bool verbose; /* true -> be verbose in messages */
308  bool retain; /* retain log files on success */
309  /* Set of internal directories for output files */
310  char *rootdir; /* Root directory, aka pg_upgrade_output.d */
311  char *basedir; /* Base output directory, with timestamp */
312  char *dumpdir; /* Dumps */
313  char *logdir; /* Log files */
314  bool isatty; /* is stdout a tty */
315 } LogOpts;
316 
317 
318 /*
319  * UserOpts
320 */
321 typedef struct
322 {
323  bool check; /* true -> ask user for permission to make
324  * changes */
325  bool do_sync; /* flush changes to disk */
326  transferMode transfer_mode; /* copy files or link them? */
327  int jobs; /* number of processes/threads to use */
328  char *socketdir; /* directory to use for Unix sockets */
329  char *sync_method;
330 } UserOpts;
331 
332 typedef struct
333 {
334  char *name;
335  int dbnum;
336 } LibraryInfo;
337 
338 /*
339  * OSInfo
340  */
341 typedef struct
342 {
343  const char *progname; /* complete pathname for this program */
344  char *user; /* username for clusters */
345  bool user_specified; /* user specified on command-line */
346  char **old_tablespaces; /* tablespaces */
347  int num_old_tablespaces;
348  LibraryInfo *libraries; /* loadable libraries */
349  int num_libraries;
350  ClusterInfo *running_cluster;
351 } OSInfo;
352 
353 
354 /*
355  * Global variables
356  */
357 extern LogOpts log_opts;
358 extern UserOpts user_opts;
359 extern ClusterInfo old_cluster,
360  new_cluster;
361 extern OSInfo os_info;
362 
363 
364 /* check.c */
365 
366 void output_check_banner(bool live_check);
367 void check_and_dump_old_cluster(bool live_check);
368 void check_new_cluster(void);
369 void report_clusters_compatible(void);
370 void issue_warnings_and_set_wal_level(void);
371 void output_completion_banner(char *deletion_script_file_name);
372 void check_cluster_versions(void);
373 void check_cluster_compatibility(bool live_check);
374 void create_script_for_old_cluster_deletion(char **deletion_script_file_name);
375 
376 
377 /* controldata.c */
378 
379 void get_control_data(ClusterInfo *cluster, bool live_check);
380 void check_control_data(ControlData *oldctrl, ControlData *newctrl);
381 void disable_old_cluster(void);
382 
383 
384 /* dump.c */
385 
386 void generate_old_dump(void);
387 
388 
389 /* exec.c */
390 
391 #define EXEC_PSQL_ARGS "--echo-queries --set ON_ERROR_STOP=on --no-psqlrc --dbname=template1"
392 
393 bool exec_prog(const char *log_filename, const char *opt_log_file,
394  bool report_error, bool exit_on_error, const char *fmt,...) pg_attribute_printf(5, 6);
395 void verify_directories(void);
396 bool pid_lock_file_exists(const char *datadir);
397 
398 
399 /* file.c */
400 
401 void cloneFile(const char *src, const char *dst,
402  const char *schemaName, const char *relName);
403 void copyFile(const char *src, const char *dst,
404  const char *schemaName, const char *relName);
405 void linkFile(const char *src, const char *dst,
406  const char *schemaName, const char *relName);
407 void rewriteVisibilityMap(const char *fromfile, const char *tofile,
408  const char *schemaName, const char *relName);
409 void check_file_clone(void);
410 void check_hard_link(void);
411 
412 /* fopen_priv() is no longer different from fopen() */
413 #define fopen_priv(path, mode) fopen(path, mode)
414 
415 /* function.c */
416 
417 void get_loadable_libraries(void);
418 void check_loadable_libraries(void);
419 
420 /* info.c */
421 
422 FileNameMap *gen_db_file_maps(DbInfo *old_db,
423  DbInfo *new_db, int *nmaps, const char *old_pgdata,
424  const char *new_pgdata);
425 void get_db_rel_and_slot_infos(ClusterInfo *cluster, bool live_check);
426 int count_old_cluster_logical_slots(void);
427 int count_old_cluster_subscriptions(void);
428 
429 /* option.c */
430 
431 void parseCommandLine(int argc, char *argv[]);
432 void adjust_data_dir(ClusterInfo *cluster);
433 void get_sock_dir(ClusterInfo *cluster, bool live_check);
434 
435 /* relfilenumber.c */
436 
437 void transfer_all_new_tablespaces(DbInfoArr *old_db_arr,
438  DbInfoArr *new_db_arr, char *old_pgdata, char *new_pgdata);
439 void transfer_all_new_dbs(DbInfoArr *old_db_arr,
440  DbInfoArr *new_db_arr, char *old_pgdata, char *new_pgdata,
441  char *old_tablespace);
442 
443 /* tablespace.c */
444 
445 void init_tablespaces(void);
446 
447 
448 /* server.c */
449 
450 PGconn *connectToServer(ClusterInfo *cluster, const char *db_name);
451 PGresult *executeQueryOrDie(PGconn *conn, const char *fmt,...) pg_attribute_printf(2, 3);
452 
453 char *cluster_conn_opts(ClusterInfo *cluster);
454 
455 bool start_postmaster(ClusterInfo *cluster, bool report_and_exit_on_error);
456 void stop_postmaster(bool in_atexit);
457 uint32 get_major_server_version(ClusterInfo *cluster);
458 void check_pghost_envvar(void);
459 
460 
461 /* util.c */
462 
463 char *quote_identifier(const char *s);
464 int get_user_info(char **user_name_p);
465 void check_ok(void);
466 void report_status(eLogType type, const char *fmt,...) pg_attribute_printf(2, 3);
467 void pg_log(eLogType type, const char *fmt,...) pg_attribute_printf(2, 3);
468 void pg_fatal(const char *fmt,...) pg_attribute_printf(1, 2) pg_attribute_noreturn();
469 void end_progress_output(void);
470 void cleanup_output_dirs(void);
471 void prep_status(const char *fmt,...) pg_attribute_printf(1, 2);
472 void prep_status_progress(const char *fmt,...) pg_attribute_printf(1, 2);
473 unsigned int str2uint(const char *str);
474 
475 
476 /* version.c */
477 
478 bool check_for_data_types_usage(ClusterInfo *cluster,
479  const char *base_query,
480  const char *output_path);
481 bool check_for_data_type_usage(ClusterInfo *cluster,
482  const char *type_name,
483  const char *output_path);
484 void old_9_3_check_for_line_data_type_usage(ClusterInfo *cluster);
485 void old_9_6_check_for_unknown_data_type_usage(ClusterInfo *cluster);
486 void old_9_6_invalidate_hash_indexes(ClusterInfo *cluster,
487  bool check_mode);
488 
489 void old_11_check_for_sql_identifier_data_type_usage(ClusterInfo *cluster);
490 void report_extension_updates(ClusterInfo *cluster);
491 
492 /* parallel.c */
493 void parallel_exec_prog(const char *log_file, const char *opt_log_file,
494  const char *fmt,...) pg_attribute_printf(3, 4);
495 void parallel_transfer_all_new_dbs(DbInfoArr *old_db_arr, DbInfoArr *new_db_arr,
496  char *old_pgdata, char *new_pgdata,
497  char *old_tablespace);
498 bool reap_child(bool wait_for_child);
char * output_files[]
Definition: pg_upgrade.c:68