From 9bb955c8286c20474b5462eea3e3cf76c694d88f Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 18 Feb 2015 22:33:39 -0500 Subject: Update assorted TOAST-related documentation. While working on documentation for expanded arrays, I noticed a number of details in the TOAST-related documentation that were already inaccurate or obsolete. This should be fixed independently of whether expanded arrays get in or not. One issue is that the already existing indirect-pointer facility was not documented at all. Also, the documentation says that you only need to use VARSIZE/SET_VARSIZE if you've made your variable-length type TOAST-aware, but actually we've forced that business on all varlena types even if they've opted out of TOAST by setting storage = plain. Wordsmith a few other things too, like an amusingly archaic claim that there are few 64-bit machines. I thought about back-patching this, but since all this doco is oriented to hackers and C-coded extension authors, fixing it in HEAD is probably good enough. --- doc/src/sgml/ref/create_type.sgml | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) (limited to 'doc/src/sgml/ref') diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml index e5d7992bbf5..f9e1297d0b0 100644 --- a/doc/src/sgml/ref/create_type.sgml +++ b/doc/src/sgml/ref/create_type.sgml @@ -329,15 +329,17 @@ CREATE TYPE name to VARIABLE. (Internally, this is represented by setting typlen to -1.) The internal representation of all variable-length types must start with a 4-byte integer giving the total - length of this value of the type. + length of this value of the type. (Note that the length field is often + encoded, as described in ; it's unwise + to access it directly.) The optional flag PASSEDBYVALUE indicates that values of this data type are passed by value, rather than by - reference. You cannot pass by value types whose internal - representation is larger than the size of the Datum type - (4 bytes on most machines, 8 bytes on a few). + reference. Types passed by value must be fixed-length, and their internal + representation cannot be larger than the size of the Datum type + (4 bytes on some machines, 8 bytes on others). @@ -367,6 +369,17 @@ CREATE TYPE name external items.) + + All storage values other + than plain imply that the functions of the data type + can handle values that have been toasted, as described + in and . + The specific other value given merely determines the default TOAST + storage strategy for columns of a toastable data type; users can pick + other strategies for individual columns using ALTER TABLE + SET STORAGE. + + The like_type parameter provides an alternative method for specifying the basic representation @@ -465,8 +478,8 @@ CREATE TYPE name identical things, and you want to allow these things to be accessed directly by subscripting, in addition to whatever operations you plan to provide for the type as a whole. For example, type point - is represented as just two floating-point numbers, each can be accessed using - point[0] and point[1]. + is represented as just two floating-point numbers, which can be accessed + using point[0] and point[1]. Note that this facility only works for fixed-length types whose internal form is exactly a sequence of identical fixed-length fields. A subscriptable -- cgit v1.2.3