Thread: GUC and postgresql.conf docs

GUC and postgresql.conf docs

From
Josh Berkus
Date:
Folks,

I'm trying to prepare comprehensive documentation on the contents of the
postgresql.conf file for 7.3.2.   However, I'm running into some confusion in
the docs (which is why I'm preparing the document in the first place).

Can I aassume that any setting documented under "3.4. Run-time Configuration"
is a GUC variable modifiable through a SET statement?  If not, where can I
find documenation on which .conf settings are GUC variables and which are
not?

Thanks ... this'll go up at Techdocs when I have a draft together.

--
Josh Berkus
Aglio Database Solutions
San Francisco



Re: GUC and postgresql.conf docs

From
Tom Lane
Date:
Josh Berkus <josh@agliodbs.com> writes:
> Can I aassume that any setting documented under "3.4. Run-time Configuration"
> is a GUC variable modifiable through a SET statement?  If not, where can I 
> find documenation on which .conf settings are GUC variables and which are 
> not?

Use the source, Luke.

The tables in src/backend/utils/misc/guc.c are the authoritative reference.
Read the comments in src/include/utils/guc.h first.

Yes, everything in postgresql.conf is a GUC variable; but I think there
may be some GUC variables that were omitted from postgresql.conf.
Hopefully intentionally, not by oversight ...
        regards, tom lane



Re: GUC and postgresql.conf docs

From
Peter Eisentraut
Date:
Josh Berkus writes:

> Can I aassume that any setting documented under "3.4. Run-time Configuration"
> is a GUC variable

Yes, although "GUC" is not an official term that is defined anywhere.

> modifiable through a SET statement?

No, some of them say that they can only be set at server start.  But you
can run SHOW on all of them.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: GUC and postgresql.conf docs

From
Josh Berkus
Date:
Tom,

> The tables in src/backend/utils/misc/guc.c are the authoritative reference.
> Read the comments in src/include/utils/guc.h first.

Thanks.   Would never have found it on my own ...

> Yes, everything in postgresql.conf is a GUC variable; but I think there
> may be some GUC variables that were omitted from postgresql.conf.
> Hopefully intentionally, not by oversight ...

Mmm?   I think I have some terminology confusion somewhere.  I thought that a
GUC variable meant that it could be changed through a SET statement.  But
some settings, like TCP/IP socket, cannot be SET.   What distinguises
settings that can be SET from GUC variables that are restart-only?

I sense more posts to the list in the offing.

--
Josh Berkus
Aglio Database Solutions
San Francisco



Re: GUC and postgresql.conf docs

From
Tom Lane
Date:
Josh Berkus <josh@agliodbs.com> writes:
> What distinguises 
> settings that can be SET from GUC variables that are restart-only?

The PGC_CONTEXT settings.  Go back and read those comments I pointed
you to.
        regards, tom lane



Re: GUC and postgresql.conf docs

From
Josh Berkus
Date:
Tom, Peter,

Since I had to do this anyway, I thought the following would help you clean up
a little.  Please check my report for accuracy; postgresql.conf.sample lists
the GUC variables in one order, the online documentation in another, and
guc.c in a third, completely different order.  So it's entirely possible I
missed something.

BTW, my next proposal after finishing this list will be to re-order the
variables in postgresql.conf.sample into something more logical than the
current "incremental development order".  Expect it next week.

GUC Options with no documentation:
The following options exist in postgresql.conf.sample and in guc.c but not in
the online documenation anywhere the search box can find:

trace_locks
trace_userlocks
trace_lwlocks
debug_deadlocks
trace_lock_oidmin
trace_lock_table

show_btree_build_stats


Defined in guc.c but not in PostgreSQL.conf or docs:
The following four GUC variables are defined in guc.c, but are not included in
postgresql.conf.sample, and do not show up in the online docs under anything
I can search on.  Do they do anything?  If so, what?


{"fixbtree", PGC_POSTMASTER}, &FixBTree,    true, NULL, NULL
{"pre_auth_delay", PGC_SIGHUP}, &PreAuthDelay,    0, 0, 60, NULL, NULL
{"server_encoding", PGC_USERSET}, &server_encoding_string,    "SQL_ASCII", assign_server_encoding, show_server_encoding
{"session_authorization", PGC_USERSET, GUC_NO_SHOW_ALL | GUC_NO_RESET_ALL},    &session_authorization_string,    NULL,
assign_session_authorization,show_session_authorization     

Defined in guc.c and docs but not in postgresql.conf:
These four related settings are defined guc's that somehow made it into the
docs but not into postgresql.conf.sample:

{"lc_messages", PGC_SUSET}, &locale_messages,
"", locale_messages_assign, NULL

{"lc_monetary", PGC_USERSET}, &locale_monetary,
"C", locale_monetary_assign, NULL

{"lc_numeric", PGC_USERSET}, &locale_numeric,
"C", locale_numeric_assign, NULL

{"lc_time", PGC_USERSET}, &locale_time,
"C", locale_time_assign, NULL


Hope that helps clean up for the next release!

--
Josh Berkus
Aglio Database Solutions
San Francisco



Re: GUC and postgresql.conf docs

From
Tom Lane
Date:
Josh Berkus <josh@agliodbs.com> writes:
> GUC Options with no documentation:
> The following options exist in postgresql.conf.sample and in guc.c but not in
> the online documenation anywhere the search box can find:

> trace_locks
> trace_userlocks
> trace_lwlocks
> debug_deadlocks
> trace_lock_oidmin
> trace_lock_table
> show_btree_build_stats

These are all debugging options that probably don't need to be in the
user documentation (ie, if you aren't familiar enough with the source
code to find out about 'em from there, you do not need them and should
probably not be messing with 'em --- in fact, many of them don't even
exist except in specially-hacked builds).  I'd vote for taking them out
of postgresql.conf.sample, I think.

> The following four GUC variables are defined in guc.c, but are not included in 
> postgresql.conf.sample, and do not show up in the online docs under anything 
> I can search on.  Do they do anything?  If so, what?

> {"fixbtree", PGC_POSTMASTER}, &FixBTree,
>         true, NULL, NULL

This one is gone anyway in CVS tip.

> {"pre_auth_delay", PGC_SIGHUP}, &PreAuthDelay,
>         0, 0, 60, NULL, NULL

This is another debugging option of rather questionable general
usefulness.

> {"server_encoding", PGC_USERSET}, &server_encoding_string,
>         "SQL_ASCII", assign_server_encoding, show_server_encoding

I'm not sure why this one is marked PGC_USERSET --- seems like it should
not be possible to override it from SET.  It should be documented as a
read-only option, I think.  (Looks ... actually it is set up that way
in CVS tip.)

> {"session_authorization", PGC_USERSET, GUC_NO_SHOW_ALL | GUC_NO_RESET_ALL},
>         &session_authorization_string,
>         NULL, assign_session_authorization, show_session_authorization

This one makes no sense to set in postgresql.conf, certainly.  Not sure
how the docs ought to describe it.

> These four related settings are defined guc's that somehow made it into the 
> docs but not into postgresql.conf.sample:

> {"lc_messages", PGC_SUSET}, &locale_messages,
> "", locale_messages_assign, NULL
> {"lc_monetary", PGC_USERSET}, &locale_monetary,
> "C", locale_monetary_assign, NULL
> {"lc_numeric", PGC_USERSET}, &locale_numeric,
> "C", locale_numeric_assign, NULL
> {"lc_time", PGC_USERSET}, &locale_time,
> "C", locale_time_assign, NULL

These guys are added to postgresql.conf by initdb, so I think that's
okay.  But perhaps that process could be documented better.
        regards, tom lane



Re: GUC and postgresql.conf docs

From
Peter Eisentraut
Date:
Tom Lane writes:

> > {"server_encoding", PGC_USERSET}, &server_encoding_string,
> >         "SQL_ASCII", assign_server_encoding, show_server_encoding
>
> I'm not sure why this one is marked PGC_USERSET --- seems like it should
> not be possible to override it from SET.  It should be documented as a
> read-only option, I think.  (Looks ... actually it is set up that way
> in CVS tip.)

Do we even need this one?  If you want to find out the server encoding
(which should be rare anyway), you can select it from pg_database.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: GUC and postgresql.conf docs

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> {"server_encoding", PGC_USERSET}, &server_encoding_string,
> "SQL_ASCII", assign_server_encoding, show_server_encoding

> Do we even need this one?  If you want to find out the server encoding
> (which should be rare anyway), you can select it from pg_database.

This is now in the same class as server_version, i.e., it's a read-only
GUC variable.  I did it that way so that these values could be
transmitted to the frontend via the new 3.0 protocol's ParameterStatus
mechanism.

I know we have a difference of opinion about the cleanliness of
read-only "variables", but I think it's a reasonable approach to take.
It certainly beats inventing a mechanism that duplicates the display
portions of GUC.  For instance, isn't "show lc_collate" a lot better
than having to run pg_controldata to find out the database locale?
        regards, tom lane



Re: GUC and postgresql.conf docs

From
Peter Eisentraut
Date:
Tom Lane writes:

> This is now in the same class as server_version, i.e., it's a read-only
> GUC variable.  I did it that way so that these values could be
> transmitted to the frontend via the new 3.0 protocol's ParameterStatus
> mechanism.

Do we need to communicate the server encoding during any part of the
protocol?  ISTM that the server encoding shouldn't ever be needed by a
client for computation, except out of pure interest.

> For instance, isn't "show lc_collate" a lot better than having to run
> pg_controldata to find out the database locale?

No, because you would like to be able to see it inside an SQL session.
But the server encoding can already be fetched inside an SQL session from
the official source.  A read-only parameter to make this information
available in a different way just seems wasteful.  We don't have read-only
parameters for any of the other columns in pg_database either.

-- 
Peter Eisentraut   peter_e@gmx.net



Re: GUC and postgresql.conf docs

From
Josh Berkus
Date:
Guys,

One dumb question:

What numbers are INT_MAX and DBL_MAX in C?

--
Josh Berkus
Aglio Database Solutions
San Francisco



Re: GUC and postgresql.conf docs

From
Larry Rosenman
Date:

--On Tuesday, May 13, 2003 09:16:44 -0700 Josh Berkus <josh@agliodbs.com> 
wrote:

> Guys,
>
> One dumb question:
>
> What numbers are INT_MAX and DBL_MAX in C?
The maximum for that type that can be represented.  It's platform dependent.

on FreeBSD 4:
#define INT_MAX         0x7fffffff      /* max value for an int */
#define DBL_MAX         1.7976931348623157E+308



-- 
Larry Rosenman                     http://www.lerctr.org/~ler
Phone: +1 972-414-9812                 E-Mail: ler@lerctr.org
US Mail: 1905 Steamboat Springs Drive, Garland, TX 75044-6749



Re: GUC and postgresql.conf docs

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> Do we need to communicate the server encoding during any part of the
> protocol?

Probably.  What if the client needs to know what is the set of
characters that can actually be stored in the database?  client_encoding
doesn't tell you the whole truth on that.  I'm also still unconvinced
that binary data I/O should perform encoding conversion (it does as of
CVS tip, but I'm not 100% sold that that's the right choice).

> But the server encoding can already be fetched inside an SQL session from
> the official source.

... if you know where to look for it, and if you know that you are not
currently in an aborted transaction, and probably a few other "if's".

> A read-only parameter to make this information
> available in a different way just seems wasteful.

It is duplicative to a certain extent, but the point is to make life
easier for client libraries.  See past discussions with Barry Lind in
particular.  The general mechanism seems necessary in any case, and
once we have it, applying it to these particular values isn't adding
much bloat.
        regards, tom lane



Re: GUC and postgresql.conf docs

From
Tom Lane
Date:
Peter Eisentraut <peter_e@gmx.net> writes:
> Tom Lane writes:
>> I'm also still unconvinced that binary data I/O should perform encoding
>> conversion (it does as of CVS tip, but I'm not 100% sold that that's the
>> right choice).

> That depends on what you intend to achieve with the binary format.  For
> some of the numeric types it's obvious, but for strings it's not.

Sorry if I wasn't clear.  Binary-encoded numeric values don't go through
encoding conversion.  Text strings currently do.  The only place where I
had any difficulty deciding what a particular datatype should do is with
the 1-byte "char" type, which has a foot in both camps.  I decided to
treat it as an unconverted single byte (but am willing to listen to
argument if anyone thinks differently).

>> The general mechanism seems necessary in any case, and once we have it,
>> applying it to these particular values isn't adding much bloat.

> But where does it stop?  What's the criterion?

Usefulness to client libraries, I think.  If anyone pops up and says "my
library really needs to know the value of setting X", I'm happy to add X
to the set of values reported by ParameterStatus.  If that set starts to
get large then I'd be willing to think about making it
run-time-configurable --- the only reason it isn't already is we don't
have enough examples to prove the need.
        regards, tom lane



Re: GUC and postgresql.conf docs

From
Peter Eisentraut
Date:
Tom Lane writes:

> > Do we need to communicate the server encoding during any part of the
> > protocol?
>
> Probably.  What if the client needs to know what is the set of
> characters that can actually be stored in the database?

That sort of thing might be interesting to know, but it does not seem to
be part of the protocol.

Anyway, you cannot answer that question reliably by looking at the server
encoding.  You need to know which conversion will be invoked and what that
conversion will do, and that is a lot harder to do programmatically.

> I'm also still unconvinced that binary data I/O should perform encoding
> conversion (it does as of CVS tip, but I'm not 100% sold that that's the
> right choice).

That depends on what you intend to achieve with the binary format.  For
some of the numeric types it's obvious, but for strings it's not.

> The general mechanism seems necessary in any case, and once we have it,
> applying it to these particular values isn't adding much bloat.

But where does it stop?  What's the criterion?

-- 
Peter Eisentraut   peter_e@gmx.net



Re: GUC and postgresql.conf docs

From
Josh Berkus
Date:
Tom, Peter,

While I'm writing this guide ... where does PostgreSQL store temp files for
queires which are too large for sort_mem?   I can't seem to find docs on
this.

--
-Josh BerkusAglio Database SolutionsSan Francisco



Re: GUC and postgresql.conf docs

From
Tom Lane
Date:
Josh Berkus <josh@agliodbs.com> writes:
> While I'm writing this guide ... where does PostgreSQL store temp files for 
> queires which are too large for sort_mem?

Each database has a temp directory.  I think it's called
$PGDATA/base/DBOID/pgsql_tmp.  You can replace that subdirectory by a
symlink if you want to put temp files someplace else.
        regards, tom lane



Re: GUC and postgresql.conf docs

From
"Zeugswetter Andreas SB SD"
Date:
> Binary-encoded numeric values don't go through
> encoding conversion.  Text strings currently do.  The only place where I
> had any difficulty deciding what a particular datatype should do is with
> the 1-byte "char" type, which has a foot in both camps.  I decided to
> treat it as an unconverted single byte (but am willing to listen to
> argument if anyone thinks differently).

One concern I would have is how to get at the raw unconverted text data
without changing the client encoding. I do not really see an advantage in
providing the same thing for text and binary format if it is now
a per column thing. I would do text unconverted if binary format is selected
for that column.

Did COPY BINARY convert text ?

Andreas


"Zeugswetter Andreas SB SD" <ZeugswetterA@spardat.at> writes:
>> Binary-encoded numeric values don't go through
>> encoding conversion.  Text strings currently do.  The only place where I
>> had any difficulty deciding what a particular datatype should do is with
>> the 1-byte "char" type, which has a foot in both camps.  I decided to
>> treat it as an unconverted single byte (but am willing to listen to
>> argument if anyone thinks differently).

> One concern I would have is how to get at the raw unconverted text data
> without changing the client encoding. I do not really see an advantage in
> providing the same thing for text and binary format if it is now 
> a per column thing. I would do text unconverted if binary format is
> selected for that column.

That's a good point: as things currently stand in CVS tip, there's
really no difference between text and binary output of textual
datatypes.  Perhaps that's how it should be, but one could make an
argument that we're missing a chance to expose possibly-useful
functionality.

> Did COPY BINARY convert text ?

COPY BINARY currently does the same conversions as binary I/O to the
client.  This is arguably reasonable when doing COPY to/from the
frontend, but it's probably not very reasonable when doing COPY to/from
a file in the server's filesystem --- there's no obvious reason why that
should be affected by client_encoding.  And yet, I'm not sure the cases
should be different either.  Wouldn't it be a bad thing if a COPY dump
made through psql's \copy didn't reload correctly through "COPY FROM
file"?

We could sidestep that issue if binary I/O for text was in server
encoding in all cases.
        regards, tom lane


Re: GUC and postgresql.conf docs

From
Bruce Momjian
Date:
Tom Lane wrote:
> Josh Berkus <josh@agliodbs.com> writes:
> > GUC Options with no documentation:
> > The following options exist in postgresql.conf.sample and in guc.c but not in
> > the online documenation anywhere the search box can find:
> 
> > trace_locks
> > trace_userlocks
> > trace_lwlocks
> > debug_deadlocks
> > trace_lock_oidmin
> > trace_lock_table
> > show_btree_build_stats
> 
> These are all debugging options that probably don't need to be in the
> user documentation (ie, if you aren't familiar enough with the source
> code to find out about 'em from there, you do not need them and should
> probably not be messing with 'em --- in fact, many of them don't even
> exist except in specially-hacked builds).  I'd vote for taking them out
> of postgresql.conf.sample, I think.

Agreed, they should not be in postgresql.conf.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: GUC and postgresql.conf docs

From
Bruce Momjian
Date:
Josh Berkus wrote:
> Tom, Peter,
> 
> While I'm writing this guide ... where does PostgreSQL store temp files for 
> queires which are too large for sort_mem?   I can't seem to find docs on 
> this.

They exist under each database directory in /pgsql_tmp.

--  Bruce Momjian                        |  http://candle.pha.pa.us pgman@candle.pha.pa.us               |  (610)
359-1001+  If your life is a hard drive,     |  13 Roberts Road +  Christ can be your backup.        |  Newtown Square,
Pennsylvania19073
 


Re: Client encoding conversion for binary data (was Re:

From
Peter Eisentraut
Date:
Tom Lane writes:

> That's a good point: as things currently stand in CVS tip, there's
> really no difference between text and binary output of textual
> datatypes.  Perhaps that's how it should be, but one could make an
> argument that we're missing a chance to expose possibly-useful
> functionality.

Let's look at this in a broader context.  Depending on the data type,
there may be zero, one, or more useful text formats and zero, one, or more
useful binary formats.  The general rule ought to be that text formats are
subject to character set conversion, and the binary formats are not.

For example, the type timestamp might have:

text format "ISO"
text format "German"
binary format "struct tm"
binary format "time_t"

and possibly others.  I would expect the format two to be subject to
character set conversion, but the latter two not.

That same rule applied to character types would say that the "normal" text
format is subject to character set conversion (of course), and any other
text format (whatever that would be) would also be.  Any binary format for
character types would not be subject to character set conversion.  But
that does not say what would be in that binary format.  It could be the
internal server encoding representation or mule internal code or the data
preconverted to the client encoding outside the automatic mechanisms or
anything else.  Unless someone can come up with a binary representation
that would be genuinely useful, the simplest answer would be that
character types don't have one and you have to use the text format.

-- 
Peter Eisentraut   peter_e@gmx.net



Peter Eisentraut <peter_e@gmx.net> writes:
> That same rule applied to character types would say that the "normal" text
> format is subject to character set conversion (of course), and any other
> text format (whatever that would be) would also be.  Any binary format for
> character types would not be subject to character set conversion.  But
> that does not say what would be in that binary format.  It could be the
> internal server encoding representation or mule internal code or the data
> preconverted to the client encoding outside the automatic mechanisms or
> anything else.

True.

> Unless someone can come up with a binary representation
> that would be genuinely useful, the simplest answer would be that
> character types don't have one and you have to use the text format.

You're prejudging the question at hand, which is whether or not access
to the server-encoding representation is useful.  I'm inclined to think
that it is, particularly for backup purposes (no need to worry about
lossage from character set conversions).  Of course one can set
client_encoding equal to server_encoding to get the same effect, but
that doesn't seem to be an argument that it's not useful.
        regards, tom lane