src/backend/catalog/toasting.c

   1 /*-------------------------------------------------------------------------
   2  *
   3  * toasting.c
   4  *        This file contains routines to support creation of toast tables
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2009, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * IDENTIFICATION
  11  *        $PostgreSQL: pgsql/src/backend/catalog/toasting.c,v 1.18 2009/07/29 20:56:18 tgl Exp $
  12  *
  13  *-------------------------------------------------------------------------
  14  */
  15 #include "postgres.h"
  16
  17 #include "access/heapam.h"
  18 #include "access/tuptoaster.h"
  19 #include "access/xact.h"
  20 #include "catalog/dependency.h"
  21 #include "catalog/heap.h"
  22 #include "catalog/index.h"
  23 #include "catalog/indexing.h"
  24 #include "catalog/namespace.h"
  25 #include "catalog/pg_namespace.h"
  26 #include "catalog/pg_opclass.h"
  27 #include "catalog/pg_type.h"
  28 #include "catalog/toasting.h"
  29 #include "miscadmin.h"
  30 #include "nodes/makefuncs.h"
  31 #include "utils/builtins.h"
  32 #include "utils/syscache.h"
  33
  34
  35 static bool create_toast_table(Relation rel, Oid toastOid, Oid toastIndexOid,
  36                                    Datum reloptions, bool force);
  37 static bool needs_toast_table(Relation rel);
  38
  39
  40 /*
  41  * AlterTableCreateToastTable
  42  *              If the table needs a toast table, and doesn't already have one,
  43  *              then create a toast table for it.  (With the force option, make
  44  *              a toast table even if it appears unnecessary.)
  45  *
  46  * The caller can also specify the OID to be used for the toast table.
  47  * Usually, toastOid should be InvalidOid to allow a free OID to be assigned.
  48  * (This option, as well as the force option, is not used by core Postgres,
  49  * but is provided to support pg_migrator.)
  50  *
  51  * reloptions for the toast table can be passed, too.  Pass (Datum) 0
  52  * for default reloptions.
  53  *
  54  * We expect the caller to have verified that the relation is a table and have
  55  * already done any necessary permission checks.  Callers expect this function
  56  * to end with CommandCounterIncrement if it makes any changes.
  57  */
  58 void
  59 AlterTableCreateToastTable(Oid relOid, Oid toastOid,
  60                                                    Datum reloptions, bool force)
  61 {
  62         Relation        rel;
  63
  64         /*
  65          * Grab an exclusive lock on the target table, which we will NOT release
  66          * until end of transaction.  (This is probably redundant in all present
  67          * uses...)
  68          */
  69         rel = heap_open(relOid, AccessExclusiveLock);
  70
  71         /* create_toast_table does all the work */
  72         (void) create_toast_table(rel, toastOid, InvalidOid, reloptions, force);
  73
  74         heap_close(rel, NoLock);
  75 }
  76
  77 /*
  78  * Create a toast table during bootstrap
  79  *
  80  * Here we need to prespecify the OIDs of the toast table and its index
  81  */
  82 void
  83 BootstrapToastTable(char *relName, Oid toastOid, Oid toastIndexOid)
  84 {
  85         Relation        rel;
  86
  87         rel = heap_openrv(makeRangeVar(NULL, relName, -1), AccessExclusiveLock);
  88
  89         /* Note: during bootstrap may see uncataloged relation */
  90         if (rel->rd_rel->relkind != RELKIND_RELATION &&
  91                 rel->rd_rel->relkind != RELKIND_UNCATALOGED)
  92                 ereport(ERROR,
  93                                 (errcode(ERRCODE_WRONG_OBJECT_TYPE),
  94                                  errmsg("\"%s\" is not a table",
  95                                                 relName)));
  96
  97         /* create_toast_table does all the work */
  98         if (!create_toast_table(rel, toastOid, toastIndexOid, (Datum) 0, false))
  99                 elog(ERROR, "\"%s\" does not require a toast table",
 100                          relName);
 101
 102         heap_close(rel, NoLock);
 103 }
 104
 105
 106 /*
 107  * create_toast_table --- internal workhorse
 108  *
 109  * rel is already opened and exclusive-locked
 110  * toastOid and toastIndexOid are normally InvalidOid, but
 111  * either or both can be nonzero to specify caller-assigned OIDs
 112  */
 113 static bool
 114 create_toast_table(Relation rel, Oid toastOid, Oid toastIndexOid,
 115                                    Datum reloptions, bool force)
 116 {
 117         Oid                     relOid = RelationGetRelid(rel);
 118         HeapTuple       reltup;
 119         TupleDesc       tupdesc;
 120         bool            shared_relation;
 121         Relation        class_rel;
 122         Oid                     toast_relid;
 123         Oid                     toast_idxid;
 124         Oid                     namespaceid;
 125         char            toast_relname[NAMEDATALEN];
 126         char            toast_idxname[NAMEDATALEN];
 127         IndexInfo  *indexInfo;
 128         Oid                     classObjectId[2];
 129         int16           coloptions[2];
 130         ObjectAddress baseobject,
 131                                 toastobject;
 132
 133         /*
 134          * Toast table is shared if and only if its parent is.
 135          *
 136          * We cannot allow toasting a shared relation after initdb (because
 137          * there's no way to mark it toasted in other databases' pg_class).
 138          */
 139         shared_relation = rel->rd_rel->relisshared;
 140         if (shared_relation && !IsBootstrapProcessingMode())
 141                 ereport(ERROR,
 142                                 (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),
 143                                  errmsg("shared tables cannot be toasted after initdb")));
 144
 145         /*
 146          * Is it already toasted?
 147          */
 148         if (rel->rd_rel->reltoastrelid != InvalidOid)
 149                 return false;
 150
 151         /*
 152          * Check to see whether the table actually needs a TOAST table.
 153          *
 154          * Caller can optionally override this check.  (Note: at present no
 155          * callers in core Postgres do so, but this option is needed by
 156          * pg_migrator.)
 157          */
 158         if (!force && !needs_toast_table(rel))
 159                 return false;
 160
 161         /*
 162          * Create the toast table and its index
 163          */
 164         snprintf(toast_relname, sizeof(toast_relname),
 165                          "pg_toast_%u", relOid);
 166         snprintf(toast_idxname, sizeof(toast_idxname),
 167                          "pg_toast_%u_index", relOid);
 168
 169         /* this is pretty painful...  need a tuple descriptor */
 170         tupdesc = CreateTemplateTupleDesc(3, false);
 171         TupleDescInitEntry(tupdesc, (AttrNumber) 1,
 172                                            "chunk_id",
 173                                            OIDOID,
 174                                            -1, 0);
 175         TupleDescInitEntry(tupdesc, (AttrNumber) 2,
 176                                            "chunk_seq",
 177                                            INT4OID,
 178                                            -1, 0);
 179         TupleDescInitEntry(tupdesc, (AttrNumber) 3,
 180                                            "chunk_data",
 181                                            BYTEAOID,
 182                                            -1, 0);
 183
 184         /*
 185          * Ensure that the toast table doesn't itself get toasted, or we'll be
 186          * toast :-(.  This is essential for chunk_data because type bytea is
 187          * toastable; hit the other two just to be sure.
 188          */
 189         tupdesc->attrs[0]->attstorage = 'p';
 190         tupdesc->attrs[1]->attstorage = 'p';
 191         tupdesc->attrs[2]->attstorage = 'p';
 192
 193         /*
 194          * Toast tables for regular relations go in pg_toast; those for temp
 195          * relations go into the per-backend temp-toast-table namespace.
 196          */
 197         if (rel->rd_islocaltemp)
 198                 namespaceid = GetTempToastNamespace();
 199         else
 200                 namespaceid = PG_TOAST_NAMESPACE;
 201
 202         toast_relid = heap_create_with_catalog(toast_relname,
 203                                                                                    namespaceid,
 204                                                                                    rel->rd_rel->reltablespace,
 205                                                                                    toastOid,
 206                                                                                    rel->rd_rel->relowner,
 207                                                                                    tupdesc,
 208                                                                                    NIL,
 209                                                                                    RELKIND_TOASTVALUE,
 210                                                                                    shared_relation,
 211                                                                                    true,
 212                                                                                    0,
 213                                                                                    ONCOMMIT_NOOP,
 214                                                                                    reloptions,
 215                                                                                    true);
 216
 217         /* make the toast relation visible, else index creation will fail */
 218         CommandCounterIncrement();
 219
 220         /*
 221          * Create unique index on chunk_id, chunk_seq.
 222          *
 223          * NOTE: the normal TOAST access routines could actually function with a
 224          * single-column index on chunk_id only. However, the slice access
 225          * routines use both columns for faster access to an individual chunk. In
 226          * addition, we want it to be unique as a check against the possibility of
 227          * duplicate TOAST chunk OIDs. The index might also be a little more
 228          * efficient this way, since btree isn't all that happy with large numbers
 229          * of equal keys.
 230          */
 231
 232         indexInfo = makeNode(IndexInfo);
 233         indexInfo->ii_NumIndexAttrs = 2;
 234         indexInfo->ii_KeyAttrNumbers[0] = 1;
 235         indexInfo->ii_KeyAttrNumbers[1] = 2;
 236         indexInfo->ii_Expressions = NIL;
 237         indexInfo->ii_ExpressionsState = NIL;
 238         indexInfo->ii_Predicate = NIL;
 239         indexInfo->ii_PredicateState = NIL;
 240         indexInfo->ii_Unique = true;
 241         indexInfo->ii_ReadyForInserts = true;
 242         indexInfo->ii_Concurrent = false;
 243         indexInfo->ii_BrokenHotChain = false;
 244
 245         classObjectId[0] = OID_BTREE_OPS_OID;
 246         classObjectId[1] = INT4_BTREE_OPS_OID;
 247
 248         coloptions[0] = 0;
 249         coloptions[1] = 0;
 250
 251         toast_idxid = index_create(toast_relid, toast_idxname, toastIndexOid,
 252                                                            indexInfo,
 253                                                            BTREE_AM_OID,
 254                                                            rel->rd_rel->reltablespace,
 255                                                            classObjectId, coloptions, (Datum) 0,
 256                                                            true, false, false, false,
 257                                                            true, false, false);
 258
 259         /*
 260          * Store the toast table's OID in the parent relation's pg_class row
 261          */
 262         class_rel = heap_open(RelationRelationId, RowExclusiveLock);
 263
 264         reltup = SearchSysCacheCopy(RELOID,
 265                                                                 ObjectIdGetDatum(relOid),
 266                                                                 0, 0, 0);
 267         if (!HeapTupleIsValid(reltup))
 268                 elog(ERROR, "cache lookup failed for relation %u", relOid);
 269
 270         ((Form_pg_class) GETSTRUCT(reltup))->reltoastrelid = toast_relid;
 271
 272         if (!IsBootstrapProcessingMode())
 273         {
 274                 /* normal case, use a transactional update */
 275                 simple_heap_update(class_rel, &reltup->t_self, reltup);
 276
 277                 /* Keep catalog indexes current */
 278                 CatalogUpdateIndexes(class_rel, reltup);
 279         }
 280         else
 281         {
 282                 /* While bootstrapping, we cannot UPDATE, so overwrite in-place */
 283                 heap_inplace_update(class_rel, reltup);
 284         }
 285
 286         heap_freetuple(reltup);
 287
 288         heap_close(class_rel, RowExclusiveLock);
 289
 290         /*
 291          * Register dependency from the toast table to the master, so that the
 292          * toast table will be deleted if the master is.  Skip this in bootstrap
 293          * mode.
 294          */
 295         if (!IsBootstrapProcessingMode())
 296         {
 297                 baseobject.classId = RelationRelationId;
 298                 baseobject.objectId = relOid;
 299                 baseobject.objectSubId = 0;
 300                 toastobject.classId = RelationRelationId;
 301                 toastobject.objectId = toast_relid;
 302                 toastobject.objectSubId = 0;
 303
 304                 recordDependencyOn(&toastobject, &baseobject, DEPENDENCY_INTERNAL);
 305         }
 306
 307         /*
 308          * Make changes visible
 309          */
 310         CommandCounterIncrement();
 311
 312         return true;
 313 }
 314
 315 /*
 316  * Check to see whether the table needs a TOAST table.  It does only if
 317  * (1) there are any toastable attributes, and (2) the maximum length
 318  * of a tuple could exceed TOAST_TUPLE_THRESHOLD.  (We don't want to
 319  * create a toast table for something like "f1 varchar(20)".)
 320  */
 321 static bool
 322 needs_toast_table(Relation rel)
 323 {
 324         int32           data_length = 0;
 325         bool            maxlength_unknown = false;
 326         bool            has_toastable_attrs = false;
 327         TupleDesc       tupdesc;
 328         Form_pg_attribute *att;
 329         int32           tuple_length;
 330         int                     i;
 331
 332         tupdesc = rel->rd_att;
 333         att = tupdesc->attrs;
 334
 335         for (i = 0; i < tupdesc->natts; i++)
 336         {
 337                 if (att[i]->attisdropped)
 338                         continue;
 339                 data_length = att_align_nominal(data_length, att[i]->attalign);
 340                 if (att[i]->attlen > 0)
 341                 {
 342                         /* Fixed-length types are never toastable */
 343                         data_length += att[i]->attlen;
 344                 }
 345                 else
 346                 {
 347                         int32           maxlen = type_maximum_size(att[i]->atttypid,
 348                                                                                                    att[i]->atttypmod);
 349
 350                         if (maxlen < 0)
 351                                 maxlength_unknown = true;
 352                         else
 353                                 data_length += maxlen;
 354                         if (att[i]->attstorage != 'p')
 355                                 has_toastable_attrs = true;
 356                 }
 357         }
 358         if (!has_toastable_attrs)
 359                 return false;                   /* nothing to toast? */
 360         if (maxlength_unknown)
 361                 return true;                    /* any unlimited-length attrs? */
 362         tuple_length = MAXALIGN(offsetof(HeapTupleHeaderData, t_bits) +
 363                                                         BITMAPLEN(tupdesc->natts)) +
 364                 MAXALIGN(data_length);
 365         return (tuple_length > TOAST_TUPLE_THRESHOLD);
 366 }