CONSTRAINT syntax in ALTER TABLE

Jim C. Nasby wrote:

Maybe it's just me, but I find it annoying that the ALTER TABLE docs
say to look at the CREATE TABLE docs for info on CONSTRAINT syntax. ISTM
it would be much better to:

Include the docs in both places, or
Break constraint syntax/info into it's own page

A last-resort would be to still refer to CREATE TABLE, but at least make
it link to the actual constraint section, instead of just linking to the
top of the page as it does now.

I like that last idea. I don't think duplicate documentation or a
separate section are a win.

-- 
  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, Pennsylvania 19073

On Mon, Jan 02, 2006 at 09:04:50PM -0500, Bruce Momjian wrote:

Jim C. Nasby wrote:

Maybe it's just me, but I find it annoying that the ALTER TABLE docs
say to look at the CREATE TABLE docs for info on CONSTRAINT syntax. ISTM
it would be much better to:

Include the docs in both places, or
Break constraint syntax/info into it's own page

A last-resort would be to still refer to CREATE TABLE, but at least make
it link to the actual constraint section, instead of just linking to the
top of the page as it does now.

I like that last idea. I don't think duplicate documentation or a
separate section are a win.

By #2 I assume you mean my 'last resort'. One thing I dislike about that
is (I assume) it would do nothing to help \h ALTER TABLE in psql. Maybe
a good compromise would be to include the table_constraint section of
the CREATE TABLE syntax in the ALTER TABLE syntax.
--
Jim C. Nasby, Sr. Engineering Consultant jnasby@pervasive.com
Pervasive Software http://pervasive.com work: 512-231-6117
vcard: http://jim.nasby.net/pervasive.vcf cell: 512-569-9461

Jim C. Nasby wrote:

On Mon, Jan 02, 2006 at 09:04:50PM -0500, Bruce Momjian wrote:

Jim C. Nasby wrote:

Maybe it's just me, but I find it annoying that the ALTER TABLE docs
say to look at the CREATE TABLE docs for info on CONSTRAINT syntax. ISTM
it would be much better to:

Include the docs in both places, or
Break constraint syntax/info into it's own page

A last-resort would be to still refer to CREATE TABLE, but at least make
it link to the actual constraint section, instead of just linking to the
top of the page as it does now.

I like that last idea. I don't think duplicate documentation or a
separate section are a win.

By #2 I assume you mean my 'last resort'. One thing I dislike about that

Yes, sorry.

is (I assume) it would do nothing to help \h ALTER TABLE in psql. Maybe
a good compromise would be to include the table_constraint section of
the CREATE TABLE syntax in the ALTER TABLE syntax.

If they created the table, they have already seen the constraint syntax.
I see no reason to repeat it.

-- 
  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, Pennsylvania 19073

From: Bruce Momjian [mailto:pgman@candle.pha.pa.us]

is (I assume) it would do nothing to help \h ALTER TABLE in

psql. Maybe

a good compromise would be to include the table_constraint

section of

the CREATE TABLE syntax in the ALTER TABLE syntax.

If they created the table, they have already seen the
constraint syntax.
I see no reason to repeat it.

The reason I'd repeat it is because when you're going to modify
existing constraints, you'll be using ALTER TABLE. Sure, if the
user memorized the constraint syntax when they created the table,
they won't need extra help. Personally, I usually make use of
column-level constraints when writing DDL, so any time I need to
use table-level syntax I often have to look something up. That's
why I'd like to see the info in \h.

If you look at our docs from a newbie standpoint, they're not very
easy to use, because it's difficult to find stuff unless you know
where to look. If you're looking in the SQL Syntax section, ALTER
TABLE is the obvious choice if you need to change something about
the table, but it's a PITA to have to refer to other documentation
to find the full syntax for the command.
--
Jim C. Nasby, Sr. Engineering Consultant jnasby@pervasive.com
Pervasive Software http://pervasive.com work: 512-231-6117
vcard: http://jim.nasby.net/pervasive.vcf cell: 512-569-9461