← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/storage-toast.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/storage-toast.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>TOAST</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.1beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="Database Physical Storage"
 
16
HREF="storage.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Database File Layout"
 
19
HREF="storage-file-layout.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="Free Space Map"
 
22
HREF="storage-fsm.html"><LINK
 
23
REL="STYLESHEET"
 
24
TYPE="text/css"
 
25
HREF="stylesheet.css"><META
 
26
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2011-04-27T21:20:33"></HEAD
 
30
><BODY
 
31
CLASS="SECT1"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.1beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="Database File Layout"
 
57
HREF="storage-file-layout.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="Database Physical Storage"
 
67
HREF="storage.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
>Chapter 55. Database Physical Storage</TD
 
75
><TD
 
76
WIDTH="10%"
 
77
ALIGN="right"
 
78
VALIGN="top"
 
79
><A
 
80
TITLE="Database Physical Storage"
 
81
HREF="storage.html"
 
82
>Fast Forward</A
 
83
></TD
 
84
><TD
 
85
WIDTH="10%"
 
86
ALIGN="right"
 
87
VALIGN="top"
 
88
><A
 
89
TITLE="Free Space Map"
 
90
HREF="storage-fsm.html"
 
91
ACCESSKEY="N"
 
92
>Next</A
 
93
></TD
 
94
></TR
 
95
></TABLE
 
96
><HR
 
97
ALIGN="LEFT"
 
98
WIDTH="100%"></DIV
 
99
><DIV
 
100
CLASS="SECT1"
 
101
><H1
 
102
CLASS="SECT1"
 
103
><A
 
104
NAME="STORAGE-TOAST"
 
105
>55.2. TOAST</A
 
106
></H1
 
107
><P
 
108
>This section provides an overview of <ACRONYM
 
109
CLASS="ACRONYM"
 
110
>TOAST</ACRONYM
 
111
> (The
 
112
Oversized-Attribute Storage Technique).</P
 
113
><P
 
114
><SPAN
 
115
CLASS="PRODUCTNAME"
 
116
>PostgreSQL</SPAN
 
117
> uses a fixed page size (commonly
 
118
8 kB), and does not allow tuples to span multiple pages.  Therefore,  it is
 
119
not possible to store very large field values directly.  To overcome
 
120
this limitation, large  field values are compressed and/or broken up into
 
121
multiple physical rows. This happens transparently to the user, with only
 
122
small impact on most of the backend code.  The technique is affectionately
 
123
known as <ACRONYM
 
124
CLASS="ACRONYM"
 
125
>TOAST</ACRONYM
 
126
>  (or <SPAN
 
127
CLASS="QUOTE"
 
128
>"the best thing since sliced bread"</SPAN
 
129
>).</P
 
130
><P
 
131
>Only certain data types support <ACRONYM
 
132
CLASS="ACRONYM"
 
133
>TOAST</ACRONYM
 
134
> &mdash; there is no need to
 
135
impose the overhead on data types that cannot produce large field values.
 
136
To support <ACRONYM
 
137
CLASS="ACRONYM"
 
138
>TOAST</ACRONYM
 
139
>, a data type must have a variable-length
 
140
(<I
 
141
CLASS="FIRSTTERM"
 
142
>varlena</I
 
143
>) representation, in which the first 32-bit word of any
 
144
stored value contains the total length of the value in bytes (including
 
145
itself).  <ACRONYM
 
146
CLASS="ACRONYM"
 
147
>TOAST</ACRONYM
 
148
> does not constrain the rest of the representation.
 
149
All the C-level functions supporting a <ACRONYM
 
150
CLASS="ACRONYM"
 
151
>TOAST</ACRONYM
 
152
>-able data type must
 
153
be careful to handle <ACRONYM
 
154
CLASS="ACRONYM"
 
155
>TOAST</ACRONYM
 
156
>ed input values.  (This is normally done
 
157
by invoking <CODE
 
158
CLASS="FUNCTION"
 
159
>PG_DETOAST_DATUM</CODE
 
160
> before doing anything with an input
 
161
value, but in some cases more efficient approaches are possible.)</P
 
162
><P
 
163
><ACRONYM
 
164
CLASS="ACRONYM"
 
165
>TOAST</ACRONYM
 
