granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/create_table.sgml

   1 <REFENTRY ID="SQL-CREATETABLE-1">
   2  <REFMETA>
   3   <REFENTRYTITLE>
   4    CREATE TABLE
   5   </REFENTRYTITLE>
   6   <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
   7  </REFMETA>
   8  <REFNAMEDIV>
   9   <REFNAME>
  10    CREATE TABLE
  11   </REFNAME>
  12   <REFPURPOSE>
  13    Creates a new table
  14   </REFPURPOSE>
  15
  16  <REFSYNOPSISDIV>
  17   <REFSYNOPSISDIVINFO>
  18    <DATE>1998-04-15</DATE>
  19   </REFSYNOPSISDIVINFO>
  20   <SYNOPSIS>
  21    CREATE TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> (
  22         <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE> [DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>] [CONSTRAINT <REPLACEABLE CLASS="PARAMETER">column_constraint</REPLACEABLE>] [, ...]
  23         [, <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> ...]
  24         [, CONSTRAINT <REPLACEABLE CLASS="PARAMETER">table_constraint</REPLACEABLE>]
  25         ) [INHERITS ( <REPLACEABLE CLASS="PARAMETER">inherited_table</REPLACEABLE> [, ...] )]
  26   </SYNOPSIS>
  27
  28   <REFSECT2 ID="R2-SQL-CREATETABLE-1">
  29    <REFSECT2INFO>
  30     <DATE>1998-04-15</DATE>
  31    </REFSECT2INFO>
  32    <TITLE>
  33     Inputs
  34    </TITLE>
  35    <PARA>
  36    </PARA>
  37
  38    <VARIABLELIST>
  39     <VARLISTENTRY>
  40      <TERM>
  41       <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
  42      </TERM>
  43      <LISTITEM>
  44       <PARA>
  45        The name of a new table to be created.
  46       </PARA>
  47      </LISTITEM>
  48     </VARLISTENTRY>
  49
  50     <VARLISTENTRY>
  51      <TERM>
  52       <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
  53      </TERM>
  54      <LISTITEM>
  55       <PARA>
  56        The name of a column.
  57       </PARA>
  58      </LISTITEM>
  59     </VARLISTENTRY>
  60
  61     <VARLISTENTRY>
  62      <TERM>
  63       <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE>
  64      </TERM>
  65      <LISTITEM>
  66       <PARA>
  67        The type of the column.
  68        (Refer to the <ProductName>Postgres</ProductName> User's Guide for
  69        further information about data types).
  70       </PARA>
  71      </LISTITEM>
  72     </VARLISTENTRY>
  73
  74     <VARLISTENTRY>
  75      <TERM>
  76       <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>
  77      </TERM>
  78      <LISTITEM>
  79       <PARA>
  80        A default value for a column.
  81        See the DEFAULT clause for more information.
  82       </PARA>
  83      </LISTITEM>
  84     </VARLISTENTRY>
  85
  86     <VARLISTENTRY>
  87      <TERM>
  88       <REPLACEABLE CLASS="PARAMETER">inherited_table</REPLACEABLE>
  89      </TERM>
  90      <LISTITEM>
  91       <PARA>
  92        The optional INHERITS clause specifies a collection of table
  93        names from which this table automatically inherits all fields.
  94        If any inherited field name appears more than once, PostgreSQL
  95        reports an error. PostgreSQL automatically allows the created
  96        table to inherit functions on tables above it in the inheritance
  97        hierarchy. Inheritance of functions is done according
  98        to the conventions of the Common Lisp Object System (CLOS).
  99       </PARA>
 100      </LISTITEM>
 101     </VARLISTENTRY>
 102
 103     <VARLISTENTRY>
 104      <TERM>
 105       <REPLACEABLE CLASS="PARAMETER">column_constraint</REPLACEABLE>
 106       <REPLACEABLE CLASS="PARAMETER">table_constraint</REPLACEABLE>
 107      </TERM>
 108      <LISTITEM>
 109       <PARA>
 110        The optional CONSTRAINT clause specifies a list of integrity
 111        constraints which new or updated entries must satisfy for
 112        an insert or update operation to succeed. Each constraint
 113        must evaluate to a boolean expression. Multiple columns
 114        may be referenced within a single constraint.
 115        See CONSTRAINT clause for more information.
 116       </PARA>
 117      </LISTITEM>
 118     </VARLISTENTRY>
 119    </VARIABLELIST>
 120
 121
 122   </REFSECT2>
 123
 124   <REFSECT2 ID="R2-SQL-CREATETABLE-2">
 125    <REFSECT2INFO>
 126     <DATE>1998-04-15</DATE>
 127    </REFSECT2INFO>
 128    <TITLE>
 129     Outputs
 130    </TITLE>
 131    <PARA>
 132    </PARA>
 133    <VARIABLELIST>
 134     <VARLISTENTRY>
 135      <TERM>
 136       <ReturnValue>status</ReturnValue>
 137      </TERM>
 138      <LISTITEM>
 139       <PARA>
 140        <VARIABLELIST>
 141         <VARLISTENTRY>
 142          <TERM>
 143           <ReturnValue>CREATE</ReturnValue>
 144          </TERM>
 145          <LISTITEM>
 146           <PARA>
 147            Message returned if table is successfully created.
 148           </PARA>
 149          </LISTITEM>
 150         </VARLISTENTRY>
 151
 152         <VARLISTENTRY>
 153          <TERM>
 154           <ReturnValue>ERROR</ReturnValue>
 155          </TERM>
 156          <LISTITEM>
 157           <PARA>
 158            Message returned if table creation failed.
 159            This is usually accompanied by some descriptive text, such as:
 160            <ProgramListing>
 161    amcreate: "<replaceable class="parameter">table</replaceable>" relation already exists
 162            </ProgramListing>
 163            which occurs at runtime, if the table specified already exists
 164            in the database.
 165           </PARA>
 166          </LISTITEM>
 167         </VARLISTENTRY>
 168        </VARIABLELIST>
 169       </PARA>
 170      </LISTITEM>
 171     </VARLISTENTRY>
 172    </VARIABLELIST>
 173   </REFSECT2>
 174  </REFSYNOPSISDIV>
 175
 176  <REFSECT1 ID="R1-SQL-CREATETABLE-1">
 177   <REFSECT1INFO>
 178    <DATE>1998-04-15</DATE>
 179   </REFSECT1INFO>
 180   <TITLE>
 181    Description
 182   </TITLE>
 183   <PARA>
 184    CREATE TABLE will enter a new table into the current data
 185    base. The table will be "owned" by the user issuing the
 186    command.
 187
 188   <PARA>
 189    The new table is created as a heap with no initial data.
 190    A table can have no more than 1600 columns (realistically,
 191    this is limited by the fact that tuple sizes must
 192    be less than 8192 bytes), but this limit may be configured
 193    lower at some sites. A table cannot have the same name as
 194    a system catalog table.
 195   </PARA>
 196
 197   <REFSECT2 ID="R2-SQL-DEFAULTCLAUSE-1">
 198    <REFSECT2INFO>
 199     <DATE>1998-04-15</DATE>
 200    </REFSECT2INFO>
 201    <TITLE>
 202     DEFAULT clause
 203    </TITLE>
 204    <PARA>
 205     <SYNOPSIS>
 206      DEFAULT <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>
 207     </SYNOPSIS>
 208    <PARA>
 209     The DEFAULT clause assigns a default data value to a column.
 210    </PARA>
 211    <VARIABLELIST>
 212     <VARLISTENTRY>
 213      <TERM>
 214      </TERM>
 215      <LISTITEM>
 216       <PARA>
 217        <VARIABLELIST>
 218         <VARLISTENTRY>
 219          <TERM>
 220           <ReturnValue><replaceable class="parameter">value</replaceable></ReturnValue>
 221          </TERM>
 222          <LISTITEM>
 223           <PARA>
 224            The possible values for expression are:
 225            <itemizedlist>
 226             <listitem>
 227              <simpara>
 228               a literal value
 229              </simpara>
 230             </listitem>
 231             <listitem>
 232              <simpara>
 233               a user function
 234              </simpara>
 235             </listitem>
 236             <listitem>
 237              <simpara>
 238               a niladic function
 239              </simpara>
 240             </listitem>
 241            </itemizedlist>
 242           </para>
 243          </listitem>
 244         </VARLISTENTRY>
 245
 246         <VARLISTENTRY>
 247          <TERM>
 248           <ReturnValue>ERROR:  DEFAULT: type mismatched</ReturnValue>
 249          </TERM>
 250          <LISTITEM>
 251           <PARA>
 252            if data type of default value doesn't match the
 253            column definition's data type.
 254           </PARA>
 255          </LISTITEM>
 256         </VARLISTENTRY>
 257        </variablelist>
 258       <PARA>
 259        The DEFAULT clause assigns a default data value to a column
 260        (via a column definition in the CREATE TABLE statement).
 261        The data type of a default value must match the column definition's
 262        data type.
 263       </PARA>
 264       <PARA>
 265        An INSERT operation that includes a column without a specified
 266        default value will assign the NULL value to the column
 267        if no explicit data value is provided for it.
 268        Default <replaceable class="parameter">literal</replaceable> means
 269        that the default is the specified constant value.
 270        Default <replaceable class="parameter">niladic-function</replaceable>
 271        or <replaceable class="parameter">user-function</replaceable> means
 272        that the default
 273        is the value of the specified function at the time of the INSERT.
 274       </PARA>
 275       <PARA>
 276        There are two types of niladic functions:<variablelist>
 277         <varlistentry>
 278          <term>niladic USER</term>
 279          <listitem>
 280           <variablelist>
 281            <varlistentry>
 282             <term>CURRENT_USER / USER</term>
 283             <listitem>
 284              <simpara>See CURRENT_USER function</simpara>
 285             </listitem>
 286            </varlistentry>
 287            <varlistentry>
 288             <term>SESSION_USER</term>
 289             <listitem>
 290              <simpara>not yet supported</simpara>
 291             </listitem>
 292            </varlistentry>
 293            <varlistentry>
 294             <term>SYSTEM_USER</term>
 295             <listitem>
 296              <simpara>not yet supported</simpara>
 297             </listitem>
 298            </varlistentry>
 299           </variablelist>
 300          </listitem>
 301         </varlistentry>
 302         <varlistentry>
 303          <term>niladic datetime</term>
 304          <listitem>
 305           <variablelist>
 306            <varlistentry>
 307             <term> CURRENT_DATE</term>
 308             <listitem>
 309              <simpara>See CURRENT_DATE function</simpara>
 310             </listitem>
 311            </varlistentry>
 312            <varlistentry>
 313             <term>CURRENT_TIME</term>
 314             <listitem>
 315              <simpara>See CURRENT_TIME function</simpara>
 316             </listitem>
 317            </varlistentry>
 318            <varlistentry>
 319             <term>CURRENT_TIMESTAMP</term>
 320             <listitem>
 321              <simpara>See CURRENT_TIMESTAMP function</simpara>
 322             </listitem>
 323            </varlistentry>
 324           </variablelist>
 325          </listitem>
 326         </varlistentry>
 327        </variablelist>
 328      </LISTITEM>
 329     </VARLISTENTRY>
 330    </VARIABLELIST>
 331   </REFSECT2>
 332
 333   <REFSECT2 ID="R2-SQL-NOTNULL-1">
 334    <REFSECT2INFO>
 335     <DATE>1998-04-15</DATE>
 336    </REFSECT2INFO>
 337    <TITLE>
 338     NOT NULL constraint
 339    </TITLE>
 340    <SYNOPSIS>
 341     [ CONSTRAINT <replaceable class="parameter">name</replaceable> ] NOT NULL
 342    </SYNOPSIS>
 343    <PARA>
 344     The NOT NULL constraint specifies a rule that a column may
 345     contain only non-null values.
 346    </PARA>
 347    <PARA>
 348     The NOT NULL constraint is a column constraint.
 349    </PARA>
 350    <VARIABLELIST>
 351     <VARLISTENTRY>
 352      <TERM>
 353      </TERM>
 354      <LISTITEM>
 355       <PARA>
 356        <VARIABLELIST>
 357         <VARLISTENTRY>
 358          <TERM>
 359           <ReturnValue><replaceable class="parameter">name</replaceable></ReturnValue>
 360          </TERM>
 361          <LISTITEM>
 362           <PARA>
 363            The optional name of a constraint.
 364           </PARA>
 365          </LISTITEM>
 366         </VARLISTENTRY>
 367        </variablelist>
 368      </LISTITEM>
 369     </VARLISTENTRY>
 370    </VARIABLELIST>
 371
 372   <REFSECT3 ID="R3-SQL-NOTNULL-1">
 373    <REFSECT3INFO>
 374     <DATE>1998-04-15</DATE>
 375    </REFSECT3INFO>
 376    <TITLE>
 377     Outputs
 378    </TITLE>
 379    <PARA>
 380    </PARA>
 381    <VARIABLELIST>
 382     <VARLISTENTRY>
 383      <TERM>
 384      </TERM>
 385      <LISTITEM>
 386       <PARA>
 387        <VARIABLELIST>
 388         <VARLISTENTRY>
 389          <TERM>
 390           <ReturnValue>ERROR:  ExecAppend: Fail to add null value in not
 391            null attribute "<replaceable class="parameter">column</replaceable>".</ReturnValue>
 392          </TERM>
 393          <LISTITEM>
 394           <PARA>
 395            This error occurs at runtime if one tries to insert a null value
 396            into a column which has a NOT NULL constraint.
 397           </PARA>
 398          </LISTITEM>
 399         </VARLISTENTRY>
 400        </variablelist>
 401      </LISTITEM>
 402     </VARLISTENTRY>
 403    </VARIABLELIST>
 404   </REFSECT3>
 405   </REFSECT2>
 406
 407   <REFSECT2 ID="R2-SQL-UNIQUECLAUSE-1">
 408    <REFSECT2INFO>
 409     <DATE>1998-04-15</DATE>
 410    </REFSECT2INFO>
 411    <TITLE>
 412     UNIQUE constraint
 413    </TITLE>
 414    <para>
 415     Table Constraint definition
 416    </para>
 417    <synopsis>
 418     [ CONSTRAINT <replaceable class="parameter">name</replaceable> ] UNIQUE ( <replaceable class="parameter">column</replaceable> [, ...] )
 419    </SYNOPSIS>
 420    <para>
 421     Column Constraint definition
 422    </para>
 423    <synopsis>
 424     [ CONSTRAINT <replaceable class="parameter">name</replaceable> ] UNIQUE
 425    </SYNOPSIS>
 426    <refsect3>
 427     <title>Parameters</title>
 428     <variablelist>
 429      <varlistentry>
 430       <term>
 431        <replaceable class="parameter">name</replaceable>
 432       </term>
 433       <listitem>
 434        <para>
 435         An arbitrary name given to a constraint.
 436        </para>
 437       </listitem>
 438      </varlistentry>
 439      <varlistentry>
 440       <term>
 441        <replaceable class="parameter">column</replaceable>
 442       </term>
 443       <listitem>
 444        <para>
 445         A name of a column in a table.
 446        </para>
 447       </listitem>
 448      </varlistentry>
 449     </variablelist>
 450    </refsect3>
 451    <refsect3>
 452     <title>Outputs</title>
 453     <PARA>
 454     </PARA>
 455     <VARIABLELIST>
 456      <VARLISTENTRY>
 457       <TERM>
 458       </TERM>
 459       <LISTITEM>
 460        <PARA>
 461         <VARIABLELIST>
 462          <VARLISTENTRY>
 463           <TERM>
 464            ERROR: Cannot insert a duplicate key into a unique index.
 465           </term>
 466           <listitem>
 467            <para>
 468             This error occurs at runtime if one tries to insert a
 469             duplicate value into a column.
 470            </para>
 471           </listitem>
 472          </varlistentry>
 473         </variablelist></para>
 474       </listitem>
 475      </varlistentry>
 476     </variablelist>
 477    </refsect3>
 478    <refsect3>
 479     <title>Description</title>
 480     <PARA>
 481      The UNIQUE constraint specifies a rule that a group of one or
 482      more distinct columns of a table may contain only unique values.
 483     </para>
 484     <para>
 485      The column definitions of the specified columns do not have to
 486      include a NOT NULL constraint to be included in a UNIQUE
 487      constraint.  Having more than one null value in a column without a
 488      NOT NULL constraint, does not violate a UNIQUE constraint.
 489     </PARA>
 490     <PARA>
 491      Each UNIQUE constraint must name a set of columns that is
 492      different from the set of columns named by any other UNIQUE or
 493      PRIMARY KEY constraint defined for the Table.
 494     </PARA>
 495     <Note>
 496      <Para>
 497       PostgreSQL automatically creates a unique index for each UNIQUE
 498       constraint, to assure
 499       data integrity. See CREATE INDEX for more information.
 500      </Para>
 501     </Note>
 502   </REFSECT2>
 503
 504   <REFSECT2 ID="R2-SQL-CONSTRAINT-1">
 505    <REFSECT2INFO>
 506     <DATE>1998-04-15</DATE>
 507    </REFSECT2INFO>
 508    <TITLE>
 509     CONSTRAINT clause
 510    </TITLE>
 511    <para>
 512     Table constraint definition
 513    </para>
 514    <SYNOPSIS>
 515     [ CONSTRAINT name ]
 516     { PRIMARY KEY constraint |
 517     UNIQUE constraint |
 518     CHECK constraint }
 519    </SYNOPSIS>
 520    <PARA>
 521     Column constraint definition
 522    </PARA>
 523    <SYNOPSIS>
 524     [ CONSTRAINT name ]
 525     { NOT NULL constraint |
 526     PRIMARY KEY constraint |
 527     UNIQUE constraint |
 528     CHECK constraint }
 529    </SYNOPSIS>
 530    <PARA>
 531    </PARA>
 532    <VARIABLELIST>
 533     <VARLISTENTRY>
 534      <TERM>
 535      </TERM>
 536      <LISTITEM>
 537       <PARA>
 538        <VARIABLELIST>
 539         <VARLISTENTRY>
 540          <TERM>
 541           <ReturnValue>
 542            <replaceable class="parameter">name</replaceable>
 543           </ReturnValue>
 544          </TERM>
 545          <LISTITEM>
 546           <PARA>
 547           An arbitrary name given to an integrity constraint.
 548           </PARA>
 549          </LISTITEM>
 550         </VARLISTENTRY>
 551         <VARLISTENTRY>
 552          <TERM>
 553           <ReturnValue>
 554            <replaceable class="parameter">constraint</replaceable>
 555           </ReturnValue>
 556          </TERM>
 557          <LISTITEM>
 558           <PARA>
 559            The definition of the constraint.
 560           </PARA>
 561          </LISTITEM>
 562         </VARLISTENTRY>
 563        </VARIABLELIST>
 564      </LISTITEM>
 565     </VARLISTENTRY>
 566    </VARIABLELIST>
 567    <para>
 568     A Constraint is a named rule: a SQL object which helps define
 569     valid sets of values by putting limits on the results of INSERT,
 570     UPDATE or DELETE operations performed on a Base table.
 571    </para>
 572    <para>
 573     There are two ways to define integrity constraints:
 574     Table constraint and Column constraint.
 575    </para>
 576    <para>
 577     A Table Constraint is an integrity Constraint defined on one or
 578     more Columns of a Base table. The four variations of "Table
 579     Constraint" are:
 580     <simplelist columns="1">
 581      <member>PRIMARY KEY</member>
 582      <member>FOREIGN KEY</member>
 583      <member>UNIQUE</member>
 584      <member>CHECK</member>
 585     </simplelist>
 586    </para>
 587    <para>
 588     A column constraint is an integrity constraint defined as part
 589     of a column definition, and logically becomes a table
 590     constraint as soon as it is created. The column
 591     constraints available are:
 592     <simplelist columns="1">
 593      <member>PRIMARY KEY</member>
 594      <member>REFERENCES</member>
 595      <member>UNIQUE</member>
 596      <member>CHECK</member>
 597      <member>NOT NULL</member>
 598     </simplelist></para>
 599    <note>
 600     <para>
 601      PostgreSQL does not yet (at release 6.3.2) support the FOREIGN KEY or
 602      REFERENCES integrity constraints, although the parser will accept them.
 603      Foreign keys may be partially emulated by triggers (See CREATE TRIGGER
 604      statement)
 605     </para>
 606    </note>
 607    <note>
 608     <para>
 609      PostgreSQL does not yet support either DOMAINs or ASSERTIONs.
 610     </para>
 611    </note>
 612
 613   </REFSECT2>
 614
 615   <REFSECT2 ID="R2-SQL-CHECK-1">
 616    <REFSECT2INFO>
 617     <DATE>1998-04-15</DATE>
 618    </REFSECT2INFO>
 619    <title>The CHECK constraint</title>
 620   <SYNOPSIS>
 621    [ CONSTRAINT name ] CHECK ( condition [, ...] )
 622   </SYNOPSIS>
 623    <refsect3 id="R3-SQL-CHECK-1">
 624     <title>Inputs</title>
 625    <PARA>
 626        <VARIABLELIST>
 627         <VARLISTENTRY>
 628          <TERM>
 629           <ReturnValue><replaceable class="parameter">name</replaceable></ReturnValue>
 630          </TERM>
 631          <LISTITEM>
 632           <PARA>
 633            An arbitrary name given to a constraint.
 634           </PARA>
 635          </LISTITEM>
 636         </VARLISTENTRY>
 637         <VARLISTENTRY>
 638          <TERM>
 639           <ReturnValue>condition</ReturnValue>
 640          </TERM>
 641          <LISTITEM>
 642           <PARA>
 643            Any valid conditional expression.
 644           </PARA>
 645          </LISTITEM>
 646         </VARLISTENTRY>
 647        </variablelist>
 648   </REFSECT3>
 649
 650   <REFSECT3 ID="R3-SQL-CHECK-2">
 651    <REFSECT3INFO>
 652     <DATE>1998-04-15</DATE>
 653    </REFSECT3INFO>
 654     <TITLE>
 655      Outputs
 656     </TITLE>
 657     <PARA>
 658      <VARIABLELIST>
 659       <VARLISTENTRY>
 660        <TERM>
 661         <ReturnValue>
 662          ERROR:  ExecAppend: rejected due to CHECK constraint
 663          "<replaceable class="parameter">table_column</replaceable>".
 664         </ReturnValue>
 665        </TERM>
 666        <LISTITEM>
 667         <PARA>
 668          This error occurs at runtime if one tries to insert an illegal
 669          value into a column subject to a CHECK constraint.
 670         </PARA>
 671        </LISTITEM>
 672       </VARLISTENTRY>
 673      </variablelist>
 674    </REFSECT3>
 675    <refsect3>
 676     <title>Description</title>
 677     <para>
 678      The CHECK constraint specifies a rule that a group of one or
 679      more columns of a table may contain only those values allowed by
 680      the rule.
 681      The CHECK constraint is either a table constraint or a column
 682      constraint.
 683     </PARA>
 684     <PARA>
 685      PostgreSQL automatically creates an unique index to assure
 686      data integrity (See CREATE INDEX statement).
 687      The SQL92 CHECK column constraints can only be defined on, and
 688      refer to, one column of the table. PostgreSQL does not have
 689      this restriction.
 690     </PARA>
 691    </refsect3>
 692   </REFSECT2>
 693
 694   <REFSECT2 ID="R2-SQL-PRIMARYKEY-1">
 695    <REFSECT2INFO>
 696     <DATE>1998-04-15</DATE>
 697    </REFSECT2INFO>
 698    <TITLE>
 699     PRIMARY KEY clause
 700    </TITLE>
 701    <PARA>
 702    Table constraint definition
 703    </PARA>
 704    <SYNOPSIS>
 705     [ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ] PRIMARY KEY ( <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] )
 706    </SYNOPSIS>
 707    <PARA>
 708     Column constraint definition
 709    </PARA>
 710    <SYNOPSIS>
 711     [ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE> ] PRIMARY KEY
 712    </SYNOPSIS>
 713
 714    <refsect3>
 715     <title>Parameters</title>
 716     <PARA>
 717      <VARIABLELIST>
 718       <VARLISTENTRY>
 719        <TERM>
 720         <ReturnValue><REPLACEABLE CLASS="PARAMETER">name</REPLACEABLE></ReturnValue>
 721        </TERM>
 722        <LISTITEM>
 723         <PARA>
 724          An arbitrary name for the constraint.
 725         </PARA>
 726        </LISTITEM>
 727       </VARLISTENTRY>
 728       <VARLISTENTRY>
 729        <TERM>
 730         <ReturnValue><REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE></ReturnValue>
 731        </TERM>
 732        <LISTITEM>
 733         <PARA>
 734          The name of a column in the table.
 735         </PARA>
 736        </LISTITEM>
 737       </VARLISTENTRY>
 738      </VARIABLELIST>
 739     </para>
 740    </refsect3>
 741    <refsect3>
 742     <title>Outputs</title>
 743     <variablelist>
 744      <varlistentry>
 745       <term>ERROR: Cannot insert a duplicate key into a unique index.</term>
 746       <listitem>
 747        <para>
 748         This occurs at run-time if one tries to insert a duplicate value into
 749         a column subject to a PRIMARY KEY constraint.
 750       </PARA>
 751       </listitem>
 752      </varlistentry>
 753     </variablelist>
 754    </refsect3>
 755    <refsect3>
 756     <title>Description</title>
 757     <PARA>
 758      The PRIMARY KEY constraint specifies a rule that a group of one
 759      or more distinct columns of a table may contain only unique,
 760      (not duplicates), non-null values. The column definitions of
 761      the specified columns do not have to include a NOT NULL
 762      constraint to be included in a PRIMARY KEY constraint.
 763     </PARA>
 764     <PARA>
 765      A table's set of valid values may be constrained by only one
 766      PRIMARY KEY constraint at a time.
 767     </PARA>
 768     <PARA>
 769      The PRIMARY KEY constraint must name a set of columns that is
 770      different from the set of columns named by any UNIQUE constraint
 771      defined for the same table.
 772     </PARA>
 773    </REFSECT3>
 774
 775    <REFSECT3 ID="R3-SQL-PRIMARYKEY-3">
 776     <REFSECT3INFO>
 777      <DATE>1998-04-15</DATE>
 778     </REFSECT3INFO>
 779     <TITLE>
 780      Notes
 781     </TITLE>
 782     <PARA>
 783      PostgreSQL automatically creates an unique index to assure
 784      data integrity. (See CREATE INDEX statement)
 785     </PARA>
 786    </refsect3>
 787
 788   </REFSECT2>
 789  </refsect1>
 790
 791  <REFSECT1 ID="R1-SQL-CREATETABLE-2">
 792   <TITLE>
 793    Usage
 794   </TITLE>
 795   <PARA>
 796    Create table films and table distributors
 797   </PARA>
 798   <ProgramListing>
 799    CREATE TABLE films (
 800           code      CHARACTER(5) CONSTRAINT firstkey PRIMARY KEY,
 801           title     CHARACTER VARYING(40) NOT NULL,
 802           did       DECIMAL(3) NOT NULL,
 803           date_prod DATE,
 804           kind      CHAR(10),
 805           len       INTERVAL HOUR TO MINUTE
 806           );
 807   </ProgramListing>
 808
 809   <ProgramListing>
 810    CREATE TABLE distributors (
 811           did      DECIMAL(03) PRIMARY KEY DEFAULT NEXTVAL('serial'),
 812           name     VARCHAR(40) NOT NULL CHECK (name &lt;&gt; '')
 813           );
 814   </ProgramListing>
 815
 816   <PARA>
 817    Create a table with a 2-dimensional array
 818   </PARA>
 819   <ProgramListing>
 820    CREATE TABLE array (
 821           vector INT[][]
 822           );
 823   </ProgramListing>
 824
 825   <PARA>
 826    Define two NOT NULL column constraints on the table distributors
 827   </PARA>
 828   <ProgramListing>
 829    CREATE TABLE distributors (
 830         did      DECIMAL(3) CONSTRAINT no_null NOT NULL,
 831         name     VARCHAR(40) NOT NULL
 832         );
 833   </ProgramListing>
 834
 835   <PARA>
 836    Define a UNIQUE table constraint for the table films.
 837    UNIQUE table constraints can be defined on one or more
 838    columns of the table
 839   </PARA>
 840   <ProgramListing>
 841    CREATE TABLE films (
 842        code      CHAR(5),
 843        title     VARCHAR(40),
 844        did       DECIMAL(03),
 845        date_prod DATE,
 846        kind      CHAR(10),
 847        len       INTERVAL HOUR TO MINUTE,
 848        CONSTRAINT production UNIQUE(date_prod)
 849        );
 850   </ProgramListing>
 851
 852   <PARA>
 853    Defines a UNIQUE column constraint for the table distributors.
 854    UNIQUE column constraints can only be defined on one column
 855    of the table (the following two examples are equivalents).
 856   </PARA>
 857   <ProgramListing>
 858    CREATE TABLE distributors (
 859         did      DECIMAL(03),
 860         name     VARCHAR(40) UNIQUE,
 861         UNIQUE(name)
 862         );
 863   </ProgramListing>
 864
 865   <ProgramListing>
 866    CREATE TABLE distributors (
 867         did      DECIMAL(3),
 868         name     VARCHAR(40) UNIQUE
 869         );
 870   </ProgramListing>
 871
 872   <PARA>
 873    Define a CHECK column constraint.
 874   </PARA>
 875   <ProgramListing>
 876    CREATE TABLE distributors (
 877         did      DECIMAL(3) CHECK (did > 100),
 878         name     VARCHAR(40)
 879         );
 880   </ProgramListing>
 881
 882   <PARA>
 883    Define a CHECK table constraint
 884   </PARA>
 885   <ProgramListing>
 886    CREATE TABLE distributors (
 887         did      DECIMAL(3),
 888         name     VARCHAR(40)
 889         CONSTRAINT con1 CHECK (did > 100 AND name > '')
 890         );
 891   </ProgramListing>
 892
 893   <PARA>
 894    Define a PRIMARY KEY table constraint for the table films.
 895    PRIMARY KEY table constraints can be defined on one or more
 896    columns of the table
 897   </PARA>
 898   <ProgramListing>
 899    CREATE TABLE films (
 900        code      CHAR(05),
 901        title     VARCHAR(40),
 902        did       DECIMAL(03),
 903        date_prod DATE,
 904        kind      CHAR(10),
 905        len       INTERVAL HOUR TO MINUTE,
 906        CONSTRAINT code_title PRIMARY KEY(code,title)
 907        );
 908   </ProgramListing>
 909
 910   <PARA>
 911    Defines a PRIMARY KEY column constraint for table distributors.
 912    PRIMARY KEY column constraints can only be defined on one column
 913    of the table (the following two examples are equivalents)
 914   </PARA>
 915   <ProgramListing>
 916    CREATE TABLE distributors (
 917         did      DECIMAL(03),
 918         name     CHAR VARYING(40),
 919         PRIMARY KEY(did)
 920         );
 921
 922    CREATE TABLE distributors (
 923         did      DECIMAL(03) PRIMARY KEY,
 924         name     VARCHAR(40)
 925         );
 926   </ProgramListing>
 927   <para>
 928    To assign a sequence as the default for the column did,
 929    and a literal to the column name
 930   </PARA>
 931
 932   <ProgramListing>
 933        CREATE TABLE distributors (
 934               did      DECIMAL(3) DEFAULT NEXTVAL('serial'),
 935               name     VARCHAR(40) DEFAULT 'luso films'
 936               );
 937   </ProgramListing>
 938
 939   <REFSECT2 ID="R2-SQL-CREATETABLE-3">
 940    <REFSECT2INFO>
 941     <DATE>1998-04-15</DATE>
 942    </REFSECT2INFO>
 943    <TITLE>
 944     Notes
 945    </TITLE>
 946    <PARA>
 947     CREATE TABLE/INHERITS is a PostgreSQL language extension.
 948    </PARA>
 949   </refsect2>
 950
 951  </REFSECT1>
 952
 953  <REFSECT1 ID="R1-SQL-CREATETABLE-3">
 954   <TITLE>
 955    Compatibility
 956   </TITLE>
 957   <PARA>
 958   </PARA>
 959
 960   <REFSECT2 ID="R2-SQL-CREATETABLE-4">
 961    <REFSECT2INFO>
 962     <DATE>1998-04-15</DATE>
 963    </REFSECT2INFO>
 964    <TITLE>
 965     SQL92
 966    </TITLE>
 967    <PARA>
 968     In addition to normal CREATE TABLE, SQL92 also defines a
 969     CREATE TEMPORARY TABLE statement:
 970    </PARA>
 971    <synopsis>
 972    CREATE [ {GLOBAL | LOCAL} ] TEMPORARY TABLE table (
 973         column type [DEFAULT value] [CONSTRAINT column_constraint] [, ...] )
 974         [CONSTRAINT table_constraint ]
 975         [ ON COMMIT {DELETE | PRESERVE} ROWS ]
 976    </synopsis>
 977    <para>
 978     For temporary tables, the CREATE TEMPORARY TABLE statement
 979     names a new table and defines the table's columns and
 980     constraints.
 981    </para>
 982    <para>
 983     The optional ON COMMIT clause of CREATE TEMPORARY TABLE
 984     specifies whether or not the temporary table should be emptied of
 985     rows whenever COMMIT is executed. If the ON COMMIT clause is
 986     omitted, the default option, ON COMMIT DELETE ROWS, is assumed.
 987    </para>
 988    <para>
 989     To create a temporary table:
 990    </para>
 991    <programlisting>
 992       CREATE TEMPORARY TABLE actors (
 993              id      DECIMAL(03),
 994              name    VARCHAR(40),
 995              CONSTRAINT actor_id CHECK (id &lt; 150)
 996              ) ON COMMIT DELETE ROWS
 997    </programlisting>
 998    <para>
 999 Temporary tables are not currently available in <productname>Postgres</productname>.
