Thread: Documentation needs significant improvement

The new website look is nice.  It's a significant improvement over the
previous version, and it's much easier to find important things.  There
are some nits but they're not the main point of this message.

I installed PostgreSQL a couple months back on a FreeBSD system, and got
it working and started evaluating it for a large conversion from another
database effort.  Then other important projects came up, and I didn't
look at PostgreSQL for a couple months.  In the meantime, we got a new
development machine in-house.  Time to install PostgreSQL 7.3.1, the
latest and greatest, and continue the effort.

I just wasted 20 minutes or so trying to re-figure out how the heck to
create the first user.  Frankly, the documentation between the step of
installing the binaries and the step of doing useful stuff with the
database sucks.

* The arrangement and order of the primary documentation is not
conducive to getting this thing up and running.

* As far as I can tell, after reading 40+ sections, and searching up and
down, it never even really tells you that you probably should create a
database (e.g. "test") first and then use that database to bootstrap
your user creation, or at least, that it MIGHT be safe to use a database
called template1 (or 0) to do this, or that those 2 database are all
that exist at this point, or even how to find out which databases, if
any, exist.

* The web formatting of said documentation is hosed.  I'm guessing it's
a result of some conversion process from a former web layout.  Some
pages flow into resized windows just fine, as all good HTML documents
should.  Others have pre-formatted monospace-font lines with missing
line breaks resulting in ridiculously wide pages which have to be
scrolled horizontally -- which makes them near unusable.

Finally, after looking elsewhere than in the "official" docuemtation, I
found a link to this site:  "PostgreSQL 101 by Shridhar Daithankar."  Lo
and behold, Sridhar says create database "test" and go from there.
Eureka.  Now I can get somewhere.

I'm not some clueless newbie who can be expected to stumble around for a
while.  I'm an expert.

It should not be this hard, folks.

On Saturday 25 January 2003 10:02 am, you wrote:
> I just wasted 20 minutes or so trying to re-figure out how the heck to
> create the first user.  Frankly, the documentation between the step of
> installing the binaries and the step of doing useful stuff with the
> database sucks.

Well, IMO, administrators guide is pretty nice. Just that if you try to do
anything before you finish reading it, chances that you will trip over
someplace.

In fact relooking at 7.3 admin guide, I would say that the order of chapters
is perfectl.

> * As far as I can tell, after reading 40+ sections, and searching up and
> down, it never even really tells you that you probably should create a
> database (e.g. "test") first and then use that database to bootstrap
> your user creation, or at least, that it MIGHT be safe to use a database
> called template1 (or 0) to do this, or that those 2 database are all
> that exist at this point, or even how to find out which databases, if
> any, exist.

Well, surely you haven't compeleted the manual reading, did you?

To quote from
http://candle.pha.pa.us/main/writings/pgsql/sgml/user-manag.html,
"Every database cluster contains a set of database users."

Then you can proceed to
http://candle.pha.pa.us/main/writings/pgsql/sgml/creating-cluster.html which
occure earlier than users page. So definition of cluster is already covered.

It is pretty clear that database users are in database cluster and can be
created even before database is created because template0 exists.

> Finally, after looking elsewhere than in the "official" docuemtation, I
> found a link to this site:  "PostgreSQL 101 by Shridhar Daithankar."  Lo
> and behold, Sridhar says create database "test" and go from there.
> Eureka.  Now I can get somewhere.

Glad that it helped you. But remember it is just one way to get things right.

> I'm not some clueless newbie who can be expected to stumble around for a
> while.  I'm an expert.

In general I agree with you that postgresql documentation is something that
should be read in one go. It is not that you can refer to a single page and
get done.

But in long term I find it an advantage. By the time you are set to do
something, either you know what to do or know where to find all relevent
stuff.

 Shridhar

Chris Johnson <chris@chaska.com> writes:
> I just wasted 20 minutes or so trying to re-figure out how the heck to
> create the first user.  Frankly, the documentation between the step of
> installing the binaries and the step of doing useful stuff with the
> database sucks.

