Re: How to make a good documentation of a database ?

dpradier(at)apartia(dot)fr (David Pradier) writes:
> Well, yes, that's what I currently use.
> The dot output is very interesting, but I guess the complete database
> image will be 16 meters x 16 meters large when I have finished adding
> the constraints.
> I have already stopped to print it.
> That's why I'd like to make something more 'paper-y' like 'The book of
> my database', with lots of comments.
>
> Or, I could insert the comments in the database itself so that autodoc
> auto-documents them :-)
> In fact, I have already looked a little into the tables of PostgreSQL itself
> to see if I could hack it by adding a column "Comments" in the "table of
> columns".
> But I guess it isn't wise nor feasible, is it ?

Not only can you put comments on tables, but you can put comments on
columns.

From the Slony-I sources:

comment on table @NAMESPACE(at)(dot)sl_setsync is 'SYNC information';
comment on column @NAMESPACE(at)(dot)sl_setsync(dot)ssy_setid is 'ID number of the replication set';
comment on column @NAMESPACE(at)(dot)sl_setsync(dot)ssy_origin is 'ID number of the node';
comment on column @NAMESPACE(at)(dot)sl_setsync(dot)ssy_seqno is 'Slony-I sequence number';
comment on column @NAMESPACE(at)(dot)sl_setsync(dot)ssy_minxid is 'Earliest XID in provider system affected by SYNC';
comment on column @NAMESPACE(at)(dot)sl_setsync(dot)ssy_maxxid is 'Latest XID in provider system affected by SYNC';
comment on column @NAMESPACE(at)(dot)sl_setsync(dot)ssy_xip is 'Contains the list of XIDs in progress at SYNC time';
comment on column @NAMESPACE(at)(dot)sl_setsync(dot)ssy_action_list is 'action list used during the subscription process. At the time a subscriber copies over data from the origin, it sees all tables in a state somewhere between two SYNC events. Therefore this list must contains all XIDs that are visible at that time, whose operations have therefore already been included in the data copied at the time the initial data copy is done. Those actions may therefore be filtered out of the first SYNC done after subscribing.';

(@NAMESPACE@ gets transformed into a namespace name via a sed script;
use your favorite namespace as needed...)
--
let name="cbbrowne" and tld="cbbrowne.com" in String.concat "@" [name;tld];;
http://www.ntlug.org/~cbbrowne/linuxxian.html
A VAX is virtually a computer, but not quite.