1/*-------------------------------------------------------------------------
4 * Catalog-to-filenumber mapping
6 * For most tables, the physical file underlying the table is specified by
7 * pg_class.relfilenode. However, that obviously won't work for pg_class
8 * itself, nor for the other "nailed" catalogs for which we have to be able
9 * to set up working Relation entries without access to pg_class. It also
10 * does not work for shared catalogs, since there is no practical way to
11 * update other databases' pg_class entries when relocating a shared catalog.
12 * Therefore, for these special catalogs (henceforth referred to as "mapped
13 * catalogs") we rely on a separately maintained file that shows the mapping
14 * from catalog OIDs to filenumbers. Each database has a map file for
15 * its local mapped catalogs, and there is a separate map file for shared
16 * catalogs. Mapped catalogs have zero in their pg_class.relfilenode entries.
18 * Relocation of a normal table is committed (ie, the new physical file becomes
19 * authoritative) when the pg_class row update commits. For mapped catalogs,
20 * the act of updating the map file is effectively commit of the relocation.
21 * We postpone the file update till just before commit of the transaction
22 * doing the rewrite, but there is necessarily a window between. Therefore
23 * mapped catalogs can only be relocated by operations such as VACUUM FULL
24 * and CLUSTER, which make no transactionally-significant changes: it must be
25 * safe for the new file to replace the old, even if the transaction itself
26 * aborts. An important factor here is that the indexes and toast table of
27 * a mapped catalog must also be mapped, so that the rewrites/relocations of
28 * all these files commit in a single map file update rather than being tied
29 * to transaction commit.
31 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
32 * Portions Copyright (c) 1994, Regents of the University of California
36 * src/backend/utils/cache/relmapper.c
38 *-------------------------------------------------------------------------
60 * The map file is critical data: we have no automatic method for recovering
61 * from loss or corruption of it. We use a CRC so that we can detect
62 * corruption. Since the file might be more than one standard-size disk
63 * sector in size, we cannot rely on overwrite-in-place. Instead, we generate
64 * a new file and rename it into place, atomically replacing the original file.
66 * Entries in the mappings[] array are in no particular order. We could
67 * speed searching by insisting on OID order, but it really shouldn't be
68 * worth the trouble given the intended size of the mapping sets.
70 #define RELMAPPER_FILENAME "pg_filenode.map"
71 #define RELMAPPER_TEMP_FILENAME "pg_filenode.map.tmp"
73 #define RELMAPPER_FILEMAGIC 0x592717 /* version ID value */
76 * There's no need for this constant to have any particular value, and we
77 * can raise it as necessary if we end up with more mapped relations. For
78 * now, we just pick a round number that is modestly larger than the expected
81 #define MAX_MAPPINGS 64
98 * State for serializing local and shared relmappings for parallel workers
99 * (active states only). See notes on active_* and pending_* updates state.
108 * The currently known contents of the shared map file and our database's
109 * local map file are stored here. These can be reloaded from disk
110 * immediately whenever we receive an update sinval message.
116 * We use the same RelMapFile data structure to track uncommitted local
117 * changes in the mappings (but note the magic and crc fields are not made
118 * valid in these variables). Currently, map updates are not allowed within
119 * subtransactions, so one set of transaction-level changes is sufficient.
121 * The active_xxx variables contain updates that are valid in our transaction
122 * and should be honored by RelationMapOidToFilenumber. The pending_xxx
123 * variables contain updates we have been told about that aren't active yet;
124 * they will become active at the next CommandCounterIncrement. This setup
125 * lets map updates act similarly to updates of pg_class rows, ie, they
126 * become visible only at the next CommandCounterIncrement boundary.
128 * Active shared and active local updates are serialized by the parallel
129 * infrastructure, and deserialized within parallel workers.
137/* non-export function prototypes */
146 bool send_sinval,
bool preserve_files,
147 Oid dbid,
Oid tsid,
const char *dbpath);
152 * RelationMapOidToFilenumber
154 * The raison d' etre ... given a relation OID, look up its filenumber.
156 * Although shared and local relation OIDs should never overlap, the caller
157 * always knows which we need --- so pass that information to avoid useless
160 * Returns InvalidRelFileNumber if the OID is not known (which should never
161 * happen, but the caller is in a better position to report a meaningful
170 /* If there are active updates, believe those over the main maps */
206 * RelationMapFilenumberToOid
208 * Do the reverse of the normal direction of mapping done in
209 * RelationMapOidToFilenumber.
211 * This is not supposed to be used during normal running but rather for
212 * information purposes when looking at the filesystem or xlog.
214 * Returns InvalidOid if the OID is not known; this can easily happen if the
215 * relfilenumber doesn't pertain to a mapped relation.
223 /* If there are active updates, believe those over the main maps */
259 * RelationMapOidToFilenumberForDatabase
261 * Like RelationMapOidToFilenumber, but reads the mapping from the indicated
262 * path instead of using the one for the current database.
270 /* Read the relmap file from the source database. */
273 /* Iterate over the relmap entries to find the input relation OID. */
286 * Copy relmapfile from source db path to the destination db path and WAL log
287 * the operation. This is intended for use in creating a new relmap file
288 * for a database that doesn't have one yet, not for replacing an existing
297 * Read the relmap file from the source database.
302 * Write the same data into the destination database's relmap file.
304 * No sinval is needed because no one can be connected to the destination
307 * There's no point in trying to preserve files here. The new database
308 * isn't usable yet anyway, and won't ever be if we can't install a relmap
317 * RelationMapUpdateMap
319 * Install a new relfilenumber mapping for the specified relation.
321 * If immediate is true (or we're bootstrapping), the mapping is activated
322 * immediately. Otherwise it is made pending until CommandCounterIncrement.
333 * In bootstrap mode, the mapping gets installed in permanent map.
343 * We don't currently support map changes within subtransactions, or
344 * when in parallel mode. This could be done with more bookkeeping
345 * infrastructure, but it doesn't presently seem worth it.
348 elog(
ERROR,
"cannot change relation mapping within subtransaction");
351 elog(
ERROR,
"cannot change relation mapping in parallel mode");
355 /* Make it active, but only locally */
363 /* Make it pending */
376 * Insert a new mapping into the given map variable, replacing any existing
377 * mapping for the same relation.
379 * In some cases the caller knows there must be an existing mapping; pass
380 * add_okay = false to draw an error if not.
388 /* Replace any existing mapping */
398 /* Nope, need to add a new mapping */
400 elog(
ERROR,
"attempt to apply a mapping to unmapped relation %u",
403 elog(
ERROR,
"ran out of space in relation map");
412 * Merge all the updates in the given pending-update map into the target map.
413 * This is just a bulk form of apply_map_update.
430 * RelationMapRemoveMapping
432 * Remove a relation's entry in the map. This is only allowed for "active"
433 * (but not committed) local mappings. We need it so we can back out the
434 * entry for the transient target file when doing VACUUM FULL/CLUSTER on
447 /* Found it, collapse it out */
453 elog(
ERROR,
"could not find temporary mapping for relation %u",
458 * RelationMapInvalidate
460 * This routine is invoked for SI cache flush messages. We must re-read
461 * the indicated map file. However, we might receive a SI message in a
462 * process that hasn't yet, and might never, load the mapping files;
463 * for example the autovacuum launcher, which *must not* try to read
464 * a local map since it is attached to no particular database.
465 * So, re-read only if the map is valid now.
483 * RelationMapInvalidateAll
485 * Reload all map files. This is used to recover from SI message buffer
486 * overflow: we can't be sure if we missed an inval message.
487 * Again, reload only currently-valid maps.
501 * Activate any "pending" relation map updates at CommandCounterIncrement time.
523 * AtEOXact_RelationMap
525 * Handle relation mapping at main-transaction commit or abort.
527 * During commit, this must be called as late as possible before the actual
528 * transaction commit, so as to minimize the window where the transaction
529 * could still roll back after committing map changes. Although nothing
530 * critically bad happens in such a case, we still would prefer that it
531 * not happen, since we'd possibly be losing useful updates to the relations'
534 * During abort, we just have to throw away any pending map changes.
535 * Normal post-abort cleanup will take care of fixing relcache entries.
536 * Parallel worker commit/abort is handled by resetting active mappings
537 * that may have been received from the leader process. (There should be
538 * no pending updates in parallel workers.)
543 if (isCommit && !isParallelWorker)
546 * We should not get here with any "pending" updates. (We could
547 * logically choose to treat such as committed, but in the current
548 * code this should never happen.)
554 * Write any active updates to the actual map files, then reset them.
569 /* Abort or parallel worker --- drop all local and pending updates */
581 * AtPrepare_RelationMap
583 * Handle relation mapping at PREPARE.
585 * Currently, we don't support preparing any transaction that changes the map.
595 (
errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
596 errmsg(
"cannot PREPARE a transaction that modified relation mapping")));
600 * CheckPointRelationMap
602 * This is called during a checkpoint. It must ensure that any relation map
603 * updates that were WAL-logged before the start of the checkpoint are
604 * securely flushed to disk and will not need to be replayed later. This
605 * seems unlikely to be a performance-critical issue, so we use a simple
606 * method: we just take and release the RelationMappingLock. This ensures
607 * that any already-logged map update is complete, because write_relmap_file
608 * will fsync the map file before the lock is released.
618 * RelationMapFinishBootstrap
620 * Write out the initial relation mapping files at the completion of
621 * bootstrap. All the mapped files should have been made known to us
622 * via RelationMapUpdateMap calls.
629 /* Shouldn't be anything "pending" ... */
635 /* Write the files; no WAL or sinval needed */
645 * RelationMapInitialize
647 * This initializes the mapper module at process startup. We can't access the
648 * database yet, so just make sure the maps are empty.
653 /* The static variables should initialize to zeroes, but let's be sure */
665 * RelationMapInitializePhase2
667 * This is called to prepare for access to pg_database during startup.
668 * We should be able to read the shared map file now.
674 * In bootstrap mode, the map file isn't there yet, so do nothing.
680 * Load the shared map file, die on error.
686 * RelationMapInitializePhase3
688 * This is called as soon as we have determined MyDatabaseId and set up
689 * DatabasePath. At this point we should be able to read the local map file.
695 * In bootstrap mode, the map file isn't there yet, so do nothing.
701 * Load the local map file, die on error.
707 * EstimateRelationMapSpace
709 * Estimate space needed to pass active shared and local relmaps to parallel
719 * SerializeRelationMap
721 * Serialize active shared and local relmap state for parallel workers.
738 * Restore active shared and local relmap state within a parallel worker.
749 elog(
ERROR,
"parallel worker has existing mappings");
757 * load_relmap_file -- load the shared or local map file
759 * Because these files are essential for access to core system catalogs,
760 * failure to load either of them is a fatal error.
762 * Note that the local case requires DatabasePath to be set up.
774 * read_relmap_file -- load data from any relation mapper file
776 * dbpath must be the relevant database path, or "global" for shared relations.
778 * RelationMappingLock will be acquired released unless lock_held = true.
780 * Errors will be reported at the indicated elevel, which should be at least
794 * Grab the lock to prevent the file from being updated while we read it,
795 * unless the caller is already holding the lock. If the file is updated
796 * shortly after we look, the sinval signaling mechanism will make us
797 * re-read it before we are able to access any relation that's affected by
804 * Open the target file.
806 * Because Windows isn't happy about the idea of renaming over a file that
807 * someone has open, we only open this file after acquiring the lock, and
808 * for the same reason, we close it before releasing the lock. That way,
809 * by the time write_relmap_file() acquires an exclusive lock, no one else
812 snprintf(mapfilename,
sizeof(mapfilename),
"%s/%s", dbpath,
818 errmsg(
"could not open file \"%s\": %m",
821 /* Now read the data. */
829 errmsg(
"could not read file \"%s\": %m", mapfilename)));
833 errmsg(
"could not read file \"%s\": read %d of %zu",
841 errmsg(
"could not close file \"%s\": %m",
847 /* check for correct magic number, etc */
852 (
errmsg(
"relation mapping file \"%s\" contains invalid data",
862 (
errmsg(
"relation mapping file \"%s\" contains incorrect checksum",
867 * Write out a new shared or local map file with the given contents.
869 * The magic number and CRC are automatically updated in *newmap. On
870 * success, we copy the data to the appropriate permanent static variable.
872 * If write_wal is true then an appropriate WAL message is emitted.
873 * (It will be false for bootstrap and WAL replay cases.)
875 * If send_sinval is true then a SI invalidation message is sent.
876 * (This should be true except in bootstrap case.)
878 * If preserve_files is true then the storage manager is warned not to
879 * delete the files listed in the map.
881 * Because this may be called during WAL replay when MyDatabaseId,
882 * DatabasePath, etc aren't valid, we require the caller to pass in suitable
883 * values. Pass dbpath as "global" for the shared map.
885 * The caller is also responsible for being sure no concurrent map update
886 * could be happening.
890 bool preserve_files,
Oid dbid,
Oid tsid,
const char *dbpath)
897 * Even without concurrent use of this map, CheckPointRelationMap() relies
898 * on this locking. Without it, a restore of a base backup taken after
899 * this function's XLogInsert() and before its durable_rename() would not
900 * have the changes. wal_level=minimal doesn't need the lock, but this
901 * isn't performance-critical enough for such a micro-optimization.
906 * Fill in the overhead fields and update CRC.
910 elog(
ERROR,
"attempt to write bogus relation mapping");
917 * Construct filenames -- a temporary file that we'll create to write the
918 * data initially, and then the permanent name to which we will rename it.
920 snprintf(mapfilename,
sizeof(mapfilename),
"%s/%s",
922 snprintf(maptempfilename,
sizeof(maptempfilename),
"%s/%s",
926 * Open a temporary file. If a file already exists with this name, it must
927 * be left over from a previous crash, so we can overwrite it. Concurrent
928 * calls to this function are not allowed.
931 O_WRONLY | O_CREAT | O_TRUNC |
PG_BINARY);
935 errmsg(
"could not open file \"%s\": %m",
938 /* Write new data to the file. */
942 /* if write didn't set errno, assume problem is no disk space */
947 errmsg(
"could not write file \"%s\": %m",
952 /* And close the file. */
956 errmsg(
"could not close file \"%s\": %m",
964 /* now errors are fatal ... */
977 /* As always, WAL must hit the disk before the data update does */
982 * durable_rename() does all the hard work of making sure that we rename
983 * the temporary file into place in a crash-safe manner.
985 * NB: Although we instruct durable_rename() to use ERROR, we will often
986 * be in a critical section at this point; if so, ERROR will become PANIC.
993 * Now that the file is safely on disk, send sinval message to let other
994 * backends know to re-read it. We must do this inside the critical
995 * section: if for some reason we fail to send the message, we have to
996 * force a database-wide PANIC. Otherwise other backends might continue
997 * execution with stale mapping information, which would be catastrophic
998 * as soon as others began to use the now-committed data.
1004 * Make sure that the files listed in the map are not deleted if the outer
1005 * transaction aborts. This had better be within the critical section
1006 * too: it's not likely to fail, but if it did, we'd arrive at transaction
1007 * abort with the files still vulnerable. PANICing will leave things in a
1008 * good state on-disk.
1010 * Note: we're cheating a little bit here by assuming that mapped files
1011 * are either in pg_global or the database's default tablespace.
1022 rlocator.
dbOid = dbid;
1028 /* Critical section done */
1034 * Merge the specified updates into the appropriate "real" map,
1035 * and write out the changes. This function must be used for committing
1036 * updates during normal multiuser operation.
1044 * Anyone updating a relation's mapping info should take exclusive lock on
1045 * that rel and hold it until commit. This ensures that there will not be
1046 * concurrent updates on the same mapping value; but there could easily be
1047 * concurrent updates on different values in the same file. We cover that
1048 * by acquiring the RelationMappingLock, re-reading the target file to
1049 * ensure it's up to date, applying the updates, and writing the data
1050 * before releasing RelationMappingLock.
1052 * There is only one RelationMappingLock. In principle we could try to
1053 * have one per mapping file, but it seems unlikely to be worth the
1058 /* Be certain we see any other updates just made */
1061 /* Prepare updated data in a local variable */
1068 * Apply the updates to newmap. No new mappings should appear, unless
1069 * somebody is adding indexes to system catalogs.
1073 /* Write out the updated map and do other necessary tasks */
1080 * We successfully wrote the updated file, so it's now safe to rely on the
1081 * new values in this process, too.
1088 /* Now we can release the lock */
1093 * RELMAP resource manager's routines
1100 /* Backup blocks are not used in relmap records */
1110 elog(
PANIC,
"relmap_redo: wrong size %u in relmap update record",
1112 memcpy(&newmap, xlrec->
data,
sizeof(newmap));
1114 /* We need to construct the pathname for this database */
1118 * Write out the new map and send sinval, but of course don't write a
1119 * new WAL entry. There's no surrounding transaction to tell to
1120 * preserve files, either.
1122 * There shouldn't be anyone else updating relmaps during WAL replay,
1123 * but grab the lock to interlock against load_relmap_file().
1125 * Note that we use the same WAL record for updating the relmap of an
1126 * existing database as we do for creating a new database. In the
1127 * latter case, taking the relmap log and sending sinval messages is
1128 * unnecessary, but harmless. If we wanted to avoid it, we could add a
1129 * flag to the WAL record to indicate which operation is being
1140 elog(
PANIC,
"relmap_redo: unknown op code %u", info);
int errcode_for_file_access(void)
int errcode(int sqlerrcode)
int errmsg(const char *fmt,...)
#define ereport(elevel,...)
int durable_rename(const char *oldfile, const char *newfile, int elevel)
int CloseTransientFile(int fd)
int OpenTransientFile(const char *fileName, int fileFlags)
bool allowSystemTableMods
Assert(PointerIsAligned(start, uint64))
void CacheInvalidateRelmap(Oid databaseId)
bool LWLockAcquire(LWLock *lock, LWLockMode mode)
bool LWLockHeldByMeInMode(LWLock *lock, LWLockMode mode)
void LWLockRelease(LWLock *lock)
void pfree(void *pointer)
#define IsBootstrapProcessingMode()
#define START_CRIT_SECTION()
#define END_CRIT_SECTION()
#define ERRCODE_DATA_CORRUPTED
#define COMP_CRC32C(crc, data, len)
#define EQ_CRC32C(c1, c2)
static int fd(const char *x, int i)
RelFileNumber RelationMapOidToFilenumberForDatabase(char *dbpath, Oid relationId)
static RelMapFile pending_local_updates
Size EstimateRelationMapSpace(void)
void RelationMapRemoveMapping(Oid relationId)
struct RelMapping RelMapping
void SerializeRelationMap(Size maxSize, char *startAddress)
#define RELMAPPER_FILEMAGIC
void RelationMapCopy(Oid dbid, Oid tsid, char *srcdbpath, char *dstdbpath)
static void apply_map_update(RelMapFile *map, Oid relationId, RelFileNumber fileNumber, bool add_okay)
static void write_relmap_file(RelMapFile *newmap, bool write_wal, bool send_sinval, bool preserve_files, Oid dbid, Oid tsid, const char *dbpath)
Oid RelationMapFilenumberToOid(RelFileNumber filenumber, bool shared)
void RelationMapInvalidateAll(void)
void RestoreRelationMap(char *startAddress)
static RelMapFile shared_map
static RelMapFile active_local_updates
static void perform_relmap_update(bool shared, const RelMapFile *updates)
static void read_relmap_file(RelMapFile *map, char *dbpath, bool lock_held, int elevel)
void RelationMapInitialize(void)
void AtPrepare_RelationMap(void)
static RelMapFile local_map
#define RELMAPPER_TEMP_FILENAME
void relmap_redo(XLogReaderState *record)
#define RELMAPPER_FILENAME
void AtEOXact_RelationMap(bool isCommit, bool isParallelWorker)
void RelationMapInvalidate(bool shared)
static RelMapFile pending_shared_updates
void RelationMapInitializePhase2(void)
void RelationMapFinishBootstrap(void)
struct SerializedActiveRelMaps SerializedActiveRelMaps
RelFileNumber RelationMapOidToFilenumber(Oid relationId, bool shared)
void RelationMapUpdateMap(Oid relationId, RelFileNumber fileNumber, bool shared, bool immediate)
void RelationMapInitializePhase3(void)
struct RelMapFile RelMapFile
void AtCCI_RelationMap(void)
static void merge_map_updates(RelMapFile *map, const RelMapFile *updates, bool add_okay)
void CheckPointRelationMap(void)
static RelMapFile active_shared_updates
static void load_relmap_file(bool shared, bool lock_held)
#define XLOG_RELMAP_UPDATE
#define MinSizeOfRelmapUpdate
char * GetDatabasePath(Oid dbOid, Oid spcOid)
#define InvalidRelFileNumber
void RelationPreserveStorage(RelFileLocator rlocator, bool atCommit)
RelMapping mappings[MAX_MAPPINGS]
RelFileNumber mapfilenumber
RelMapFile active_local_updates
RelMapFile active_shared_updates
char data[FLEXIBLE_ARRAY_MEMBER]
static void pgstat_report_wait_start(uint32 wait_event_info)
static void pgstat_report_wait_end(void)
int GetCurrentTransactionNestLevel(void)
bool IsInParallelMode(void)
void XLogFlush(XLogRecPtr record)
XLogRecPtr XLogInsert(RmgrId rmid, uint8 info)
void XLogRegisterData(const void *data, uint32 len)
void XLogBeginInsert(void)
#define XLogRecGetInfo(decoder)
#define XLogRecGetData(decoder)
#define XLogRecHasAnyBlockRefs(decoder)