166
> usurps two bits of the varlena length word (the high-order
 
167
bits on big-endian machines, the low-order bits on little-endian machines),
 
168
thereby limiting the logical size of any value of a <ACRONYM
 
169
CLASS="ACRONYM"
 
170
>TOAST</ACRONYM
 
171
>-able
 
172
data type to 1 GB (2<SUP
 
173
>30</SUP
 
174
> - 1 bytes).  When both bits are zero,
 
175
the value is an ordinary un-<ACRONYM
 
176
CLASS="ACRONYM"
 
177
>TOAST</ACRONYM
 
178
>ed value of the data type, and
 
179
the remaining bits of the length word give the total datum size (including
 
180
length word) in bytes.  When the highest-order or lowest-order bit is set,
 
181
the value has only a single-byte header instead of the normal four-byte
 
182
header, and the remaining bits give the total datum size (including length
 
183
byte) in bytes.  As a special case, if the remaining bits are all zero
 
184
(which would be impossible for a self-inclusive length), the value is a
 
185
pointer to out-of-line data stored in a separate TOAST table.  (The size of
 
186
a TOAST pointer is given in the second byte of the datum.)
 
187
Values with single-byte headers aren't aligned on any particular
 
188
boundary, either.  Lastly, when the highest-order or lowest-order bit is
 
189
clear but the adjacent bit is set, the content of the datum has been
 
190
compressed and must be decompressed before use.  In this case the remaining
 
191
bits of the length word give the total size of the compressed datum, not the
 
192
original data.  Note that compression is also possible for out-of-line data
 
193
but the varlena header does not tell whether it has occurred &mdash;
 
194
the content of the TOAST pointer tells that, instead.</P
 
195
><P
 
196
>If any of the columns of a table are <ACRONYM
 
197
CLASS="ACRONYM"
 
198
>TOAST</ACRONYM
 
199
>-able, the table will
 
200
have an associated <ACRONYM
 
201
CLASS="ACRONYM"
 
202
>TOAST</ACRONYM
 
203
> table, whose OID is stored in the table's
 
204
<TT
 
205
CLASS="STRUCTNAME"
 
206
>pg_class</TT
 
207
>.<TT
 
208
CLASS="STRUCTFIELD"
 
209
>reltoastrelid</TT
 
210
> entry.  Out-of-line
 
211
<ACRONYM
 
212
CLASS="ACRONYM"
 
213
>TOAST</ACRONYM
 
214
>ed values are kept in the <ACRONYM
 
215
CLASS="ACRONYM"
 
216
>TOAST</ACRONYM
 
217
> table, as
 
218
described in more detail below.</P
 
219
><P
 
220
>The compression technique used is a fairly simple and very fast member
 
221
of the LZ family of compression techniques.  See
 
222
<TT
 
223
CLASS="FILENAME"
 
224
>src/backend/utils/adt/pg_lzcompress.c</TT
 
225
> for the details.</P
 
226
><P
 
227
>Out-of-line values are divided (after compression if used) into chunks of at
 
228
most <TT
 
229
CLASS="SYMBOL"
 
230
>TOAST_MAX_CHUNK_SIZE</TT
 
231
> bytes (by default this value is chosen
 
232
so that four chunk rows will fit on a page, making it about 2000 bytes).
 
233
Each chunk is stored
 
234
as a separate row in the <ACRONYM
 
235
CLASS="ACRONYM"
 
236
>TOAST</ACRONYM
 
237
> table for the owning table.  Every
 
238
<ACRONYM
 
239
CLASS="ACRONYM"
 
240
>TOAST</ACRONYM
 
241
> table has the columns <TT
 
242
CLASS="STRUCTFIELD"
 
243
>chunk_id</TT
 
244
> (an OID
 
245
identifying the particular <ACRONYM
 
246
CLASS="ACRONYM"
 
247
>TOAST</ACRONYM
 
248
>ed value),
 
249
<TT
 
250
CLASS="STRUCTFIELD"
 
251
>chunk_seq</TT
 
252
> (a sequence number for the chunk within its value),
 
253
and <TT
 
254
CLASS="STRUCTFIELD"
 
255
>chunk_data</TT
 
256
> (the actual data of the chunk).  A unique index
 
257
on <TT
 
258
CLASS="STRUCTFIELD"
 