Criticism in the form of patches would be the most helpful ;-).
I hear your pain, but it's not clear to me exactly what to fix where.
For example:

> * The web formatting of said documentation is hosed.  I'm guessing it's
> a result of some conversion process from a former web layout.  Some
> pages flow into resized windows just fine, as all good HTML documents
> should.  Others have pre-formatted monospace-font lines with missing
> line breaks resulting in ridiculously wide pages which have to be
> scrolled horizontally -- which makes them near unusable.

I use the HTML docs all the time, and it's been awhile since I saw any
pages that rendered that badly.  *Exactly which* pages are you
complaining about?  What browser are you looking at them with?

            regards, tom lane

On Fri, Jan 24, 2003 at 10:32:56PM -0600, Chris Johnson wrote:
> * The arrangement and order of the primary documentation is not
> conducive to getting this thing up and running.
[snip]
> Finally, after looking elsewhere than in the "official" docuemtation, I
> found a link to this site:  "PostgreSQL 101 by Shridhar Daithankar."  Lo
> and behold, Sridhar says create database "test" and go from there.
> Eureka.  Now I can get somewhere.
>
> I'm not some clueless newbie who can be expected to stumble around for a
> while.  I'm an expert.
>
> It should not be this hard, folks.

any chance you can help onjure a rough draft of what would have
helped you get up-to-speed? maybe we can help out the next guy
that way.

just a couple of paragraphs: "Chris's Quick-Start Guide to
PostGREsql v7.x.x". hmm?

--
There are 10 kinds of people:
ones that get binary, and ones that don't.

will@serensoft.com
http://sourceforge.net/projects/newbiedoc -- we need your brain!
http://www.dontUthink.com/ -- your brain needs us!

Looking for a firewall? Do you think smoothwall sucks? You're
probably right... Try the folks at http://clarkconnect.org/ !

On Sat, Jan 25, 2003 at 12:46:32AM -0500, Tom Lane wrote:
> Chris Johnson <chris@chaska.com> writes:
> > * The web formatting of said documentation is hosed.  I'm guessing it's
> > a result of some conversion process from a former web layout.  Some
> > pages flow into resized windows just fine, as all good HTML documents
> > should.  Others have pre-formatted monospace-font lines with missing
> > line breaks resulting in ridiculously wide pages which have to be
> > scrolled horizontally -- which makes them near unusable.
>
> I use the HTML docs all the time, and it's been awhile since I saw any
> pages that rendered that badly.  *Exactly which* pages are you
> complaining about?  What browser are you looking at them with?

i think what he's referring to might be some of the
user-contributed techdocs. the body text is wrapped in <pre>
tags so linebreaks are hard-coded; a narrow window might lead to
awkward wrapping snafus. (depends on browser's behavior, of
course...)

for example, try my regex intro at
    http://techdocs.postgresql.org/guides/RegularExpressionIntro
and make your window narrow. it might look okay -- or not...

is there a way to revisit those and allow html formatting with
<h2> and <em> and such, and let the browser's text wrapping do
its thing?

:)

--
There are 10 kinds of people:
ones that get binary, and ones that don't.

will@serensoft.com
http://sourceforge.net/projects/newbiedoc -- we need your brain!
http://www.dontUthink.com/ -- your brain needs us!

Looking for a firewall? Do you think smoothwall sucks? You're
probably right... Try the folks at http://clarkconnect.org/ !

At 12:53 AM 1/25/03 -0600, will trillich wrote:

>any chance you can help onjure a rough draft of what would have
>helped you get up-to-speed? maybe we can help out the next guy
>that way.
>
>just a couple of paragraphs: "Chris's Quick-Start Guide to
>PostGREsql v7.x.x". hmm?

The detailed HTML docs are actually fine.