1000 <tip>
1001    <para>
1002     In the current release of <productname>Postgres</productname> (v6.4), to create a temporary
1003     table you must create and drop the table by explicit commands.
1004 </tip>
1005
1006    <REFSECT3 ID="R3-SQL-UNIQUECLAUSE-1">
1007     <REFSECT3INFO>
1008      <DATE>1998-04-15</DATE>
1009     </REFSECT3INFO>
1010     <TITLE>
1011      UNIQUE clause
1012     </TITLE>
1013     <PARA>
1014      SQL92 specifies some additional capabilities for UNIQUE:
1015     <para>
1016      Table Constraint definition
1017     </PARA>
1018     <synopsis>
1019       [ CONSTRAINT name ]
1020       UNIQUE ( column [, ...] )
1021       [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1022       [ [ NOT ] DEFERRABLE ]
1023     </synopsis>
1024     <para>
1025      Column Constraint definition
1026     </para>
1027     <synopsis>
1028       [ CONSTRAINT name ]
1029       UNIQUE
1030       [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1031       [ [ NOT ] DEFERRABLE ]
1032     </synopsis>
1033    </refsect3>
1034
1035    <REFSECT3 ID="R3-SQL-NOTNULL-4">
1036     <REFSECT3INFO>
1037      <DATE>1998-04-15</DATE>
1038     </REFSECT3INFO>
1039     <TITLE>
1040      NOT NULL clause
1041     </TITLE>
1042     <PARA>
1043
1044      SQL92 specifies some additional capabilities for NOT NULL:
1045     </PARA>
1046     <synopsis>
1047       [ CONSTRAINT name ] NOT NULL
1048       [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1049       [ [ NOT ] DEFERRABLE ]
1050     </synopsis>
1051    </REFSECT3>
1052
1053 <!--
1054 I can't figure out why DEFAULT clause is different from what we already have.
1055 Perhaps because CURRENT_USER and CURRENT_DATE have specific types (currently
1056 the "name" type), if you aren't careful then the types won't match up with
1057 the column. Not our problem...
1058 - Thomas 1998-08-16
1059
1060    <REFSECT3 ID="R3-SQL-DEFAULTCLAUSE-1">
1061     <REFSECT3INFO>
1062      <DATE>1998-04-15</DATE>
1063     </REFSECT3INFO>
1064     <TITLE>
1065      DEFAULT clause
1066     </TITLE>
1067     <PARA>
1068      SQL92 specifies some additional capabilities for the DEFAULT clause.
1069      A DEFAULT clause is used to set the default value for a column
1070      or a domain.
1071     </para>
1072     <synopsis>
1073      DEFAULT niladic USER function |
1074              niladic datetime function |
1075              NULL
1076     </synopsis>
1077    </refsect3>
1078 -->
1079
1080    <REFSECT3 ID="R3-SQL-CONSTRAINT-3">
1081     <REFSECT3INFO>
1082      <DATE>1998-04-15</DATE>
1083     </REFSECT3INFO>
1084     <TITLE>
1085      CONSTRAINT clause
1086     </TITLE>
1087     <PARA>
1088      SQL92 specifies some additional capabilities for CONSTRAINTs,
1089      and also defines assertions and domain constraints.
1090     </PARA>
1091     <PARA>
1092      An assertion is a special type of integrity constraint and share
1093      the same namespace as other constraints.
1094      However, an assertion is not necessarily dependent on one
1095      particular base table as constraints are, so SQL-92 provides the
1096      CREATE ASSERTION statement as an alternate method for defining a
1097      constraint:
1098     </para>
1099     <synopsis>
1100      CREATE ASSERTION name CHECK ( condition )
1101     </synopsis>
1102
1103     <PARA>
1104      Domain constraints are defined by CREATE DOMAIN or ALTER DOMAIN
1105      statements:
1106     </para>
1107     <PARA>
1108      Domain constraint:
1109     </para>
1110     <synopsis>
1111       [ CONSTRAINT name ]
1112           CHECK constraint
1113           [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1114           [ [ NOT ] DEFERRABLE ]
1115     </synopsis>
1116     <para>
1117      Table constraint definition:
1118     </para>
1119     <synopsis>
1120       [ CONSTRAINT name ]
1121         { PRIMARY KEY constraint |
1122           FOREIGN KEY constraint |
1123           UNIQUE constraint |
1124           CHECK constraint }
1125           [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1126           [ [ NOT ] DEFERRABLE ]</synopsis>
1127     <para>
1128      Column constraint definition:
1129     </para>
1130     <synopsis>
1131      [ CONSTRAINT name ]
1132         { NOT NULL constraint |
1133           PRIMARY KEY constraint |
1134           FOREIGN KEY constraint |
1135           UNIQUE constraint |
1136           CHECK constraint }
1137           [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1138           [ [ NOT ] DEFERRABLE ]
1139     </synopsis>
1140     <para>
1141      A CONSTRAINT definition may contain one deferment attribute
1142      clause and/or one initial constraint mode clause, in any order.
1143      <variablelist>
1144       <varlistentry>
1145        <term>NOT DEFERRABLE</term>
1146        <listitem>
1147         <para>
1148          means that the Constraint must be checked for
1149          violation of its rule after the execution of every SQL statement.
1150         </para>
1151        </listitem>
1152       </varlistentry>
1153       <varlistentry>
1154        <term>DEFERRABLE</term>
1155        <listitem>
1156         <para>
1157          means that checking of the Constraint may be deferred
1158          until some later time, but no later than the end of the current
1159          transaction.
1160         </para>
1161        </listitem>
1162       </varlistentry>
1163      </variablelist>
1164     </para>
1165     <para>
1166      The constraint mode for every Constraint always has an initial
1167      default value which is set for that Constraint at the beginning
1168      of a transaction.
1169      <variablelist>
1170       <varlistentry>
1171        <term>INITIALLY IMMEDIATE</term>
1172        <listitem>
1173         <para>
1174          means that, as of the start of the transaction,
1175          the Constraint must be checked for violation of its rule after the
1176          execution of every SQL statement.
1177         </para>
1178        </listitem>
1179       </varlistentry>
1180       <varlistentry>
1181        <term>INITIALLY DEFERRED</term>
1182        <listitem>
1183         <para>
1184          means that, as of the start of the transaction,
1185          checking of the Constraint may be deferred until some later time,
1186          but no later than the end of the current transaction.</para>
1187        </listitem>
1188       </varlistentry>
1189      </variablelist>
1190     </para>
1191    </refsect3>
1192
1193
1194    <REFSECT3 ID="R3-SQL-CHECK-4">
1195     <REFSECT3INFO>
1196      <DATE>1998-04-15</DATE>
1197     </REFSECT3INFO>
1198     <TITLE>
1199      CHECK clause
1200     </TITLE>
1201     <PARA>
1202      SQL92 specifies some additional capabilities for CHECK in either
1203 table or column constraints.
1204     </PARA>
1205 <!--
1206 Constraints associated with domains do not need to be mentioned here,
1207 even though it is the case that a domain constraint may possibly
1208 affect a column or a table.
1209 - Thomas 1998-08-16
1210     <para>
1211      A CHECK constraint is either a table constraint, a column
1212      constraint or a domain constraint.
1213     </para>
1214 -->
1215     <para>
1216      table constraint definition:
1217     </para>
1218     <synopsis>
1219      [ CONSTRAINT name ]
1220       CHECK ( VALUE condition )
1221       [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1222       [ [ NOT ] DEFERRABLE ]
1223     </synopsis>
1224     <para>
1225      column constraint definition:
1226     </para>
1227     <synopsis>
1228       [ CONSTRAINT name ]
1229       CHECK ( VALUE condition )
1230       [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1231       [ [ NOT ] DEFERRABLE ]
1232     </synopsis>
1233 <!--
1234     <para>
1235      domain constraint definition:
1236     </para>
1237     <synopsis>
1238      [ CONSTRAINT name ]
1239       CHECK ( VALUE condition )
1240       [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1241       [ [ NOT ] DEFERRABLE ]
1242     </synopsis>
1243     <para>
1244      CHECK domain constraints can be defined in either
1245      a CREATE DOMAIN statement or an ALTER DOMAIN statement:
1246     </para>
1247     <programlisting>
1248      CREATE DOMAIN duration AS SMALLINT
1249         CONSTRAINT minutes CHECK (VALUE IN (90,120,180,240));
1250
1251      ALTER DOMAIN cities
1252         ADD CONSTRAINT new_city CHECK (VALUE LIKE 'L%');
1253     </programlisting>
1254 -->
1255    </refsect3>
1256
1257
1258    <REFSECT3 ID="R3-SQL-PRIMARYKEY-1">
1259     <REFSECT3INFO>
1260      <DATE>1998-04-15</DATE>
1261     </REFSECT3INFO>
1262     <TITLE>
1263      PRIMARY KEY clause
1264     </TITLE>
1265     <PARA>
1266      SQL92 specifies some additional capabilities for PRIMARY KEY:
1267     </para>
1268     <PARA>
1269      Table Constraint definition:
1270     </para>
1271     <synopsis>
1272       [ CONSTRAINT name ]
1273       PRIMARY KEY ( column [, ...] )
1274       [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1275       [ [ NOT ] DEFERRABLE ]
1276     </synopsis>
1277     <para>
1278      Column Constraint definition:
1279     </para>
1280     <synopsis>
1281       [ CONSTRAINT name ]
1282       PRIMARY KEY
1283       [ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
1284       [ [ NOT ] DEFERRABLE ]
1285     </synopsis>
1286    </refsect3>
1287   </refsect2>
1288  </refsect1>
1289 </refentry>
1290
1291 <!-- Keep this comment at the end of the file
1292 Local variables:
1293 mode: sgml
1294 sgml-omittag:t
1295 sgml-shorttag:t
1296 sgml-minimize-attributes:nil
1297 sgml-always-quote-attributes:t
1298 sgml-indent-step:1
1299 sgml-indent-data:t
1300 sgml-parent-document:nil
1301 sgml-default-dtd-file:"../reference.ced"
1302 sgml-exposed-tags:nil
1303 sgml-local-catalogs:"/usr/lib/sgml/catalog"
1304 sgml-local-ecat-files:nil
1305 End:
1306 -->