259
>chunk_id</TT
 
260
> and <TT
 
261
CLASS="STRUCTFIELD"
 
262
>chunk_seq</TT
 
263
> provides fast
 
264
retrieval of the values.  A pointer datum representing an out-of-line
 
265
<ACRONYM
 
266
CLASS="ACRONYM"
 
267
>TOAST</ACRONYM
 
268
>ed value therefore needs to store the OID of the
 
269
<ACRONYM
 
270
CLASS="ACRONYM"
 
271
>TOAST</ACRONYM
 
272
> table in which to look and the OID of the specific value
 
273
(its <TT
 
274
CLASS="STRUCTFIELD"
 
275
>chunk_id</TT
 
276
>).  For convenience, pointer datums also store the
 
277
logical datum size (original uncompressed data length) and actual stored size
 
278
(different if compression was applied).  Allowing for the varlena header bytes,
 
279
the total size of a <ACRONYM
 
280
CLASS="ACRONYM"
 
281
>TOAST</ACRONYM
 
282
> pointer datum is therefore 18 bytes
 
283
regardless of the actual size of the represented value.</P
 
284
><P
 
285
>The <ACRONYM
 
286
CLASS="ACRONYM"
 
287
>TOAST</ACRONYM
 
288
> code is triggered only
 
289
when a row value to be stored in a table is wider than
 
290
<TT
 
291
CLASS="SYMBOL"
 
292
>TOAST_TUPLE_THRESHOLD</TT
 
293
> bytes (normally 2 kB).
 
294
The <ACRONYM
 
295
CLASS="ACRONYM"
 
296
>TOAST</ACRONYM
 
297
> code will compress and/or move
 
298
field values out-of-line until the row value is shorter than
 
299
<TT
 
300
CLASS="SYMBOL"
 
301
>TOAST_TUPLE_TARGET</TT
 
302
> bytes (also normally 2 kB)
 
303
or no more gains can be had.  During an UPDATE
 
304
operation, values of unchanged fields are normally preserved as-is; so an
 
305
UPDATE of a row with out-of-line values incurs no <ACRONYM
 
306
CLASS="ACRONYM"
 
307
>TOAST</ACRONYM
 
308
> costs if
 
309
none of the out-of-line values change.</P
 
310
><P
 
311
>The <ACRONYM
 
312
CLASS="ACRONYM"
 
313
>TOAST</ACRONYM
 
314
> code recognizes four different strategies for storing
 
315
<ACRONYM
 
316
CLASS="ACRONYM"
 
317
>TOAST</ACRONYM
 
318
>-able columns:
 
319
 
 
320
   <P
 
321
></P
 
322
></P><UL
 
323
><LI
 
324
><P
 
325
>      <TT
 
326
CLASS="LITERAL"
 
327
>PLAIN</TT
 
328
> prevents either compression or
 
329
      out-of-line storage; furthermore it disables use of single-byte headers
 
330
      for varlena types.
 
331
      This is the only possible strategy for
 
332
      columns of non-<ACRONYM
 
333
CLASS="ACRONYM"
 
334
>TOAST</ACRONYM
 
335
>-able data types.
 
336
     </P
 
337
></LI
 
338
><LI
 
339
><P
 
340
>      <TT
 
341
CLASS="LITERAL"
 
342
>EXTENDED</TT
 
343
> allows both compression and out-of-line
 
344
      storage.  This is the default for most <ACRONYM
 
345
CLASS="ACRONYM"
 
346
>TOAST</ACRONYM
 
347
>-able data types.
 
348
      Compression will be attempted first, then out-of-line storage if
 
349
      the row is still too big.
 
350
     </P
 
351
></LI
 
352
><LI
 
353
><P
 
354
>      <TT
 
355
CLASS="LITERAL"
 
356
>EXTERNAL</TT
 
357
> allows out-of-line storage but not
 
358
      compression.  Use of <TT
 
359
CLASS="LITERAL"
 
360
>EXTERNAL</TT
 
361
> will
 
362
      make substring operations on wide <TT
 
363
CLASS="TYPE"
 
364
>text</TT
 
365
> and
 
366
      <TT
 
367
CLASS="TYPE"
 
368
>bytea</TT
 
369
> columns faster (at the penalty of increased storage
 
370
      space) because these operations are optimized to fetch only the
 