And there is a short version which works. But sets up what seems to be a
quick for test install with a superuser, no other users, and no startup and
shutdown scripts.

http://www.ca.postgresql.org/users-lounge/docs/7.3/postgres/installation.html

So far that's much better than the Oracle doc I last saw- a huge thick
installation manual which is written for everyone and no one because it is
full of details for different scenarios. I had to turn to 3rd party Oracle
HOWTO to install Oracle- and it was a lot easier :).

Maybe people want an intermediate version?

 From memory my steps are usually:

Follow the INSTALL.TXT, configure, compile, regression test and if ok,
install the software.

Create a pgsql or postgres O/S user.

Set up the filesystem permissions and structure for the "database
cluster/instance".
do the initdb. Includes where you want the instance's logs to go.

Configure O/S to start postgresql instance on bootup (copy contrib scripts
over or write own using the pg_ctl stuff).

psql -U pgsql template1

alter user pgsql with password 'superuserpassword';
create user myuser with password 'blahblah' createdb;

\c - myuser
create database myuser;

edit pg_hba.conf to use passwords (note you may wish to use a different
authentication method).
restart postgresql instance.

Voila, postgresql up with one super user and one power user.

Note that most people won't want to follow my install because requiring
authentication breaks many Postgresql commandline utilities (not sure if
this is changed, since I haven't been using most of them - coz they didn't
work for me ;) ).

HTH,
Link.

I have a farily general question about structuring a database, and
considering this is the 'general' mailist for postgresql my database of
choice for the project I am working on, I thought this would be a good place
to start. Please forgive me if this should be posted elsewhere. Of course a
hint on where it should be posted would be great if this is not the correct
place to ask this.

Anyway, I am trying to come up with a logging table scheme for an
application that indexes rental properties around the world. Currently we do
not have anything in place in our current database tables to keep an
accurate ongoing tally of the hits each of these properties gets on any kind
of time interval.

What I do have is a table that keeps a running total for each property. The
way that is implimented is through a javascript function that makes a
request to a script that then updates the database table containing a unique
id for that property and then ups its count for each hit. So we have a table
that looks like...

TABLENAME:     Hits
TABLE COLUMNS:     ID_Property | hit_total | last_updated

However, we want to expand this and be able to keep a running tally of hits
per week, month, day perhaps. But I am having trouble wrapping my head
around the best way to go about doing so. A sensible table scheme escapes
me.

My first inclination was to create a table as follows...

TABLENAME:     Weekly hit total table
TABLE COLUMNS:     ID_property | week 1 | week 2 | week 3 | week 4 | etc...

That table would be populated via an automated script that would tally up
the weekly totals for each property based upon the number of hits drawn off
of a modified version of the hits table described earlier. In other words,
the current hit counter table would be cleared every week to make way for
the tally to start fresh for the next week.

The problem with the above scheme however is that I would be adding a column
to the table every week, and it just seems like bad design to do so. There
must be a better way.

To avoid having to create a table that requires that I alter its structure
every week, I thought of the following solution but It seems overkill, as it
would add a huge number of tables. Anyway, this scheme would have a seperate
table for each property with a structure something like the following.

TABLENAME:     Hit Totals for Property 'foo'
TABLE COLUMNS:     Week | weekly hit total

For every week there would be a new row added to the table, again, it would
be populated by a cron script. However, I do not like this solution as I am
not interested in having 5000 tables set up for all the properties, and then
each time one of the properties were added or deleted I have to alter the
database to add or delete tables.

to sum it up....

Solution 1 which provides a unique row for each property, seems inadaquate
because it will require adding columns to the database on each update, thus
altering the table structure on a constant basis.

Solution 2 which provides a unique table for each property in the database
seems inadaquate for the same reason as above, I am altering the database
itself all too often, not to mention I have to deal with thousands of
tables.

Considering postgreSQL is an object oriented database, and I am new to that
concept in databases, I was hoping maybe someone here had a workable
solution or suggestion that may or may not take advantage of PostgreSQL's
object oriented features. Any help or suggestions on this would be very
highly appreciated.

