To: Jay Levitt <jay.levitt@gmail.com>
cc: "pgsql-docs@postgresql.org" <pgsql-docs@postgresql.org>
Subject: Re: [PATCH] Use idiomatic style for varlena structs 
In-reply-to: <4F392203.2040907@gmail.com> 
References: <4F392203.2040907@gmail.com>
Comments: In-reply-to Jay Levitt <jay.levitt@gmail.com>
	message dated "Mon, 13 Feb 2012 09:45:23 -0500"
Date: Mon, 13 Feb 2012 10:51:51 -0500
Message-ID: <10780.1329148311@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>

Jay Levitt <jay.levitt@gmail.com> writes:
> I'm new to the codebase, but I think this patch reflects real-world usage; 
> the PostgreSQL code itself always calls the length field "vl_len_", and I 
> believe int32 is preferred over int4 (yes?)

The point of calling it vl_len_ is that it should never be referenced by
that name, so I'm not sure that propagating that name into user
documentation is a good idea.  I do agree with the part of this patch
that recommends use of SET_VARSIZE.

For context, the issues you're concerned about only matter when dealing
with a toastable datatype (not all varlena types are toastable).  The
particular bit of docs here doesn't pretend to be explaining how to
write toast-safe code.  I think it might be better from an expository
standpoint to cover that separately, rather than try to work it into the
very first pass over the concepts.

			regards, tom lane