371
      required parts of the out-of-line value when it is not compressed.
 
372
     </P
 
373
></LI
 
374
><LI
 
375
><P
 
376
>      <TT
 
377
CLASS="LITERAL"
 
378
>MAIN</TT
 
379
> allows compression but not out-of-line
 
380
      storage.  (Actually, out-of-line storage will still be performed
 
381
      for such columns, but only as a last resort when there is no other
 
382
      way to make the row small enough to fit on a page.)
 
383
     </P
 
384
></LI
 
385
></UL
 
386
><P>
 
387
 
 
388
Each <ACRONYM
 
389
CLASS="ACRONYM"
 
390
>TOAST</ACRONYM
 
391
>-able data type specifies a default strategy for columns
 
392
of that data type, but the strategy for a given table column can be altered
 
393
with <TT
 
394
CLASS="COMMAND"
 
395
>ALTER TABLE SET STORAGE</TT
 
396
>.</P
 
397
><P
 
398
>This scheme has a number of advantages compared to a more straightforward
 
399
approach such as allowing row values to span pages.  Assuming that queries are
 
400
usually qualified by comparisons against relatively small key values, most of
 
401
the work of the executor will be done using the main row entry. The big values
 
402
of <ACRONYM
 
403
CLASS="ACRONYM"
 
404
>TOAST</ACRONYM
 
405
>ed attributes will only be pulled out (if selected at all)
 
406
at the time the result set is sent to the client. Thus, the main table is much
 
407
smaller and more of its rows fit in the shared buffer cache than would be the
 
408
case without any out-of-line storage. Sort sets shrink also, and sorts will
 
409
more often be done entirely in memory. A little test showed that a table
 
410
containing typical HTML pages and their URLs was stored in about half of the
 
411
raw data size including the <ACRONYM
 
412
CLASS="ACRONYM"
 
413
>TOAST</ACRONYM
 
414
> table, and that the main table
 
415
contained only about 10% of the entire data (the URLs and some small HTML
 
416
pages). There was no run time difference compared to an un-<ACRONYM
 
417
CLASS="ACRONYM"
 
418
>TOAST</ACRONYM
 
419
>ed
 
420
comparison table, in which all the HTML pages were cut down to 7 kB to fit.</P
 
421
></DIV
 
422
><DIV
 
423
CLASS="NAVFOOTER"
 
424
><HR
 
425
ALIGN="LEFT"
 
426
WIDTH="100%"><TABLE
 
427
SUMMARY="Footer navigation table"
 
428
WIDTH="100%"
 
429
BORDER="0"
 
430
CELLPADDING="0"
 
431
CELLSPACING="0"
 
432
><TR
 
433
><TD
 
434
WIDTH="33%"
 
435
ALIGN="left"
 
436
VALIGN="top"
 
437
><A
 
438
HREF="storage-file-layout.html"
 
439
ACCESSKEY="P"
 
440
>Prev</A
 
441
></TD
 
442
><TD
 
443
WIDTH="34%"
 
444
ALIGN="center"
 
445
VALIGN="top"
 
446
><A
 
447
HREF="index.html"
 
448
ACCESSKEY="H"
 
449
>Home</A
 
450
></TD
 
451
><TD
 
452
WIDTH="33%"
 
453
ALIGN="right"
 
454
VALIGN="top"
 
455
><A
 
456
HREF="storage-fsm.html"
 
457
ACCESSKEY="N"
 
458
>Next</A
 
459
></TD
 
460
></TR
 
461
><TR
 
462
><TD
 
463
WIDTH="33%"
 
464
ALIGN="left"
 
465
VALIGN="top"
 
466
>Database File Layout</TD
 
467
><TD
 
468
WIDTH="34%"
 
469
ALIGN="center"
 
470
VALIGN="top"
 
471
><A
 
472
HREF="storage.html"
 
473
ACCESSKEY="U"
 
474
>Up</A
 
475
></TD
 
476
><TD
 
477
WIDTH="33%"
 
478
ALIGN="right"
 
479
VALIGN="top"
 
480
>Free Space Map</TD
 
481
></TR
 
482
></TABLE
 
483
></DIV
 
484
></BODY
 
485
></HTML
 
486
>
 
 
b'\\ No newline at end of file'