Thanks,
Alan

I would suggest a combination of both.  Have a table with a structure
similar to the following:
TABLENAME:  Weekly Hits
Cols: ID_Property, week_start, hits

This way, you would have a new row for each property each week.  It's
also easy to expand you search.  If you want to see how many hits a
property got between March and June, say, that's an easy query to make
(select sum(hits) from weekly_hits where week_start > '01-mar-03' and
week_start < '30-jun-03' and prop_id = 42).

Hope this helps,
Jeffrey Melloy

What I do for such tallies is create a table similar to the following:

create table activity_log (object oid, activity oid, activity_time
timestamp)

With an additional summary table:

create table activity_summary_log (object oid, activity oid, month int,
year int,  instances int);

Periodically, I summarize my tallies into the summary log:

insert into activity_summary_log (object, activity, year, month,
instances) select object, activity, extract(year from activity_timestamp)
as year, extract(month from activity_timestamp) as month, count(*) from
activity_log where extract(month from activity_timestamp) < extract(month
from CURRENT_TIMESTAMP) group by object, activity, month, year;
followed by (in the same transaction)
delete from activity_log where extract(month from activity_timestamp) <
extract(month from CURRENT_TIMESTAMP)

Then to get all my summarized data (even the ongoing tallies), I have a
view which grabs from the summary tables and summarizes the activity_log
table.  I like this setup because:

a) If my summarizing script doesn't function, I haven't lost anything.  I
just run it again when I feel like it

b) If my summarizing script is called too often, it's fine

c) I can record additional information about each transaction in my
activity log for audit purposes, which get automatically removed when I
summarize everything

Jon

On Sat, 25 Jan 2003, Alan T. Miller wrote:

> I have a farily general question about structuring a database, and
> considering this is the 'general' mailist for postgresql my database of
> choice for the project I am working on, I thought this would be a good place
> to start. Please forgive me if this should be posted elsewhere. Of course a
> hint on where it should be posted would be great if this is not the correct
> place to ask this.
>
> Anyway, I am trying to come up with a logging table scheme for an
> application that indexes rental properties around the world. Currently we do
> not have anything in place in our current database tables to keep an
> accurate ongoing tally of the hits each of these properties gets on any kind
> of time interval.
>
> What I do have is a table that keeps a running total for each property. The
> way that is implimented is through a javascript function that makes a
> request to a script that then updates the database table containing a unique
> id for that property and then ups its count for each hit. So we have a table
> that looks like...
>
> TABLENAME:     Hits
> TABLE COLUMNS:     ID_Property | hit_total | last_updated
>
> However, we want to expand this and be able to keep a running tally of hits
> per week, month, day perhaps. But I am having trouble wrapping my head
> around the best way to go about doing so. A sensible table scheme escapes
> me.
>
> My first inclination was to create a table as follows...
>
> TABLENAME:     Weekly hit total table
> TABLE COLUMNS:     ID_property | week 1 | week 2 | week 3 | week 4 | etc...
>
> That table would be populated via an automated script that would tally up
> the weekly totals for each property based upon the number of hits drawn off
> of a modified version of the hits table described earlier. In other words,
> the current hit counter table would be cleared every week to make way for
> the tally to start fresh for the next week.
>
> The problem with the above scheme however is that I would be adding a column
> to the table every week, and it just seems like bad design to do so. There
> must be a better way.
>
> To avoid having to create a table that requires that I alter its structure
> every week, I thought of the following solution but It seems overkill, as it
> would add a huge number of tables. Anyway, this scheme would have a seperate
> table for each property with a structure something like the following.
>
> TABLENAME:     Hit Totals for Property 'foo'
> TABLE COLUMNS:     Week | weekly hit total
>
> For every week there would be a new row added to the table, again, it would
> be populated by a cron script. However, I do not like this solution as I am
> not interested in having 5000 tables set up for all the properties, and then
> each time one of the properties were added or deleted I have to alter the
> database to add or delete tables.
>
> to sum it up....
>
> Solution 1 which provides a unique row for each property, seems inadaquate
> because it will require adding columns to the database on each update, thus
> altering the table structure on a constant basis.
>
> Solution 2 which provides a unique table for each property in the database
> seems inadaquate for the same reason as above, I am altering the database
> itself all too often, not to mention I have to deal with thousands of
> tables.
>
> Considering postgreSQL is an object oriented database, and I am new to that
> concept in databases, I was hoping maybe someone here had a workable
> solution or suggestion that may or may not take advantage of PostgreSQL's
> object oriented features. Any help or suggestions on this would be very
> highly appreciated.
>
> Thanks,
> Alan
>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 5: Have you checked our extensive FAQ?
>
> http://www.postgresql.org/users-lounge/docs/faq.html
>

