ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>
-ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceable>new_owner</replaceable>
+ALTER DATABASE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceable>newowner</replaceable>
</synopsis>
</refsynopsisdiv>
<title>Description</title>
<para>
- <command>ALTER DATABASE</command> is used to change the attributes
+ <command>ALTER DATABASE</command> changes the attributes
of a database.
</para>
<para>
- The first two forms change the session default of a run-time
+ The first two forms change the session default for a run-time
configuration variable for a <productname>PostgreSQL</productname>
database. Whenever a new session is subsequently started in that
database, the specified value becomes the session default value.
in <filename>postgresql.conf</> or has been received from the
<command>postmaster</command> command line. Only the database
owner or a superuser can change the session defaults for a
- database.
+ database. Certain variables cannot be set this way, or can only be
+ set by a superuser.
</para>
<para>
The third form changes the name of the database. Only the database
- owner can rename a database, and only if he has the
+ owner or a superuser can rename a database; non-superuser owners must
+ also have the
<literal>CREATEDB</literal> privilege. The current database cannot
be renamed. (Connect to a different database if you need to do
that.)
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
- The name of the database whose session defaults are to be altered.
+ The name of the database whose attributes are to be altered.
</para>
</listitem>
</varlistentry>
<term><replaceable>value</replaceable></term>
<listitem>
<para>
- Set the session default for this database of the specified
- configuration parameter to the given value. If
+ Set this database's session default for the specified configuration
+ parameter to the given value. If
<replaceable>value</replaceable> is <literal>DEFAULT</literal>
or, equivalently, <literal>RESET</literal> is used, the
- database-specific variable setting is removed and the system-wide
- default
+ database-specific setting is removed, so the system-wide default
setting will be inherited in new sessions. Use <literal>RESET
- ALL</literal> to clear all settings.
+ ALL</literal> to clear all database-specific settings.
</para>
<para>
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><replaceable class="parameter">newowner</replaceable></term>
+ <listitem>
+ <para>
+ The new owner of the database.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
<title>Notes</title>
<para>
- Using <xref linkend="sql-alteruser" endterm="sql-alteruser-title">,
- it is also possible to tie a session default to a specific user
- rather than a database. User-specific settings override database-specific
+ It is also possible to tie a session default to a specific user
+ rather than to a database; see
+ <xref linkend="sql-alteruser" endterm="sql-alteruser-title">.
+ User-specific settings override database-specific
ones if there is a conflict.
</para>
</refsect1>
<title>See Also</title>
<simplelist type="inline">
- <member><xref linkend="sql-alteruser" endterm="sql-alteruser-title"></member>
<member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member>
<member><xref linkend="sql-dropdatabase" endterm="sql-dropdatabase-title"></member>
<member><xref linkend="sql-set" endterm="sql-set-title"></member>
<title>Description</title>
<para>
- <command>ALTER GROUP</command> is used to change a user group. The
- first two variants add or remove users from a group. Only database
- superusers can use this command. Adding a user to a group does not
- create the user. Similarly, removing a user from a group does not
- drop the user itself.
+ <command>ALTER GROUP</command> changes the attributes of a user group.
+ </para>
+
+ <para>
+ The first two variants add users to a group or remove them from a group.
+ Only database superusers can use this command.
</para>
<para>
<term><replaceable class="PARAMETER">username</replaceable></term>
<listitem>
<para>
- Users which are to be added or removed from the group. The users
- must exist.
+ Users that are to be added to or removed from the group. The users
+ must already exist; <command>ALTER GROUP</> does not create or
+ drop users.
</para>
</listitem>
</varlistentry>
<xref linkend="sql-analyze" endterm="sql-analyze-title"> operations.
The target can be set in the range 0 to 1000; alternatively, set it
to -1 to revert to using the system default statistics
- target. For more information on the use of statistics by the
+ target (<xref linkend="guc-default-statistics-target">).
+ For more information on the use of statistics by the
<productname>PostgreSQL</productname> query planner, refer to
<xref linkend="planner-stats">.
</para>
compressible data. <literal>EXTERNAL</literal> is for external,
uncompressed data, and <literal>EXTENDED</literal> is for external,
compressed data. <literal>EXTENDED</literal> is the default for all
- data types that support it. The use of <literal>EXTERNAL</literal> will, for example,
- make substring operations on a <type>text</type> column faster, at the penalty of
- increased storage space.
+ data types that support it. Use of <literal>EXTERNAL</literal> will
+ make substring operations on <type>text</type> and <type>bytea</type>
+ columns faster, at the penalty of increased storage space.
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
- The name (possibly schema-qualified) of an existing table to
- alter. If <literal>ONLY</> is specified, only that table is
- altered. If <literal>ONLY</> is not specified, the table and all
- its descendant tables (if any) are updated. <literal>*</> can be
- appended to the table name to indicate that descendant tables are
- to be altered, but in the current version, this is the default
- behavior. (In releases before 7.1, <literal>ONLY</> was the
- default behavior. The default can be altered by changing the
- configuration parameter <xref linkend="guc-sql-inheritance">.)
+ The name (possibly schema-qualified) of an existing table to
+ alter. If <literal>ONLY</> is specified, only that table is
+ altered. If <literal>ONLY</> is not specified, the table and all
+ its descendant tables (if any) are updated. <literal>*</> can be
+ appended to the table name to indicate that descendant tables are
+ to be altered, but in the current version, this is the default
+ behavior. (In releases before 7.1, <literal>ONLY</> was the
+ default behavior. The default can be altered by changing the
+ configuration parameter <xref linkend="guc-sql-inheritance">.)
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">column</replaceable></term>
<listitem>
<para>
- Name of a new or existing column.
+ Name of a new or existing column.
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">new_column</replaceable></term>
<listitem>
<para>
- New name for an existing column.
+ New name for an existing column.
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">new_name</replaceable></term>
<listitem>
<para>
- New name for the table.
+ New name for the table.
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">type</replaceable></term>
<listitem>
<para>
- Data type of the new column, or new data type for an existing
- column.
+ Data type of the new column, or new data type for an existing
+ column.
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">table_constraint</replaceable></term>
<listitem>
<para>
- New table constraint for the table.
+ New table constraint for the table.
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">constraint_name</replaceable></term>
<listitem>
<para>
- Name of an existing constraint to drop.
+ Name of an existing constraint to drop.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Automatically drop objects that depend on the dropped column
- or constraint (for example, views referencing the column).
+ or constraint (for example, views referencing the column).
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Refuse to drop the column or constraint if there are any dependent
- objects. This is the default behavior.
+ objects. This is the default behavior.
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">index_name</replaceable></term>
<listitem>
<para>
- The index name on which the table should be marked for clustering.
+ The index name on which the table should be marked for clustering.
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">new_owner</replaceable></term>
<listitem>
<para>
- The user name of the new owner of the table.
+ The user name of the new owner of the table.
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">tablespace_name</replaceable></term>
<listitem>
<para>
- The tablespace name to which the table will be moved.
+ The tablespace name to which the table will be moved.
</para>
</listitem>
</varlistentry>
though a <literal>USING</literal> clause is supplied. In such cases,
drop the default with <literal>DROP DEFAULT</>, perform the <literal>ALTER
TYPE</>, and then use <literal>SET DEFAULT</> to add a suitable new
- default.
+ default. Similar considerations apply to indexes and constraints involving
+ the column.
</para>
<para>
</para>
<para>
- To move a table to a different tablespace:
+ To move a table to a different tablespace:
<programlisting>
ALTER TABLE distributors SET TABLESPACE fasttablespace;
</programlisting>
where <replaceable class="PARAMETER">option</replaceable> can be:
- [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
- | CREATEDB | NOCREATEDB
+ CREATEDB | NOCREATEDB
| CREATEUSER | NOCREATEUSER
+ | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
| VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
ALTER USER <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>
<title>Description</title>
<para>
- <command>ALTER USER</command> is used to change the attributes of a
+ <command>ALTER USER</command> changes the attributes of a
<productname>PostgreSQL</productname> user account. Attributes not
mentioned in the command retain their previous settings.
</para>
<para>
- The first variant of this command in the synopsis changes certain
- global user privileges and authentication settings. (See below for
- details.) Only a database superuser can change these privileges and
- the password expiration with this command. Ordinary users can only
- change their own password.
+ The first variant of this command listed in the synopsis changes certain
+ per-user privileges and authentication settings. (See below for
+ details.) Database superusers can change any of these settings for any
+ user. Ordinary users can only change their own password.
</para>
<para>
The second variant changes the name of the user. Only a database
- superuser can rename user accounts. The session user cannot be
+ superuser can rename user accounts. The current session user cannot be
renamed. (Connect as a different user if you need to do that.)
Because <literal>MD5</>-encrypted passwords use the user name as
cryptographic salt, renaming a user clears their <literal>MD5</>
or has been received from the <command>postmaster</command> command line.
Ordinary users can change their own session defaults.
Superusers can change anyone's session defaults.
+ Certain variables cannot be set this way, or can only be
+ set by a superuser.
</para>
</refsect1>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
- The name of the user whose attributes are to be altered.
+ The name of the user whose attributes are to be altered.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><replaceable class="PARAMETER">password</replaceable></term>
+ <term><literal>CREATEDB</literal></term>
+ <term><literal>NOCREATEDB</literal></term>
<listitem>
<para>
- The new password to be used for this account.
+ These clauses define a user's ability to create databases. If
+ <literal>CREATEDB</literal> is specified, the user
+ will be allowed to create his own databases. Using
+ <literal>NOCREATEDB</literal> will deny a user the ability to
+ create databases. (If the user is also a superuser, then this
+ setting has no real effect.)
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>ENCRYPTED</literal></term>
- <term><literal>UNENCRYPTED</literal></term>
+ <term><literal>CREATEUSER</literal></term>
+ <term><literal>NOCREATEUSER</literal></term>
<listitem>
<para>
- These key words control whether the password is stored
- encrypted in <literal>pg_shadow</>. (See
- <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
- for more information about this choice.)
+ These clauses determine whether a user will be permitted to
+ create new users himself. <literal>CREATEUSER</literal> will also make
+ the user a superuser, who can override all access restrictions.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>CREATEDB</literal></term>
- <term><literal>NOCREATEDB</literal></term>
+ <term><replaceable class="PARAMETER">password</replaceable></term>
<listitem>
<para>
- These clauses define a user's ability to create databases. If
- <literal>CREATEDB</literal> is specified, the user
- will be allowed to create his own databases. Using
- <literal>NOCREATEDB</literal> will deny a user the ability to
- create databases.
+ The new password to be used for this account.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>CREATEUSER</literal></term>
- <term><literal>NOCREATEUSER</literal></term>
+ <term><literal>ENCRYPTED</literal></term>
+ <term><literal>UNENCRYPTED</literal></term>
<listitem>
<para>
- These clauses determine whether a user will be permitted to
- create new users himself. This option will also make the user
- a superuser who can override all access restrictions.
+ These key words control whether the password is stored
+ encrypted in <literal>pg_shadow</>. (See
+ <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
+ for more information about this choice.)
</para>
</listitem>
</varlistentry>
<term><replaceable class="PARAMETER">abstime</replaceable></term>
<listitem>
<para>
- The date (and, optionally, the time)
- at which this user's password is to expire. To set the password
- never to expire, use <literal>'infinity'</>.
+ The date (and, optionally, the time)
+ at which this user's password is to expire. To set the password
+ never to expire, use <literal>'infinity'</>.
</para>
</listitem>
</varlistentry>
<term><replaceable>newname</replaceable></term>
<listitem>
<para>
- The new name of the user.
+ The new name of the user.
</para>
</listitem>
</varlistentry>
parameter to the given value. If
<replaceable>value</replaceable> is <literal>DEFAULT</literal>
or, equivalently, <literal>RESET</literal> is used, the
- user-specific variable setting is removed and the user will
+ user-specific variable setting is removed, so the user will
inherit the system-wide default setting in new sessions. Use
- <literal>RESET ALL</literal> to clear all settings.
+ <literal>RESET ALL</literal> to clear all user-specific settings.
</para>
<para>
</para>
<para>
- Using <xref linkend="sql-alterdatabase"
- endterm="sql-alterdatabase-title">, it is also possible to tie a
- session default to a specific database rather than a user.
+ The <literal>VALID UNTIL</> clause defines an expiration time for a
+ password only, not for the user account <foreignphrase>per se</>. In
+ particular, the expiration time is not enforced when logging in using
+ a non-password-based authentication method.
+ </para>
+
+ <para>
+ It is also possible to tie a
+ session default to a specific database rather than to a user; see
+ <xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">.
+ User-specific settings override database-specific
+ ones if there is a conflict.
</para>
</refsect1>
<title>Examples</title>
<para>
- Change a user password:
+ Change a user's password:
<programlisting>
ALTER USER davide WITH PASSWORD 'hu8jmn3';
</para>
<para>
- Change a user's valid until date:
+ Change the expiration date of the user's password:
<programlisting>
ALTER USER manuel VALID UNTIL 'Jan 31 2030';
</para>
<para>
- Change a user's valid until date, specifying that his
- authorization should expire at midday on 4th May 2005 using
+ Change a password expiration date, specifying that the password
+ should expire at midday on 4th May 2005 using
the time zone which is one hour ahead of <acronym>UTC</>:
<programlisting>
ALTER USER chris VALID UNTIL 'May 4 12:00:00 2005 +1';
</para>
<para>
- Make a user valid forever:
+ Make a password valid forever:
<programlisting>
ALTER USER fred VALID UNTIL 'infinity';
</programlisting>
<para>
A checkpoint is a point in the transaction log sequence at which
all data files have been updated to reflect the information in the
- log. All data files will be flushed to disk. Refer to the
+ log. All data files will be flushed to disk. Refer to
<xref linkend="wal"> for more information about the WAL system.
</para>
<para>
<productname>PostgreSQL</productname> does not have an explicit
<command>OPEN</command> cursor statement; a cursor is considered
- open when it is declared. Use the <command>DECLARE</command>
+ open when it is declared. Use the
+ <xref linkend="sql-declare" endterm="sql-declare-title">
statement to declare a cursor.
</para>
</refsect1>
<command>CLOSE</command> is fully conforming with the SQL standard.
</para>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-declare" endterm="sql-declare-title"></member>
+ <member><xref linkend="sql-fetch" endterm="sql-fetch-title"></member>
+ <member><xref linkend="sql-move" endterm="sql-move-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
</para>
<para>
- Cluster all the tables on the database that have previously been clustered:
+ Cluster all tables in the database that have previously been clustered:
<programlisting>
CLUSTER;
</programlisting>
<para>
<command>COMMENT</command> stores a comment about a database object.
- Comments can be
- easily retrieved with the <application>psql</application> commands
- <command>\dd</command>, <command>\d+</command>, and <command>\l+</command>.
- Other user interfaces to retrieve comments can be built atop
- the same built-in functions that <application>psql</application> uses, namely
- <function>obj_description</> and <function>col_description</>.
</para>
<para>
string.
Comments are automatically dropped when the object is dropped.
</para>
+
+ <para>
+ Comments can be
+ easily retrieved with the <application>psql</application> commands
+ <command>\dd</command>, <command>\d+</command>, and <command>\l+</command>.
+ Other user interfaces to retrieve comments can be built atop
+ the same built-in functions that <application>psql</application> uses, namely
+ <function>obj_description</> and <function>col_description</>
+ (see <xref linkend="functions-info-comment-table">).
+ </para>
</refsect1>
<refsect1>
<term><replaceable class="parameter">text</replaceable></term>
<listitem>
<para>
- The new comment.
+ The new comment, written as a string literal; or <literal>NULL</>
+ to drop the comment.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Causes all data to be stored or read in binary format rather
- than as text. You cannot specify the <option>DELIMITER</option>
- or <option>NULL</option> options in binary mode.
+ than as text. You cannot specify the <option>DELIMITER</option>,
+ <option>NULL</option>, or <option>CSV</> options in binary mode.
</para>
</listitem>
</varlistentry>
<term><literal>CSV</literal></term>
<listitem>
<para>
- Enables Comma Separated Variable (<literal>CSV</>) mode. (Also
- called Comma Separated Value). It sets the default
- <literal>DELIMITER</> to comma, and <literal>QUOTE</> and
- <literal>ESCAPE</> values to double-quote.
+ Selects Comma Separated Value (<literal>CSV</>) mode.
</para>
</listitem>
</varlistentry>
<para>
In <literal>CSV</> <command>COPY FROM</> mode, process each
specified column as though it were quoted and hence not a
- <literal>NULL</> value. For the default <literal>null string</> in
- <literal>CSV</> mode (<literal>''</>), this causes a missing
- values to be input as a zero-length strings.
+ <literal>NULL</> value. For the default null string in
+ <literal>CSV</> mode (<literal>''</>), this causes missing
+ values to be input as zero-length strings.
</para>
</listitem>
</varlistentry>
<para>
<command>COPY</command> input and output is affected by
- <varname>DateStyle </varname>. For portability with other
- <productname>PostgreSQL</productname> installations which might use
+ <varname>DateStyle</varname>. To ensure portability to other
+ <productname>PostgreSQL</productname> installations that might use
non-default <varname>DateStyle</varname> settings,
<varname>DateStyle</varname> should be set to <literal>ISO</> before
- using <command>COPY</>. In <literal>CSV</> mode, use <literal>ISO</>
- or a <varname>DateStyle</varname> setting appropriate for the
- external application.
+ using <command>COPY TO</>.
</para>
<para>
<title>Text Format</title>
<para>
- When <command>COPY</command> is used without the <literal>BINARY</literal> option,
- the data read or written is a text file with one line per table row,
- unless <literal>CSV</> mode is used.
+ When <command>COPY</command> is used without the <literal>BINARY</literal>
+ or <literal>CSV</> options,
+ the data read or written is a text file with one line per table row.
Columns in a row are separated by the delimiter character.
The column values themselves are strings generated by the
output function, or acceptable to the input function, of each
<para>
This format is used for importing and exporting the Comma
- Separated Variable (<literal>CSV</>) file format used by many other
+ Separated Value (<literal>CSV</>) file format used by many other
programs, such as spreadsheets. Instead of the escaping used by
<productname>PostgreSQL</productname>'s standard text mode, it
produces and recognises the common CSV escaping mechanism.
</para>
<para>
- In general, the <literal>CSV</> format has no way to distinguish a
+ The <literal>CSV</> format has no standard way to distinguish a
<literal>NULL</> value from an empty string.
<productname>PostgreSQL</>'s <command>COPY</> handles this by
quoting. A <literal>NULL</> is output as the <literal>NULL</>
so the file format is more a convention than a standard. Thus you
might encounter some files that cannot be imported using this
mechanism, and <command>COPY</> might produce files that other
- programs can not process.
+ programs cannot process.
</para>
</note>
<para>
<command>CREATE AGGREGATE</command> is a
<productname>PostgreSQL</productname> language extension. The SQL
- standard does not provide for user-defined aggregate function.
+ standard does not provide for user-defined aggregate functions.
</para>
</refsect1>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
- The name (optionally schema-qualified) of a domain to be created.
+ The name (optionally schema-qualified) of a domain to be created.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
The underlying data type of the domain. This may include array
- specifiers.
+ specifiers.
</para>
</listitem>
</varlistentry>
<title>See Also</title>
<simplelist type="inline">
+ <member><xref linkend="sql-alterdomain" endterm="sql-alterdomain-title"></member>
<member><xref linkend="sql-dropdomain" endterm="sql-dropdomain-title"></member>
</simplelist>
</refsect1>
<para>
If you drop and then recreate a function, the new function is not
- the same entity as the old; you will break existing rules, views,
- triggers, etc. that referred to the old function. Use
+ the same entity as the old; you will have to drop existing rules, views,
+ triggers, etc. that refer to the old function. Use
<command>CREATE OR REPLACE FUNCTION</command> to change a function
definition without breaking objects that refer to the function.
</para>
<listitem>
<para>
The data type(s) of the function's arguments (optionally
- schema-qualified), if any. The argument types may be base, complex, or
- domains, or copy the type of an existing column.
- </para>
- <para>
- The type of a column is referenced by writing
- <literal><replaceable
- class="parameter">tablename</replaceable>.<replaceable
- class="parameter">columnname</replaceable>%TYPE</literal>;
- using this can sometimes help make a function independent from
- changes to the definition of a table.
+ schema-qualified), if any. The argument types may be base, composite,
+ or domain types, or may reference the type of a table column.
</para>
<para>
Depending on the implementation language it may also be allowed
Pseudotypes indicate that the actual argument type is either
incompletely specified, or outside the set of ordinary SQL data types.
</para>
+ <para>
+ The type of a column is referenced by writing
+ <literal><replaceable
+ class="parameter">tablename</replaceable>.<replaceable
+ class="parameter">columnname</replaceable>%TYPE</literal>.
+ Using this feature can sometimes help make a function independent of
+ changes to the definition of a table.
+ </para>
</listitem>
</varlistentry>
<listitem>
<para>
The return data type (optionally schema-qualified). The return type
- may be a base type, complex type, or a domain,
- or may be specified to copy the type of an existing column. See the description
- under <literal>argtype</literal> above on how to reference the type
- of an existing column.
- </para>
- <para>
+ may be a base, composite, or domain type,
+ or may reference the type of a table column.
Depending on the implementation language it may also be allowed
to specify <quote>pseudotypes</> such as <type>cstring</>.
+ </para>
+ <para>
The <literal>SETOF</literal>
modifier indicates that the function will return a set of
items, rather than a single item.
</para>
+ <para>
+ The type of a column is referenced by writing
+ <literal><replaceable
+ class="parameter">tablename</replaceable>.<replaceable
+ class="parameter">columnname</replaceable>%TYPE</literal>.
+ </para>
</listitem>
</varlistentry>
The name of the language that the function is implemented in.
May be <literal>SQL</literal>, <literal>C</literal>,
<literal>internal</literal>, or the name of a user-defined
- procedural language. (See also <xref linkend="app-createlang"
- endterm="app-createlang-title">.) For backward compatibility,
+ procedural language. For backward compatibility,
the name may be enclosed by single quotes.
</para>
</listitem>
<term><literal>isStrict</></term>
<listitem>
<para>
- Equivalent to <literal>STRICT</literal> or <literal>RETURNS NULL ON NULL INPUT</literal>
+ Equivalent to <literal>STRICT</literal> or <literal>RETURNS NULL ON NULL INPUT</literal>.
</para>
</listitem>
</varlistentry>
information and examples, see <xref linkend="xfunc">.
<programlisting>
CREATE FUNCTION add(integer, integer) RETURNS integer
- AS $$select $1 + $2;$$
+ AS 'select $1 + $2;'
LANGUAGE SQL
IMMUTABLE
RETURNS NULL ON NULL INPUT;
<application>PL/pgSQL</application>:
<programlisting>
-CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS '
+CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS $$
BEGIN
RETURN i + 1;
- END;' LANGUAGE plpgsql;
+ END;
+$$ LANGUAGE plpgsql;
</programlisting>
</para>
</refsect1>
</refsect1>
- <refsect1 id="sql-createfunction-seealso">
+ <refsect1>
<title>See Also</title>
- <para>
- <xref linkend="sql-alterfunction" endterm="sql-alterfunction-title">,
- <xref linkend="sql-dropfunction" endterm="sql-dropfunction-title">,
- <xref linkend="sql-grant" endterm="sql-grant-title">,
- <xref linkend="sql-load" endterm="sql-load-title">,
- <xref linkend="sql-revoke" endterm="sql-revoke-title">,
- <xref linkend="app-createlang">
- </para>
+ <simplelist type="inline">
+ <member><xref linkend="sql-alterfunction" endterm="sql-alterfunction-title"></member>
+ <member><xref linkend="sql-dropfunction" endterm="sql-dropfunction-title"></member>
+ <member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
+ <member><xref linkend="sql-load" endterm="sql-load-title"></member>
+ <member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
+ <member><xref linkend="app-createlang" endterm="app-createlang-title"></member>
+ </simplelist>
</refsect1>
</refentry>
<title>Description</title>
<para>
- <command>CREATE GROUP</command> will create a new group in the
- database cluster. You must be a database
- superuser to use this command.
+ <command>CREATE GROUP</command> will create a new group of users.
+ You must be a database superuser to use this command.
+ </para>
+
+ <para>
+ Note that both users and groups are defined at the database cluster
+ level, and so are valid in all databases in the cluster.
</para>
<para>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
- The name of the group.
+ The name of the group.
</para>
</listitem>
</varlistentry>
<para>
The <literal>SYSID</literal> clause can be used to choose
the <productname>PostgreSQL</productname> group ID of the new
- group. It is not necessary to do so, however.
+ group.
+ This is normally not necessary, but may
+ be useful if you need to recreate a group referenced in the
+ permissions of some object.
</para>
<para>
- If this is not specified, the highest assigned group ID plus one,
- starting at 1, will be used as default.
+ If this is not specified, the highest assigned group ID plus one
+ (with a minimum of 100) will be used as default.
</para>
</listitem>
</varlistentry>
standard. Roles are similar in concept to groups.
</para>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-altergroup" endterm="sql-altergroup-title"></member>
+ <member><xref linkend="sql-dropgroup" endterm="sql-dropgroup-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
can improve performance by creating an index on just that portion.
Another possible application is to use <literal>WHERE</literal> with
<literal>UNIQUE</literal> to enforce uniqueness over a subset of a
- table.
- </para>
-
- <para>
- Indexes are not used for <literal>IS NULL</> clauses by default.
- The best way to use indexes in such cases is to create a partial index
- using an <literal>IS NULL</> comparison.
+ table. See <xref linkend="indexes-partial"> for more discussion.
</para>
<para>
<para>
See <xref linkend="indexes"> for information about when indexes can
be used, when they are not used, and in which particular situations
- can be useful.
+ they can be useful.
</para>
<para>
Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
to remove an index.
</para>
+
+ <para>
+ Indexes are not used for <literal>IS NULL</> clauses by default.
+ The best way to use indexes in such cases is to create a partial index
+ using an <literal>IS NULL</> predicate.
+ </para>
</refsect1>
<refsect1>
are no provisions for indexes in the SQL standard.
</para>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-alterindex" endterm="sql-alterindex-title"></member>
+ <member><xref linkend="sql-dropindex" endterm="sql-dropindex-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
<para>
<command>CREATE LANGUAGE</command> effectively associates the
language name with a call handler that is responsible for executing
- functions written in the language. Refer to <xref linkend="xfunc">
+ functions written in the language. Refer to <xref linkend="xplang">
for more information about language call handlers.
</para>
has an option to list the installed languages.
</para>
- <para>
- The definition of a procedural language cannot be changed once it
- has been created, with the exception of the privileges.
- </para>
-
<para>
To be able to use a procedural language, a user must be granted the
<literal>USAGE</literal> privilege. The
<member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member>
<member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
<member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
- <member><xref linkend="app-createlang"></member>
- <member><xref linkend="app-droplang"></member>
+ <member><xref linkend="app-createlang" endterm="app-createlang-title"></member>
+ <member><xref linkend="app-droplang" endterm="app-droplang-title"></member>
</simplelist>
</refsect1>
</refentry>
<para>
The other clauses specify optional operator optimization clauses.
- Their meaning is detailed in <xref linkend="xoper">.
+ Their meaning is detailed in <xref linkend="xoper-optimization">.
</para>
</refsect1>
provisions for user-defined operators in the SQL standard.
</para>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-alteroperator" endterm="sql-alteroperator-title"></member>
+ <member><xref linkend="sql-createopclass" endterm="sql-createopclass-title"></member>
+ <member><xref linkend="sql-dropoperator" endterm="sql-dropoperator-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
attempts to perform the update action, because it thinks it might
end up trying to perform the action on the dummy table of the view
in some cases. If you want to handle all the useful cases in
- conditional rules, you can; just add an unconditional <literal>DO
+ conditional rules, add an unconditional <literal>DO
INSTEAD NOTHING</literal> rule to ensure that the system
understands it will never be called on to update the dummy table.
- Then make the conditional rules not <literal>INSTEAD</literal>; in
+ Then make the conditional rules non-<literal>INSTEAD</literal>; in
the cases where they are applied, they add to the default
<literal>INSTEAD NOTHING</literal> action.
</para>
CREATE RULE "_RETURN" AS
ON SELECT TO t1
DO INSTEAD
- SELECT * FROM t2;
+ SELECT * FROM t2;
CREATE RULE "_RETURN" AS
ON SELECT TO t2
DO INSTEAD
- SELECT * FROM t1;
+ SELECT * FROM t1;
SELECT * FROM t1;
</programlisting>
<title>Description</title>
<para>
- <command>CREATE SCHEMA</command> will enter a new schema
+ <command>CREATE SCHEMA</command> enters a new schema
into the current database.
The schema name must be distinct from the name of any existing schema
in the current database.
whose names may duplicate those of other objects existing in other
schemas. Named objects are accessed either by <quote>qualifying</>
their names with the schema name as a prefix, or by setting a search
- path that includes the desired schema(s). Unqualified objects are
- created in the current schema (the one at the front of the search path,
+ path that includes the desired schema(s). A <literal>CREATE</> command
+ specifying an unqualified object name creates the object
+ in the current schema (the one at the front of the search path,
which can be determined with the function <function>current_schema</function>).
</para>
</para>
<para>
- A table cannot have more than 1600 columns. (In practice, the
- effective limit is lower because of tuple-length constraints).
- </para>
-
- <para>
- The optional constraint clauses specify constraints (or tests) that
+ The optional constraint clauses specify constraints (tests) that
new or updated rows must satisfy for an insert or update operation
to succeed. A constraint is an SQL object that helps define the
set of valid values in the table in various ways.
column definition. A table constraint definition is not tied to a
particular column, and it can encompass more than one column.
Every column constraint can also be written as a table constraint;
- a column constraint is only a notational convenience if the
+ a column constraint is only a notational convenience for use when the
constraint only affects one column.
</para>
</refsect1>
<listitem>
<para>
The data type of the column. This may include array
- specifiers. For more information on the data types included with
+ specifiers. For more information on the data types supported by
<productname>PostgreSQL</productname>, refer to <xref
linkend="datatype">.
</para>
</listitem>
</varlistentry>
- <varlistentry>
- <term><literal>LIKE <replaceable>parent_table</replaceable> [ { INCLUDING | EXCLUDING } DEFAULTS ]</literal></term>
- <listitem>
- <para>
- The <literal>LIKE</literal> clause specifies a table from which
- the new table automatically copies all column names, their data types,
- and their not-null constraints.
- </para>
- <para>
- Unlike <literal>INHERITS</literal>, the new table and original table
- are completely decoupled after creation is complete. Changes to the
- original table will not be applied to the new table, and it is not
- possible to include data of the new table in scans of the original
- table.
- </para>
- <para>
- Default expressions for the copied column definitions will only be
- included if <literal>INCLUDING DEFAULTS</literal> is specified. The
- default is to exclude default expressions.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><literal>INHERITS ( <replaceable>parent_table</replaceable> [, ... ] )</literal></term>
<listitem>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><literal>LIKE <replaceable>parent_table</replaceable> [ { INCLUDING | EXCLUDING } DEFAULTS ]</literal></term>
+ <listitem>
+ <para>
+ The <literal>LIKE</literal> clause specifies a table from which
+ the new table automatically copies all column names, their data types,
+ and their not-null constraints.
+ </para>
+ <para>
+ Unlike <literal>INHERITS</literal>, the new table and original table
+ are completely decoupled after creation is complete. Changes to the
+ original table will not be applied to the new table, and it is not
+ possible to include data of the new table in scans of the original
+ table.
+ </para>
+ <para>
+ Default expressions for the copied column definitions will only be
+ copied if <literal>INCLUDING DEFAULTS</literal> is specified. The
+ default behavior is to exclude default expressions, resulting in
+ all columns of the new table having null defaults.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><literal>WITH OIDS</></term>
<term><literal>WITHOUT OIDS</></term>
</para>
<para>
- If <literal>WITHOUT OIDS</literal> is specified or implied, this
- means that the generation of OIDs for this table will be
- supressed. This is generally considered worthwhile, since it
+ If <literal>WITHOUT OIDS</literal> is specified or implied, the new
+ table does not store OIDs and no OID will be assigned for a row inserted
+ into it. This is generally considered worthwhile, since it
will reduce OID consumption and thereby postpone the wraparound
of the 32-bit OID counter. Once the counter wraps around, OIDs
can no longer be assumed to be unique, which makes them
considerably less useful. In addition, excluding OIDs from a
- table reduces the space required on disk to storage the table by
- 4 bytes per row, leading to increased performance.
+ table reduces the space required to store the table on disk by
+ 4 bytes per row (on most machines), slightly improving performance.
</para>
<para>
</para>
<para>
- This clause is only available for compatibility with
+ This clause is only provided for compatibility with
non-standard SQL databases. Its use is discouraged in new
applications.
</para>
<listitem>
<para>
The <literal>UNIQUE</literal> constraint specifies that a
- group of one or more distinct columns of a table may contain
+ group of one or more columns of a table may contain
only unique values. The behavior of the unique table constraint
is the same as that for column constraints, with the additional
capability to span multiple columns.
clause specifies the action to perform when a referenced column
in the referenced table is being updated to a new value. If the
row is updated, but the referenced column is not actually
- changed, no action is done. Referential actions apart from the
- check of <literal>NO ACTION</literal> can not be deferred even if
- the constraint is deferrable. There are the following possible
+ changed, no action is done. Referential actions other than the
+ <literal>NO ACTION</literal> check cannot be deferred, even if
+ the constraint is declared deferrable. There are the following possible
actions for each clause:
<variablelist>
Produce an error indicating that the deletion or update
would create a foreign key constraint violation.
This is the same as <literal>NO ACTION</literal> except that
- the check is not deferrable.
+ the check is not deferrable.
</para>
</listitem>
</varlistentry>
<refsect1 id="SQL-CREATETABLE-notes">
<title>Notes</title>
- <itemizedlist>
- <listitem>
<para>
Using OIDs in new applications is not recommended: where
possible, using a <literal>SERIAL</literal> or other sequence
generator as the table's primary key is preferred. However, if
- your application does make use of OIDs to identify specific rows
+ your application does make use of OIDs to identify specific
rows of a table, it is recommended to create a unique constraint
on the <structfield>oid</> column of that table, to ensure that
OIDs in the table will indeed uniquely identify rows even after
unique data key, it is difficult to identify specific rows.
</para>
</tip>
- </listitem>
- <listitem>
<para>
<productname>PostgreSQL</productname> automatically creates an
index for each unique constraint and primary key constraint to
- enforce the uniqueness. Thus, it is not necessary to create an
- explicit index for primary key columns. (See <xref
+ enforce uniqueness. Thus, it is not necessary to create an
+ index explicitly for primary key columns. (See <xref
linkend="sql-createindex" endterm="sql-createindex-title"> for more information.)
</para>
- </listitem>
- <listitem>
<para>
Unique constraints and primary keys are not inherited in the
current implementation. This makes the combination of
inheritance and unique constraints rather dysfunctional.
</para>
- </listitem>
- </itemizedlist>
+
+ <para>
+ A table cannot have more than 1600 columns. (In practice, the
+ effective limit is lower because of tuple-length constraints.)
+ </para>
+
</refsect1>
Define a primary key constraint for table
<structname>distributors</>. The following two examples are
equivalent, the first using the table constraint syntax, the second
- the column constraint notation.
+ the column constraint syntax.
<programlisting>
CREATE TABLE distributors (
<refsynopsisdiv>
<synopsis>
-CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable> [ (<replaceable>column_name</replaceable> [, ...] ) ] [ [ WITH | WITHOUT ] OIDS ]
+CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable>
+ [ (<replaceable>column_name</replaceable> [, ...] ) ] [ [ WITH | WITHOUT ] OIDS ]
AS <replaceable>query</replaceable>
</synopsis>
</refsynopsisdiv>
<para>
The name of a column in the new table. If column names are not
provided, they are taken from the output column names of the
- query. If the table is created out of an
- <command>EXECUTE</command> command, a column name list can
- currently not be specified.
+ query. If the table is created from an
+ <command>EXECUTE</command> command, a column name list cannot be
+ specified.
</para>
</listitem>
</varlistentry>
<para>
This optional clause specifies whether the table created by
<command>CREATE TABLE AS</command> should include OIDs. If
- neither form of this clause if specified, the value of the
+ neither form of this clause is specified, the value of the
<xref linkend="guc-default-with-oids"> configuration parameter is
used.
</para>
<para>
Prior to <productname>PostgreSQL</productname> 8.0, <command>CREATE
TABLE AS</command> always included OIDs in the table it
- produced. Furthermore, these OIDs were newly generated: they were
- distinct from the OIDs of any of the rows in the source tables of
- the <command>SELECT</command> or <command>EXECUTE</command>
- statement. Therefore, if <command>CREATE TABLE AS</command> was
- frequently executed, the OID counter would be rapidly
- incremented. As of <productname>PostgresSQL</productname> 8.0,
+ produced. As of <productname>PostgresSQL</productname> 8.0,
the <command>CREATE TABLE AS</command> command allows the user to
explicitly specify whether OIDs should be included. If the
presence of OIDs is not explicitly specified,
<para>
<command>CREATE TYPE</command> registers a new data type for use in
- the current data base. The user who defines a type becomes its
+ the current database. The user who defines a type becomes its
owner.
</para>
This is essentially the same as the row type
of a table, but using <command>CREATE TYPE</command> avoids the need to
create an actual table when all that is wanted is to define a type.
- A stand-alone composite type is useful as the return type of a function.
+ A stand-alone composite type is useful as the argument or return type of a
+ function.
</para>
</refsect2>
The first argument is the input text as a C string, the second
argument is the element type's OID in case this is an array type
(or the type's own OID for a composite type),
- and the third is the <literal>typmod</> of the destination column, if known.
+ and the third is the <literal>typmod</> of the destination column, if known
+ (-1 will be passed if not).
The input function should return a value of the data type itself.
The output function may be
declared as taking one argument of the new data type, or as taking
a function definition:
<programlisting>
CREATE TYPE compfoo AS (f1 int, f2 text);
+
CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS $$
SELECT fooid, fooname FROM foo
$$ LANGUAGE SQL;
<para>
More examples, including suitable input and output functions, are
- in <xref linkend="extend">.
+ in <xref linkend="xtypes">.
</para>
</refsect1>
where <replaceable class="PARAMETER">option</replaceable> can be:
SYSID <replaceable class="PARAMETER">uid</replaceable>
- | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
| CREATEDB | NOCREATEDB
| CREATEUSER | NOCREATEUSER
| IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...]
+ | [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
| VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
</synopsis>
</refsynopsisdiv>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
- The name of the user.
+ The name of the new user.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
The <literal>SYSID</literal> clause can be used to choose the
- <productname>PostgreSQL</productname> user ID of the user that
- is being created. This is not normally not necessary, but may
+ <productname>PostgreSQL</productname> user ID of the new user.
+ This is normally not necessary, but may
be useful if you need to recreate the owner of an orphaned
object.
</para>
<para>
If this is not specified, the highest assigned user ID plus one
- (with a minimum of 100) will be used as default.
+ (with a minimum of 100) will be used as default.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><replaceable class="parameter">password</replaceable></term>
+ <term><literal>CREATEDB</></term>
+ <term><literal>NOCREATEDB</></term>
<listitem>
<para>
- Sets the user's password. If you do not plan to use password
- authentication you can omit this option, but then the user
- won't be able to connect if you decide to switch to password
- authentication. The password can be set or changed later,
- using <xref linkend="SQL-ALTERUSER"
- endterm="SQL-ALTERUSER-title">.
+ These clauses define a user's ability to create databases. If
+ <literal>CREATEDB</literal> is specified, the user being
+ defined will be allowed to create his own databases. Using
+ <literal>NOCREATEDB</literal> will deny a user the ability to
+ create databases. If not specified,
+ <literal>NOCREATEDB</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>ENCRYPTED</></term>
- <term><literal>UNENCRYPTED</></term>
+ <term><literal>CREATEUSER</literal></term>
+ <term><literal>NOCREATEUSER</literal></term>
<listitem>
<para>
- These key words control whether the password is stored
- encrypted in the system catalogs. (If neither is specified,
- the default behavior is determined by the configuration
- parameter <xref linkend="guc-password-encryption">.) If the
- presented password string is already in MD5-encrypted format,
- then it is stored encrypted as-is, regardless of whether
- <literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified
- (since the system cannot decrypt the specified encrypted
- password string). This allows reloading of encrypted
- passwords during dump/restore.
- </para>
-
- <para>
- Note that older clients may lack support for the MD5
- authentication mechanism that is needed to work with passwords
- that are stored encrypted.
+ These clauses determine whether a user will be permitted to
+ create new users himself. <literal>CREATEUSER</literal> will also make
+ the user a superuser, who can override all access restrictions.
+ If not specified,
+ <literal>NOCREATEUSER</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>CREATEDB</></term>
- <term><literal>NOCREATEDB</></term>
+ <term><replaceable class="parameter">groupname</replaceable></term>
<listitem>
<para>
- These clauses define a user's ability to create databases. If
- <literal>CREATEDB</literal> is specified, the user being
- defined will be allowed to create his own databases. Using
- <literal>NOCREATEDB</literal> will deny a user the ability to
- create databases. If this clause is omitted,
- <literal>NOCREATEDB</literal> is used by default.
+ A name of an existing group into which to insert the user as a new
+ member. Multiple group names may be listed.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>CREATEUSER</literal></term>
- <term><literal>NOCREATEUSER</literal></term>
+ <term><replaceable class="parameter">password</replaceable></term>
<listitem>
<para>
- These clauses determine whether a user will be permitted to
- create new users himself. This option will also make the user
- a superuser who can override all access restrictions.
- Omitting this clause will set the user's value of this
- attribute to be <literal>NOCREATEUSER</literal>.
+ Sets the user's password. If you do not plan to use password
+ authentication you can omit this option, but then the user
+ won't be able to connect if you decide to switch to password
+ authentication. The password can be set or changed later,
+ using <xref linkend="SQL-ALTERUSER"
+ endterm="SQL-ALTERUSER-title">.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><replaceable class="parameter">groupname</replaceable></term>
+ <term><literal>ENCRYPTED</></term>
+ <term><literal>UNENCRYPTED</></term>
<listitem>
<para>
- A name of a group into which to insert the user as a new member.
- Multiple group names may be listed.
+ These key words control whether the password is stored
+ encrypted in the system catalogs. (If neither is specified,
+ the default behavior is determined by the configuration
+ parameter <xref linkend="guc-password-encryption">.) If the
+ presented password string is already in MD5-encrypted format,
+ then it is stored encrypted as-is, regardless of whether
+ <literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified
+ (since the system cannot decrypt the specified encrypted
+ password string). This allows reloading of encrypted
+ passwords during dump/restore.
+ </para>
+
+ <para>
+ Note that older clients may lack support for the MD5
+ authentication mechanism that is needed to work with passwords
+ that are stored encrypted.
</para>
</listitem>
</varlistentry>
<term><replaceable class="parameter">abstime</replaceable></term>
<listitem>
<para>
- The <literal>VALID UNTIL</literal> clause sets an absolute
- time after which the user's password is no longer valid. If
- this clause is omitted the login will be valid for all time.
+ The <literal>VALID UNTIL</literal> clause sets an absolute
+ time after which the user's password is no longer valid. If
+ this clause is omitted the password will be valid for all time.
</para>
</listitem>
</varlistentry>
the same functionality as <command>CREATE USER</command> (in fact, it calls this
command) but can be run from the command shell.
</para>
+
+ <para>
+ The <literal>VALID UNTIL</> clause defines an expiration time for a
+ password only, not for the user account <foreignphrase>per se</>. In
+ particular, the expiration time is not enforced when logging in using
+ a non-password-based authentication method.
+ </para>
</refsect1>
<refsect1>
<term><literal>CHECK OPTION</literal></term>
<listitem>
<para>
- This option is to do with updatable views. All
+ This option has to do with updatable views. All
<command>INSERT</> and <command>UPDATE</> commands on the view
will be checked to ensure data satisfy the view-defining
condition (that is, the new data would be visible through the
<productname>PostgreSQL</productname> language extension.
</para>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-dropview" endterm="sql-dropview-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
extension.
</para>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-close" endterm="sql-close-title"></member>
+ <member><xref linkend="sql-fetch" endterm="sql-fetch-title"></member>
+ <member><xref linkend="sql-move" endterm="sql-move-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
<tip>
<para>
<xref linkend="sql-truncate" endterm="sql-truncate-title"> is a
- <productname>PostgreSQL</productname> extension which provides a
+ <productname>PostgreSQL</productname> extension that provides a
faster mechanism to remove all rows from a table.
</para>
</tip>
<para>
By default, <command>DELETE</command> will delete rows in the
- specified table and all its subtables. If you wish to only delete
+ specified table and all its subtables. If you wish to delete only
from the specific table mentioned, you must use the
<literal>ONLY</literal> clause.
</para>
</variablelist>
</refsect1>
+ <refsect1>
+ <title>Notes</title>
+
+ <para>
+ It is unwise to drop a group that has any
+ granted permissions on objects. Currently, this is not enforced,
+ but it is likely that future versions of
+ <productname>PostgreSQL</productname> will check for the error.
+ </para>
+ </refsect1>
+
<refsect1>
<title>Examples</title>
<title>Compatibility</title>
<para>
- <command>DROP SEQUENCE</command> conforms with <acronym>SQL:2003</acronym>.
+ <command>DROP SEQUENCE</command> conforms with
+ <acronym>SQL:2003</acronym>, except that the standard only allows one
+ sequence to be dropped per command.
</para>
</refsect1>
<para>
<command>DROP TABLE</command> always removes any indexes, rules,
triggers, and constraints that exist for the target table.
- However, to drop a table that is referenced by a foreign-key
+ However, to drop a table that is referenced by a view or a foreign-key
constraint of another table, <literal>CASCADE</> must be
- specified. (<literal>CASCADE</> will remove the foreign-key
+ specified. (<literal>CASCADE</> will remove a dependent view entirely,
+ but in the foreign-key case it will only remove the foreign-key
constraint, not the other table entirely.)
</para>
</refsect1>
<title>Compatibility</title>
<para>
- This command conforms to the SQL standard.
+ This command conforms to the SQL standard, except that the standard only
+ allows one table to be dropped per command.
</para>
</refsect1>
To drop a user who owns a database, first drop the database or change
its ownership.
</para>
+
+ <para>
+ It is unwise to drop a user who either owns any database objects or has any
+ granted permissions on objects. Currently, this is only enforced for
+ the case of owners of databases, but it is likely that future versions of
+ <productname>PostgreSQL</productname> will check other cases.
+ </para>
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
- This command conforms to the SQL standard.
+ This command conforms to the SQL standard, except that the standard only
+ allows one view to be dropped per command.
</para>
</refsect1>
This command displays the execution plan that the
<productname>PostgreSQL</productname> planner generates for the
supplied statement. The execution plan shows how the table(s)
- referenced by the statement will be scanned---by plain sequential scan,
- index scan, etc.---and if multiple tables are referenced, what join
- algorithms will be used to bring together the required row from
+ referenced by the statement will be scanned — by plain sequential scan,
+ index scan, etc. — and if multiple tables are referenced, what join
+ algorithms will be used to bring together the required rows from
each input table.
</para>
<para>
Show the full internal representation of the plan tree, rather
than just a summary. Usually this option is only useful for
- debugging <productname>PostgreSQL</productname>. The
+ specialized debugging purposes. The
<literal>VERBOSE</literal> output is either pretty-printed or
not, depending on the setting of the <xref
linkend="guc-explain-pretty-print"> configuration parameter.
There is no <command>EXPLAIN</command> statement defined in the SQL standard.
</para>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-analyze" endterm="sql-analyze-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
name; the option to use <literal>IN</> is an extension.
</para>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-close" endterm="sql-close-title"></member>
+ <member><xref linkend="sql-declare" endterm="sql-declare-title"></member>
+ <member><xref linkend="sql-move" endterm="sql-move-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
<title>Description</title>
<para>
- <command>INSERT</command> allows one to insert new rows into a
- table. One can insert
- a single row at a time or several rows as a result of a query.
+ <command>INSERT</command> inserts new rows into a table.
+ One can insert a single row specified by value expressions,
+ or several rows as a result of a query.
</para>
<para>
- The columns in the target list may be listed in any order.
- Each column not present in the target list will be inserted
- using a default value, either its declared default value
- or null.
+ The target column names may be listed in any order. If no list of
+ column names is given at all, the default is all the columns of the
+ table in their declared order; or the first <replaceable>N</> column
+ names, if there are only <replaceable>N</> columns supplied by the
+ <literal>VALUES</> clause or <replaceable>query</>. The values
+ supplied by the <literal>VALUES</> clause or <replaceable>query</> are
+ associated with the explicit or implicit column list left-to-right.
</para>
<para>
- If the expression for each column is not of the correct data type,
+ Each column not present in the explicit or implicit column list will be
+ filled with a default value, either its declared default value
+ or null if there is none.
+ </para>
+
+ <para>
+ If the expression for any column is not of the correct data type,
automatic type conversion will be attempted.
</para>
<term><replaceable class="PARAMETER">expression</replaceable></term>
<listitem>
<para>
- An expression or value to assign to <replaceable
+ An expression or value to assign to the corresponding <replaceable
class="PARAMETER">column</replaceable>.
</para>
</listitem>
<term><literal>DEFAULT</literal></term>
<listitem>
<para>
- This column will be filled with its default value.
+ The corresponding <replaceable>column</replaceable> will be filled with
+ its default value.
</para>
</listitem>
</varlistentry>
</para>
<para>
- In this second example, the last column <literal>len</literal> is
- omitted and therefore it will have the default value of null:
+ In this second example, the <literal>len</literal> column is
+ omitted and therefore it will have the default value:
<programlisting>
INSERT INTO films (code, title, did, date_prod, kind)
</para>
<para>
- This examples inserts several rows into table
+ This example inserts several rows into table
<literal>films</literal> from table <literal>tmp</literal>:
<programlisting>
<title>Compatibility</title>
<para>
- <command>INSERT</command> conforms fully to the SQL standard.
+ <command>INSERT</command> conforms to the SQL standard. The case in
+ which a column name list is omitted, but not all the columns are
+ filled from the <literal>VALUES</> clause or <replaceable>query</>,
+ is disallowed by the standard.
+ </para>
+
+ <para>
Possible limitations of the <replaceable
class="PARAMETER">query</replaceable> clause are documented under
<xref linkend="sql-select" endterm="sql-select-title">.
The file name is specified in the same way as for shared library
names in <xref linkend="sql-createfunction" endterm="sql-createfunction-title">; in particular, one
may rely on a search path and automatic addition of the system's standard
- shared library file name extension. See <xref linkend="xfunc"> for
+ shared library file name extension. See <xref linkend="xfunc-c"> for
more information on this topic.
</para>
</refsect1>
restrictive lock mode possible. <command>LOCK TABLE</command>
provides for cases when you might need more restrictive locking.
For example, suppose an application runs a transaction at the
- isolation level read committed and needs to ensure that data in a
+ Read Committed isolation level and needs to ensure that data in a
table remains stable for the duration of the transaction. To
achieve this you could obtain <literal>SHARE</> lock mode over the
table before querying. This will prevent concurrent data changes
</para>
<para>
- To achieve a similar effect when running a transaction at the
- isolation level serializable, you have to execute the <command>LOCK
- TABLE</> statement before executing any data modification
- statement. A serializable transaction's view of data will be
- frozen when its first data modification statement begins. A later
- <command>LOCK TABLE</> will still prevent concurrent writes — but it
- won't ensure that what the transaction reads corresponds to the
- latest committed values.
+ To achieve a similar effect when running a transaction at the Serializable
+ isolation level, you have to execute the <command>LOCK TABLE</> statement
+ before executing any <command>SELECT</> or data modification statement.
+ A serializable transaction's view of data will be frozen when its first
+ <command>SELECT</> or data modification statement begins. A <command>LOCK
+ TABLE</> later in the transaction will still prevent concurrent writes
+ — but it won't ensure that what the transaction reads corresponds to
+ the latest committed values.
</para>
<para>
<listitem>
<para>
Specifies that <command>LOCK TABLE</command> should not wait for
- any conflicting locks to be released: if the specified lock
- cannot be immediately acquired without waiting, the transaction
+ any conflicting locks to be released: if the specified lock(s)
+ cannot be acquired immediately without waiting, the transaction
is aborted.
</para>
</listitem>
<refsect1>
<title>Compatibility</title>
-
+
<para>
There is no <command>LOCK TABLE</command> in the SQL standard,
which instead uses <command>SET TRANSACTION</command> to specify
<refsect1>
<title>Compatibility</title>
-
+
<para>
There is no <command>MOVE</command> statement in the SQL standard.
</para>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-close" endterm="sql-close-title"></member>
+ <member><xref linkend="sql-declare" endterm="sql-declare-title"></member>
+ <member><xref linkend="sql-fetch" endterm="sql-fetch-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
for the specified notification name in the current database.
</para>
+ <para>
+ <command>NOTIFY</command> provides a simple form of signal or
+ interprocess communication mechanism for a collection of processes
+ accessing the same <productname>PostgreSQL</productname> database.
+ Higher-level mechanisms can be built by using tables in the database to
+ pass additional data (beyond a mere notification name) from notifier to
+ listener(s).
+ </para>
+
<para>
The information passed to the client for a notification event includes the notification
name and the notifying session's server process <acronym>PID</>. It is up to the
to signal different sorts of changes to a single table.
</para>
- <para>
- <command>NOTIFY</command> provides a simple form of signal or
- interprocess communication mechanism for a collection of processes
- accessing the same <productname>PostgreSQL</productname> database.
- Higher-level mechanisms can be built by using tables in the database to
- pass additional data (beyond a mere notification name) from notifier to
- listener(s).
- </para>
-
<para>
When <command>NOTIFY</command> is used to signal the occurrence of changes
to a particular table, a useful programming technique is to put the
the notification event will not be delivered to its connected client until just
after the transaction is completed (either committed or aborted). Again, the
reasoning is that if a notification were delivered within a transaction that was
- later aborted, one would want the notification to be undone somehow---but
+ later aborted, one would want the notification to be undone somehow —
+ but
the server cannot <quote>take back</quote> a notification once it has sent it to the client.
So notification events are only delivered between transactions. The upshot of this
is that applications using <command>NOTIFY</command> for real-time signaling
projects / users / bernd / postgres.git / commitdiff