Lincoln Yeoh wrote:
> The detailed HTML docs are actually fine.

Not to start a flame-fest, but really, just fine?  No room at all for
improvement?  Or very little room for improvement?  Let's take a
positive approach, instead of a defensive one.

> And there is a short version which works. But sets up what seems to be a
> quick for test install with a superuser, no other users, and no startup and
> shutdown scripts.
>
> http://www.ca.postgresql.org/users-lounge/docs/7.3/postgres/installation.html

That would have given me a few clues, although it still doesn't address
the prerequisites for user creation.  However, when I viewed it the
other day, ALL of the commands were on ONE long line without a break, so
  I would have to scroll horizontally for an eternity to find that
"createdb" command which provided the clue.

Today, I am unable to find the pages in all their horrible mess that I
read the other day.  My bet?  Someone or something hosed up a web page
install or upgrade or mirror site, and I *did* see garbage, but now it's
all gone.  I was not hallucinating.

> So far that's much better than the Oracle doc I last saw- a huge thick
> installation manual which is written for everyone and no one because it is
> full of details for different scenarios. I had to turn to 3rd party Oracle
> HOWTO to install Oracle- and it was a lot easier :).

Oracle's documentation is incredibly obtuse.  I wouldn't want to strive
to be like them.

> Maybe people want an intermediate version?
>
>  From memory my steps are usually:
>
> Follow the INSTALL.TXT, configure, compile, regression test and if ok,
> install the software.
>
> Create a pgsql or postgres O/S user.
>
    [snip]

> Voila, postgresql up with one super user and one power user.

Good summary.  Note that some people (some being more than a few) will
be installing PostgreSQL on FreeBSD systems using the ports collection.
  The steps to get the source, build, test and install are handled by
one command:  "make install".  The only remaining steps are starting the
server and initializing the database, requiring exactly 2 more command
lines.

What I was looking for was the answer to the questions:  "I've got a
running instance of PostgreSQL.  I want to get administrative control of
the access (users) and create any initial databases (if necessary).  How
do I do that?  Which do I do first?"

It was non-obvious that the Unix username pgsql was the only
pre-existing superuser available, and that it had no default database,
but rather required use of template[01].  Or alternatively, through the
magic of opaque behavior, one can run createuser and it will magically
use template[01], or when trying to use createdb magically, one has to
know somehow that one must be the Unix user which owns the databases
(pgsql on FreeBSD).

I'll be more than happy to contribute better documentation.  However, I
looked in the "how to contribute" section and it only talked about
source code patches, so I was lead to believe that documentation was not
open to modification by the user community.

On Mon, 27 Jan 2003, Chris Johnson wrote:

> Lincoln Yeoh wrote:
> > The detailed HTML docs are actually fine.
>
> Not to start a flame-fest, but really, just fine?  No room at all for
> improvement?  Or very little room for improvement?  Let's take a
> positive approach, instead of a defensive one.

Let's be reasonable here, there's a large difference between "actually
fine" to "No room at all for improvement" or even "very little room for
improvement".  I think that was unnecessary.

> It was non-obvious that the Unix username pgsql was the only
> pre-existing superuser available, and that it had no default database,

I assume the text in the Administrator's Guide section 4.1 (using the
online dev docs) was not clear enough as for the existance and name of the
superuser.  The existance of a created superuser is  also mentioned in
context of the -U switch to initdb but not in the description.  Perhaps
it needs to stand out more.

> but rather required use of template[01].  Or alternatively, through the

Well the existances of at least template1 is mentioned in a few places
(initdb, 3.2, 5.2) and mentioned in terms of bootstrapping creating
addtional databases in 5.2 but again maybe this isn't clear enough or
doesn't stand out enough.

> magic of opaque behavior, one can run createuser and it will magically
> use template[01], or when trying to use createdb magically, one has to
> know somehow that one must be the Unix user which owns the databases
> (pgsql on FreeBSD).

At least the current doc srcs seem to mention in the man page source for
createdb that it's a wrapper over psql and AG 4.1 mentions that many
applications assume the name of the current operating system user by
default (including createuser and psql).

The docs are like most of the rest of the project, if you can work with
the document source files, you can probably get patches applied if you
make something better.

On Mon, Jan 27, 2003 at 06:33:13PM -0600, Chris Johnson wrote:
> Lincoln Yeoh wrote:
> >The detailed HTML docs are actually fine.
>
> Not to start a flame-fest, but really, just fine?  No room at all for
> improvement?  Or very little room for improvement?  Let's take a
> positive approach, instead of a defensive one.

from your perspective (and mine) you're right. not knowing WHAT
to look for or WHERE to look for it, makes the existing docs
obtuse, obscure and non-helpful. once you know, sure, you can
find it easily -- but there's a threshold there. plus, you
already know it, so why look?

from the perspective of the folks who worked on making the
documentation as good as it is, you're being a tad petulant.
"don't be defensive" and all that.

don't take it personally; the docwriters aren't TRYING to make
your life difficult [it just works out that way :) ]...

the problem is, the folks who grok every nook and cranny of the
pgsql engine ALREADY know everything about it and are in a bad
position when it comes to introducing it to newbies; THEY know
it, so it's reasonable that YOU should be able to see it the way
they do. this is why i started the newbiedoc project for newbies
coming into debian -- documents written BY newbies FOR newbies
tend to be much more meaningful when you're entering the on-ramp.

> What I was looking for was the answer to the questions:  "I've
> got a running instance of PostgreSQL.  I want to get
> administrative control of the access (users) and create any
> initial databases (if necessary).  How do I do that?  Which do
> I do first?"
>
> It was non-obvious that the Unix username pgsql was the only
> pre-existing superuser available, and that it had no default
> database, but rather required use of template[01].  Or
> alternatively, through the magic of opaque behavior, one can
> run createuser and it will magically use template[01], or when
> trying to use createdb magically, one has to know somehow that
> one must be the Unix user which owns the databases (pgsql on
> FreeBSD).

we await your improved documentation. :)

> I'll be more than happy to contribute better documentation.
> However, I looked in the "how to contribute" section and it
> only talked about source code patches, so I was lead to
> believe that documentation was not open to modification by the
> user community.

the "idocs" portion of the website allows all kinds of
commentary, but that's basically footnotes appended to the
bottom of the page, forum-style. so that doesn't count--

i wrote an intro to regular-expressions, postgresql style, at
http://techdocs.postgresql.org/guides/RegularExpressionIntro ;
have a look -- and notice the "edit this page" link at the top.

piece of cake! i first submitted it right here on the mailing
list; after a few feedback cycles -- notably r. schwartz
(rightly) pointing out my email pattern was substandard -- it
wound up on the website. nothing to it!

--
There are 10 kinds of people:
ones that get binary, and ones that don't.

will@serensoft.com
http://sourceforge.net/projects/newbiedoc -- we need your brain!
http://www.dontUthink.com/ -- your brain needs us!

Looking for a firewall? Do you think smoothwall sucks? You're
probably right... Try the folks at http://clarkconnect.org/ !

A little while ago I was a db newbie and a complete postgres newbie, so
I'll add my two cents worth. The current documentation is really quite
good, however the problem I had was trying to find what I needed in
them. Two things helped quite a bit:
1 - a good reference book eg PostgreSQL Essential Reference (but not
Practical PostgreSQL - the index is VERY sparse)
2 - pgAdminII - The searching mechanism in the help files is AWESOME.
It's a very quick and easy tool to use, and it's current (my version is
7.3 rc1). If you have a windows box available, I urge you to try pgAdmin
II, even for the documentation alone.

So, if someone created a web interface that did the same as pgAdminII
(its Help contents), it would solve most of the problems of finding what
a user needs in the documentation (in my humble opinion).

BTW Will, your regular expression docs are very good, they've been quite
helpful to me over the last couple of days.


will trillich wrote:

>On Mon, Jan 27, 2003 at 06:33:13PM -0600, Chris Johnson wrote:
>
>
>>Lincoln Yeoh wrote:
>>
>>
>>>The detailed HTML docs are actually fine.
>>>
>>>
>>Not to start a flame-fest, but really, just fine?  No room at all for
>>improvement?  Or very little room for improvement?  Let's take a
>>positive approach, instead of a defensive one.
>>
>>
>
>from your perspective (and mine) you're right. not knowing WHAT
>to look for or WHERE to look for it, makes the existing docs
>obtuse, obscure and non-helpful. once you know, sure, you can
>find it easily -- but there's a threshold there. plus, you
>already know it, so why look?
>
>from the perspective of the folks who worked on making the
>documentation as good as it is, you're being a tad petulant.
>"don't be defensive" and all that.
>
>don't take it personally; the docwriters aren't TRYING to make
>your life difficult [it just works out that way :) ]...
>
>the problem is, the folks who grok every nook and cranny of the
>pgsql engine ALREADY know everything about it and are in a bad
>position when it comes to introducing it to newbies; THEY know
>it, so it's reasonable that YOU should be able to see it the way
>they do. this is why i started the newbiedoc project for newbies
>coming into debian -- documents written BY newbies FOR newbies
>tend to be much more meaningful when you're entering the on-ramp.
>
>
>
>>What I was looking for was the answer to the questions:  "I've
>>got a running instance of PostgreSQL.  I want to get
>>administrative control of the access (users) and create any
>>initial databases (if necessary).  How do I do that?  Which do
>>I do first?"
>>
>>It was non-obvious that the Unix username pgsql was the only
>>pre-existing superuser available, and that it had no default
>>database, but rather required use of template[01].  Or
>>alternatively, through the magic of opaque behavior, one can
>>run createuser and it will magically use template[01], or when
>>trying to use createdb magically, one has to know somehow that
>>one must be the Unix user which owns the databases (pgsql on
>>FreeBSD).
>>
>>
>
>we await your improved documentation. :)
>
>
>
>>I'll be more than happy to contribute better documentation.
>>However, I looked in the "how to contribute" section and it
>>only talked about source code patches, so I was lead to
>>believe that documentation was not open to modification by the
>>user community.
>>
>>
>
>the "idocs" portion of the website allows all kinds of
>commentary, but that's basically footnotes appended to the
>bottom of the page, forum-style. so that doesn't count--
>
>i wrote an intro to regular-expressions, postgresql style, at
>http://techdocs.postgresql.org/guides/RegularExpressionIntro ;
>have a look -- and notice the "edit this page" link at the top.
>
>piece of cake! i first submitted it right here on the mailing
>list; after a few feedback cycles -- notably r. schwartz
>(rightly) pointing out my email pattern was substandard -- it
>wound up on the website. nothing to it!
>
>
>


--
Ron St.Pierre
Syscor R&D
tel: 250-361-1681
email: rstpierre@syscor.com

On Thu, Jan 30, 2003 at 17:59:17 +0000,
  "Ron St.Pierre" <rstpierre@syscor.com> wrote:
> A little while ago I was a db newbie and a complete postgres newbie, so
> I'll add my two cents worth. The current documentation is really quite
> good, however the problem I had was trying to find what I needed in
> them. Two things helped quite a bit:
> 1 - a good reference book eg PostgreSQL Essential Reference (but not
> Practical PostgreSQL - the index is VERY sparse)
> 2 - pgAdminII - The searching mechanism in the help files is AWESOME.

Another good step is too read through the entire documentation once.
It will give you a good idea of what is there and where abouts it
might be located. So when a question comes up you have some idea
where to look.

On Thursday 30 Jan 2003 11:06 pm, you wrote:
> On Mon, Jan 27, 2003 at 06:33:13PM -0600, Chris Johnson wrote:
> > Lincoln Yeoh wrote:
> > Not to start a flame-fest, but really, just fine?  No room at all for
> > improvement?  Or very little room for improvement?  Let's take a
> > positive approach, instead of a defensive one.

OK. (Sorry I am replying to a reply but lost original one.)

> > What I was looking for was the answer to the questions:  "I've
> > got a running instance of PostgreSQL.  I want to get
> > administrative control of the access (users) and create any
> > initial databases (if necessary).  How do I do that?  Which do
> > I do first?"

Well, I hope you have read postgresql 101, I have written. Who is postgresql
superuser? Any OS user that starts the postmaster process. It is as simple as
that. Why you need a pre-defined postgreql superuser? Is pg_ctl too hard for
you?

So you have a running instance of postgresql. Who is postgresql superuser. The
userid with which postmaster is running. Is it that difficult to understand?

> > It was non-obvious that the Unix username pgsql was the only
> > pre-existing superuser available, and that it had no default
> > database, but rather required use of template[01].  Or
> > alternatively, through the magic of opaque behavior, one can
> > run createuser and it will magically use template[01], or when
> > trying to use createdb magically, one has to know somehow that
> > one must be the Unix user which owns the databases (pgsql on
> > FreeBSD).

That has nothing to do with postgresql. It can run with any user as superuser.
OS users postgresql and pgsql are packaging wrappers created by OS packagers
like freeBSD and distros. You are all too free to run a instance by yourself.

> > I'll be more than happy to contribute better documentation.
> > However, I looked in the "how to contribute" section and it
> > only talked about source code patches, so I was lead to
> > believe that documentation was not open to modification by the
> > user community.

Join the postgresql-doc mailing list. You will find more than enough ways to
contribute.


 Nothing is wrong with anything, either you or postgresql documentation. It's
just that the documentation assumes some knowledge of OS administration.
Probably they should mention it ..;-)

 Shridhar

Hi,

I just want to know if the command :

ALTER TABLE [ ONLY ] table [ * ]
     ALTER [ COLUMN ] column SET STATISTICS integer

is also applied after a pg_dumpall, and the integration of the data in a new
database ?

How to know if so or not ?

Thanks for your answer,

Regards,
--
Hervé Piedvache

Elma Ingénierie Informatique
6 rue du Faubourg Saint-Honoré
F-75008 - Paris - France
Tel. 33-144949901
fax. 33-144949902

=?iso-8859-15?q?Herv=E9=20Piedvache?= <herve@elma.fr> writes:
> I just want to know if the command :
> ALTER TABLE [ ONLY ] table [ * ]
> � � �ALTER [ COLUMN ] column SET STATISTICS integer
> is also applied after a pg_dumpall, and the integration of the data in a new
> database ?

IIRC, pg_dump 7.3 dumps that, but 7.2 does not.

> How to know if so or not ?

Look in the dump file to see if there are any ALTER SET STATISTICS
commands ...

            regards, tom lane