PostgreSQL 8.3 Documentation Copyright (c) 1996-2009 The PostgreSQL Global Development Group ------------------------------------------------------------------------ VI. Reference The entries in this Reference are meant to provide in reasonable length an authoritative, complete, and formal summary about their respective subjects. More information about the use of PostgreSQL, in narrative, tutorial, or example form, can be found in other parts of this book. See the cross-references listed on each reference page. The reference entries are also available as traditional "man" pages. Table of Contents I. SQL Commands ABORT -- abort the current transaction ALTER AGGREGATE -- change the definition of an aggregate function ALTER CONVERSION -- change the definition of a conversion ALTER DATABASE -- change a database ALTER DOMAIN -- change the definition of a domain ALTER FUNCTION -- change the definition of a function ALTER GROUP -- change role name or membership ALTER INDEX -- change the definition of an index ALTER LANGUAGE -- change the definition of a procedural language ALTER OPERATOR -- change the definition of an operator ALTER OPERATOR CLASS -- change the definition of an operator class ALTER OPERATOR FAMILY -- change the definition of an operator family ALTER ROLE -- change a database role ALTER SCHEMA -- change the definition of a schema ALTER SEQUENCE -- change the definition of a sequence generator ALTER TABLE -- change the definition of a table ALTER TABLESPACE -- change the definition of a tablespace ALTER TEXT SEARCH CONFIGURATION -- change the definition of a text search configuration ALTER TEXT SEARCH DICTIONARY -- change the definition of a text search dictionary ALTER TEXT SEARCH PARSER -- change the definition of a text search parser ALTER TEXT SEARCH TEMPLATE -- change the definition of a text search template ALTER TRIGGER -- change the definition of a trigger ALTER TYPE -- change the definition of a type ALTER USER -- change a database role ALTER VIEW -- change the definition of a view ANALYZE -- collect statistics about a database BEGIN -- start a transaction block CHECKPOINT -- force a transaction log checkpoint CLOSE -- close a cursor CLUSTER -- cluster a table according to an index COMMENT -- define or change the comment of an object COMMIT -- commit the current transaction COMMIT PREPARED -- commit a transaction that was earlier prepared for two-phase commit COPY -- copy data between a file and a table CREATE AGGREGATE -- define a new aggregate function CREATE CAST -- define a new cast CREATE CONSTRAINT TRIGGER -- define a new constraint trigger CREATE CONVERSION -- define a new encoding conversion CREATE DATABASE -- create a new database CREATE DOMAIN -- define a new domain CREATE FUNCTION -- define a new function CREATE GROUP -- define a new database role CREATE INDEX -- define a new index CREATE LANGUAGE -- define a new procedural language CREATE OPERATOR -- define a new operator CREATE OPERATOR CLASS -- define a new operator class CREATE OPERATOR FAMILY -- define a new operator family CREATE ROLE -- define a new database role CREATE RULE -- define a new rewrite rule CREATE SCHEMA -- define a new schema CREATE SEQUENCE -- define a new sequence generator CREATE TABLE -- define a new table CREATE TABLE AS -- define a new table from the results of a query CREATE TABLESPACE -- define a new tablespace CREATE TEXT SEARCH CONFIGURATION -- define a new text search configuration CREATE TEXT SEARCH DICTIONARY -- define a new text search dictionary CREATE TEXT SEARCH PARSER -- define a new text search parser CREATE TEXT SEARCH TEMPLATE -- define a new text search template CREATE TRIGGER -- define a new trigger CREATE TYPE -- define a new data type CREATE USER -- define a new database role CREATE VIEW -- define a new view DEALLOCATE -- deallocate a prepared statement DECLARE -- define a cursor DELETE -- delete rows of a table DISCARD -- discard session state DROP AGGREGATE -- remove an aggregate function DROP CAST -- remove a cast DROP CONVERSION -- remove a conversion DROP DATABASE -- remove a database DROP DOMAIN -- remove a domain DROP FUNCTION -- remove a function DROP GROUP -- remove a database role DROP INDEX -- remove an index DROP LANGUAGE -- remove a procedural language DROP OPERATOR -- remove an operator DROP OPERATOR CLASS -- remove an operator class DROP OPERATOR FAMILY -- remove an operator family DROP OWNED -- remove database objects owned by a database role DROP ROLE -- remove a database role DROP RULE -- remove a rewrite rule DROP SCHEMA -- remove a schema DROP SEQUENCE -- remove a sequence DROP TABLE -- remove a table DROP TABLESPACE -- remove a tablespace DROP TEXT SEARCH CONFIGURATION -- remove a text search configuration DROP TEXT SEARCH DICTIONARY -- remove a text search dictionary DROP TEXT SEARCH PARSER -- remove a text search parser DROP TEXT SEARCH TEMPLATE -- remove a text search template DROP TRIGGER -- remove a trigger DROP TYPE -- remove a data type DROP USER -- remove a database role DROP VIEW -- remove a view END -- commit the current transaction EXECUTE -- execute a prepared statement EXPLAIN -- show the execution plan of a statement FETCH -- retrieve rows from a query using a cursor GRANT -- define access privileges INSERT -- create new rows in a table LISTEN -- listen for a notification LOAD -- load or reload a shared library file LOCK -- lock a table MOVE -- position a cursor NOTIFY -- generate a notification PREPARE -- prepare a statement for execution PREPARE TRANSACTION -- prepare the current transaction for two- phase commit REASSIGN OWNED -- change the ownership of database objects owned by a database role REINDEX -- rebuild indexes RELEASE SAVEPOINT -- destroy a previously defined savepoint RESET -- restore the value of a run-time parameter to the default value REVOKE -- remove access privileges ROLLBACK -- abort the current transaction ROLLBACK PREPARED -- cancel a transaction that was earlier prepared for two-phase commit ROLLBACK TO SAVEPOINT -- roll back to a savepoint SAVEPOINT -- define a new savepoint within the current transaction SELECT -- retrieve rows from a table or view SELECT INTO -- define a new table from the results of a query SET -- change a run-time parameter SET CONSTRAINTS -- set constraint checking modes for the current transaction SET ROLE -- set the current user identifier of the current session SET SESSION AUTHORIZATION -- set the session user identifier and the current user identifier of the current session SET TRANSACTION -- set the characteristics of the current transaction SHOW -- show the value of a run-time parameter START TRANSACTION -- start a transaction block TRUNCATE -- empty a table or set of tables UNLISTEN -- stop listening for a notification UPDATE -- update rows of a table VACUUM -- garbage-collect and optionally analyze a database VALUES -- compute a set of rows II. PostgreSQL Client Applications clusterdb -- cluster a PostgreSQL database createdb -- create a new PostgreSQL database createlang -- define a new PostgreSQL procedural language createuser -- define a new PostgreSQL user account dropdb -- remove a PostgreSQL database droplang -- remove a PostgreSQL procedural language dropuser -- remove a PostgreSQL user account ecpg -- embedded SQL C preprocessor pg_config -- retrieve information about the installed version of PostgreSQL pg_dump -- extract a PostgreSQL database into a script file or other archive file pg_dumpall -- extract a PostgreSQL database cluster into a script file pg_restore -- restore a PostgreSQL database from an archive file created by pg_dump psql -- PostgreSQL interactive terminal reindexdb -- reindex a PostgreSQL database vacuumdb -- garbage-collect and analyze a PostgreSQL database III. PostgreSQL Server Applications initdb -- create a new PostgreSQL database cluster ipcclean -- remove shared memory and semaphores from a failed PostgreSQL server pg_controldata -- display control information of a PostgreSQL database cluster pg_ctl -- start, stop, or restart a PostgreSQL server pg_resetxlog -- reset the write-ahead log and other control information of a PostgreSQL database cluster postgres -- PostgreSQL database server postmaster -- PostgreSQL database server ------------------------------------------------------------------------ ------------------------------------------------------------------------ I. SQL Commands This part contains reference information for the SQL commands supported by PostgreSQL. By "SQL" the language in general is meant; information about the standards conformance and compatibility of each command can be found on the respective reference page. Table of Contents ABORT -- abort the current transaction ALTER AGGREGATE -- change the definition of an aggregate function ALTER CONVERSION -- change the definition of a conversion ALTER DATABASE -- change a database ALTER DOMAIN -- change the definition of a domain ALTER FUNCTION -- change the definition of a function ALTER GROUP -- change role name or membership ALTER INDEX -- change the definition of an index ALTER LANGUAGE -- change the definition of a procedural language ALTER OPERATOR -- change the definition of an operator ALTER OPERATOR CLASS -- change the definition of an operator class ALTER OPERATOR FAMILY -- change the definition of an operator family ALTER ROLE -- change a database role ALTER SCHEMA -- change the definition of a schema ALTER SEQUENCE -- change the definition of a sequence generator ALTER TABLE -- change the definition of a table ALTER TABLESPACE -- change the definition of a tablespace ALTER TEXT SEARCH CONFIGURATION -- change the definition of a text search configuration ALTER TEXT SEARCH DICTIONARY -- change the definition of a text search dictionary ALTER TEXT SEARCH PARSER -- change the definition of a text search parser ALTER TEXT SEARCH TEMPLATE -- change the definition of a text search template ALTER TRIGGER -- change the definition of a trigger ALTER TYPE -- change the definition of a type ALTER USER -- change a database role ALTER VIEW -- change the definition of a view ANALYZE -- collect statistics about a database BEGIN -- start a transaction block CHECKPOINT -- force a transaction log checkpoint CLOSE -- close a cursor CLUSTER -- cluster a table according to an index COMMENT -- define or change the comment of an object COMMIT -- commit the current transaction COMMIT PREPARED -- commit a transaction that was earlier prepared for two-phase commit COPY -- copy data between a file and a table CREATE AGGREGATE -- define a new aggregate function CREATE CAST -- define a new cast CREATE CONSTRAINT TRIGGER -- define a new constraint trigger CREATE CONVERSION -- define a new encoding conversion CREATE DATABASE -- create a new database CREATE DOMAIN -- define a new domain CREATE FUNCTION -- define a new function CREATE GROUP -- define a new database role CREATE INDEX -- define a new index CREATE LANGUAGE -- define a new procedural language CREATE OPERATOR -- define a new operator CREATE OPERATOR CLASS -- define a new operator class CREATE OPERATOR FAMILY -- define a new operator family CREATE ROLE -- define a new database role CREATE RULE -- define a new rewrite rule CREATE SCHEMA -- define a new schema CREATE SEQUENCE -- define a new sequence generator CREATE TABLE -- define a new table CREATE TABLE AS -- define a new table from the results of a query CREATE TABLESPACE -- define a new tablespace CREATE TEXT SEARCH CONFIGURATION -- define a new text search configuration CREATE TEXT SEARCH DICTIONARY -- define a new text search dictionary CREATE TEXT SEARCH PARSER -- define a new text search parser CREATE TEXT SEARCH TEMPLATE -- define a new text search template CREATE TRIGGER -- define a new trigger CREATE TYPE -- define a new data type CREATE USER -- define a new database role CREATE VIEW -- define a new view DEALLOCATE -- deallocate a prepared statement DECLARE -- define a cursor DELETE -- delete rows of a table DISCARD -- discard session state DROP AGGREGATE -- remove an aggregate function DROP CAST -- remove a cast DROP CONVERSION -- remove a conversion DROP DATABASE -- remove a database DROP DOMAIN -- remove a domain DROP FUNCTION -- remove a function DROP GROUP -- remove a database role DROP INDEX -- remove an index DROP LANGUAGE -- remove a procedural language DROP OPERATOR -- remove an operator DROP OPERATOR CLASS -- remove an operator class DROP OPERATOR FAMILY -- remove an operator family DROP OWNED -- remove database objects owned by a database role DROP ROLE -- remove a database role DROP RULE -- remove a rewrite rule DROP SCHEMA -- remove a schema DROP SEQUENCE -- remove a sequence DROP TABLE -- remove a table DROP TABLESPACE -- remove a tablespace DROP TEXT SEARCH CONFIGURATION -- remove a text search configuration DROP TEXT SEARCH DICTIONARY -- remove a text search dictionary DROP TEXT SEARCH PARSER -- remove a text search parser DROP TEXT SEARCH TEMPLATE -- remove a text search template DROP TRIGGER -- remove a trigger DROP TYPE -- remove a data type DROP USER -- remove a database role DROP VIEW -- remove a view END -- commit the current transaction EXECUTE -- execute a prepared statement EXPLAIN -- show the execution plan of a statement FETCH -- retrieve rows from a query using a cursor GRANT -- define access privileges INSERT -- create new rows in a table LISTEN -- listen for a notification LOAD -- load or reload a shared library file LOCK -- lock a table MOVE -- position a cursor NOTIFY -- generate a notification PREPARE -- prepare a statement for execution PREPARE TRANSACTION -- prepare the current transaction for two-phase commit REASSIGN OWNED -- change the ownership of database objects owned by a database role REINDEX -- rebuild indexes RELEASE SAVEPOINT -- destroy a previously defined savepoint RESET -- restore the value of a run-time parameter to the default value REVOKE -- remove access privileges ROLLBACK -- abort the current transaction ROLLBACK PREPARED -- cancel a transaction that was earlier prepared for two-phase commit ROLLBACK TO SAVEPOINT -- roll back to a savepoint SAVEPOINT -- define a new savepoint within the current transaction SELECT -- retrieve rows from a table or view SELECT INTO -- define a new table from the results of a query SET -- change a run-time parameter SET CONSTRAINTS -- set constraint checking modes for the current transaction SET ROLE -- set the current user identifier of the current session SET SESSION AUTHORIZATION -- set the session user identifier and the current user identifier of the current session SET TRANSACTION -- set the characteristics of the current transaction SHOW -- show the value of a run-time parameter START TRANSACTION -- start a transaction block TRUNCATE -- empty a table or set of tables UNLISTEN -- stop listening for a notification UPDATE -- update rows of a table VACUUM -- garbage-collect and optionally analyze a database VALUES -- compute a set of rows ------------------------------------------------------------------------ ABORT Name ABORT -- abort the current transaction Synopsis ABORT [ WORK | TRANSACTION ] Description ABORT rolls back the current transaction and causes all the updates made by the transaction to be discarded. This command is identical in behavior to the standard SQL command ROLLBACK, and is present only for historical reasons. Parameters WORK TRANSACTION Optional key words. They have no effect. Notes Use COMMIT to successfully terminate a transaction. Issuing ABORT when not inside a transaction does no harm, but it will provoke a warning message. Examples To abort all changes: ABORT; Compatibility This command is a PostgreSQL extension present for historical reasons. ROLLBACK is the equivalent standard SQL command. See Also BEGIN, COMMIT, ROLLBACK ------------------------------------------------------------------------ ALTER AGGREGATE Name ALTER AGGREGATE -- change the definition of an aggregate function Synopsis ALTER AGGREGATE name ( type [ , ... ] ) RENAME TO new_name ALTER AGGREGATE name ( type [ , ... ] ) OWNER TO new_owner ALTER AGGREGATE name ( type [ , ... ] ) SET SCHEMA new_schema Description ALTER AGGREGATE changes the definition of an aggregate function. You must own the aggregate function to use ALTER AGGREGATE. To change the schema of an aggregate function, you must also have CREATE privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the aggregate function's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the aggregate function. However, a superuser can alter ownership of any aggregate function anyway.) Parameters name The name (optionally schema-qualified) of an existing aggregate function. type An input data type on which the aggregate function operates. To reference a zero-argument aggregate function, write * in place of the list of input data types. new_name The new name of the aggregate function. new_owner The new owner of the aggregate function. new_schema The new schema for the aggregate function. Examples To rename the aggregate function myavg for type integer to my_average: ALTER AGGREGATE myavg(integer) RENAME TO my_average; To change the owner of the aggregate function myavg for type integer to joe: ALTER AGGREGATE myavg(integer) OWNER TO joe; To move the aggregate function myavg for type integer into schema myschema: ALTER AGGREGATE myavg(integer) SET SCHEMA myschema; Compatibility There is no ALTER AGGREGATE statement in the SQL standard. See Also CREATE_AGGREGATE, DROP_AGGREGATE ------------------------------------------------------------------------ ALTER CONVERSION Name ALTER CONVERSION -- change the definition of a conversion Synopsis ALTER CONVERSION name RENAME TO newname ALTER CONVERSION name OWNER TO newowner Description ALTER CONVERSION changes the definition of a conversion. You must own the conversion to use ALTER CONVERSION. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the conversion's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the conversion. However, a superuser can alter ownership of any conversion anyway.) Parameters name The name (optionally schema-qualified) of an existing conversion. newname The new name of the conversion. newowner The new owner of the conversion. Examples To rename the conversion iso_8859_1_to_utf8 to latin1_to_unicode: ALTER CONVERSION iso_8859_1_to_utf8 RENAME TO latin1_to_unicode; To change the owner of the conversion iso_8859_1_to_utf8 to joe: ALTER CONVERSION iso_8859_1_to_utf8 OWNER TO joe; Compatibility There is no ALTER CONVERSION statement in the SQL standard. See Also CREATE_CONVERSION, DROP_CONVERSION ------------------------------------------------------------------------ ALTER DATABASE Name ALTER DATABASE -- change a database Synopsis ALTER DATABASE name [ [ WITH ] option [ ... ] ] where option can be: CONNECTION LIMIT connlimit ALTER DATABASE name RENAME TO newname ALTER DATABASE name OWNER TO new_owner ALTER DATABASE name SET configuration_parameter { TO | = } { value | DEFAULT } ALTER DATABASE name SET configuration_parameter FROM CURRENT ALTER DATABASE name RESET configuration_parameter ALTER DATABASE name RESET ALL Description ALTER DATABASE changes the attributes of a database. The first form changes certain per-database settings. (See below for details.) Only the database owner or a superuser can change these settings. The second form changes the name of the database. Only the database owner or a superuser can rename a database; non-superuser owners must also have the CREATEDB privilege. The current database cannot be renamed. (Connect to a different database if you need to do that.) The third form changes the owner of the database. To alter the owner, you must own the database and also be a direct or indirect member of the new owning role, and you must have the CREATEDB privilege. (Note that superusers have all these privileges automatically.) The remaining forms change the session default for a run-time configuration variable for a PostgreSQL database. Whenever a new session is subsequently started in that database, the specified value becomes the session default value. The database-specific default overrides whatever setting is present in postgresql.conf or has been received from the postgres command line. Only the database owner or a superuser can change the session defaults for a database. Certain variables cannot be set this way, or can only be set by a superuser. Parameters name The name of the database whose attributes are to be altered. connlimit How many concurrent connections can be made to this database. - 1 means no limit. newname The new name of the database. new_owner The new owner of the database. configuration_parameter value Set this database's session default for the specified configuration parameter to the given value. If value is DEFAULT or, equivalently, RESET is used, the database-specific setting is removed, so the system-wide default setting will be inherited in new sessions. Use RESET ALL to clear all database-specific settings. SET FROM CURRENT saves the session's current value of the parameter as the database- specific value. See SET and Chapter_18 for more information about allowed parameter names and values. Notes It is also possible to tie a session default to a specific role rather than to a database; see ALTER_ROLE. Role-specific settings override database- specific ones if there is a conflict. Examples To disable index scans by default in the database test: ALTER DATABASE test SET enable_indexscan TO off; Compatibility The ALTER DATABASE statement is a PostgreSQL extension. See Also CREATE_DATABASE, DROP_DATABASE, SET ------------------------------------------------------------------------ ALTER DOMAIN Name ALTER DOMAIN -- change the definition of a domain Synopsis ALTER DOMAIN name { SET DEFAULT expression | DROP DEFAULT } ALTER DOMAIN name { SET | DROP } NOT NULL ALTER DOMAIN name ADD domain_constraint ALTER DOMAIN name DROP CONSTRAINT constraint_name [ RESTRICT | CASCADE ] ALTER DOMAIN name OWNER TO new_owner ALTER DOMAIN name SET SCHEMA new_schema Description ALTER DOMAIN changes the definition of an existing domain. There are several sub-forms: SET/DROP DEFAULT These forms set or remove the default value for a domain. Note that defaults only apply to subsequent INSERT commands; they do not affect rows already in a table using the domain. SET/DROP NOT NULL These forms change whether a domain is marked to allow NULL values or to reject NULL values. You can only SET NOT NULL when the columns using the domain contain no null values. ADD domain_constraint This form adds a new constraint to a domain using the same syntax as CREATE_DOMAIN. This will only succeed if all columns using the domain satisfy the new constraint. DROP CONSTRAINT This form drops constraints on a domain. OWNER This form changes the owner of the domain to the specified user. SET SCHEMA This form changes the schema of the domain. Any constraints associated with the domain are moved into the new schema as well. You must own the domain to use ALTER DOMAIN. To change the schema of a domain, you must also have CREATE privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the domain's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the domain. However, a superuser can alter ownership of any domain anyway.) Parameters name The name (possibly schema-qualified) of an existing domain to alter. domain_constraint New domain constraint for the domain. constraint_name Name of an existing constraint to drop. CASCADE Automatically drop objects that depend on the constraint. RESTRICT Refuse to drop the constraint if there are any dependent objects. This is the default behavior. new_owner The user name of the new owner of the domain. new_schema The new schema for the domain. Notes Currently, ALTER DOMAIN ADD CONSTRAINT and ALTER DOMAIN SET NOT NULL will fail if the named domain or any derived domain is used within a composite- type column of any table in the database. They should eventually be improved to be able to verify the new constraint for such nested columns. Examples To add a NOT NULL constraint to a domain: ALTER DOMAIN zipcode SET NOT NULL; To remove a NOT NULL constraint from a domain: ALTER DOMAIN zipcode DROP NOT NULL; To add a check constraint to a domain: ALTER DOMAIN zipcode ADD CONSTRAINT zipchk CHECK (char_length(VALUE) = 5); To remove a check constraint from a domain: ALTER DOMAIN zipcode DROP CONSTRAINT zipchk; To move the domain into a different schema: ALTER DOMAIN zipcode SET SCHEMA customers; Compatibility ALTER DOMAIN conforms to the SQL standard, except for the OWNER and SET SCHEMA variants, which are PostgreSQL extensions. See Also CREATE_DOMAIN, DROP_DOMAIN ------------------------------------------------------------------------ ALTER FUNCTION Name ALTER FUNCTION -- change the definition of a function Synopsis ALTER FUNCTION name ( [ [ argmode ] [ argname ] argtype [, ...] ] ) action [ ... ] [ RESTRICT ] ALTER FUNCTION name ( [ [ argmode ] [ argname ] argtype [, ...] ] ) RENAME TO new_name ALTER FUNCTION name ( [ [ argmode ] [ argname ] argtype [, ...] ] ) OWNER TO new_owner ALTER FUNCTION name ( [ [ argmode ] [ argname ] argtype [, ...] ] ) SET SCHEMA new_schema where action is one of: CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT IMMUTABLE | STABLE | VOLATILE [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER COST execution_cost ROWS result_rows SET configuration_parameter { TO | = } { value | DEFAULT } SET configuration_parameter FROM CURRENT RESET configuration_parameter RESET ALL Description ALTER FUNCTION changes the definition of a function. You must own the function to use ALTER FUNCTION. To change a function's schema, you must also have CREATE privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the function's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the function. However, a superuser can alter ownership of any function anyway.) Parameters name The name (optionally schema-qualified) of an existing function. argmode The mode of an argument: either IN, OUT, or INOUT. If omitted, the default is IN. Note that ALTER FUNCTION does not actually pay any attention to OUT arguments, since only the input arguments are needed to determine the function's identity. So it is sufficient to list the IN and INOUT arguments. argname The name of an argument. Note that ALTER FUNCTION does not actually pay any attention to argument names, since only the argument data types are needed to determine the function's identity. argtype The data type(s) of the function's arguments (optionally schema- qualified), if any. new_name The new name of the function. new_owner The new owner of the function. Note that if the function is marked SECURITY DEFINER, it will subsequently execute as the new owner. new_schema The new schema for the function. CALLED ON NULL INPUT RETURNS NULL ON NULL INPUT STRICT CALLED ON NULL INPUT changes the function so that it will be invoked when some or all of its arguments are null. RETURNS NULL ON NULL INPUT or STRICT changes the function so that it is not invoked if any of its arguments are null; instead, a null result is assumed automatically. See CREATE_FUNCTION for more information. IMMUTABLE STABLE VOLATILE Change the volatility of the function to the specified setting. See CREATE_FUNCTION for details. [ EXTERNAL ] SECURITY INVOKER [ EXTERNAL ] SECURITY DEFINER Change whether the function is a security definer or not. The key word EXTERNAL is ignored for SQL conformance. See CREATE_FUNCTION for more information about this capability. COST execution_cost Change the estimated execution cost of the function. See CREATE FUNCTION for more information. ROWS result_rows Change the estimated number of rows returned by a set-returning function. See CREATE_FUNCTION for more information. configuration_parameter value Add or change the assignment to be made to a configuration parameter when the function is called. If value is DEFAULT or, equivalently, RESET is used, the function-local setting is removed, so that the function executes with the value present in its environment. Use RESET ALL to clear all function-local settings. SET FROM CURRENT saves the session's current value of the parameter as the value to be applied when the function is entered. See SET and Chapter_18 for more information about allowed parameter names and values. RESTRICT Ignored for conformance with the SQL standard. Examples To rename the function sqrt for type integer to square_root: ALTER FUNCTION sqrt(integer) RENAME TO square_root; To change the owner of the function sqrt for type integer to joe: ALTER FUNCTION sqrt(integer) OWNER TO joe; To change the schema of the function sqrt for type integer to maths: ALTER FUNCTION sqrt(integer) SET SCHEMA maths; To adjust the search path that is automatically set for a function: ALTER FUNCTION check_password(text) SET search_path = admin, pg_temp; To disable automatic setting of search_path for a function: ALTER FUNCTION check_password(text) RESET search_path; The function will now execute with whatever search path is used by its caller. Compatibility This statement is partially compatible with the ALTER FUNCTION statement in the SQL standard. The standard allows more properties of a function to be modified, but does not provide the ability to rename a function, make a function a security definer, attach configuration parameter values to a function, or change the owner, schema, or volatility of a function. The standard also requires the RESTRICT key word, which is optional in PostgreSQL. See Also CREATE_FUNCTION, DROP_FUNCTION ------------------------------------------------------------------------ ALTER GROUP Name ALTER GROUP -- change role name or membership Synopsis ALTER GROUP groupname ADD USER username [, ... ] ALTER GROUP groupname DROP USER username [, ... ] ALTER GROUP groupname RENAME TO newname Description ALTER GROUP changes the attributes of a user group. This is an obsolete command, though still accepted for backwards compatibility, because groups (and users too) have been superseded by the more general concept of roles. The first two variants add users to a group or remove them from a group. (Any role can play the part of either a "user" or a "group" for this purpose.) These variants are effectively equivalent to granting or revoking membership in the role named as the "group"; so the preferred way to do this is to use GRANT or REVOKE. The third variant changes the name of the group. This is exactly equivalent to renaming the role with ALTER_ROLE. Parameters groupname The name of the group (role) to modify. username Users (roles) that are to be added to or removed from the group. The users must already exist; ALTER GROUP does not create or drop users. newname The new name of the group. Examples Add users to a group: ALTER GROUP staff ADD USER karl, john; Remove a user from a group: ALTER GROUP workers DROP USER beth; Compatibility There is no ALTER GROUP statement in the SQL standard. See Also GRANT, REVOKE, ALTER_ROLE ------------------------------------------------------------------------ ALTER INDEX Name ALTER INDEX -- change the definition of an index Synopsis ALTER INDEX name RENAME TO new_name ALTER INDEX name SET TABLESPACE tablespace_name ALTER INDEX name SET ( storage_parameter = value [, ... ] ) ALTER INDEX name RESET ( storage_parameter [, ... ] ) Description ALTER INDEX changes the definition of an existing index. There are several subforms: RENAME The RENAME form changes the name of the index. There is no effect on the stored data. SET TABLESPACE This form changes the index's tablespace to the specified tablespace and moves the data file(s) associated with the index to the new tablespace. See also CREATE_TABLESPACE. SET ( storage_parameter = value [, ... ] ) This form changes one or more index-method-specific storage parameters for the index. See CREATE_INDEX for details on the available parameters. Note that the index contents will not be modified immediately by this command; depending on the parameter you might need to rebuild the index with REINDEX to get the desired effects. RESET ( storage_parameter [, ... ] ) This form resets one or more index-method-specific storage parameters to their defaults. As with SET, a REINDEX might be needed to update the index entirely. Parameters name The name (possibly schema-qualified) of an existing index to alter. new_name The new name for the index. tablespace_name The tablespace to which the index will be moved. storage_parameter The name of an index-method-specific storage parameter. value The new value for an index-method-specific storage parameter. This might be a number or a word depending on the parameter. Notes These operations are also possible using ALTER_TABLE. ALTER INDEX is in fact just an alias for the forms of ALTER TABLE that apply to indexes. There was formerly an ALTER INDEX OWNER variant, but this is now ignored (with a warning). An index cannot have an owner different from its table's owner. Changing the table's owner automatically changes the index as well. Changing any part of a system catalog index is not permitted. Examples To rename an existing index: ALTER INDEX distributors RENAME TO suppliers; To move an index to a different tablespace: ALTER INDEX distributors SET TABLESPACE fasttablespace; To change an index's fill factor (assuming that the index method supports it): ALTER INDEX distributors SET (fillfactor = 75); REINDEX INDEX distributors; Compatibility ALTER INDEX is a PostgreSQL extension. See Also CREATE_INDEX, REINDEX ------------------------------------------------------------------------ ALTER LANGUAGE Name ALTER LANGUAGE -- change the definition of a procedural language Synopsis ALTER [ PROCEDURAL ] LANGUAGE name RENAME TO newname ALTER [ PROCEDURAL ] LANGUAGE name OWNER TO new_owner Description ALTER LANGUAGE changes the definition of a procedural language. The only functionality is to rename the language or assign a new owner. You must be superuser or owner of the language to use ALTER LANGUAGE. Parameters name Name of a language newname The new name of the language new_owner The new owner of the language Compatibility There is no ALTER LANGUAGE statement in the SQL standard. See Also CREATE_LANGUAGE, DROP_LANGUAGE ------------------------------------------------------------------------ ALTER OPERATOR Name ALTER OPERATOR -- change the definition of an operator Synopsis ALTER OPERATOR name ( { lefttype | NONE } , { righttype | NONE } ) OWNER TO newowner Description ALTER OPERATOR changes the definition of an operator. The only currently available functionality is to change the owner of the operator. You must own the operator to use ALTER OPERATOR. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the operator's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the operator. However, a superuser can alter ownership of any operator anyway.) Parameters name The name (optionally schema-qualified) of an existing operator. lefttype The data type of the operator's left operand; write NONE if the operator has no left operand. righttype The data type of the operator's right operand; write NONE if the operator has no right operand. newowner The new owner of the operator. Examples Change the owner of a custom operator a @@ b for type text: ALTER OPERATOR @@ (text, text) OWNER TO joe; Compatibility There is no ALTER OPERATOR statement in the SQL standard. See Also CREATE_OPERATOR, DROP_OPERATOR ------------------------------------------------------------------------ ALTER OPERATOR CLASS Name ALTER OPERATOR CLASS -- change the definition of an operator class Synopsis ALTER OPERATOR CLASS name USING index_method RENAME TO newname ALTER OPERATOR CLASS name USING index_method OWNER TO newowner Description ALTER OPERATOR CLASS changes the definition of an operator class. You must own the operator class to use ALTER OPERATOR CLASS. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the operator class's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the operator class. However, a superuser can alter ownership of any operator class anyway.) Parameters name The name (optionally schema-qualified) of an existing operator class. index_method The name of the index method this operator class is for. newname The new name of the operator class. newowner The new owner of the operator class. Compatibility There is no ALTER OPERATOR CLASS statement in the SQL standard. See Also CREATE_OPERATOR_CLASS, DROP_OPERATOR_CLASS, ALTER_OPERATOR_FAMILY ------------------------------------------------------------------------ ALTER OPERATOR FAMILY Name ALTER OPERATOR FAMILY -- change the definition of an operator family Synopsis ALTER OPERATOR FAMILY name USING index_method ADD { OPERATOR strategy_number operator_name ( op_type, op_type ) [ RECHECK ] | FUNCTION support_number [ ( op_type [ , op_type ] ) ] funcname ( argument_type [, ...] ) } [, ... ] ALTER OPERATOR FAMILY name USING index_method DROP { OPERATOR strategy_number ( op_type [ , op_type ] ) | FUNCTION support_number ( op_type [ , op_type ] ) } [, ... ] ALTER OPERATOR FAMILY name USING index_method RENAME TO newname ALTER OPERATOR FAMILY name USING index_method OWNER TO newowner Description ALTER OPERATOR FAMILY changes the definition of an operator family. You can add operators and support functions to the family, remove them from the family, or change the family's name or owner. When operators and support functions are added to a family with ALTER OPERATOR FAMILY, they are not part of any specific operator class within the family, but are just "loose" within the family. This indicates that these operators and functions are compatible with the family's semantics, but are not required for correct functioning of any specific index. (Operators and functions that are so required should be declared as part of an operator class, instead; see CREATE_OPERATOR_CLASS.) PostgreSQL will allow loose members of a family to be dropped from the family at any time, but members of an operator class cannot be dropped without dropping the whole class and any indexes that depend on it. Typically, single-data-type operators and functions are part of operator classes because they are needed to support an index on that specific data type, while cross-data- type operators and functions are made loose members of the family. You must be a superuser to use ALTER OPERATOR FAMILY. (This restriction is made because an erroneous operator family definition could confuse or even crash the server.) ALTER OPERATOR FAMILY does not presently check whether the operator family definition includes all the operators and functions required by the index method, nor whether the operators and functions form a self-consistent set. It is the user's responsibility to define a valid operator family. Refer to Section_34.14 for further information. Parameters name The name (optionally schema-qualified) of an existing operator family. index_method The name of the index method this operator family is for. strategy_number The index method's strategy number for an operator associated with the operator family. operator_name The name (optionally schema-qualified) of an operator associated with the operator family. op_type In an OPERATOR clause, the operand data type(s) of the operator, or NONE to signify a left-unary or right-unary operator. Unlike the comparable syntax in CREATE OPERATOR CLASS, the operand data types must always be specified. In an ADD FUNCTION clause, the operand data type(s) the function is intended to support, if different from the input data type(s) of the function. For B-tree and hash indexes it is not necessary to specify op_type since the function's input data type(s) are always the correct ones to use. For GIN and GiST indexes it is necessary to specify the input data type the function is to be used with. In a DROP FUNCTION clause, the operand data type(s) the function is intended to support must be specified. RECHECK If present, the index is "lossy" for this operator, and so the rows retrieved using the index must be rechecked to verify that they actually satisfy the qualification clause involving this operator. support_number The index method's support procedure number for a function associated with the operator family. funcname The name (optionally schema-qualified) of a function that is an index method support procedure for the operator family. argument_types The parameter data type(s) of the function. newname The new name of the operator family. newowner The new owner of the operator family. The OPERATOR and FUNCTION clauses can appear in any order. Notes Notice that the DROP syntax only specifies the "slot" in the operator family, by strategy or support number and input data type(s). The name of the operator or function occupying the slot is not mentioned. Also, for DROP FUNCTION the type(s) to specify are the input data type(s) the function is intended to support; for GIN and GiST indexes this might have nothing to do with the actual input argument types of the function. Because the index machinery does not check access permissions on functions before using them, including a function or operator in an operator family is tantamount to granting public execute permission on it. This is usually not an issue for the sorts of functions that are useful in an operator family. The operators should not be defined by SQL functions. A SQL function is likely to be inlined into the calling query, which will prevent the optimizer from recognizing that the query matches an index. Examples The following example command adds cross-data-type operators and support functions to an operator family that already contains B-tree operator classes for data types int4 and int2. ALTER OPERATOR FAMILY integer_ops USING btree ADD -- int4 vs int2 OPERATOR 1 < (int4, int2) , OPERATOR 2 <= (int4, int2) , OPERATOR 3 = (int4, int2) , OPERATOR 4 >= (int4, int2) , OPERATOR 5 > (int4, int2) , FUNCTION 1 btint42cmp(int4, int2) , -- int2 vs int4 OPERATOR 1 < (int2, int4) , OPERATOR 2 <= (int2, int4) , OPERATOR 3 = (int2, int4) , OPERATOR 4 >= (int2, int4) , OPERATOR 5 > (int2, int4) , FUNCTION 1 btint24cmp(int2, int4) ; To remove these entries again: ALTER OPERATOR FAMILY integer_ops USING btree DROP -- int4 vs int2 OPERATOR 1 (int4, int2) , OPERATOR 2 (int4, int2) , OPERATOR 3 (int4, int2) , OPERATOR 4 (int4, int2) , OPERATOR 5 (int4, int2) , FUNCTION 1 (int4, int2) , -- int2 vs int4 OPERATOR 1 (int2, int4) , OPERATOR 2 (int2, int4) , OPERATOR 3 (int2, int4) , OPERATOR 4 (int2, int4) , OPERATOR 5 (int2, int4) , FUNCTION 1 (int2, int4) ; Compatibility There is no ALTER OPERATOR FAMILY statement in the SQL standard. See Also CREATE_OPERATOR_FAMILY, DROP_OPERATOR_FAMILY, CREATE_OPERATOR_CLASS, ALTER OPERATOR_CLASS, DROP_OPERATOR_CLASS ------------------------------------------------------------------------ ALTER ROLE Name ALTER ROLE -- change a database role Synopsis ALTER ROLE name [ [ WITH ] option [ ... ] ] where option can be: SUPERUSER | NOSUPERUSER | CREATEDB | NOCREATEDB | CREATEROLE | NOCREATEROLE | CREATEUSER | NOCREATEUSER | INHERIT | NOINHERIT | LOGIN | NOLOGIN | CONNECTION LIMIT connlimit | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' | VALID UNTIL 'timestamp' ALTER ROLE name RENAME TO newname ALTER ROLE name SET configuration_parameter { TO | = } { value | DEFAULT } ALTER ROLE name SET configuration_parameter FROM CURRENT ALTER ROLE name RESET configuration_parameter ALTER ROLE name RESET ALL Description ALTER ROLE changes the attributes of a PostgreSQL role. The first variant of this command listed in the synopsis can change many of the role attributes that can be specified in CREATE_ROLE. (All the possible attributes are covered, except that there are no options for adding or removing memberships; use GRANT and REVOKE for that.) Attributes not mentioned in the command retain their previous settings. Database superusers can change any of these settings for any role. Roles having CREATEROLE privilege can change any of these settings, but only for non- superuser roles. Ordinary roles can only change their own password. The second variant changes the name of the role. Database superusers can rename any role. Roles having CREATEROLE privilege can rename non-superuser roles. The current session user cannot be renamed. (Connect as a different user if you need to do that.) Because MD5-encrypted passwords use the role name as cryptographic salt, renaming a role clears its password if the password is MD5-encrypted. The remaining variants change a role's session default for a specified configuration variable. Whenever the role subsequently starts a new session, the specified value becomes the session default, overriding whatever setting is present in postgresql.conf or has been received from the postgres command line. (For a role without LOGIN privilege, session defaults have no effect.) Ordinary roles can change their own session defaults. Superusers can change anyone's session defaults. Roles having CREATEROLE privilege can change defaults for non-superuser roles. Certain variables cannot be set this way, or can only be set if a superuser issues the command. Parameters name The name of the role whose attributes are to be altered. SUPERUSER NOSUPERUSER CREATEDB NOCREATEDB CREATEROLE NOCREATEROLE CREATEUSER NOCREATEUSER INHERIT NOINHERIT LOGIN NOLOGIN CONNECTION LIMIT connlimit PASSWORD password ENCRYPTED UNENCRYPTED VALID UNTIL 'timestamp' These clauses alter attributes originally set by CREATE_ROLE. For more information, see the CREATE ROLE reference page. newname The new name of the role. configuration_parameter value Set this role's session default for the specified configuration parameter to the given value. If value is DEFAULT or, equivalently, RESET is used, the role-specific variable setting is removed, so the role will inherit the system-wide default setting in new sessions. Use RESET ALL to clear all role-specific settings. SET FROM CURRENT saves the session's current value of the parameter as the role- specific value. See SET and Chapter_18 for more information about allowed parameter names and values. Notes Use CREATE_ROLE to add new roles, and DROP_ROLE to remove a role. ALTER ROLE cannot change a role's memberships. Use GRANT and REVOKE to do that. Caution must be exercised when specifying an unencrypted password with this command. The password will be transmitted to the server in cleartext, and it might also be logged in the client's command history or the server log. psql contains a command \password that can be used to safely change a role's password. It is also possible to tie a session default to a specific database rather than to a role; see ALTER_DATABASE. Role-specific settings override database-specific ones if there is a conflict. Examples Change a role's password: ALTER ROLE davide WITH PASSWORD 'hu8jmn3'; Change a password expiration date, specifying that the password should expire at midday on 4th May 2015 using the time zone which is one hour ahead of UTC: ALTER ROLE chris VALID UNTIL 'May 4 12:00:00 2015 +1'; Make a password valid forever: ALTER ROLE fred VALID UNTIL 'infinity'; Give a role the ability to create other roles and new databases: ALTER ROLE miriam CREATEROLE CREATEDB; Give a role a non-default setting of the maintenance_work_mem parameter: ALTER ROLE worker_bee SET maintenance_work_mem = 100000; Compatibility The ALTER ROLE statement is a PostgreSQL extension. See Also CREATE_ROLE, DROP_ROLE, SET ------------------------------------------------------------------------ ALTER SCHEMA Name ALTER SCHEMA -- change the definition of a schema Synopsis ALTER SCHEMA name RENAME TO newname ALTER SCHEMA name OWNER TO newowner Description ALTER SCHEMA changes the definition of a schema. You must own the schema to use ALTER SCHEMA. To rename a schema you must also have the CREATE privilege for the database. To alter the owner, you must also be a direct or indirect member of the new owning role, and you must have the CREATE privilege for the database. (Note that superusers have all these privileges automatically.) Parameters name The name of an existing schema. newname The new name of the schema. The new name cannot begin with pg_, as such names are reserved for system schemas. newowner The new owner of the schema. Compatibility There is no ALTER SCHEMA statement in the SQL standard. See Also CREATE_SCHEMA, DROP_SCHEMA ------------------------------------------------------------------------ ALTER SEQUENCE Name ALTER SEQUENCE -- change the definition of a sequence generator Synopsis ALTER SEQUENCE name [ INCREMENT [ BY ] increment ] [ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ] [ RESTART [ WITH ] start ] [ CACHE cache ] [ [ NO ] CYCLE ] [ OWNED BY { table.column | NONE } ] ALTER SEQUENCE name RENAME TO new_name ALTER SEQUENCE name SET SCHEMA new_schema Description ALTER SEQUENCE changes the parameters of an existing sequence generator. Any parameters not specifically set in the ALTER SEQUENCE command retain their prior settings. You must own the sequence to use ALTER SEQUENCE. To change a sequence's schema, you must also have CREATE privilege on the new schema. Parameters name The name (optionally schema-qualified) of a sequence to be altered. increment The clause INCREMENT BY increment is optional. A positive value will make an ascending sequence, a negative one a descending sequence. If unspecified, the old increment value will be maintained. minvalue NO MINVALUE The optional clause MINVALUE minvalue determines the minimum value a sequence can generate. If NO MINVALUE is specified, the defaults of 1 and -263-1 for ascending and descending sequences, respectively, will be used. If neither option is specified, the current minimum value will be maintained. maxvalue NO MAXVALUE The optional clause MAXVALUE maxvalue determines the maximum value for the sequence. If NO MAXVALUE is specified, the defaults are 263- 1 and -1 for ascending and descending sequences, respectively, will be used. If neither option is specified, the current maximum value will be maintained. start The optional clause RESTART WITH start changes the current value of the sequence. This is equivalent to calling the setval function with is_called = false: the specified value will be returned by the next call of nextval. cache The clause CACHE cache enables sequence numbers to be preallocated and stored in memory for faster access. The minimum value is 1 (only one value can be generated at a time, i.e., no cache). If unspecified, the old cache value will be maintained. CYCLE The optional CYCLE key word can be used to enable the sequence to wrap around when the maxvalue or minvalue has been reached by an ascending or descending sequence respectively. If the limit is reached, the next number generated will be the minvalue or maxvalue, respectively. NO CYCLE If the optional NO CYCLE key word is specified, any calls to nextval after the sequence has reached its maximum value will return an error. If neither CYCLE or NO CYCLE are specified, the old cycle behavior will be maintained. OWNED BY table.column OWNED BY NONE The OWNED BY option causes the sequence to be associated with a specific table column, such that if that column (or its whole table) is dropped, the sequence will be automatically dropped as well. If specified, this association replaces any previously specified association for the sequence. The specified table must have the same owner and be in the same schema as the sequence. Specifying OWNED BY NONE removes any existing association, making the sequence "free- standing". new_name The new name for the sequence. new_schema The new schema for the sequence. Notes To avoid blocking of concurrent transactions that obtain numbers from the same sequence, ALTER SEQUENCE's effects on the sequence generation parameters are never rolled back; those changes take effect immediately and are not reversible. However, the OWNED BY, RENAME, and SET SCHEMA clauses cause ordinary catalog updates that can be rolled back. ALTER SEQUENCE will not immediately affect nextval results in backends, other than the current one, that have preallocated (cached) sequence values. They will use up all cached values prior to noticing the changed sequence generation parameters. The current backend will be affected immediately. ALTER SEQUENCE does not affect the currval status for the sequence. (Before PostgreSQL 8.3, it sometimes did.) Some variants of ALTER TABLE can be used with sequences as well; for example, to rename a sequence it is also possible to use ALTER TABLE RENAME. Examples Restart a sequence called serial, at 105: ALTER SEQUENCE serial RESTART WITH 105; Compatibility ALTER SEQUENCE conforms to the SQL standard, except for the OWNED BY, RENAME, and SET SCHEMA clauses, which are PostgreSQL extensions. See Also CREATE_SEQUENCE, DROP_SEQUENCE ------------------------------------------------------------------------ ALTER TABLE Name ALTER TABLE -- change the definition of a table Synopsis ALTER TABLE [ ONLY ] name [ * ] action [, ... ] ALTER TABLE [ ONLY ] name [ * ] RENAME [ COLUMN ] column TO new_column ALTER TABLE name RENAME TO new_name ALTER TABLE name SET SCHEMA new_schema where action is one of: ADD [ COLUMN ] column type [ column_constraint [ ... ] ] DROP [ COLUMN ] column [ RESTRICT | CASCADE ] ALTER [ COLUMN ] column TYPE type [ USING expression ] ALTER [ COLUMN ] column SET DEFAULT expression ALTER [ COLUMN ] column DROP DEFAULT ALTER [ COLUMN ] column { SET | DROP } NOT NULL ALTER [ COLUMN ] column SET STATISTICS integer ALTER [ COLUMN ] column SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN } ADD table_constraint DROP CONSTRAINT constraint_name [ RESTRICT | CASCADE ] DISABLE TRIGGER [ trigger_name | ALL | USER ] ENABLE TRIGGER [ trigger_name | ALL | USER ] ENABLE REPLICA TRIGGER trigger_name ENABLE ALWAYS TRIGGER trigger_name DISABLE RULE rewrite_rule_name ENABLE RULE rewrite_rule_name ENABLE REPLICA RULE rewrite_rule_name ENABLE ALWAYS RULE rewrite_rule_name CLUSTER ON index_name SET WITHOUT CLUSTER SET WITHOUT OIDS SET ( storage_parameter = value [, ... ] ) RESET ( storage_parameter [, ... ] ) INHERIT parent_table NO INHERIT parent_table OWNER TO new_owner SET TABLESPACE new_tablespace Description ALTER TABLE changes the definition of an existing table. There are several subforms: ADD COLUMN This form adds a new column to the table, using the same syntax as CREATE_TABLE. DROP COLUMN This form drops a column from a table. Indexes and table constraints involving the column will be automatically dropped as well. You will need to say CASCADE if anything outside the table depends on the column, for example, foreign key references or views. ALTER COLUMN TYPE This form changes the type of a column of a table. Indexes and simple table constraints involving the column will be automatically converted to use the new column type by reparsing the originally supplied expression. The optional USING clause specifies how to compute the new column value from the old; if omitted, the default conversion is the same as an assignment cast from old data type to new. A USING clause must be provided if there is no implicit or assignment cast from old to new type. SET/DROP DEFAULT These forms set or remove the default value for a column. The default values only apply to subsequent INSERT commands; they do not cause rows already in the table to change. Defaults can also be created for views, in which case they are inserted into INSERT statements on the view before the view's ON INSERT rule is applied. SET/DROP NOT NULL These forms change whether a column is marked to allow null values or to reject null values. You can only use SET NOT NULL when the column contains no null values. SET STATISTICS This form sets the per-column statistics-gathering target for subsequent ANALYZE 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 (default_statistics_target). For more information on the use of statistics by the PostgreSQL query planner, refer to Section_14.2. SET STORAGE This form sets the storage mode for a column. This controls whether this column is held inline or in a supplementary table, and whether the data should be compressed or not. PLAIN must be used for fixed- length values such as integer and is inline, uncompressed. MAIN is for inline, compressible data. EXTERNAL is for external, uncompressed data, and EXTENDED is for external, compressed data. EXTENDED is the default for most data types that support non-PLAIN storage. Use of EXTERNAL will make substring operations on text and bytea columns faster, at the penalty of increased storage space. Note that SET STORAGE doesn't itself change anything in the table, it just sets the strategy to be pursued during future table updates. See Section_53.2 for more information. ADD table_constraint This form adds a new constraint to a table using the same syntax as CREATE_TABLE. DROP CONSTRAINT This form drops the specified constraint on a table. DISABLE/ENABLE [ REPLICA | ALWAYS ] TRIGGER These forms configure the firing of trigger(s) belonging to the table. A disabled trigger is still known to the system, but is not executed when its triggering event occurs. For a deferred trigger, the enable status is checked when the event occurs, not when the trigger function is actually executed. One can disable or enable a single trigger specified by name, or all triggers on the table, or only user triggers (this option excludes triggers that are used to implement foreign key constraints). Disabling or enabling constraint triggers requires superuser privileges; it should be done with caution since of course the integrity of the constraint cannot be guaranteed if the triggers are not executed. The trigger firing mechanism is also affected by the configuration variable session_replication_role. Simply enabled triggers will fire when the replication role is "origin" (the default) or "local". Triggers configured ENABLE REPLICA will only fire if the session is in "replica" mode and triggers configured ENABLE ALWAYS will fire regardless of the current replication mode. DISABLE/ENABLE [ REPLICA | ALWAYS ] RULE These forms configure the firing of rewrite rules belonging to the table. A disabled rule is still known to the system, but is not applied during query rewriting. The semantics are as for disabled/ enabled triggers. This configuration is ignored for ON SELECT rules, which are always applied in order to keep views working even if the current session is in a non-default replication role. CLUSTER This form selects the default index for future CLUSTER operations. It does not actually re-cluster the table. SET WITHOUT CLUSTER This form removes the most recently used CLUSTER index specification from the table. This affects future cluster operations that don't specify an index. SET WITHOUT OIDS This form removes the oid system column from the table. This is exactly equivalent to DROP COLUMN oid RESTRICT, except that it will not complain if there is already no oid column. Note that there is no variant of ALTER TABLE that allows OIDs to be restored to a table once they have been removed. SET ( storage_parameter = value [, ... ] ) This form changes one or more storage parameters for the table. See CREATE_TABLE for details on the available parameters. Note that the table contents will not be modified immediately by this command; depending on the parameter you might need to rewrite the table to get the desired effects. That can be done with CLUSTER or one of the forms of ALTER TABLE that forces a table rewrite. Note: While CREATE TABLE allows OIDS to be specified in the WITH (storage_parameter) syntax, ALTER TABLE does not treat OIDS as a storage parameter. RESET ( storage_parameter [, ... ] ) This form resets one or more storage parameters to their defaults. As with SET, a table rewrite might be needed to update the table entirely. INHERIT parent_table This form adds the target table as a new child of the specified parent table. Subsequently, queries against the parent will include records of the target table. To be added as a child, the target table must already contain all the same columns as the parent (it could have additional columns, too). The columns must have matching data types, and if they have NOT NULL constraints in the parent then they must also have NOT NULL constraints in the child. There must also be matching child-table constraints for all CHECK constraints of the parent. Currently UNIQUE, PRIMARY KEY, and FOREIGN KEY constraints are not considered, but this might change in the future. NO INHERIT parent_table This form removes the target table from the list of children of the specified parent table. Queries against the parent table will no longer include records drawn from the target table. OWNER This form changes the owner of the table, sequence, or view to the specified user. SET TABLESPACE This form changes the table's tablespace to the specified tablespace and moves the data file(s) associated with the table to the new tablespace. Indexes on the table, if any, are not moved; but they can be moved separately with additional SET TABLESPACE commands. See also CREATE_TABLESPACE. RENAME The RENAME forms change the name of a table (or an index, sequence, or view) or the name of an individual column in a table. There is no effect on the stored data. SET SCHEMA This form moves the table into another schema. Associated indexes, constraints, and sequences owned by table columns are moved as well. All the actions except RENAME and SET SCHEMA can be combined into a list of multiple alterations to apply in parallel. For example, it is possible to add several columns and/or alter the type of several columns in a single command. This is particularly useful with large tables, since only one pass over the table need be made. You must own the table to use ALTER TABLE. To change the schema of a table, you must also have CREATE privilege on the new schema. To add the table as a new child of a parent table, you must own the parent table as well. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the table's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the table. However, a superuser can alter ownership of any table anyway.) Parameters name The name (possibly schema-qualified) of an existing table to alter. If ONLY is specified, only that table is altered. If ONLY is not specified, the table and all its descendant tables (if any) are updated. * 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, ONLY was the default behavior. The default can be altered by changing the configuration parameter sql_inheritance.) column Name of a new or existing column. new_column New name for an existing column. new_name New name for the table. type Data type of the new column, or new data type for an existing column. table_constraint New table constraint for the table. constraint_name Name of an existing constraint to drop. CASCADE Automatically drop objects that depend on the dropped column or constraint (for example, views referencing the column). RESTRICT Refuse to drop the column or constraint if there are any dependent objects. This is the default behavior. trigger_name Name of a single trigger to disable or enable. ALL Disable or enable all triggers belonging to the table. (This requires superuser privilege if any of the triggers are for foreign key constraints.) USER Disable or enable all triggers belonging to the table except for foreign key constraint triggers. index_name The index name on which the table should be marked for clustering. storage_parameter The name of a table storage parameter. value The new value for a table storage parameter. This might be a number or a word depending on the parameter. parent_table A parent table to associate or de-associate with this table. new_owner The user name of the new owner of the table. new_tablespace The name of the tablespace to which the table will be moved. new_schema The name of the schema to which the table will be moved. Notes The key word COLUMN is noise and can be omitted. When a column is added with ADD COLUMN, all existing rows in the table are initialized with the column's default value (NULL if no DEFAULT clause is specified). Adding a column with a non-null default or changing the type of an existing column will require the entire table to be rewritten. This might take a significant amount of time for a large table; and it will temporarily require double the disk space. Adding a CHECK or NOT NULL constraint requires scanning the table to verify that existing rows meet the constraint. The main reason for providing the option to specify multiple changes in a single ALTER TABLE is that multiple table scans or rewrites can thereby be combined into a single pass over the table. The DROP COLUMN form does not physically remove the column, but simply makes it invisible to SQL operations. Subsequent insert and update operations in the table will store a null value for the column. Thus, dropping a column is quick but it will not immediately reduce the on-disk size of your table, as the space occupied by the dropped column is not reclaimed. The space will be reclaimed over time as existing rows are updated. The fact that ALTER TYPE requires rewriting the whole table is sometimes an advantage, because the rewriting process eliminates any dead space in the table. For example, to reclaim the space occupied by a dropped column immediately, the fastest way is: ALTER TABLE table ALTER COLUMN anycol TYPE anytype; where anycol is any remaining table column and anytype is the same type that column already has. This results in no semantically-visible change in the table, but the command forces rewriting, which gets rid of no-longer- useful data. The USING option of ALTER TYPE can actually specify any expression involving the old values of the row; that is, it can refer to other columns as well as the one being converted. This allows very general conversions to be done with the ALTER TYPE syntax. Because of this flexibility, the USING expression is not applied to the column's default value (if any); the result might not be a constant expression as required for a default. This means that when there is no implicit or assignment cast from old to new type, ALTER TYPE might fail to convert the default even though a USING clause is supplied. In such cases, drop the default with DROP DEFAULT, perform the ALTER TYPE, and then use SET DEFAULT to add a suitable new default. Similar considerations apply to indexes and constraints involving the column. If a table has any descendant tables, it is not permitted to add, rename, or change the type of a column in the parent table without doing the same to the descendants. That is, ALTER TABLE ONLY will be rejected. This ensures that the descendants always have columns matching the parent. A recursive DROP COLUMN operation will remove a descendant table's column only if the descendant does not inherit that column from any other parents and never had an independent definition of the column. A nonrecursive DROP COLUMN (i.e., ALTER TABLE ONLY ... DROP COLUMN) never removes any descendant columns, but instead marks them as independently defined rather than inherited. The TRIGGER, CLUSTER, OWNER, and TABLESPACE actions never recurse to descendant tables; that is, they always act as though ONLY were specified. Adding a constraint can recurse only for CHECK constraints. Changing any part of a system catalog table is not permitted. Refer to CREATE_TABLE for a further description of valid parameters. Chapter_5 has further information on inheritance. Examples To add a column of type varchar to a table: ALTER TABLE distributors ADD COLUMN address varchar(30); To drop a column from a table: ALTER TABLE distributors DROP COLUMN address RESTRICT; To change the types of two existing columns in one operation: ALTER TABLE distributors ALTER COLUMN address TYPE varchar(80), ALTER COLUMN name TYPE varchar(100); To change an integer column containing UNIX timestamps to timestamp with time zone via a USING clause: ALTER TABLE foo ALTER COLUMN foo_timestamp TYPE timestamp with time zone USING timestamp with time zone 'epoch' + foo_timestamp * interval '1 second'; The same, when the column has a default expression that won't automatically cast to the new data type: ALTER TABLE foo ALTER COLUMN foo_timestamp DROP DEFAULT, ALTER COLUMN foo_timestamp TYPE timestamp with time zone USING timestamp with time zone 'epoch' + foo_timestamp * interval '1 second', ALTER COLUMN foo_timestamp SET DEFAULT now(); To rename an existing column: ALTER TABLE distributors RENAME COLUMN address TO city; To rename an existing table: ALTER TABLE distributors RENAME TO suppliers; To add a not-null constraint to a column: ALTER TABLE distributors ALTER COLUMN street SET NOT NULL; To remove a not-null constraint from a column: ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL; To add a check constraint to a table: ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length (zipcode) = 5); To remove a check constraint from a table and all its children: ALTER TABLE distributors DROP CONSTRAINT zipchk; To add a foreign key constraint to a table: ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address) MATCH FULL; To add a (multicolumn) unique constraint to a table: ALTER TABLE distributors ADD CONSTRAINT dist_id_zipcode_key UNIQUE (dist_id, zipcode); To add an automatically named primary key constraint to a table, noting that a table can only ever have one primary key: ALTER TABLE distributors ADD PRIMARY KEY (dist_id); To move a table to a different tablespace: ALTER TABLE distributors SET TABLESPACE fasttablespace; To move a table to a different schema: ALTER TABLE myschema.distributors SET SCHEMA yourschema; Compatibility The ADD, DROP, and SET DEFAULT forms conform with the SQL standard. The other forms are PostgreSQL extensions of the SQL standard. Also, the ability to specify more than one manipulation in a single ALTER TABLE command is an extension. ALTER TABLE DROP COLUMN can be used to drop the only column of a table, leaving a zero-column table. This is an extension of SQL, which disallows zero-column tables. ------------------------------------------------------------------------ ALTER TABLESPACE Name ALTER TABLESPACE -- change the definition of a tablespace Synopsis ALTER TABLESPACE name RENAME TO newname ALTER TABLESPACE name OWNER TO newowner Description ALTER TABLESPACE changes the definition of a tablespace. You must own the tablespace to use ALTER TABLESPACE. To alter the owner, you must also be a direct or indirect member of the new owning role. (Note that superusers have these privileges automatically.) Parameters name The name of an existing tablespace. newname The new name of the tablespace. The new name cannot begin with pg_, as such names are reserved for system tablespaces. newowner The new owner of the tablespace. Examples Rename tablespace index_space to fast_raid: ALTER TABLESPACE index_space RENAME TO fast_raid; Change the owner of tablespace index_space: ALTER TABLESPACE index_space OWNER TO mary; Compatibility There is no ALTER TABLESPACE statement in the SQL standard. See Also CREATE_TABLESPACE, DROP_TABLESPACE ------------------------------------------------------------------------ ALTER TEXT SEARCH CONFIGURATION Name ALTER TEXT SEARCH CONFIGURATION -- change the definition of a text search configuration Synopsis ALTER TEXT SEARCH CONFIGURATION name ADD MAPPING FOR token_type [, ... ] WITH dictionary_name [, ... ] ALTER TEXT SEARCH CONFIGURATION name ALTER MAPPING FOR token_type [, ... ] WITH dictionary_name [, ... ] ALTER TEXT SEARCH CONFIGURATION name ALTER MAPPING REPLACE old_dictionary WITH new_dictionary ALTER TEXT SEARCH CONFIGURATION name ALTER MAPPING FOR token_type [, ... ] REPLACE old_dictionary WITH new_dictionary ALTER TEXT SEARCH CONFIGURATION name DROP MAPPING [ IF EXISTS ] FOR token_type [, ... ] ALTER TEXT SEARCH CONFIGURATION name RENAME TO newname ALTER TEXT SEARCH CONFIGURATION name OWNER TO newowner Description ALTER TEXT SEARCH CONFIGURATION changes the definition of a text search configuration. You can modify its mappings from token types to dictionaries, or change the configuration's name or owner. You must be the owner of the configuration to use ALTER TEXT SEARCH CONFIGURATION. Parameters name The name (optionally schema-qualified) of an existing text search configuration. token_type The name of a token type that is emitted by the configuration's parser. dictionary_name The name of a text search dictionary to be consulted for the specified token type(s). If multiple dictionaries are listed, they are consulted in the specified order. old_dictionary The name of a text search dictionary to be replaced in the mapping. new_dictionary The name of a text search dictionary to be substituted for old_dictionary. newname The new name of the text search configuration. newowner The new owner of the text search configuration. The ADD MAPPING FOR form installs a list of dictionaries to be consulted for the specified token type(s); it is an error if there is already a mapping for any of the token types. The ALTER MAPPING FOR form does the same, but first removing any existing mapping for those token types. The ALTER MAPPING REPLACE forms substitute new_dictionary for old_dictionary anywhere the latter appears. This is done for only the specified token types when FOR appears, or for all mappings of the configuration when it doesn't. The DROP MAPPING form removes all dictionaries for the specified token type(s), causing tokens of those types to be ignored by the text search configuration. It is an error if there is no mapping for the token types, unless IF EXISTS appears. Examples The following example replaces the english dictionary with the swedish dictionary anywhere that english is used within my_config. ALTER TEXT SEARCH CONFIGURATION my_config ALTER MAPPING REPLACE english WITH swedish; Compatibility There is no ALTER TEXT SEARCH CONFIGURATION statement in the SQL standard. See Also CREATE_TEXT_SEARCH_CONFIGURATION, DROP_TEXT_SEARCH_CONFIGURATION ------------------------------------------------------------------------ ALTER TEXT SEARCH DICTIONARY Name ALTER TEXT SEARCH DICTIONARY -- change the definition of a text search dictionary Synopsis ALTER TEXT SEARCH DICTIONARY name ( option [ = value ] [, ... ] ) ALTER TEXT SEARCH DICTIONARY name RENAME TO newname ALTER TEXT SEARCH DICTIONARY name OWNER TO newowner Description ALTER TEXT SEARCH DICTIONARY changes the definition of a text search dictionary. You can change the dictionary's template-specific options, or change the dictionary's name or owner. You must be the owner of the dictionary to use ALTER TEXT SEARCH DICTIONARY. Parameters name The name (optionally schema-qualified) of an existing text search dictionary. option The name of a template-specific option to be set for this dictionary. value The new value to use for a template-specific option. If the equal sign and value are omitted, then any previous setting for the option is removed from the dictionary, allowing the default to be used. newname The new name of the text search dictionary. newowner The new owner of the text search dictionary. Template-specific options can appear in any order. Examples The following example command changes the stopword list for a Snowball- based dictionary. Other parameters remain unchanged. ALTER TEXT SEARCH DICTIONARY my_dict ( StopWords = newrussian ); The following example command changes the language option to dutch, and removes the stopword option entirely. ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); The following example command "updates" the dictionary's definition without actually changing anything. ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (The reason this works is that the option removal code doesn't complain if there is no such option.) This trick is useful when changing configuration files for the dictionary: the ALTER will force existing database sessions to re-read the configuration files, which otherwise they would never do if they had read them earlier. Compatibility There is no ALTER TEXT SEARCH DICTIONARY statement in the SQL standard. See Also CREATE_TEXT_SEARCH_DICTIONARY, DROP_TEXT_SEARCH_DICTIONARY ------------------------------------------------------------------------ ALTER TEXT SEARCH PARSER Name ALTER TEXT SEARCH PARSER -- change the definition of a text search parser Synopsis ALTER TEXT SEARCH PARSER name RENAME TO newname Description ALTER TEXT SEARCH PARSER changes the definition of a text search parser. Currently, the only supported functionality is to change the parser's name. You must be a superuser to use ALTER TEXT SEARCH PARSER. Parameters name The name (optionally schema-qualified) of an existing text search parser. newname The new name of the text search parser. Compatibility There is no ALTER TEXT SEARCH PARSER statement in the SQL standard. See Also CREATE_TEXT_SEARCH_PARSER, DROP_TEXT_SEARCH_PARSER ------------------------------------------------------------------------ ALTER TEXT SEARCH TEMPLATE Name ALTER TEXT SEARCH TEMPLATE -- change the definition of a text search template Synopsis ALTER TEXT SEARCH TEMPLATE name RENAME TO newname Description ALTER TEXT SEARCH TEMPLATE changes the definition of a text search template. Currently, the only supported functionality is to change the template's name. You must be a superuser to use ALTER TEXT SEARCH TEMPLATE. Parameters name The name (optionally schema-qualified) of an existing text search template. newname The new name of the text search template. Compatibility There is no ALTER TEXT SEARCH TEMPLATE statement in the SQL standard. See Also CREATE_TEXT_SEARCH_TEMPLATE, DROP_TEXT_SEARCH_TEMPLATE ------------------------------------------------------------------------ ALTER TRIGGER Name ALTER TRIGGER -- change the definition of a trigger Synopsis ALTER TRIGGER name ON table RENAME TO newname Description ALTER TRIGGER changes properties of an existing trigger. The RENAME clause changes the name of the given trigger without otherwise changing the trigger definition. You must own the table on which the trigger acts to be allowed to change its properties. Parameters name The name of an existing trigger to alter. table The name of the table on which this trigger acts. newname The new name for the trigger. Notes The ability to temporarily enable or disable a trigger is provided by ALTER TABLE, not by ALTER TRIGGER, because ALTER TRIGGER has no convenient way to express the option of enabling or disabling all of a table's triggers at once. Examples To rename an existing trigger: ALTER TRIGGER emp_stamp ON emp RENAME TO emp_track_chgs; Compatibility ALTER TRIGGER is a PostgreSQL extension of the SQL standard. See Also ALTER_TABLE ------------------------------------------------------------------------ ALTER TYPE Name ALTER TYPE -- change the definition of a type Synopsis ALTER TYPE name OWNER TO new_owner ALTER TYPE name SET SCHEMA new_schema Description ALTER TYPE changes the definition of an existing type. The only currently available capabilities are changing the owner and schema of a type. You must own the type to use ALTER TYPE. To change the schema of a type, you must also have CREATE privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the type's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the type. However, a superuser can alter ownership of any type anyway.) Parameters name The name (possibly schema-qualified) of an existing type to alter. new_owner The user name of the new owner of the type. new_schema The new schema for the type. Examples To change the owner of the user-defined type email to joe: ALTER TYPE email OWNER TO joe; To change the schema of the user-defined type email to customers: ALTER TYPE email SET SCHEMA customers; Compatibility There is no ALTER TYPE statement in the SQL standard. ------------------------------------------------------------------------ ALTER USER Name ALTER USER -- change a database role Synopsis ALTER USER name [ [ WITH ] option [ ... ] ] where option can be: SUPERUSER | NOSUPERUSER | CREATEDB | NOCREATEDB | CREATEROLE | NOCREATEROLE | CREATEUSER | NOCREATEUSER | INHERIT | NOINHERIT | LOGIN | NOLOGIN | CONNECTION LIMIT connlimit | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' | VALID UNTIL 'timestamp' ALTER USER name RENAME TO newname ALTER USER name SET configuration_parameter { TO | = } { value | DEFAULT } ALTER USER name SET configuration_parameter FROM CURRENT ALTER USER name RESET configuration_parameter ALTER USER name RESET ALL Description ALTER USER is now an alias for ALTER_ROLE. Compatibility The ALTER USER statement is a PostgreSQL extension. The SQL standard leaves the definition of users to the implementation. See Also ALTER_ROLE ------------------------------------------------------------------------ ALTER VIEW Name ALTER VIEW -- change the definition of a view Synopsis ALTER VIEW name RENAME TO newname Description ALTER VIEW changes the definition of a view. The only currently available functionality is to rename the view. To execute this command you must be the owner of the view. Parameters name The name (optionally schema-qualified) of an existing view. newname The new name of the view. Notes Some variants of ALTER TABLE can be used with views as well; for example, to rename a view it is also possible to use ALTER TABLE RENAME. To change the schema or owner of a view, you currently must use ALTER TABLE. Examples To rename the view foo to bar: ALTER VIEW foo RENAME TO bar; Compatibility ALTER VIEW is a PostgreSQL extension of the SQL standard. See Also CREATE_VIEW, DROP_VIEW ------------------------------------------------------------------------ ANALYZE Name ANALYZE -- collect statistics about a database Synopsis ANALYZE [ VERBOSE ] [ table [ ( column [, ...] ) ] ] Description ANALYZE collects statistics about the contents of tables in the database, and stores the results in the pg_statistic system catalog. Subsequently, the query planner uses these statistics to help determine the most efficient execution plans for queries. With no parameter, ANALYZE examines every table in the current database. With a parameter, ANALYZE examines only that table. It is further possible to give a list of column names, in which case only the statistics for those columns are collected. Parameters VERBOSE Enables display of progress messages. table The name (possibly schema-qualified) of a specific table to analyze. Defaults to all tables in the current database. column The name of a specific column to analyze. Defaults to all columns. Outputs When VERBOSE is specified, ANALYZE emits progress messages to indicate which table is currently being processed. Various statistics about the tables are printed as well. Notes In the default PostgreSQL configuration, The_Auto-Vacuum_Daemon takes care of automatic analyzing of tables when they are first loaded with data, and as they change throughout regular operation. When autovacuum is disabled, it is a good idea to run ANALYZE periodically, or just after making major changes in the contents of a table. Accurate statistics will help the planner to choose the most appropriate query plan, and thereby improve the speed of query processing. A common strategy is to run VACUUM and ANALYZE once a day during a low-usage time of day. ANALYZE requires only a read lock on the target table, so it can run in parallel with other activity on the table. The statistics collected by ANALYZE usually include a list of some of the most common values in each column and a histogram showing the approximate data distribution in each column. One or both of these can be omitted if ANALYZE deems them uninteresting (for example, in a unique-key column, there are no common values) or if the column data type does not support the appropriate operators. There is more information about the statistics in Chapter_23. For large tables, ANALYZE takes a random sample of the table contents, rather than examining every row. This allows even very large tables to be analyzed in a small amount of time. Note, however, that the statistics are only approximate, and will change slightly each time ANALYZE is run, even if the actual table contents did not change. This might result in small changes in the planner's estimated costs shown by EXPLAIN. In rare situations, this non-determinism will cause the query optimizer to choose a different query plan between runs of ANALYZE. To avoid this, raise the amount of statistics collected by ANALYZE, as described below. The extent of analysis can be controlled by adjusting the default_statistics_target configuration variable, or on a column-by-column basis by setting the per-column statistics target with ALTER TABLE ... ALTER COLUMN ... SET STATISTICS (see ALTER_TABLE). The target value sets the maximum number of entries in the most-common-value list and the maximum number of bins in the histogram. The default target value is 10, but this can be adjusted up or down to trade off accuracy of planner estimates against the time taken for ANALYZE and the amount of space occupied in pg_statistic. In particular, setting the statistics target to zero disables collection of statistics for that column. It might be useful to do that for columns that are never used as part of the WHERE, GROUP BY, or ORDER BY clauses of queries, since the planner will have no use for statistics on such columns. The largest statistics target among the columns being analyzed determines the number of table rows sampled to prepare the statistics. Increasing the target causes a proportional increase in the time and space needed to do ANALYZE. Compatibility There is no ANALYZE statement in the SQL standard. See Also VACUUM, vacuumdb, Cost-Based_Vacuum_Delay, The_Auto-Vacuum_Daemon ------------------------------------------------------------------------ BEGIN Name BEGIN -- start a transaction block Synopsis BEGIN [ WORK | TRANSACTION ] [ transaction_mode [, ...] ] where transaction_mode is one of: ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } READ WRITE | READ ONLY Description BEGIN initiates a transaction block, that is, all statements after a BEGIN command will be executed in a single transaction until an explicit COMMIT or ROLLBACK is given. By default (without BEGIN), PostgreSQL executes transactions in "autocommit" mode, that is, each statement is executed in its own transaction and a commit is implicitly performed at the end of the statement (if execution was successful, otherwise a rollback is done). Statements are executed more quickly in a transaction block, because transaction start/commit requires significant CPU and disk activity. Execution of multiple statements inside a transaction is also useful to ensure consistency when making several related changes: other sessions will be unable to see the intermediate states wherein not all the related updates have been done. If the isolation level or read/write mode is specified, the new transaction has those characteristics, as if SET_TRANSACTION was executed. Parameters WORK TRANSACTION Optional key words. They have no effect. Refer to SET_TRANSACTION for information on the meaning of the other parameters to this statement. Notes START_TRANSACTION has the same functionality as BEGIN. Use COMMIT or ROLLBACK to terminate a transaction block. Issuing BEGIN when already inside a transaction block will provoke a warning message. The state of the transaction is not affected. To nest transactions within a transaction block, use savepoints (see SAVEPOINT). For reasons of backwards compatibility, the commas between successive transaction_modes can be omitted. Examples To begin a transaction block: BEGIN; Compatibility BEGIN is a PostgreSQL language extension. It is equivalent to the SQL- standard command START_TRANSACTION, whose reference page contains additional compatibility information. Incidentally, the BEGIN key word is used for a different purpose in embedded SQL. You are advised to be careful about the transaction semantics when porting database applications. See Also COMMIT, ROLLBACK, START_TRANSACTION, SAVEPOINT ------------------------------------------------------------------------ CHECKPOINT Name CHECKPOINT -- force a transaction log checkpoint Synopsis CHECKPOINT Description Write-Ahead Logging (WAL) puts a checkpoint in the transaction log every so often. (To adjust the automatic checkpoint interval, see the run-time configuration options checkpoint_segments and checkpoint_timeout.) The CHECKPOINT command forces an immediate checkpoint when the command is issued, without waiting for a scheduled checkpoint. 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 Chapter_28 for more information about the WAL system. Only superusers can call CHECKPOINT. The command is not intended for use during normal operation. Compatibility The CHECKPOINT command is a PostgreSQL language extension. ------------------------------------------------------------------------ CLOSE Name CLOSE -- close a cursor Synopsis CLOSE { name | ALL } Description CLOSE frees the resources associated with an open cursor. After the cursor is closed, no subsequent operations are allowed on it. A cursor should be closed when it is no longer needed. Every non-holdable open cursor is implicitly closed when a transaction is terminated by COMMIT or ROLLBACK. A holdable cursor is implicitly closed if the transaction that created it aborts via ROLLBACK. If the creating transaction successfully commits, the holdable cursor remains open until an explicit CLOSE is executed, or the client disconnects. Parameters name The name of an open cursor to close. ALL Close all open cursors. Notes PostgreSQL does not have an explicit OPEN cursor statement; a cursor is considered open when it is declared. Use the DECLARE statement to declare a cursor. You can see all available cursors by querying the pg_cursors system view. Examples Close the cursor liahona: CLOSE liahona; Compatibility CLOSE is fully conforming with the SQL standard. CLOSE ALL is a PostgreSQL extension. See Also DECLARE, FETCH, MOVE ------------------------------------------------------------------------ CLUSTER Name CLUSTER -- cluster a table according to an index Synopsis CLUSTER tablename [ USING indexname ] CLUSTER Description CLUSTER instructs PostgreSQL to cluster the table specified by tablename based on the index specified by indexname. The index must already have been defined on tablename. When a table is clustered, it is physically reordered based on the index information. Clustering is a one-time operation: when the table is subsequently updated, the changes are not clustered. That is, no attempt is made to store new or updated rows according to their index order. (If one wishes, one can periodically recluster by issuing the command again. Also, setting the table's FILLFACTOR storage parameter to less than 100% can aid in preserving cluster ordering during updates, since updated rows are preferentially kept on the same page.) When a table is clustered, PostgreSQL remembers which index it was clustered by. The form CLUSTER tablename reclusters the table using the same index as before. CLUSTER without any parameter reclusters all the previously-clustered tables in the current database that the calling user owns, or all such tables if called by a superuser. This form of CLUSTER cannot be executed inside a transaction block. When a table is being clustered, an ACCESS EXCLUSIVE lock is acquired on it. This prevents any other database operations (both reads and writes) from operating on the table until the CLUSTER is finished. Parameters tablename The name (possibly schema-qualified) of a table. indexname The name of an index. Notes In cases where you are accessing single rows randomly within a table, the actual order of the data in the table is unimportant. However, if you tend to access some data more than others, and there is an index that groups them together, you will benefit from using CLUSTER. If you are requesting a range of indexed values from a table, or a single indexed value that has multiple rows that match, CLUSTER will help because once the index identifies the table page for the first row that matches, all other rows that match are probably already on the same table page, and so you save disk accesses and speed up the query. During the cluster operation, a temporary copy of the table is created that contains the table data in the index order. Temporary copies of each index on the table are created as well. Therefore, you need free space on disk at least equal to the sum of the table size and the index sizes. Because CLUSTER remembers the clustering information, one can cluster the tables one wants clustered manually the first time, and setup a timed event similar to VACUUM so that the tables are periodically reclustered. Because the planner records statistics about the ordering of tables, it is advisable to run ANALYZE on the newly clustered table. Otherwise, the planner might make poor choices of query plans. There is another way to cluster data. The CLUSTER command reorders the original table by scanning it using the index you specify. This can be slow on large tables because the rows are fetched from the table in index order, and if the table is disordered, the entries are on random pages, so there is one disk page retrieved for every row moved. (PostgreSQL has a cache, but the majority of a big table will not fit in the cache.) The other way to cluster a table is to use: CREATE TABLE newtable AS SELECT * FROM table ORDER BY columnlist; which uses the PostgreSQL sorting code to produce the desired order; this is usually much faster than an index scan for disordered data. Then you drop the old table, use ALTER TABLE ... RENAME to rename newtable to the old name, and recreate the table's indexes. The big disadvantage of this approach is that it does not preserve OIDs, constraints, foreign key relationships, granted privileges, and other ancillary properties of the table -- all such items must be manually recreated. Another disadvantage is that this way requires a sort temporary file about the same size as the table itself, so peak disk usage is about three times the table size instead of twice the table size. Examples Cluster the table employees on the basis of its index employees_ind: CLUSTER employees USING employees_ind; Cluster the employees table using the same index that was used before: CLUSTER employees; Cluster all tables in the database that have previously been clustered: CLUSTER; Compatibility There is no CLUSTER statement in the SQL standard. The syntax CLUSTER indexname ON tablename is also supported for compatibility with pre-8.3 PostgreSQL versions. See Also clusterdb ------------------------------------------------------------------------ COMMENT Name COMMENT -- define or change the comment of an object Synopsis COMMENT ON { TABLE object_name | COLUMN table_name.column_name | AGGREGATE agg_name (agg_type [, ...] ) | CAST (sourcetype AS targettype) | CONSTRAINT constraint_name ON table_name | CONVERSION object_name | DATABASE object_name | DOMAIN object_name | FUNCTION func_name ( [ [ argmode ] [ argname ] argtype [, ...] ] ) | INDEX object_name | LARGE OBJECT large_object_oid | OPERATOR op (leftoperand_type, rightoperand_type) | OPERATOR CLASS object_name USING index_method | OPERATOR FAMILY object_name USING index_method | [ PROCEDURAL ] LANGUAGE object_name | ROLE object_name | RULE rule_name ON table_name | SCHEMA object_name | SEQUENCE object_name | TABLESPACE object_name | TEXT SEARCH CONFIGURATION object_name | TEXT SEARCH DICTIONARY object_name | TEXT SEARCH PARSER object_name | TEXT SEARCH TEMPLATE object_name | TRIGGER trigger_name ON table_name | TYPE object_name | VIEW object_name } IS 'text' Description COMMENT stores a comment about a database object. To modify a comment, issue a new COMMENT command for the same object. Only one comment string is stored for each object. To remove a comment, write NULL in place of the text string. Comments are automatically dropped when the object is dropped. Comments can be viewed using psql's \d family of commands. Other user interfaces to retrieve comments can be built atop the same built-in functions that psql uses, namely obj_description, col_description, and shobj_description (see Table_9-48). Parameters object_name table_name.column_name agg_name constraint_name func_name op rule_name trigger_name The name of the object to be commented. Names of tables, aggregates, domains, functions, indexes, operators, operator classes, operator families, sequences, text search objects, types, and views can be schema-qualified. agg_type An input data type on which the aggregate function operates. To reference a zero-argument aggregate function, write * in place of the list of input data types. sourcetype The name of the source data type of the cast. targettype The name of the target data type of the cast. argmode The mode of a function argument: either IN, OUT, or INOUT. If omitted, the default is IN. Note that COMMENT ON FUNCTION does not actually pay any attention to OUT arguments, since only the input arguments are needed to determine the function's identity. So it is sufficient to list the IN and INOUT arguments. argname The name of a function argument. Note that COMMENT ON FUNCTION does not actually pay any attention to argument names, since only the argument data types are needed to determine the function's identity. argtype The data type(s) of the function's arguments (optionally schema- qualified), if any. large_object_oid The OID of the large object. PROCEDURAL This is a noise word. text The new comment, written as a string literal; or NULL to drop the comment. Notes There is presently no security mechanism for comments: any user connected to a database can see all the comments for objects in that database (although only superusers can change comments for objects that they don't own). For shared objects such as databases, roles, and tablespaces comments are stored globally and any user connected to any database can see all the comments for shared objects. Therefore, don't put security-critical information in comments. Examples Attach a comment to the table mytable: COMMENT ON TABLE mytable IS 'This is my table.'; Remove it again: COMMENT ON TABLE mytable IS NULL; Some more examples: COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance'; COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4'; COMMENT ON COLUMN my_table.my_column IS 'Employee ID number'; COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8'; COMMENT ON DATABASE my_database IS 'Development Database'; COMMENT ON DOMAIN my_domain IS 'Email Address Domain'; COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral'; COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID'; COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures'; COMMENT ON LARGE OBJECT 346344 IS 'Planning document'; COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts'; COMMENT ON OPERATOR - (NONE, text) IS 'This is a prefix operator on text'; COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees'; COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees'; COMMENT ON ROLE my_role IS 'Administration group for finance tables'; COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records'; COMMENT ON SCHEMA my_schema IS 'Departmental data'; COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys'; COMMENT ON TABLE my_schema.my_table IS 'Employee Information'; COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes'; COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering'; COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Snowball stemmer for swedish language'; COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words'; COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer'; COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI'; COMMENT ON TYPE complex IS 'Complex number data type'; COMMENT ON VIEW my_view IS 'View of departmental costs'; Compatibility There is no COMMENT command in the SQL standard. ------------------------------------------------------------------------ COMMIT Name COMMIT -- commit the current transaction Synopsis COMMIT [ WORK | TRANSACTION ] Description COMMIT commits the current transaction. All changes made by the transaction become visible to others and are guaranteed to be durable if a crash occurs. Parameters WORK TRANSACTION Optional key words. They have no effect. Notes Use ROLLBACK to abort a transaction. Issuing COMMIT when not inside a transaction does no harm, but it will provoke a warning message. Examples To commit the current transaction and make all changes permanent: COMMIT; Compatibility The SQL standard only specifies the two forms COMMIT and COMMIT WORK. Otherwise, this command is fully conforming. See Also BEGIN, ROLLBACK ------------------------------------------------------------------------ COMMIT PREPARED Name COMMIT PREPARED -- commit a transaction that was earlier prepared for two- phase commit Synopsis COMMIT PREPARED transaction_id Description COMMIT PREPARED commits a transaction that is in prepared state. Parameters transaction_id The transaction identifier of the transaction that is to be committed. Notes To commit a prepared transaction, you must be either the same user that executed the transaction originally, or a superuser. But you do not have to be in the same session that executed the transaction. This command cannot be executed inside a transaction block. The prepared transaction is committed immediately. All currently available prepared transactions are listed in the pg_prepared_xacts system view. Examples Commit the transaction identified by the transaction identifier foobar: COMMIT PREPARED 'foobar'; See Also PREPARE_TRANSACTION, ROLLBACK_PREPARED ------------------------------------------------------------------------ COPY Name COPY -- copy data between a file and a table Synopsis COPY tablename [ ( column [, ...] ) ] FROM { 'filename' | STDIN } [ [ WITH ] [ BINARY ] [ OIDS ] [ DELIMITER [ AS ] 'delimiter' ] [ NULL [ AS ] 'null string' ] [ CSV [ HEADER ] [ QUOTE [ AS ] 'quote' ] [ ESCAPE [ AS ] 'escape' ] [ FORCE NOT NULL column [, ...] ] COPY { tablename [ ( column [, ...] ) ] | ( query ) } TO { 'filename' | STDOUT } [ [ WITH ] [ BINARY ] [ HEADER ] [ OIDS ] [ DELIMITER [ AS ] 'delimiter' ] [ NULL [ AS ] 'null string' ] [ CSV [ HEADER ] [ QUOTE [ AS ] 'quote' ] [ ESCAPE [ AS ] 'escape' ] [ FORCE QUOTE column [, ...] ] Description COPY moves data between PostgreSQL tables and standard file-system files. COPY TO copies the contents of a table to a file, while COPY FROM copies data from a file to a table (appending the data to whatever is in the table already). COPY TO can also copy the results of a SELECT query. If a list of columns is specified, COPY will only copy the data in the specified columns to or from the file. If there are any columns in the table that are not in the column list, COPY FROM will insert the default values for those columns. COPY with a file name instructs the PostgreSQL server to directly read from or write to a file. The file must be accessible to the server and the name must be specified from the viewpoint of the server. When STDIN or STDOUT is specified, data is transmitted via the connection between the client and the server. Parameters tablename The name (optionally schema-qualified) of an existing table. column An optional list of columns to be copied. If no column list is specified, all columns of the table will be copied. query A SELECT or VALUES command whose results are to be copied. Note that parentheses are required around the query. filename The absolute path name of the input or output file. Windows users might need to use an E'' string and double backslashes used as path separators. STDIN Specifies that input comes from the client application. STDOUT Specifies that output goes to the client application. BINARY Causes all data to be stored or read in binary format rather than as text. You cannot specify the DELIMITER, NULL, or CSV options in binary mode. OIDS Specifies copying the OID for each row. (An error is raised if OIDS is specified for a table that does not have OIDs, or in the case of copying a query.) delimiter The single ASCII character that separates columns within each row (line) of the file. The default is a tab character in text mode, a comma in CSV mode. null string The string that represents a null value. The default is \N (backslash-N) in text mode, and a empty value with no quotes in CSV mode. You might prefer an empty string even in text mode for cases where you don't want to distinguish nulls from empty strings. Note: When using COPY FROM, any data item that matches this string will be stored as a null value, so you should make sure that you use the same string as you used with COPY TO. CSV Selects Comma Separated Value (CSV) mode. HEADER Specifies the file contains a header line with the names of each column in the file. On output, the first line contains the column names from the table, and on input, the first line is ignored. quote Specifies the ASCII quotation character in CSV mode. The default is double-quote. escape Specifies the ASCII character that should appear before a QUOTE data character value in CSV mode. The default is the QUOTE value (usually double-quote). FORCE QUOTE In CSV COPY TO mode, forces quoting to be used for all non-NULL values in each specified column. NULL output is never quoted. FORCE NOT NULL In CSV COPY FROM mode, process each specified column as though it were quoted and hence not a NULL value. For the default null string in CSV mode (''), this causes missing values to be input as zero- length strings. Outputs On successful completion, a COPY command returns a command tag of the form COPY count The count is the number of rows copied. Notes COPY can only be used with plain tables, not with views. However, you can write COPY (SELECT * FROM viewname) TO .... The BINARY key word causes all data to be stored/read as binary format rather than as text. It is somewhat faster than the normal text mode, but a binary-format file is less portable across machine architectures and PostgreSQL versions. You must have select privilege on the table whose values are read by COPY TO, and insert privilege on the table into which values are inserted by COPY FROM. Files named in a COPY command are read or written directly by the server, not by the client application. Therefore, they must reside on or be accessible to the database server machine, not the client. They must be accessible to and readable or writable by the PostgreSQL user (the user ID the server runs as), not the client. COPY naming a file is only allowed to database superusers, since it allows reading or writing any file that the server has privileges to access. Do not confuse COPY with the psql instruction \copy. \copy invokes COPY FROM STDIN or COPY TO STDOUT, and then fetches/stores the data in a file accessible to the psql client. Thus, file accessibility and access rights depend on the client rather than the server when \copy is used. It is recommended that the file name used in COPY always be specified as an absolute path. This is enforced by the server in the case of COPY TO, but for COPY FROM you do have the option of reading from a file specified by a relative path. The path will be interpreted relative to the working directory of the server process (normally the cluster's data directory), not the client's working directory. COPY FROM will invoke any triggers and check constraints on the destination table. However, it will not invoke rules. COPY input and output is affected by DateStyle. To ensure portability to other PostgreSQL installations that might use non-default DateStyle settings, DateStyle should be set to ISO before using COPY TO. Input data is interpreted according to the current client encoding, and output data is encoded in the the current client encoding, even if the data does not pass through the client but is read from or written to a file. COPY stops operation at the first error. This should not lead to problems in the event of a COPY TO, but the target table will already have received earlier rows in a COPY FROM. These rows will not be visible or accessible, but they still occupy disk space. This might amount to a considerable amount of wasted disk space if the failure happened well into a large copy operation. You might wish to invoke VACUUM to recover the wasted space. File Formats Text Format When COPY is used without the BINARY or 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 attribute's data type. The specified null string is used in place of columns that are null. COPY FROM will raise an error if any line of the input file contains more or fewer columns than are expected. If OIDS is specified, the OID is read or written as the first column, preceding the user data columns. End of data can be represented by a single line containing just backslash- period (\.). An end-of-data marker is not necessary when reading from a file, since the end of file serves perfectly well; it is needed only when copying data to or from client applications using pre-3.0 client protocol. Backslash characters (\) can be used in the COPY data to quote data characters that might otherwise be taken as row or column delimiters. In particular, the following characters must be preceded by a backslash if they appear as part of a column value: backslash itself, newline, carriage return, and the current delimiter character. The specified null string is sent by COPY TO without adding any backslashes; conversely, COPY FROM matches the input against the null string before removing backslashes. Therefore, a null string such as \N cannot be confused with the actual data value \N (which would be represented as \\N). The following special backslash sequences are recognized by COPY FROM: ______________________________________________________________________ |Sequence|Represents___________________________________________________| |\b______|Backspace_(ASCII_8)__________________________________________| |\f______|Form_feed_(ASCII_12)_________________________________________| |\n______|Newline_(ASCII_10)___________________________________________| |\r______|Carriage_return_(ASCII_13)___________________________________| |\t______|Tab_(ASCII_9)________________________________________________| |\v______|Vertical_tab_(ASCII_11)______________________________________| |\digits |Backslash followed by one to three octal digits specifies the| |________|character_with_that_numeric_code_____________________________| |\xdigits|Backslash x followed by one or two hex digits specifies the | |________|character_with_that_numeric_code_____________________________| Presently, COPY TO will never emit an octal or hex-digits backslash sequence, but it does use the other sequences listed above for those control characters. Any other backslashed character that is not mentioned in the above table will be taken to represent itself. However, beware of adding backslashes unnecessarily, since that might accidentally produce a string matching the end-of-data marker (\.) or the null string (\N by default). These strings will be recognized before any other backslash processing is done. It is strongly recommended that applications generating COPY data convert data newlines and carriage returns to the \n and \r sequences respectively. At present it is possible to represent a data carriage return by a backslash and carriage return, and to represent a data newline by a backslash and newline. However, these representations might not be accepted in future releases. They are also highly vulnerable to corruption if the COPY file is transferred across different machines (for example, from Unix to Windows or vice versa). COPY TO will terminate each row with a Unix-style newline ("\n"). Servers running on Microsoft Windows instead output carriage return/newline ("\r\n"), but only for COPY to a server file; for consistency across platforms, COPY TO STDOUT always sends "\n" regardless of server platform. COPY FROM can handle lines ending with newlines, carriage returns, or carriage return/newlines. To reduce the risk of error due to un-backslashed newlines or carriage returns that were meant as data, COPY FROM will complain if the line endings in the input are not all alike. CSV Format This format is used for importing and exporting the Comma Separated Value (CSV) file format used by many other programs, such as spreadsheets. Instead of the escaping used by PostgreSQL's standard text mode, it produces and recognizes the common CSV escaping mechanism. The values in each record are separated by the DELIMITER character. If the value contains the delimiter character, the QUOTE character, the NULL string, a carriage return, or line feed character, then the whole value is prefixed and suffixed by the QUOTE character, and any occurrence within the value of a QUOTE character or the ESCAPE character is preceded by the escape character. You can also use FORCE QUOTE to force quotes when outputting non-NULL values in specific columns. The CSV format has no standard way to distinguish a NULL value from an empty string. PostgreSQL's COPY handles this by quoting. A NULL is output as the NULL string and is not quoted, while a data value matching the NULL string is quoted. Therefore, using the default settings, a NULL is written as an unquoted empty string, while an empty string is written with double quotes (""). Reading values follows similar rules. You can use FORCE NOT NULL to prevent NULL input comparisons for specific columns. Because backslash is not a special character in the CSV format, \., the end-of-data marker, could also appear as a data value. To avoid any misinterpretation, a \. data value appearing as a lone entry on a line is automatically quoted on output, and on input, if quoted, is not interpreted as the end-of-data marker. If you are loading a file created by another application that has a single unquoted column and might have a value of \., you might need to quote that value in the input file. Note: In CSV mode, all characters are significant. A quoted value surrounded by white space, or any characters other than DELIMITER, will include those characters. This can cause errors if you import data from a system that pads CSV lines with white space out to some fixed width. If such a situation arises you might need to preprocess the CSV file to remove the trailing white space, before importing the data into PostgreSQL. Note: CSV mode will both recognize and produce CSV files with quoted values containing embedded carriage returns and line feeds. Thus the files are not strictly one line per table row like text-mode files. Note: Many programs produce strange and occasionally perverse CSV files, 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 COPY might produce files that other programs cannot process. Binary Format The file format used for COPY BINARY changed in PostgreSQL 7.4. The new format consists of a file header, zero or more tuples containing the row data, and a file trailer. Headers and data are now in network byte order. File Header The file header consists of 15 bytes of fixed fields, followed by a variable-length header extension area. The fixed fields are: Bit 16 if 1, OIDs are included in the data; if 0, not Header extension area length 32-bit integer, length in bytes of remainder of header, not including self. Currently, this is zero, and the first tuple follows immediately. Future changes to the format might allow additional data to be present in the header. A reader should silently skip over any header extension data it does not know what to do with. The header extension area is envisioned to contain a sequence of self- identifying chunks. The flags field is not intended to tell readers what is in the extension area. Specific design of header extension contents is left for a later release. This design allows for both backwards-compatible header additions (add header extension chunks, or set low-order flag bits) and non-backwards- compatible changes (set high-order flag bits to signal such changes, and add supporting data to the extension area if needed). Tuples Each tuple begins with a 16-bit integer count of the number of fields in the tuple. (Presently, all tuples in a table will have the same count, but that might not always be true.) Then, repeated for each field in the tuple, there is a 32-bit length word followed by that many bytes of field data. (The length word does not include itself, and can be zero.) As a special case, -1 indicates a NULL field value. No value bytes follow in the NULL case. There is no alignment padding or any other extra data between fields. Presently, all data values in a COPY BINARY file are assumed to be in binary format (format code one). It is anticipated that a future extension might add a header field that allows per-column format codes to be specified. To determine the appropriate binary format for the actual tuple data you should consult the PostgreSQL source, in particular the *send and *recv functions for each column's data type (typically these functions are found in the src/backend/utils/adt/ directory of the source distribution). If OIDs are included in the file, the OID field immediately follows the field-count word. It is a normal field except that it's not included in the field-count. In particular it has a length word -- this will allow handling of 4-byte vs. 8-byte OIDs without too much pain, and will allow OIDs to be shown as null if that ever proves desirable. File Trailer The file trailer consists of a 16-bit integer word containing -1. This is easily distinguished from a tuple's field-count word. A reader should report an error if a field-count word is neither -1 nor the expected number of columns. This provides an extra check against somehow getting out of sync with the data. Examples The following example copies a table to the client using the vertical bar (|) as the field delimiter: COPY country TO STDOUT WITH DELIMITER '|'; To copy data from a file into the country table: COPY country FROM '/usr1/proj/bray/sql/country_data'; To copy into a file just the countries whose names start with 'A': COPY (SELECT * FROM country WHERE country_name LIKE 'A%') TO '/usr1/proj/ bray/sql/a_list_countries.copy'; Here is a sample of data suitable for copying into a table from STDIN: AF AFGHANISTAN AL ALBANIA DZ ALGERIA ZM ZAMBIA ZW ZIMBABWE Note that the white space on each line is actually a tab character. The following is the same data, output in binary format. The data is shown after filtering through the Unix utility od -c. The table has three columns; the first has type char(2), the second has type text, and the third has type integer. All the rows have a null value in the third column. 0000000 P G C O P Y \n 377 \r \n \0 \0 \0 \0 \0 \0 0000020 \0 \0 \0 \0 003 \0 \0 \0 002 A F \0 \0 \0 013 A 0000040 F G H A N I S T A N 377 377 377 377 \0 003 0000060 \0 \0 \0 002 A L \0 \0 \0 007 A L B A N I 0000100 A 377 377 377 377 \0 003 \0 \0 \0 002 D Z \0 \0 \0 0000120 007 A L G E R I A 377 377 377 377 \0 003 \0 \0 0000140 \0 002 Z M \0 \0 \0 006 Z A M B I A 377 377 0000160 377 377 \0 003 \0 \0 \0 002 Z W \0 \0 \0 \b Z I 0000200 M B A B W E 377 377 377 377 377 377 Compatibility There is no COPY statement in the SQL standard. The following syntax was used before PostgreSQL version 7.3 and is still supported: COPY [ BINARY ] tablename [ WITH OIDS ] FROM { 'filename' | STDIN } [ [USING] DELIMITERS 'delimiter' ] [ WITH NULL AS 'null string' ] COPY [ BINARY ] tablename [ WITH OIDS ] TO { 'filename' | STDOUT } [ [USING] DELIMITERS 'delimiter' ] [ WITH NULL AS 'null string' ] ------------------------------------------------------------------------ CREATE AGGREGATE Name CREATE AGGREGATE -- define a new aggregate function Synopsis CREATE AGGREGATE name ( input_data_type [ , ... ] ) ( SFUNC = sfunc, STYPE = state_data_type [ , FINALFUNC = ffunc ] [ , INITCOND = initial_condition ] [ , SORTOP = sort_operator ] ) or the old syntax CREATE AGGREGATE name ( BASETYPE = base_type, SFUNC = sfunc, STYPE = state_data_type [ , FINALFUNC = ffunc ] [ , INITCOND = initial_condition ] [ , SORTOP = sort_operator ] ) Description CREATE AGGREGATE defines a new aggregate function. Some basic and commonly- used aggregate functions are included with the distribution; they are documented in Section_9.18. If one defines new types or needs an aggregate function not already provided, then CREATE AGGREGATE can be used to provide the desired features. If a schema name is given (for example, CREATE AGGREGATE myschema.myagg ...) then the aggregate function is created in the specified schema. Otherwise it is created in the current schema. An aggregate function is identified by its name and input data type(s). Two aggregates in the same schema can have the same name if they operate on different input types. The name and input data type(s) of an aggregate must also be distinct from the name and input data type(s) of every ordinary function in the same schema. An aggregate function is made from one or two ordinary functions: a state transition function sfunc, and an optional final calculation function ffunc. These are used as follows: sfunc( internal-state, next-data-values ) ---> next-internal-state ffunc( internal-state ) ---> aggregate-value PostgreSQL creates a temporary variable of data type stype to hold the current internal state of the aggregate. At each input row, the aggregate argument value(s) are calculated and the state transition function is invoked with the current state value and the new argument value(s) to calculate a new internal state value. After all the rows have been processed, the final function is invoked once to calculate the aggregate's return value. If there is no final function then the ending state value is returned as-is. An aggregate function can provide an initial condition, that is, an initial value for the internal state value. This is specified and stored in the database as a value of type text, but it must be a valid external representation of a constant of the state value data type. If it is not supplied then the state value starts out null. If the state transition function is declared "strict", then it cannot be called with null inputs. With such a transition function, aggregate execution behaves as follows. Rows with any null input values are ignored (the function is not called and the previous state value is retained). If the initial state value is null, then at the first row with all-nonnull input values, the first argument value replaces the state value, and the transition function is invoked at subsequent rows with all-nonnull input values. This is handy for implementing aggregates like max. Note that this behavior is only available when state_data_type is the same as the first input_data_type. When these types are different, you must supply a nonnull initial condition or use a nonstrict transition function. If the state transition function is not strict, then it will be called unconditionally at each input row, and must deal with null inputs and null transition values for itself. This allows the aggregate author to have full control over the aggregate's handling of null values. If the final function is declared "strict", then it will not be called when the ending state value is null; instead a null result will be returned automatically. (Of course this is just the normal behavior of strict functions.) In any case the final function has the option of returning a null value. For example, the final function for avg returns null when it sees there were zero input rows. Aggregates that behave like MIN or MAX can sometimes be optimized by looking into an index instead of scanning every input row. If this aggregate can be so optimized, indicate it by specifying a sort operator. The basic requirement is that the aggregate must yield the first element in the sort ordering induced by the operator; in other words: SELECT agg(col) FROM tab; must be equivalent to: SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; Further assumptions are that the aggregate ignores null inputs, and that it delivers a null result if and only if there were no non-null inputs. Ordinarily, a data type's < operator is the proper sort operator for MIN, and > is the proper sort operator for MAX. Note that the optimization will never actually take effect unless the specified operator is the "less than" or "greater than" strategy member of a B-tree index operator class. Parameters name The name (optionally schema-qualified) of the aggregate function to create. input_data_type An input data type on which this aggregate function operates. To create a zero-argument aggregate function, write * in place of the list of input data types. (An example of such an aggregate is count (*).) base_type In the old syntax for CREATE AGGREGATE, the input data type is specified by a basetype parameter rather than being written next to the aggregate name. Note that this syntax allows only one input parameter. To define a zero-argument aggregate function, specify the basetype as "ANY" (not *). sfunc The name of the state transition function to be called for each input row. For an N-argument aggregate function, the sfunc must take N+1 arguments, the first being of type state_data_type and the rest matching the declared input data type(s) of the aggregate. The function must return a value of type state_data_type. This function takes the current state value and the current input data value(s), and returns the next state value. state_data_type The data type for the aggregate's state value. ffunc The name of the final function called to compute the aggregate's result after all input rows have been traversed. The function must take a single argument of type state_data_type. The return data type of the aggregate is defined as the return type of this function. If ffunc is not specified, then the ending state value is used as the aggregate's result, and the return type is state_data_type. initial_condition The initial setting for the state value. This must be a string constant in the form accepted for the data type state_data_type. If not specified, the state value starts out null. sort_operator The associated sort operator for a MIN- or MAX-like aggregate. This is just an operator name (possibly schema-qualified). The operator is assumed to have the same input data types as the aggregate (which must be a single-argument aggregate). The parameters of CREATE AGGREGATE can be written in any order, not just the order illustrated above. Examples See Section_34.10. Compatibility CREATE AGGREGATE is a PostgreSQL language extension. The SQL standard does not provide for user-defined aggregate functions. See Also ALTER_AGGREGATE, DROP_AGGREGATE ------------------------------------------------------------------------ CREATE CAST Name CREATE CAST -- define a new cast Synopsis CREATE CAST (sourcetype AS targettype) WITH FUNCTION funcname (argtypes) [ AS ASSIGNMENT | AS IMPLICIT ] CREATE CAST (sourcetype AS targettype) WITHOUT FUNCTION [ AS ASSIGNMENT | AS IMPLICIT ] Description CREATE CAST defines a new cast. A cast specifies how to perform a conversion between two data types. For example: SELECT CAST(42 AS float8); converts the integer constant 42 to type float8 by invoking a previously specified function, in this case float8(int4). (If no suitable cast has been defined, the conversion fails.) Two types can be binary compatible, which means that they can be converted into one another "for free" without invoking any function. This requires that corresponding values use the same internal representation. For instance, the types text and varchar are binary compatible. By default, a cast can be invoked only by an explicit cast request, that is an explicit CAST(x AS typename) or x::typename construct. If the cast is marked AS ASSIGNMENT then it can be invoked implicitly when assigning a value to a column of the target data type. For example, supposing that foo.f1 is a column of type text, then: INSERT INTO foo (f1) VALUES (42); will be allowed if the cast from type integer to type text is marked AS ASSIGNMENT, otherwise not. (We generally use the term assignment cast to describe this kind of cast.) If the cast is marked AS IMPLICIT then it can be invoked implicitly in any context, whether assignment or internally in an expression. (We generally use the term implicit cast to describe this kind of cast.) For example, consider this query: SELECT 2 + 4.0; The parser initially marks the constants as being of type integer and numeric respectively. There is no integer + numeric operator in the system catalogs, but there is a numeric + numeric operator. The query will therefore succeed if a cast from integer to numeric is available and is marked AS IMPLICIT -- which in fact it is. The parser will apply the implicit cast and resolve the query as if it had been written SELECT CAST ( 2 AS numeric ) + 4.0; Now, the catalogs also provide a cast from numeric to integer. If that cast were marked AS IMPLICIT -- which it is not -- then the parser would be faced with choosing between the above interpretation and the alternative of casting the numeric constant to integer and applying the integer + integer operator. Lacking any knowledge of which choice to prefer, it would give up and declare the query ambiguous. The fact that only one of the two casts is implicit is the way in which we teach the parser to prefer resolution of a mixed numeric-and-integer expression as numeric; there is no built-in knowledge about that. It is wise to be conservative about marking casts as implicit. An overabundance of implicit casting paths can cause PostgreSQL to choose surprising interpretations of commands, or to be unable to resolve commands at all because there are multiple possible interpretations. A good rule of thumb is to make a cast implicitly invokable only for information- preserving transformations between types in the same general type category. For example, the cast from int2 to int4 can reasonably be implicit, but the cast from float8 to int4 should probably be assignment-only. Cross-type- category casts, such as text to int4, are best made explicit-only. To be able to create a cast, you must own the source or the target data type. To create a binary-compatible cast, you must be superuser. (This restriction is made because an erroneous binary-compatible cast conversion can easily crash the server.) Parameters sourcetype The name of the source data type of the cast. targettype The name of the target data type of the cast. funcname(argtypes) The function used to perform the cast. The function name can be schema-qualified. If it is not, the function will be looked up in the schema search path. The function's result data type must match the target type of the cast. Its arguments are discussed below. WITHOUT FUNCTION Indicates that the source type and the target type are binary compatible, so no function is required to perform the cast. AS ASSIGNMENT Indicates that the cast can be invoked implicitly in assignment contexts. AS IMPLICIT Indicates that the cast can be invoked implicitly in any context. Cast implementation functions can have one to three arguments. The first argument type must be identical to the cast's source type. The second argument, if present, must be type integer; it receives the type modifier associated with the destination type, or -1 if there is none. The third argument, if present, must be type boolean; it receives true if the cast is an explicit cast, false otherwise. (Bizarrely, the SQL spec demands different behaviors for explicit and implicit casts in some cases. This argument is supplied for functions that must implement such casts. It is not recommended that you design your own data types so that this matters.) Ordinarily a cast must have different source and target data types. However, it is allowed to declare a cast with identical source and target types if it has a cast implementation function with more than one argument. This is used to represent type-specific length coercion functions in the system catalogs. The named function is used to coerce a value of the type to the type modifier value given by its second argument. When a cast has different source and target types and a function that takes more than one argument, it represents converting from one type to another and applying a length coercion in a single step. When no such entry is available, coercion to a type that uses a type modifier involves two steps, one to convert between data types and a second to apply the modifier. Notes Use DROP_CAST to remove user-defined casts. Remember that if you want to be able to convert types both ways you need to declare casts both ways explicitly. It is normally not necessary to create casts between user-defined types and the standard string types (text, varchar, and char(n)). PostgreSQL will automatically handle a cast to a string type by invoking the other type's output function, or conversely handle a cast from a string type by invoking the other type's input function. These automatically-provided casts are known as I/O conversion casts. I/O conversion casts to string types are treated as assignment casts, while I/O conversion casts from string types are explicit-only. You can override this behavior by declaring your own cast to replace an I/O conversion cast, but usually the only reason to do so is if you want the conversion to be more easily invokable than the standard assignment-only or explicit-only setting. Another possible reason is that you want the conversion to behave differently from the type's I/ O function; but that is sufficiently surprising that you should think twice about whether it's a good idea. (A small number of the built-in types do indeed have different behaviors for conversions, mostly because of requirements of the SQL standard.) Prior to PostgreSQL 7.3, every function that had the same name as a data type, returned that data type, and took one argument of a different type was automatically a cast function. This convention has been abandoned in face of the introduction of schemas and to be able to represent binary compatible casts in the system catalogs. The built-in cast functions still follow this naming scheme, but they have to be shown as casts in the system catalog pg_cast as well. While not required, it is recommended that you continue to follow this old convention of naming cast implementation functions after the target data type. Many users are used to being able to cast data types using a function-style notation, that is typename(x). This notation is in fact nothing more nor less than a call of the cast implementation function; it is not specially treated as a cast. If your conversion functions are not named to support this convention then you will have surprised users. Since PostgreSQL allows overloading of the same function name with different argument types, there is no difficulty in having multiple conversion functions from different types that all use the target type's name. Note: Actually the preceding paragraph is an oversimplification: there are two cases in which a function-call construct will be treated as a cast request without having matched it to an actual function. If a function call name(x) does not exactly match any existing function, but name is the name of a data type and pg_cast provides a binary-compatible cast to this type from the type of x, then the call will be construed as a binary-compatible cast. This exception is made so that binary-compatible casts can be invoked using functional syntax, even though they lack any function. Likewise, if there is no pg_cast entry but the cast would be to or from a string type, the call will be construed as an I/O conversion cast. This exception allows I/O conversion casts to be invoked using functional syntax. Examples To create a cast from type bigint to type int4 using the function int4 (bigint): CREATE CAST (bigint AS int4) WITH FUNCTION int4(bigint); (This cast is already predefined in the system.) Compatibility The CREATE CAST command conforms to the SQL standard, except that SQL does not make provisions for binary-compatible types or extra arguments to implementation functions. AS IMPLICIT is a PostgreSQL extension, too. See Also CREATE_FUNCTION, CREATE_TYPE, DROP_CAST ------------------------------------------------------------------------ CREATE CONSTRAINT TRIGGER Name CREATE CONSTRAINT TRIGGER -- define a new constraint trigger Synopsis CREATE CONSTRAINT TRIGGER name AFTER event [ OR ... ] ON table_name [ FROM referenced_table_name ] { NOT DEFERRABLE | [ DEFERRABLE ] { INITIALLY IMMEDIATE | INITIALLY DEFERRED } } FOR EACH ROW EXECUTE PROCEDURE funcname ( arguments ) Description CREATE CONSTRAINT TRIGGER creates a constraint trigger. This is the same as a regular trigger except that the timing of the trigger firing can be adjusted using SET_CONSTRAINTS. Constraint triggers must be AFTER ROW triggers. They can be fired either at the end of the statement causing the triggering event, or at the end of the containing transaction; in the latter case they are said to be deferred. A pending deferred-trigger firing can also be forced to happen immediately by using SET CONSTRAINTS. Parameters name The name of the constraint trigger. This is also the name to use when modifying the trigger's behavior using SET CONSTRAINTS. The name cannot be schema-qualified -- the trigger inherits the schema of its table. event One of INSERT, UPDATE, or DELETE; this specifies the event that will fire the trigger. Multiple events can be specified using OR. table_name The (possibly schema-qualified) name of the table in which the triggering events occur. referenced_table_name The (possibly schema-qualified) name of another table referenced by the constraint. This option is used for foreign-key constraints and is not recommended for general use. DEFERRABLE NOT DEFERRABLE INITIALLY IMMEDIATE INITIALLY DEFERRED The default timing of the trigger. See the CREATE_TABLE documentation for details of these constraint options. funcname The function to call when the trigger is fired. See CREATE_TRIGGER for details. arguments Optional argument strings to pass to the trigger function. See CREATE TRIGGER for details. Compatibility CREATE CONSTRAINT TRIGGER is a PostgreSQL extension of the SQL standard. See Also CREATE_TRIGGER, DROP_TRIGGER, SET_CONSTRAINTS ------------------------------------------------------------------------ CREATE CONVERSION Name CREATE CONVERSION -- define a new encoding conversion Synopsis CREATE [ DEFAULT ] CONVERSION name FOR source_encoding TO dest_encoding FROM funcname Description CREATE CONVERSION defines a new conversion between character set encodings. Also, conversions that are marked DEFAULT can be used for automatic encoding conversion between client and server. For this purpose, two conversions, from encoding A to B and from encoding B to A, must be defined. To be able to create a conversion, you must have EXECUTE privilege on the function and CREATE privilege on the destination schema. Parameters DEFAULT The DEFAULT clause indicates that this conversion is the default for this particular source to destination encoding. There should be only one default encoding in a schema for the encoding pair. name The name of the conversion. The conversion name can be schema- qualified. If it is not, the conversion is defined in the current schema. The conversion name must be unique within a schema. source_encoding The source encoding name. dest_encoding The destination encoding name. funcname The function used to perform the conversion. The function name can be schema-qualified. If it is not, the function will be looked up in the path. The function must have the following signature: conv_proc( integer, -- source encoding ID integer, -- destination encoding ID cstring, -- source string (null terminated C string) internal, -- destination (fill with a null terminated C string) integer -- source string length ) RETURNS void; Notes Use DROP CONVERSION to remove user-defined conversions. The privileges required to create a conversion might be changed in a future release. Examples To create a conversion from encoding UTF8 to LATIN1 using myfunc: CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc; Compatibility CREATE CONVERSION is a PostgreSQL extension. There is no CREATE CONVERSION statement in the SQL standard. See Also ALTER_CONVERSION, CREATE_FUNCTION, DROP_CONVERSION ------------------------------------------------------------------------ CREATE DATABASE Name CREATE DATABASE -- create a new database Synopsis CREATE DATABASE name [ [ WITH ] [ OWNER [=] dbowner ] [ TEMPLATE [=] template ] [ ENCODING [=] encoding ] [ TABLESPACE [=] tablespace ] [ CONNECTION LIMIT [=] connlimit ] ] Description CREATE DATABASE creates a new PostgreSQL database. To create a database, you must be a superuser or have the special CREATEDB privilege. See CREATE_USER. Normally, the creator becomes the owner of the new database. Superusers can create databases owned by other users, by using the OWNER clause. They can even create databases owned by users with no special privileges. Non- superusers with CREATEDB privilege can only create databases owned by themselves. By default, the new database will be created by cloning the standard system database template1. A different template can be specified by writing TEMPLATE name. In particular, by writing TEMPLATE template0, you can create a virgin database containing only the standard objects predefined by your version of PostgreSQL. This is useful if you wish to avoid copying any installation-local objects that might have been added to template1. Parameters name The name of a database to create. dbowner The name of the database user who will own the new database, or DEFAULT to use the default (namely, the user executing the command). template The name of the template from which to create the new database, or DEFAULT to use the default template (template1). encoding Character set encoding to use in the new database. Specify a string constant (e.g., 'SQL_ASCII'), or an integer encoding number, or DEFAULT to use the default encoding (namely, the encoding of the template database). The character sets supported by the PostgreSQL server are described in Section_22.2.1. See below for additional restrictions. tablespace The name of the tablespace that will be associated with the new database, or DEFAULT to use the template database's tablespace. This tablespace will be the default tablespace used for objects created in this database. See CREATE_TABLESPACE for more information. connlimit How many concurrent connections can be made to this database. -1 (the default) means no limit. Optional parameters can be written in any order, not only the order illustrated above. Notes CREATE DATABASE cannot be executed inside a transaction block. Errors along the line of "could not initialize database directory" are most likely related to insufficient permissions on the data directory, a full disk, or other file system problems. Use DROP_DATABASE to remove a database. The program createdb is a wrapper program around this command, provided for convenience. Although it is possible to copy a database other than template1 by specifying its name as the template, this is not (yet) intended as a general-purpose "COPY DATABASE" facility. The principal limitation is that no other sessions can be connected to the template database while it is being copied. CREATE DATABASE will fail if any other connection exists when it starts; otherwise, new connections to the template database are locked out until CREATE DATABASE completes. See Section_20.3 for more information. Any character set encoding specified for the new database must be compatible with the server's LC_CTYPE locale setting. If LC_CTYPE is C (or equivalently POSIX), then all encodings are allowed, but for other locale settings there is only one encoding that will work properly, and so the apparent freedom to specify an encoding is illusory if you didn't initialize the database cluster in C locale. CREATE DATABASE will allow superusers to specify SQL_ASCII encoding regardless of the locale setting, but this choice is deprecated and may result in misbehavior of character- string functions if data that is not encoding-compatible with the locale is stored in the database. The CONNECTION LIMIT option is only enforced approximately; if two new sessions start at about the same time when just one connection "slot" remains for the database, it is possible that both will fail. Also, the limit is not enforced against superusers. Examples To create a new database: CREATE DATABASE lusiadas; To create a database sales owned by user salesapp with a default tablespace of salesspace: CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace; To create a database music which supports the ISO-8859-1 character set: CREATE DATABASE music ENCODING 'LATIN1'; Compatibility There is no CREATE DATABASE statement in the SQL standard. Databases are equivalent to catalogs, whose creation is implementation-defined. See Also ALTER_DATABASE, DROP_DATABASE ------------------------------------------------------------------------ CREATE DOMAIN Name CREATE DOMAIN -- define a new domain Synopsis CREATE DOMAIN name [ AS ] data_type [ DEFAULT expression ] [ constraint [ ... ] ] where constraint is: [ CONSTRAINT constraint_name ] { NOT NULL | NULL | CHECK (expression) } Description CREATE DOMAIN creates a new domain. A domain is essentially a data type with optional constraints (restrictions on the allowed set of values). The user who defines a domain becomes its owner. If a schema name is given (for example, CREATE DOMAIN myschema.mydomain ...) then the domain is created in the specified schema. Otherwise it is created in the current schema. The domain name must be unique among the types and domains existing in its schema. Domains are useful for abstracting common constraints on fields into a single location for maintenance. For example, several tables might contain email address columns, all requiring the same CHECK constraint to verify the address syntax. Define a domain rather than setting up each table's constraint individually. Parameters name The name (optionally schema-qualified) of a domain to be created. data_type The underlying data type of the domain. This can include array specifiers. DEFAULT expression The DEFAULT clause specifies a default value for columns of the domain data type. The value is any variable-free expression (but subqueries are not allowed). The data type of the default expression must match the data type of the domain. If no default value is specified, then the default value is the null value. The default expression will be used in any insert operation that does not specify a value for the column. If a default value is defined for a particular column, it overrides any default associated with the domain. In turn, the domain default overrides any default value associated with the underlying data type. CONSTRAINT constraint_name An optional name for a constraint. If not specified, the system generates a name. NOT NULL Values of this domain are not allowed to be null. NULL Values of this domain are allowed to be null. This is the default. This clause is only intended for compatibility with nonstandard SQL databases. Its use is discouraged in new applications. CHECK (expression) CHECK clauses specify integrity constraints or tests which values of the domain must satisfy. Each constraint must be an expression producing a Boolean result. It should use the key word VALUE to refer to the value being tested. Currently, CHECK expressions cannot contain subqueries nor refer to variables other than VALUE. Examples This example creates the us_postal_code data type and then uses the type in a table definition. A regular expression test is used to verify that the value looks like a valid US postal code: CREATE DOMAIN us_postal_code AS TEXT CHECK( VALUE ~ '^\\d{5}$' OR VALUE ~ '^\\d{5}-\\d{4}$' ); CREATE TABLE us_snail_addy ( address_id SERIAL PRIMARY KEY, street1 TEXT NOT NULL, street2 TEXT, street3 TEXT, city TEXT NOT NULL, postal us_postal_code NOT NULL ); Compatibility The command CREATE DOMAIN conforms to the SQL standard. See Also ALTER_DOMAIN, DROP_DOMAIN ------------------------------------------------------------------------ CREATE FUNCTION Name CREATE FUNCTION -- define a new function Synopsis CREATE [ OR REPLACE ] FUNCTION name ( [ [ argmode ] [ argname ] argtype [, ...] ] ) [ RETURNS rettype ] { LANGUAGE langname | IMMUTABLE | STABLE | VOLATILE | CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT | [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER | COST execution_cost | ROWS result_rows | SET configuration_parameter { TO value | = value | FROM CURRENT } | AS 'definition' | AS 'obj_file', 'link_symbol' } ... [ WITH ( attribute [, ...] ) ] Description CREATE FUNCTION defines a new function. CREATE OR REPLACE FUNCTION will either create a new function, or replace an existing definition. If a schema name is included, then the function is created in the specified schema. Otherwise it is created in the current schema. The name of the new function must not match any existing function with the same argument types in the same schema. However, functions of different argument types can share a name (this is called overloading). To replace the current definition of an existing function, use CREATE OR REPLACE FUNCTION. It is not possible to change the name or argument types of a function this way (if you tried, you would actually be creating a new, distinct function). Also, CREATE OR REPLACE FUNCTION will not let you change the return type of an existing function. To do that, you must drop and recreate the function. (When using OUT parameters, that means you cannot change the names or types of any OUT parameters except by dropping the function.) If you drop and then recreate a function, the new function is not the same entity as the old; you will have to drop existing rules, views, triggers, etc. that refer to the old function. Use CREATE OR REPLACE FUNCTION to change a function definition without breaking objects that refer to the function. Also, ALTER FUNCTION can be used to change most of the auxiliary properties of an existing function. The user that creates the function becomes the owner of the function. Parameters isStrict Equivalent to STRICT or RETURNS NULL ON NULL INPUT. isCachable isCachable is an obsolete equivalent of IMMUTABLE; it's still accepted for backwards-compatibility reasons. Attribute names are not case-sensitive. Notes Refer to Section_34.3 for further information on writing functions. The full SQL type syntax is allowed for input arguments and return value. However, some details of the type specification (e.g., the precision field for type numeric) are the responsibility of the underlying function implementation and are silently swallowed (i.e., not recognized or enforced) by the CREATE FUNCTION command. PostgreSQL allows function overloading; that is, the same name can be used for several different functions so long as they have distinct argument types. However, the C names of all functions must be different, so you must give overloaded C functions different C names (for example, use the argument types as part of the C names). Two functions are considered the same if they have the same names and input argument types, ignoring any OUT parameters. Thus for example these declarations conflict: CREATE FUNCTION foo(int) ... CREATE FUNCTION foo(int, out text) ... When repeated CREATE FUNCTION calls refer to the same object file, the file is only loaded once per session. To unload and reload the file (perhaps during development), use the LOAD command. Use DROP_FUNCTION to remove user-defined functions. It is often helpful to use dollar quoting (see Section_4.1.2.2) to write the function definition string, rather than the normal single quote syntax. Without dollar quoting, any single quotes or backslashes in the function definition must be escaped by doubling them. If a SET clause is attached to a function, then the effects of a SET LOCAL command executed inside the function for the same variable are restricted to the function: the configuration parameter's prior value is still restored at function exit. However, an ordinary SET command (without LOCAL) overrides the SET clause, much as it would do for a previous SET LOCAL command: the effects of such a command will persist after function exit, unless the current transaction is rolled back. To be able to define a function, the user must have the USAGE privilege on the language. Examples Here are some trivial examples to help you get started. For more information and examples, see Section_34.3. CREATE FUNCTION add(integer, integer) RETURNS integer AS 'select $1 + $2;' LANGUAGE SQL IMMUTABLE RETURNS NULL ON NULL INPUT; Increment an integer, making use of an argument name, in PL/pgSQL: CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS $$ BEGIN RETURN i + 1; END; $$ LANGUAGE plpgsql; Return a record containing multiple output parameters: CREATE FUNCTION dup(in int, out f1 int, out f2 text) AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$ LANGUAGE SQL; SELECT * FROM dup(42); You can do the same thing more verbosely with an explicitly named composite type: CREATE TYPE dup_result AS (f1 int, f2 text); CREATE FUNCTION dup(int) RETURNS dup_result AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$ LANGUAGE SQL; SELECT * FROM dup(42); Writing SECURITY DEFINER Functions Safely Because a SECURITY DEFINER function is executed with the privileges of the user that created it, care is needed to ensure that the function cannot be misused. For security, search_path should be set to exclude any schemas writable by untrusted users. This prevents malicious users from creating objects that mask objects used by the function. Particularly important in this regard is the temporary-table schema, which is searched first by default, and is normally writable by anyone. A secure arrangement can be had by forcing the temporary schema to be searched last. To do this, write pg_temp as the last entry in search_path. This function illustrates safe usage: CREATE FUNCTION check_password(uname TEXT, pass TEXT) RETURNS BOOLEAN AS $$ DECLARE passed BOOLEAN; BEGIN SELECT (pwd = $2) INTO passed FROM pwds WHERE username = $1; RETURN passed; END; $$ LANGUAGE plpgsql SECURITY DEFINER -- Set a secure search_path: trusted schema(s), then 'pg_temp'. SET search_path = admin, pg_temp; Before PostgreSQL version 8.3, the SET option was not available, and so older functions may contain rather complicated logic to save, set, and restore search_path. The SET option is far easier to use for this purpose. Another point to keep in mind is that by default, execute privilege is granted to PUBLIC for newly created functions (see GRANT for more information). Frequently you will wish to restrict use of a security definer function to only some users. To do that, you must revoke the default PUBLIC privileges and then grant execute privilege selectively. To avoid having a window where the new function is accessible to all, create it and set the privileges within a single transaction. For example: BEGIN; CREATE FUNCTION check_password(uname TEXT, pass TEXT) ... SECURITY DEFINER; REVOKE ALL ON FUNCTION check_password(uname TEXT, pass TEXT) FROM PUBLIC; GRANT EXECUTE ON FUNCTION check_password(uname TEXT, pass TEXT) TO admins; COMMIT; Compatibility A CREATE FUNCTION command is defined in SQL:1999 and later. The PostgreSQL version is similar but not fully compatible. The attributes are not portable, neither are the different available languages. For compatibility with some other database systems, argmode can be written either before or after argname. But only the first way is standard- compliant. See Also ALTER_FUNCTION, DROP_FUNCTION, GRANT, LOAD, REVOKE, createlang ------------------------------------------------------------------------ CREATE GROUP Name CREATE GROUP -- define a new database role Synopsis CREATE GROUP name [ [ WITH ] option [ ... ] ] where option can be: SUPERUSER | NOSUPERUSER | CREATEDB | NOCREATEDB | CREATEROLE | NOCREATEROLE | CREATEUSER | NOCREATEUSER | INHERIT | NOINHERIT | LOGIN | NOLOGIN | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' | VALID UNTIL 'timestamp' | IN ROLE rolename [, ...] | IN GROUP rolename [, ...] | ROLE rolename [, ...] | ADMIN rolename [, ...] | USER rolename [, ...] | SYSID uid Description CREATE GROUP is now an alias for CREATE_ROLE. Compatibility There is no CREATE GROUP statement in the SQL standard. See Also CREATE_ROLE ------------------------------------------------------------------------ CREATE INDEX Name CREATE INDEX -- define a new index Synopsis CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] name ON table [ USING method ] ( { column | ( expression ) } [ opclass ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [, ...] ) [ WITH ( storage_parameter = value [, ... ] ) ] [ TABLESPACE tablespace ] [ WHERE predicate ] Description CREATE INDEX constructs an index name on the specified table. Indexes are primarily used to enhance database performance (though inappropriate use can result in slower performance). The key field(s) for the index are specified as column names, or alternatively as expressions written in parentheses. Multiple fields can be specified if the index method supports multicolumn indexes. An index field can be an expression computed from the values of one or more columns of the table row. This feature can be used to obtain fast access to data based on some transformation of the basic data. For example, an index computed on upper(col) would allow the clause WHERE upper(col) = 'JIM' to use an index. PostgreSQL provides the index methods B-tree, hash, GiST, and GIN. Users can also define their own index methods, but that is fairly complicated. When the WHERE clause is present, a partial index is created. A partial index is an index that contains entries for only a portion of a table, usually a portion that is more useful for indexing than the rest of the table. For example, if you have a table that contains both billed and unbilled orders where the unbilled orders take up a small fraction of the total table and yet that is an often used section, you can improve performance by creating an index on just that portion. Another possible application is to use WHERE with UNIQUE to enforce uniqueness over a subset of a table. See Section_11.8 for more discussion. The expression used in the WHERE clause can refer only to columns of the underlying table, but it can use all columns, not just the ones being indexed. Presently, subqueries and aggregate expressions are also forbidden in WHERE. The same restrictions apply to index fields that are expressions. All functions and operators used in an index definition must be "immutable", that is, their results must depend only on their arguments and never on any outside influence (such as the contents of another table or the current time). This restriction ensures that the behavior of the index is well-defined. To use a user-defined function in an index expression or WHERE clause, remember to mark the function immutable when you create it. Parameters UNIQUE Causes the system to check for duplicate values in the table when the index is created (if data already exist) and each time data is added. Attempts to insert or update data which would result in duplicate entries will generate an error. CONCURRENTLY When this option is used, PostgreSQL will build the index without taking any locks that prevent concurrent inserts, updates, or deletes on the table; whereas a standard index build locks out writes (but not reads) on the table until it's done. There are several caveats to be aware of when using this option -- see Building_Indexes Concurrently. name The name of the index to be created. No schema name can be included here; the index is always created in the same schema as its parent table. table The name (possibly schema-qualified) of the table to be indexed. method The name of the index method to be used. Choices are btree, hash, gist, and gin. The default method is btree. column The name of a column of the table. expression An expression based on one or more columns of the table. The expression usually must be written with surrounding parentheses, as shown in the syntax. However, the parentheses can be omitted if the expression has the form of a function call. opclass The name of an operator class. See below for details. ASC Specifies ascending sort order (which is the default). DESC Specifies descending sort order. NULLS FIRST Specifies that nulls sort before non-nulls. This is the default when DESC is specified. NULLS LAST Specifies that nulls sort after non-nulls. This is the default when DESC is not specified. storage_parameter The name of an index-method-specific storage parameter. See below for details. tablespace The tablespace in which to create the index. If not specified, default_tablespace is consulted, or temp_tablespaces for indexes on temporary tables. predicate The constraint expression for a partial index. Index Storage Parameters The WITH clause can specify storage parameters for indexes. Each index method can have its own set of allowed storage parameters. The built-in index methods all accept a single parameter: FILLFACTOR The fillfactor for an index is a percentage that determines how full the index method will try to pack index pages. For B-trees, leaf pages are filled to this percentage during initial index build, and also when extending the index at the right (largest key values). If pages subsequently become completely full, they will be split, leading to gradual degradation in the index's efficiency. B-trees use a default fillfactor of 90, but any value from 10 to 100 can be selected. If the table is static then fillfactor 100 is best to minimize the index's physical size, but for heavily updated tables a smaller fillfactor is better to minimize the need for page splits. The other index methods use fillfactor in different but roughly analogous ways; the default fillfactor varies between methods. Building Indexes Concurrently Creating an index can interfere with regular operation of a database. Normally PostgreSQL locks the table to be indexed against writes and performs the entire index build with a single scan of the table. Other transactions can still read the table, but if they try to insert, update, or delete rows in the table they will block until the index build is finished. This could have a severe effect if the system is a live production database. Very large tables can take many hours to be indexed, and even for smaller tables, an index build can lock out writers for periods that are unacceptably long for a production system. PostgreSQL supports building indexes without locking out writes. This method is invoked by specifying the CONCURRENTLY option of CREATE INDEX. When this option is used, PostgreSQL must perform two scans of the table, and in addition it must wait for all existing transactions that could potentially use the index to terminate. Thus this method requires more total work than a standard index build and takes significantly longer to complete. However, since it allows normal operations to continue while the index is built, this method is useful for adding new indexes in a production environment. Of course, the extra CPU and I/O load imposed by the index creation might slow other operations. In a concurrent index build, the index is actually entered into the system catalogs in one transaction, then the two table scans occur in a second and third transaction. If a problem arises while scanning the table, such as a uniqueness violation in a unique index, the CREATE INDEX command will fail but leave behind an "invalid" index. This index will be ignored for querying purposes because it might be incomplete; however it will still consume update overhead. The psql \d command will mark such an index as INVALID: postgres=# \d tab Table "public.tab" Column | Type | Modifiers --------+---------+----------- col | integer | Indexes: "idx" btree (col) INVALID The recommended recovery method in such cases is to drop the index and try again to perform CREATE INDEX CONCURRENTLY. (Another possibility is to rebuild the index with REINDEX. However, since REINDEX does not support concurrent builds, this option is unlikely to seem attractive.) Another caveat when building a unique index concurrently is that the uniqueness constraint is already being enforced against other transactions when the second table scan begins. This means that constraint violations could be reported in other queries prior to the index becoming available for use, or even in cases where the index build eventually fails. Also, if a failure does occur in the second scan, the "invalid" index continues to enforce its uniqueness constraint afterwards. Concurrent builds of expression indexes and partial indexes are supported. Errors occurring in the evaluation of these expressions could cause behavior similar to that described above for unique constraint violations. Regular index builds permit other regular index builds on the same table to occur in parallel, but only one concurrent index build can occur on a table at a time. In both cases, no other types of schema modification on the table are allowed meanwhile. Another difference is that a regular CREATE INDEX command can be performed within a transaction block, but CREATE INDEX CONCURRENTLY cannot. Notes See Chapter_11 for information about when indexes can be used, when they are not used, and in which particular situations they can be useful. Currently, only the B-tree and GiST index methods support multicolumn indexes. Up to 32 fields can be specified by default. (This limit can be altered when building PostgreSQL.) Only B-tree currently supports unique indexes. An operator class can be specified for each column of an index. The operator class identifies the operators to be used by the index for that column. For example, a B-tree index on four-byte integers would use the int4_ops class; this operator class includes comparison functions for four- byte integers. In practice the default operator class for the column's data type is usually sufficient. The main point of having operator classes is that for some data types, there could be more than one meaningful ordering. For example, we might want to sort a complex-number data type either by absolute value or by real part. We could do this by defining two operator classes for the data type and then selecting the proper class when making an index. More information about operator classes is in Section_11.9 and in Section_34.14. For index methods that support ordered scans (currently, only B-tree), the optional clauses ASC, DESC, NULLS FIRST, and/or NULLS LAST can be specified to reverse the normal sort direction of the index. Since an ordered index can be scanned either forward or backward, it is not normally useful to create a single-column DESC index -- that sort ordering is already available with a regular index. The value of these options is that multicolumn indexes can be created that match the sort ordering requested by a mixed-ordering query, such as SELECT ... ORDER BY x ASC, y DESC. The NULLS options are useful if you need to support "nulls sort low" behavior, rather than the default "nulls sort high", in queries that depend on indexes to avoid sorting steps. Use DROP_INDEX to remove an index. Prior releases of PostgreSQL also had an R-tree index method. This method has been removed because it had no significant advantages over the GiST method. If USING rtree is specified, CREATE INDEX will interpret it as USING gist, to simplify conversion of old databases to GiST. Examples To create a B-tree index on the column title in the table films: CREATE UNIQUE INDEX title_idx ON films (title); To create an index on the expression lower(title), allowing efficient case- insensitive searches: CREATE INDEX lower_title_idx ON films ((lower(title))); To create an index with non-default sort ordering of nulls: CREATE INDEX title_idx_nulls_low ON films (title NULLS FIRST); To create an index with non-default fill factor: CREATE UNIQUE INDEX title_idx ON films (title) WITH (fillfactor = 70); To create an index on the column code in the table films and have the index reside in the tablespace indexspace: CREATE INDEX code_idx ON films(code) TABLESPACE indexspace; To create an index without locking out writes to the table: CREATE INDEX CONCURRENTLY sales_quantity_index ON sales_table (quantity); Compatibility CREATE INDEX is a PostgreSQL language extension. There are no provisions for indexes in the SQL standard. See Also ALTER_INDEX, DROP_INDEX ------------------------------------------------------------------------ CREATE LANGUAGE Name CREATE LANGUAGE -- define a new procedural language Synopsis CREATE [ PROCEDURAL ] LANGUAGE name CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name HANDLER call_handler [ VALIDATOR valfunction ] Description Using CREATE LANGUAGE, a PostgreSQL user can register a new procedural language with a PostgreSQL database. Subsequently, functions and trigger procedures can be defined in this new language. CREATE LANGUAGE effectively associates the language name with a call handler that is responsible for executing functions written in the language. Refer to Chapter_37 for more information about language call handlers. There are two forms of the CREATE LANGUAGE command. In the first form, the user supplies just the name of the desired language, and the PostgreSQL server consults the pg_pltemplate system catalog to determine the correct parameters. In the second form, the user supplies the language parameters along with the language name. The second form can be used to create a language that is not defined in pg_pltemplate, but this approach is considered obsolescent. When the server finds an entry in the pg_pltemplate catalog for the given language name, it will use the catalog data even if the command includes language parameters. This behavior simplifies loading of old dump files, which are likely to contain out-of-date information about language support functions. Ordinarily, the user must have the PostgreSQL superuser privilege to register a new language. However, the owner of a database can register a new language within that database if the language is listed in the pg_pltemplate catalog and is marked as allowed to be created by database owners (tmpldbacreate is true). The default is that trusted languages can be created by database owners, but this can be adjusted by superusers by modifying the contents of pg_pltemplate. The creator of a language becomes its owner and can later drop it, rename it, or assign it to a new owner. Parameters TRUSTED TRUSTED specifies that the call handler for the language is safe, that is, it does not offer an unprivileged user any functionality to bypass access restrictions. If this key word is omitted when registering the language, only users with the PostgreSQL superuser privilege can use this language to create new functions. PROCEDURAL This is a noise word. name The name of the new procedural language. The language name is case insensitive. The name must be unique among the languages in the database. For backward compatibility, the name can be enclosed by single quotes. HANDLER call_handler call_handler is the name of a previously registered function that will be called to execute the procedural language functions. The call handler for a procedural language must be written in a compiled language such as C with version 1 call convention and registered with PostgreSQL as a function taking no arguments and returning the language_handler type, a placeholder type that is simply used to identify the function as a call handler. VALIDATOR valfunction valfunction is the name of a previously registered function that will be called when a new function in the language is created, to validate the new function. If no validator function is specified, then a new function will not be checked when it is created. The validator function must take one argument of type oid, which will be the OID of the to-be-created function, and will typically return void. A validator function would typically inspect the function body for syntactical correctness, but it can also look at other properties of the function, for example if the language cannot handle certain argument types. To signal an error, the validator function should use the ereport() function. The return value of the function is ignored. The TRUSTED option and the support function name(s) are ignored if the server has an entry for the specified language name in pg_pltemplate. Notes The createlang program is a simple wrapper around the CREATE LANGUAGE command. It eases installation of procedural languages from the shell command line. Use DROP_LANGUAGE, or better yet the droplang program, to drop procedural languages. The system catalog pg_language (see Section_44.21) records information about the currently installed languages. Also, createlang has an option to list the installed languages. To create functions in a procedural language, a user must have the USAGE privilege for the language. By default, USAGE is granted to PUBLIC (i.e., everyone) for trusted languages. This can be revoked if desired. Procedural languages are local to individual databases. However, a language can be installed into the template1 database, which will cause it to be available automatically in all subsequently-created databases. The call handler function and the validator function (if any) must already exist if the server does not have an entry for the language in pg_pltemplate. But when there is an entry, the functions need not already exist; they will be automatically defined if not present in the database. (This might result in CREATE LANGUAGE failing, if the shared library that implements the language is not available in the installation.) In PostgreSQL versions before 7.3, it was necessary to declare handler functions as returning the placeholder type opaque, rather than language_handler. To support loading of old dump files, CREATE LANGUAGE will accept a function declared as returning opaque, but it will issue a notice and change the function's declared return type to language_handler. Examples The preferred way of creating any of the standard procedural languages is just: CREATE LANGUAGE plpgsql; For a language not known in the pg_pltemplate catalog, a sequence such as this is needed: CREATE FUNCTION plsample_call_handler() RETURNS language_handler AS '$libdir/plsample' LANGUAGE C; CREATE LANGUAGE plsample HANDLER plsample_call_handler; Compatibility CREATE LANGUAGE is a PostgreSQL extension. See Also ALTER_LANGUAGE, CREATE_FUNCTION, DROP_LANGUAGE, GRANT, REVOKE, createlang, droplang ------------------------------------------------------------------------ CREATE OPERATOR Name CREATE OPERATOR -- define a new operator Synopsis CREATE OPERATOR name ( PROCEDURE = funcname [, LEFTARG = lefttype ] [, RIGHTARG = righttype ] [, COMMUTATOR = com_op ] [, NEGATOR = neg_op ] [, RESTRICT = res_proc ] [, JOIN = join_proc ] [, HASHES ] [, MERGES ] ) Description CREATE OPERATOR defines a new operator, name. The user who defines an operator becomes its owner. If a schema name is given then the operator is created in the specified schema. Otherwise it is created in the current schema. The operator name is a sequence of up to NAMEDATALEN-1 (63 by default) characters from the following list: + - * / < > = ~ ! @ # % ^ & | ` ? There are a few restrictions on your choice of name: * -- and /* cannot appear anywhere in an operator name, since they will be taken as the start of a comment. * A multicharacter operator name cannot end in + or -, unless the name also contains at least one of these characters: ~ ! @ # % ^ & | ` ? For example, @- is an allowed operator name, but *- is not. This restriction allows PostgreSQL to parse SQL-compliant commands without requiring spaces between tokens. The operator != is mapped to <> on input, so these two names are always equivalent. At least one of LEFTARG and RIGHTARG must be defined. For binary operators, both must be defined. For right unary operators, only LEFTARG should be defined, while for left unary operators only RIGHTARG should be defined. The funcname procedure must have been previously defined using CREATE FUNCTION and must be defined to accept the correct number of arguments (either one or two) of the indicated types. The other clauses specify optional operator optimization clauses. Their meaning is detailed in Section_34.13. Parameters name The name of the operator to be defined. See above for allowable characters. The name can be schema-qualified, for example CREATE OPERATOR myschema.+ (...). If not, then the operator is created in the current schema. Two operators in the same schema can have the same name if they operate on different data types. This is called overloading. funcname The function used to implement this operator. lefttype The data type of the operator's left operand, if any. This option would be omitted for a left-unary operator. righttype The data type of the operator's right operand, if any. This option would be omitted for a right-unary operator. com_op The commutator of this operator. neg_op The negator of this operator. res_proc The restriction selectivity estimator function for this operator. join_proc The join selectivity estimator function for this operator. HASHES Indicates this operator can support a hash join. MERGES Indicates this operator can support a merge join. To give a schema-qualified operator name in com_op or the other optional arguments, use the OPERATOR() syntax, for example: COMMUTATOR = OPERATOR(myschema.===) , Notes Refer to Section_34.12 for further information. The obsolete options SORT1, SORT2, LTCMP, and GTCMP were formerly used to specify the names of sort operators associated with a merge-joinable operator. This is no longer necessary, since information about associated operators is found by looking at B-tree operator families instead. If one of these options is given, it is ignored except for implicitly setting MERGES true. Use DROP_OPERATOR to delete user-defined operators from a database. Use ALTER_OPERATOR to modify operators in a database. Examples The following command defines a new operator, area-equality, for the data type box: CREATE OPERATOR === ( LEFTARG = box, RIGHTARG = box, PROCEDURE = area_equal_procedure, COMMUTATOR = ===, NEGATOR = !==, RESTRICT = area_restriction_procedure, JOIN = area_join_procedure, HASHES, MERGES ); Compatibility CREATE OPERATOR is a PostgreSQL extension. There are no provisions for user-defined operators in the SQL standard. See Also ALTER_OPERATOR, CREATE_OPERATOR_CLASS, DROP_OPERATOR ------------------------------------------------------------------------ CREATE OPERATOR CLASS Name CREATE OPERATOR CLASS -- define a new operator class Synopsis CREATE OPERATOR CLASS name [ DEFAULT ] FOR TYPE data_type USING index_method [ FAMILY family_name ] AS { OPERATOR strategy_number operator_name [ ( op_type, op_type ) ] [ RECHECK ] | FUNCTION support_number [ ( op_type [ , op_type ] ) ] funcname ( argument_type [, ...] ) | STORAGE storage_type } [, ... ] Description CREATE OPERATOR CLASS creates a new operator class. An operator class defines how a particular data type can be used with an index. The operator class specifies that certain operators will fill particular roles or "strategies" for this data type and this index method. The operator class also specifies the support procedures to be used by the index method when the operator class is selected for an index column. All the operators and functions used by an operator class must be defined before the operator class can be created. If a schema name is given then the operator class is created in the specified schema. Otherwise it is created in the current schema. Two operator classes in the same schema can have the same name only if they are for different index methods. The user who defines an operator class becomes its owner. Presently, the creating user must be a superuser. (This restriction is made because an erroneous operator class definition could confuse or even crash the server.) CREATE OPERATOR CLASS does not presently check whether the operator class definition includes all the operators and functions required by the index method, nor whether the operators and functions form a self-consistent set. It is the user's responsibility to define a valid operator class. Related operator classes can be grouped into operator families. To add a new operator class to an existing family, specify the FAMILY option in CREATE OPERATOR CLASS. Without this option, the new class is placed into a family named the same as the new class (creating that family if it doesn't already exist). Refer to Section_34.14 for further information. Parameters name The name of the operator class to be created. The name can be schema- qualified. DEFAULT If present, the operator class will become the default operator class for its data type. At most one operator class can be the default for a specific data type and index method. data_type The column data type that this operator class is for. index_method The name of the index method this operator class is for. family_name The name of the existing operator family to add this operator class to. If not specified, a family named the same as the operator class is used (creating it, if it doesn't already exist). strategy_number The index method's strategy number for an operator associated with the operator class. operator_name The name (optionally schema-qualified) of an operator associated with the operator class. op_type In an OPERATOR clause, the operand data type(s) of the operator, or NONE to signify a left-unary or right-unary operator. The operand data types can be omitted in the normal case where they are the same as the operator class's data type. In a FUNCTION clause, the operand data type(s) the function is intended to support, if different from the input data type(s) of the function (for B-tree and hash indexes) or the class's data type (for GIN and GiST indexes). These defaults are always correct, so there is no point in specifying op_type in a FUNCTION clause in CREATE OPERATOR CLASS, but the option is provided for consistency with the comparable syntax in ALTER OPERATOR FAMILY. RECHECK If present, the index is "lossy" for this operator, and so the rows retrieved using the index must be rechecked to verify that they actually satisfy the qualification clause involving this operator. support_number The index method's support procedure number for a function associated with the operator class. funcname The name (optionally schema-qualified) of a function that is an index method support procedure for the operator class. argument_types The parameter data type(s) of the function. storage_type The data type actually stored in the index. Normally this is the same as the column data type, but some index methods (currently GIN and GiST) allow it to be different. The STORAGE clause must be omitted unless the index method allows a different type to be used. The OPERATOR, FUNCTION, and STORAGE clauses can appear in any order. Notes Because the index machinery does not check access permissions on functions before using them, including a function or operator in an operator class is tantamount to granting public execute permission on it. This is usually not an issue for the sorts of functions that are useful in an operator class. The operators should not be defined by SQL functions. A SQL function is likely to be inlined into the calling query, which will prevent the optimizer from recognizing that the query matches an index. Examples The following example command defines a GiST index operator class for the data type _int4 (array of int4). See contrib/intarray/ for the complete example. CREATE OPERATOR CLASS gist__int_ops DEFAULT FOR TYPE _int4 USING gist AS OPERATOR 3 &&, OPERATOR 6 = RECHECK, OPERATOR 7 @>, OPERATOR 8 <@, OPERATOR 20 @@ (_int4, query_int), FUNCTION 1 g_int_consistent (internal, _int4, int4), FUNCTION 2 g_int_union (bytea, internal), FUNCTION 3 g_int_compress (internal), FUNCTION 4 g_int_decompress (internal), FUNCTION 5 g_int_penalty (internal, internal, internal), FUNCTION 6 g_int_picksplit (internal, internal), FUNCTION 7 g_int_same (_int4, _int4, internal); Compatibility CREATE OPERATOR CLASS is a PostgreSQL extension. There is no CREATE OPERATOR CLASS statement in the SQL standard. See Also ALTER_OPERATOR_CLASS, DROP_OPERATOR_CLASS, CREATE_OPERATOR_FAMILY, ALTER OPERATOR_FAMILY ------------------------------------------------------------------------ CREATE OPERATOR FAMILY Name CREATE OPERATOR FAMILY -- define a new operator family Synopsis CREATE OPERATOR FAMILY name USING index_method Description CREATE OPERATOR FAMILY creates a new operator family. An operator family defines a collection of related operator classes, and perhaps some additional operators and support functions that are compatible with these operator classes but not essential for the functioning of any individual index. (Operators and functions that are essential to indexes should be grouped within the relevant operator class, rather than being "loose" in the operator family. Typically, single-data-type operators are bound to operator classes, while cross-data-type operators can be loose in an operator family containing operator classes for both data types.) The new operator family is initially empty. It should be populated by issuing subsequent CREATE OPERATOR CLASS commands to add contained operator classes, and optionally ALTER OPERATOR FAMILY commands to add "loose" operators and their corresponding support functions. If a schema name is given then the operator family is created in the specified schema. Otherwise it is created in the current schema. Two operator families in the same schema can have the same name only if they are for different index methods. The user who defines an operator family becomes its owner. Presently, the creating user must be a superuser. (This restriction is made because an erroneous operator family definition could confuse or even crash the server.) Refer to Section_34.14 for further information. Parameters name The name of the operator family to be created. The name can be schema-qualified. index_method The name of the index method this operator family is for. Compatibility CREATE OPERATOR FAMILY is a PostgreSQL extension. There is no CREATE OPERATOR FAMILY statement in the SQL standard. See Also ALTER_OPERATOR_FAMILY, DROP_OPERATOR_FAMILY, CREATE_OPERATOR_CLASS, ALTER OPERATOR_CLASS, DROP_OPERATOR_CLASS ------------------------------------------------------------------------ CREATE ROLE Name CREATE ROLE -- define a new database role Synopsis CREATE ROLE name [ [ WITH ] option [ ... ] ] where option can be: SUPERUSER | NOSUPERUSER | CREATEDB | NOCREATEDB | CREATEROLE | NOCREATEROLE | CREATEUSER | NOCREATEUSER | INHERIT | NOINHERIT | LOGIN | NOLOGIN | CONNECTION LIMIT connlimit | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' | VALID UNTIL 'timestamp' | IN ROLE rolename [, ...] | IN GROUP rolename [, ...] | ROLE rolename [, ...] | ADMIN rolename [, ...] | USER rolename [, ...] | SYSID uid Description CREATE ROLE adds a new role to a PostgreSQL database cluster. A role is an entity that can own database objects and have database privileges; a role can be considered a "user", a "group", or both depending on how it is used. Refer to Chapter_19 and Chapter_21 for information about managing users and authentication. You must have CREATEROLE privilege or be a database superuser to use this command. Note that roles are defined at the database cluster level, and so are valid in all databases in the cluster. Parameters name The name of the new role. SUPERUSER NOSUPERUSER These clauses determine whether the new role is a "superuser", who can override all access restrictions within the database. Superuser status is dangerous and should be used only when really needed. You must yourself be a superuser to create a new superuser. If not specified, NOSUPERUSER is the default. CREATEDB NOCREATEDB These clauses define a role's ability to create databases. If CREATEDB is specified, the role being defined will be allowed to create new databases. Specifying NOCREATEDB will deny a role the ability to create databases. If not specified, NOCREATEDB is the default. CREATEROLE NOCREATEROLE These clauses determine whether a role will be permitted to create new roles (that is, execute CREATE ROLE). A role with CREATEROLE privilege can also alter and drop other roles. If not specified, NOCREATEROLE is the default. CREATEUSER NOCREATEUSER These clauses are an obsolete, but still accepted, spelling of SUPERUSER and NOSUPERUSER. Note that they are not equivalent to CREATEROLE as one might naively expect! INHERIT NOINHERIT These clauses determine whether a role "inherits" the privileges of roles it is a member of. A role with the INHERIT attribute can automatically use whatever database privileges have been granted to all roles it is directly or indirectly a member of. Without INHERIT, membership in another role only grants the ability to SET ROLE to that other role; the privileges of the other role are only available after having done so. If not specified, INHERIT is the default. LOGIN NOLOGIN These clauses determine whether a role is allowed to log in; that is, whether the role can be given as the initial session authorization name during client connection. A role having the LOGIN attribute can be thought of as a user. Roles without this attribute are useful for managing database privileges, but are not users in the usual sense of the word. If not specified, NOLOGIN is the default, except when CREATE ROLE is invoked through its alternative spelling CREATE USER. CONNECTION LIMIT connlimit If role can log in, this specifies how many concurrent connections the role can make. -1 (the default) means no limit. PASSWORD password Sets the role's password. (A password is only of use for roles having the LOGIN attribute, but you can nonetheless define one for roles without it.) If you do not plan to use password authentication you can omit this option. If no password is specified, the password will be set to null and password authentication will always fail for that user. A null password can optionally be written explicitly as PASSWORD NULL. ENCRYPTED UNENCRYPTED 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 password_encryption.) If the presented password string is already in MD5-encrypted format, then it is stored encrypted as-is, regardless of whether ENCRYPTED or UNENCRYPTED is specified (since the system cannot decrypt the specified encrypted password string). This allows reloading of encrypted passwords during dump/restore. Note that older clients might lack support for the MD5 authentication mechanism that is needed to work with passwords that are stored encrypted. VALID UNTIL 'timestamp' The VALID UNTIL clause sets a date and time after which the role's password is no longer valid. If this clause is omitted the password will be valid for all time. IN ROLE rolename The IN ROLE clause lists one or more existing roles to which the new role will be immediately added as a new member. (Note that there is no option to add the new role as an administrator; use a separate GRANT command to do that.) IN GROUP rolename IN GROUP is an obsolete spelling of IN ROLE. ROLE rolename The ROLE clause lists one or more existing roles which are automatically added as members of the new role. (This in effect makes the new role a "group".) ADMIN rolename The ADMIN clause is like ROLE, but the named roles are added to the new role WITH ADMIN OPTION, giving them the right to grant membership in this role to others. USER rolename The USER clause is an obsolete spelling of the ROLE clause. SYSID uid The SYSID clause is ignored, but is accepted for backwards compatibility. Notes Use ALTER_ROLE to change the attributes of a role, and DROP_ROLE to remove a role. All the attributes specified by CREATE ROLE can be modified by later ALTER ROLE commands. The preferred way to add and remove members of roles that are being used as groups is to use GRANT and REVOKE. The VALID UNTIL clause defines an expiration time for a password only, not for the role per se. In particular, the expiration time is not enforced when logging in using a non-password-based authentication method. The INHERIT attribute governs inheritance of grantable privileges (that is, access privileges for database objects and role memberships). It does not apply to the special role attributes set by CREATE ROLE and ALTER ROLE. For example, being a member of a role with CREATEDB privilege does not immediately grant the ability to create databases, even if INHERIT is set; it would be necessary to become that role via SET_ROLE before creating a database. The INHERIT attribute is the default for reasons of backwards compatibility: in prior releases of PostgreSQL, users always had access to all privileges of groups they were members of. However, NOINHERIT provides a closer match to the semantics specified in the SQL standard. Be careful with the CREATEROLE privilege. There is no concept of inheritance for the privileges of a CREATEROLE-role. That means that even if a role does not have a certain privilege but is allowed to create other roles, it can easily create another role with different privileges than its own (except for creating roles with superuser privileges). For example, if the role "user" has the CREATEROLE privilege but not the CREATEDB privilege, nonetheless it can create a new role with the CREATEDB privilege. Therefore, regard roles that have the CREATEROLE privilege as almost-superuser-roles. PostgreSQL includes a program createuser that has the same functionality as CREATE ROLE (in fact, it calls this command) but can be run from the command shell. The CONNECTION LIMIT option is only enforced approximately; if two new sessions start at about the same time when just one connection "slot" remains for the role, it is possible that both will fail. Also, the limit is never enforced for superusers. Caution must be exercised when specifying an unencrypted password with this command. The password will be transmitted to the server in cleartext, and it might also be logged in the client's command history or the server log. The command createuser, however, transmits the password encrypted. Also, psql contains a command \password that can be used to safely change the password later. Examples Create a role that can log in, but don't give it a password: CREATE ROLE jonathan LOGIN; Create a role with a password: CREATE USER davide WITH PASSWORD 'jw8s0F4'; (CREATE USER is the same as CREATE ROLE except that it implies LOGIN.) Create a role with a password that is valid until the end of 2004. After one second has ticked in 2005, the password is no longer valid. CREATE ROLE miriam WITH LOGIN PASSWORD 'jw8s0F4' VALID UNTIL '2005-01- 01'; Create a role that can create databases and manage roles: CREATE ROLE admin WITH CREATEDB CREATEROLE; Compatibility The CREATE ROLE statement is in the SQL standard, but the standard only requires the syntax CREATE ROLE name [ WITH ADMIN rolename ] Multiple initial administrators, and all the other options of CREATE ROLE, are PostgreSQL extensions. The SQL standard defines the concepts of users and roles, but it regards them as distinct concepts and leaves all commands defining users to be specified by each database implementation. In PostgreSQL we have chosen to unify users and roles into a single kind of entity. Roles therefore have many more optional attributes than they do in the standard. The behavior specified by the SQL standard is most closely approximated by giving users the NOINHERIT attribute, while roles are given the INHERIT attribute. See Also SET_ROLE, ALTER_ROLE, DROP_ROLE, GRANT, REVOKE, createuser ------------------------------------------------------------------------ CREATE RULE Name CREATE RULE -- define a new rewrite rule Synopsis CREATE [ OR REPLACE ] RULE name AS ON event TO table [ WHERE condition ] DO [ ALSO | INSTEAD ] { NOTHING | command | ( command ; command ... ) } Description CREATE RULE defines a new rule applying to a specified table or view. CREATE OR REPLACE RULE will either create a new rule, or replace an existing rule of the same name for the same table. The PostgreSQL rule system allows one to define an alternative action to be performed on insertions, updates, or deletions in database tables. Roughly speaking, a rule causes additional commands to be executed when a given command on a given table is executed. Alternatively, an INSTEAD rule can replace a given command by another, or cause a command not to be executed at all. Rules are used to implement table views as well. It is important to realize that a rule is really a command transformation mechanism, or command macro. The transformation happens before the execution of the commands starts. If you actually want an operation that fires independently for each physical row, you probably want to use a trigger, not a rule. More information about the rules system is in Chapter_36. Presently, ON SELECT rules must be unconditional INSTEAD rules and must have actions that consist of a single SELECT command. Thus, an ON SELECT rule effectively turns the table into a view, whose visible contents are the rows returned by the rule's SELECT command rather than whatever had been stored in the table (if anything). It is considered better style to write a CREATE VIEW command than to create a real table and define an ON SELECT rule for it. You can create the illusion of an updatable view by defining ON INSERT, ON UPDATE, and ON DELETE rules (or any subset of those that's sufficient for your purposes) to replace update actions on the view with appropriate updates on other tables. If you want to support INSERT RETURNING and so on, then be sure to put a suitable RETURNING clause into each of these rules. There is a catch if you try to use conditional rules for view updates: there must be an unconditional INSTEAD rule for each action you wish to allow on the view. If the rule is conditional, or is not INSTEAD, then the system will still reject 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, add an unconditional DO INSTEAD NOTHING rule to ensure that the system understands it will never be called on to update the dummy table. Then make the conditional rules non-INSTEAD; in the cases where they are applied, they add to the default INSTEAD NOTHING action. (This method does not currently work to support RETURNING queries, however.) Parameters name The name of a rule to create. This must be distinct from the name of any other rule for the same table. Multiple rules on the same table and same event type are applied in alphabetical name order. event The event is one of SELECT, INSERT, UPDATE, or DELETE. table The name (optionally schema-qualified) of the table or view the rule applies to. condition Any SQL conditional expression (returning boolean). The condition expression cannot refer to any tables except NEW and OLD, and cannot contain aggregate functions. INSTEAD INSTEAD indicates that the commands should be executed instead of the original command. ALSO ALSO indicates that the commands should be executed in addition to the original command. If neither ALSO nor INSTEAD is specified, ALSO is the default. command The command or commands that make up the rule action. Valid commands are SELECT, INSERT, UPDATE, DELETE, or NOTIFY. Within condition and command, the special table names NEW and OLD can be used to refer to values in the referenced table. NEW is valid in ON INSERT and ON UPDATE rules to refer to the new row being inserted or updated. OLD is valid in ON UPDATE and ON DELETE rules to refer to the existing row being updated or deleted. Notes You must be the owner of a table to create or change rules for it. In a rule for INSERT, UPDATE, or DELETE on a view, you can add a RETURNING clause that emits the view's columns. This clause will be used to compute the outputs if the rule is triggered by an INSERT RETURNING, UPDATE RETURNING, or DELETE RETURNING command respectively. When the rule is triggered by a command without RETURNING, the rule's RETURNING clause will be ignored. The current implementation allows only unconditional INSTEAD rules to contain RETURNING; furthermore there can be at most one RETURNING clause among all the rules for the same event. (This ensures that there is only one candidate RETURNING clause to be used to compute the results.) RETURNING queries on the view will be rejected if there is no RETURNING clause in any available rule. It is very important to take care to avoid circular rules. For example, though each of the following two rule definitions are accepted by PostgreSQL, the SELECT command would cause PostgreSQL to report an error because of recursive expansion of a rule: CREATE RULE "_RETURN" AS ON SELECT TO t1 DO INSTEAD SELECT * FROM t2; CREATE RULE "_RETURN" AS ON SELECT TO t2 DO INSTEAD SELECT * FROM t1; SELECT * FROM t1; Presently, if a rule action contains a NOTIFY command, the NOTIFY command will be executed unconditionally, that is, the NOTIFY will be issued even if there are not any rows that the rule should apply to. For example, in: CREATE RULE notify_me AS ON UPDATE TO mytable DO ALSO NOTIFY mytable; UPDATE mytable SET name = 'foo' WHERE id = 42; one NOTIFY event will be sent during the UPDATE, whether or not there are any rows that match the condition id = 42. This is an implementation restriction that might be fixed in future releases. Compatibility CREATE RULE is a PostgreSQL language extension, as is the entire query rewrite system. ------------------------------------------------------------------------ CREATE SCHEMA Name CREATE SCHEMA -- define a new schema Synopsis CREATE SCHEMA schemaname [ AUTHORIZATION username ] [ schema_element [ ... ] ] CREATE SCHEMA AUTHORIZATION username [ schema_element [ ... ] ] Description CREATE SCHEMA 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. A schema is essentially a namespace: it contains named objects (tables, data types, functions, and operators) whose names can duplicate those of other objects existing in other schemas. Named objects are accessed either by "qualifying" their names with the schema name as a prefix, or by setting a search path that includes the desired schema(s). A 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 current_schema). Optionally, CREATE SCHEMA can include subcommands to create objects within the new schema. The subcommands are treated essentially the same as separate commands issued after creating the schema, except that if the AUTHORIZATION clause is used, all the created objects will be owned by that user. Parameters schemaname The name of a schema to be created. If this is omitted, the user name is used as the schema name. The name cannot begin with pg_, as such names are reserved for system schemas. username The name of the user who will own the schema. If omitted, defaults to the user executing the command. Only superusers can create schemas owned by users other than themselves. schema_element An SQL statement defining an object to be created within the schema. Currently, only CREATE TABLE, CREATE VIEW, CREATE INDEX, CREATE SEQUENCE, CREATE TRIGGER and GRANT are accepted as clauses within CREATE SCHEMA. Other kinds of objects may be created in separate commands after the schema is created. Notes To create a schema, the invoking user must have the CREATE privilege for the current database. (Of course, superusers bypass this check.) Examples Create a schema: CREATE SCHEMA myschema; Create a schema for user joe; the schema will also be named joe: CREATE SCHEMA AUTHORIZATION joe; Create a schema and create a table and view within it: CREATE SCHEMA hollywood CREATE TABLE films (title text, release date, awards text[]) CREATE VIEW winners AS SELECT title, release FROM films WHERE awards IS NOT NULL; Notice that the individual subcommands do not end with semicolons. The following is an equivalent way of accomplishing the same result: CREATE SCHEMA hollywood; CREATE TABLE hollywood.films (title text, release date, awards text[]); CREATE VIEW hollywood.winners AS SELECT title, release FROM hollywood.films WHERE awards IS NOT NULL; Compatibility The SQL standard allows a DEFAULT CHARACTER SET clause in CREATE SCHEMA, as well as more subcommand types than are presently accepted by PostgreSQL. The SQL standard specifies that the subcommands in CREATE SCHEMA can appear in any order. The present PostgreSQL implementation does not handle all cases of forward references in subcommands; it might sometimes be necessary to reorder the subcommands in order to avoid forward references. According to the SQL standard, the owner of a schema always owns all objects within it. PostgreSQL allows schemas to contain objects owned by users other than the schema owner. This can happen only if the schema owner grants the CREATE privilege on his schema to someone else. See Also ALTER_SCHEMA, DROP_SCHEMA ------------------------------------------------------------------------ CREATE SEQUENCE Name CREATE SEQUENCE -- define a new sequence generator Synopsis CREATE [ TEMPORARY | TEMP ] SEQUENCE name [ INCREMENT [ BY ] increment ] [ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ] [ START [ WITH ] start ] [ CACHE cache ] [ [ NO ] CYCLE ] [ OWNED BY { table.column | NONE } ] Description CREATE SEQUENCE creates a new sequence number generator. This involves creating and initializing a new special single-row table with the name name. The generator will be owned by the user issuing the command. If a schema name is given then the sequence is created in the specified schema. Otherwise it is created in the current schema. Temporary sequences exist in a special schema, so a schema name cannot be given when creating a temporary sequence. The sequence name must be distinct from the name of any other sequence, table, index, or view in the same schema. After a sequence is created, you use the functions nextval, currval, and setval to operate on the sequence. These functions are documented in Section_9.15. Although you cannot update a sequence directly, you can use a query like: SELECT * FROM name; to examine the parameters and current state of a sequence. In particular, the last_value field of the sequence shows the last value allocated by any session. (Of course, this value might be obsolete by the time it's printed, if other sessions are actively doing nextval calls.) Parameters TEMPORARY or TEMP If specified, the sequence object is created only for this session, and is automatically dropped on session exit. Existing permanent sequences with the same name are not visible (in this session) while the temporary sequence exists, unless they are referenced with schema-qualified names. name The name (optionally schema-qualified) of the sequence to be created. increment The optional clause INCREMENT BY increment specifies which value is added to the current sequence value to create a new value. A positive value will make an ascending sequence, a negative one a descending sequence. The default value is 1. minvalue NO MINVALUE The optional clause MINVALUE minvalue determines the minimum value a sequence can generate. If this clause is not supplied or NO MINVALUE is specified, then defaults will be used. The defaults are 1 and - 263-1 for ascending and descending sequences, respectively. maxvalue NO MAXVALUE The optional clause MAXVALUE maxvalue determines the maximum value for the sequence. If this clause is not supplied or NO MAXVALUE is specified, then default values will be used. The defaults are 263- 1 and -1 for ascending and descending sequences, respectively. start The optional clause START WITH start allows the sequence to begin anywhere. The default starting value is minvalue for ascending sequences and maxvalue for descending ones. cache The optional clause CACHE cache specifies how many sequence numbers are to be preallocated and stored in memory for faster access. The minimum value is 1 (only one value can be generated at a time, i.e., no cache), and this is also the default. CYCLE NO CYCLE The CYCLE option allows the sequence to wrap around when the maxvalue or minvalue has been reached by an ascending or descending sequence respectively. If the limit is reached, the next number generated will be the minvalue or maxvalue, respectively. If NO CYCLE is specified, any calls to nextval after the sequence has reached its maximum value will return an error. If neither CYCLE or NO CYCLE are specified, NO CYCLE is the default. OWNED BY table.column OWNED BY NONE The OWNED BY option causes the sequence to be associated with a specific table column, such that if that column (or its whole table) is dropped, the sequence will be automatically dropped as well. The specified table must have the same owner and be in the same schema as the sequence. OWNED BY NONE, the default, specifies that there is no such association. Notes Use DROP SEQUENCE to remove a sequence. Sequences are based on bigint arithmetic, so the range cannot exceed the range of an eight-byte integer (-9223372036854775808 to 9223372036854775807). On some older platforms, there might be no compiler support for eight-byte integers, in which case sequences use regular integer arithmetic (range -2147483648 to +2147483647). Unexpected results might be obtained if a cache setting greater than one is used for a sequence object that will be used concurrently by multiple sessions. Each session will allocate and cache successive sequence values during one access to the sequence object and increase the sequence object's last_value accordingly. Then, the next cache-1 uses of nextval within that session simply return the preallocated values without touching the sequence object. So, any numbers allocated but not used within a session will be lost when that session ends, resulting in "holes" in the sequence. Furthermore, although multiple sessions are guaranteed to allocate distinct sequence values, the values might be generated out of sequence when all the sessions are considered. For example, with a cache setting of 10, session A might reserve values 1..10 and return nextval=1, then session B might reserve values 11..20 and return nextval=11 before session A has generated nextval=2. Thus, with a cache setting of one it is safe to assume that nextval values are generated sequentially; with a cache setting greater than one you should only assume that the nextval values are all distinct, not that they are generated purely sequentially. Also, last_value will reflect the latest value reserved by any session, whether or not it has yet been returned by nextval. Another consideration is that a setval executed on such a sequence will not be noticed by other sessions until they have used up any preallocated values they have cached. Examples Create an ascending sequence called serial, starting at 101: CREATE SEQUENCE serial START 101; Select the next number from this sequence: SELECT nextval('serial'); nextval --------- 101 Select the next number from this sequence: SELECT nextval('serial'); nextval --------- 102 Use this sequence in an INSERT command: INSERT INTO distributors VALUES (nextval('serial'), 'nothing'); Update the sequence value after a COPY FROM: BEGIN; COPY distributors FROM 'input_file'; SELECT setval('serial', max(id)) FROM distributors; END; Compatibility CREATE SEQUENCE conforms to the SQL standard, with the following exceptions: * The standard's AS expression is not supported. * Obtaining the next value is done using the nextval() function instead of the standard's NEXT VALUE FOR expression. * The OWNED BY clause is a PostgreSQL extension. See Also ALTER_SEQUENCE, DROP_SEQUENCE ------------------------------------------------------------------------ CREATE TABLE Name CREATE TABLE -- define a new table Synopsis CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE table_name ( [ { column_name data_type [ DEFAULT default_expr ] [ column_constraint [ ... ] ] | table_constraint | LIKE parent_table [ { INCLUDING | EXCLUDING } { DEFAULTS | CONSTRAINTS | INDEXES } ] ... } [, ... ] ] ) [ INHERITS ( parent_table [, ... ] ) ] [ WITH ( storage_parameter [= value] [, ... ] ) | WITH OIDS | WITHOUT OIDS ] [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE tablespace ] where column_constraint is: [ CONSTRAINT constraint_name ] { NOT NULL | NULL | UNIQUE index_parameters | PRIMARY KEY index_parameters | CHECK ( expression ) | REFERENCES reftable [ ( refcolumn ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE action ] [ ON UPDATE action ] } [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] and table_constraint is: [ CONSTRAINT constraint_name ] { UNIQUE ( column_name [, ... ] ) index_parameters | PRIMARY KEY ( column_name [, ... ] ) index_parameters | CHECK ( expression ) | FOREIGN KEY ( column_name [, ... ] ) REFERENCES reftable [ ( refcolumn [, ... ] ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE action ] [ ON UPDATE action ] } [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] index_parameters in UNIQUE and PRIMARY KEY constraints are: [ WITH ( storage_parameter [= value] [, ... ] ) ] [ USING INDEX TABLESPACE tablespace ] Description CREATE TABLE will create a new, initially empty table in the current database. The table will be owned by the user issuing the command. If a schema name is given (for example, CREATE TABLE myschema.mytable ...) then the table is created in the specified schema. Otherwise it is created in the current schema. Temporary tables exist in a special schema, so a schema name cannot be given when creating a temporary table. The name of the table must be distinct from the name of any other table, sequence, index, or view in the same schema. CREATE TABLE also automatically creates a data type that represents the composite type corresponding to one row of the table. Therefore, tables cannot have the same name as any existing data type in the same schema. 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. There are two ways to define constraints: table constraints and column constraints. A column constraint is defined as part of a 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 for use when the constraint only affects one column. Parameters NO ACTION Produce an error indicating that the deletion or update would create a foreign key constraint violation. If the constraint is deferred, this error will be produced at constraint check time if there still exist any referencing rows. This is the default action. RESTRICT Produce an error indicating that the deletion or update would create a foreign key constraint violation. This is the same as NO ACTION except that the check is not deferrable. CASCADE Delete any rows referencing the deleted row, or update the value of the referencing column to the new value of the referenced column, respectively. SET NULL Set the referencing column(s) to null. SET DEFAULT Set the referencing column(s) to their default values. If the referenced column(s) are changed frequently, it might be wise to add an index to the foreign key column so that referential actions associated with the foreign key column can be performed more efficiently. DEFERRABLE NOT DEFERRABLE This controls whether the constraint can be deferred. A constraint that is not deferrable will be checked immediately after every command. Checking of constraints that are deferrable can be postponed until the end of the transaction (using the SET_CONSTRAINTS command). NOT DEFERRABLE is the default. Only foreign key constraints currently accept this clause. All other constraint types are not deferrable. INITIALLY IMMEDIATE INITIALLY DEFERRED If a constraint is deferrable, this clause specifies the default time to check the constraint. If the constraint is INITIALLY IMMEDIATE, it is checked after each statement. This is the default. If the constraint is INITIALLY DEFERRED, it is checked only at the end of the transaction. The constraint check time can be altered with the SET_CONSTRAINTS command. WITH ( storage_parameter [= value] [, ... ] ) This clause specifies optional storage parameters for a table or index; see Storage_Parameters for more information. The WITH clause for a table can also include OIDS=TRUE (or just OIDS) to specify that rows of the new table should have OIDs (object identifiers) assigned to them, or OIDS=FALSE to specify that the rows should not have OIDs. If OIDS is not specified, the default setting depends upon the default_with_oids configuration parameter. (If the new table inherits from any tables that have OIDs, then OIDS=TRUE is forced even if the command says OIDS=FALSE.) If OIDS=FALSE 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 to store the table on disk by 4 bytes per row (on most machines), slightly improving performance. To remove OIDs from a table after it has been created, use ALTER_TABLE. WITH OIDS WITHOUT OIDS These are obsolescent syntaxes equivalent to WITH (OIDS) and WITH (OIDS=FALSE), respectively. If you wish to give both an OIDS setting and storage parameters, you must use the WITH ( ... ) syntax; see above. ON COMMIT The behavior of temporary tables at the end of a transaction block can be controlled using ON COMMIT. The three options are: PRESERVE ROWS No special action is taken at the ends of transactions. This is the default behavior. DELETE ROWS All rows in the temporary table will be deleted at the end of each transaction block. Essentially, an automatic TRUNCATE is done at each commit. DROP The temporary table will be dropped at the end of the current transaction block. TABLESPACE tablespace The tablespace is the name of the tablespace in which the new table is to be created. If not specified, default_tablespace is consulted, or temp_tablespaces if the table is temporary. USING INDEX TABLESPACE tablespace This clause allows selection of the tablespace in which the index associated with a UNIQUE or PRIMARY KEY constraint will be created. If not specified, default_tablespace is consulted, or temp_tablespaces if the table is temporary. Storage Parameters The WITH clause can specify storage parameters for tables, and for indexes associated with a UNIQUE or PRIMARY KEY constraint. Storage parameters for indexes are documented in CREATE_INDEX. The only storage parameter currently available for tables is: FILLFACTOR The fillfactor for a table is a percentage between 10 and 100. 100 (complete packing) is the default. When a smaller fillfactor is specified, INSERT operations pack table pages only to the indicated percentage; the remaining space on each page is reserved for updating rows on that page. This gives UPDATE a chance to place the updated copy of a row on the same page as the original, which is more efficient than placing it on a different page. For a table whose entries are never updated, complete packing is the best choice, but in heavily updated tables smaller fillfactors are appropriate. Notes Using OIDs in new applications is not recommended: where possible, using a SERIAL 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 of a table, it is recommended to create a unique constraint on the oid column of that table, to ensure that OIDs in the table will indeed uniquely identify rows even after counter wraparound. Avoid assuming that OIDs are unique across tables; if you need a database-wide unique identifier, use the combination of tableoid and row OID for the purpose. Tip: The use of OIDS=FALSE is not recommended for tables with no primary key, since without either an OID or a unique data key, it is difficult to identify specific rows. PostgreSQL automatically creates an index for each unique constraint and primary key constraint to enforce uniqueness. Thus, it is not necessary to create an index explicitly for primary key columns. (See CREATE_INDEX for more information.) Unique constraints and primary keys are not inherited in the current implementation. This makes the combination of inheritance and unique constraints rather dysfunctional. A table cannot have more than 1600 columns. (In practice, the effective limit is usually lower because of tuple-length constraints.) Examples Create table films and table distributors: CREATE TABLE films ( code char(5) CONSTRAINT firstkey PRIMARY KEY, title varchar(40) NOT NULL, did integer NOT NULL, date_prod date, kind varchar(10), len interval hour to minute ); CREATE TABLE distributors ( did integer PRIMARY KEY DEFAULT nextval('serial'), name varchar(40) NOT NULL CHECK (name <> '') ); Create a table with a 2-dimensional array: CREATE TABLE array_int ( vector int[][] ); Define a unique table constraint for the table films. Unique table constraints can be defined on one or more columns of the table: CREATE TABLE films ( code char(5), title varchar(40), did integer, date_prod date, kind varchar(10), len interval hour to minute, CONSTRAINT production UNIQUE(date_prod) ); Define a check column constraint: CREATE TABLE distributors ( did integer CHECK (did > 100), name varchar(40) ); Define a check table constraint: CREATE TABLE distributors ( did integer, name varchar(40) CONSTRAINT con1 CHECK (did > 100 AND name <> '') ); Define a primary key table constraint for the table films: CREATE TABLE films ( code char(5), title varchar(40), did integer, date_prod date, kind varchar(10), len interval hour to minute, CONSTRAINT code_title PRIMARY KEY(code,title) ); Define a primary key constraint for table distributors. The following two examples are equivalent, the first using the table constraint syntax, the second the column constraint syntax: CREATE TABLE distributors ( did integer, name varchar(40), PRIMARY KEY(did) ); CREATE TABLE distributors ( did integer PRIMARY KEY, name varchar(40) ); Assign a literal constant default value for the column name, arrange for the default value of column did to be generated by selecting the next value of a sequence object, and make the default value of modtime be the time at which the row is inserted: CREATE TABLE distributors ( name varchar(40) DEFAULT 'Luso Films', did integer DEFAULT nextval('distributors_serial'), modtime timestamp DEFAULT current_timestamp ); Define two NOT NULL column constraints on the table distributors, one of which is explicitly given a name: CREATE TABLE distributors ( did integer CONSTRAINT no_null NOT NULL, name varchar(40) NOT NULL ); Define a unique constraint for the name column: CREATE TABLE distributors ( did integer, name varchar(40) UNIQUE ); The same, specified as a table constraint: CREATE TABLE distributors ( did integer, name varchar(40), UNIQUE(name) ); Create the same table, specifying 70% fill factor for both the table and its unique index: CREATE TABLE distributors ( did integer, name varchar(40), UNIQUE(name) WITH (fillfactor=70) ) WITH (fillfactor=70); Create table cinemas in tablespace diskvol1: CREATE TABLE cinemas ( id serial, name text, location text ) TABLESPACE diskvol1; Compatibility The CREATE TABLE command conforms to the SQL standard, with exceptions listed below. Temporary Tables Although the syntax of CREATE TEMPORARY TABLE resembles that of the SQL standard, the effect is not the same. In the standard, temporary tables are defined just once and automatically exist (starting with empty contents) in every session that needs them. PostgreSQL instead requires each session to issue its own CREATE TEMPORARY TABLE command for each temporary table to be used. This allows different sessions to use the same temporary table name for different purposes, whereas the standard's approach constrains all instances of a given temporary table name to have the same table structure. The standard's definition of the behavior of temporary tables is widely ignored. PostgreSQL's behavior on this point is similar to that of several other SQL databases. The standard's distinction between global and local temporary tables is not in PostgreSQL, since that distinction depends on the concept of modules, which PostgreSQL does not have. For compatibility's sake, PostgreSQL will accept the GLOBAL and LOCAL keywords in a temporary table declaration, but they have no effect. The ON COMMIT clause for temporary tables also resembles the SQL standard, but has some differences. If the ON COMMIT clause is omitted, SQL specifies that the default behavior is ON COMMIT DELETE ROWS. However, the default behavior in PostgreSQL is ON COMMIT PRESERVE ROWS. The ON COMMIT DROP option does not exist in SQL. Column Check Constraints The SQL standard says that CHECK column constraints can only refer to the column they apply to; only CHECK table constraints can refer to multiple columns. PostgreSQL does not enforce this restriction; it treats column and table check constraints alike. NULL "Constraint" The NULL "constraint" (actually a non-constraint) is a PostgreSQL extension to the SQL standard that is included for compatibility with some other database systems (and for symmetry with the NOT NULL constraint). Since it is the default for any column, its presence is simply noise. Inheritance Multiple inheritance via the INHERITS clause is a PostgreSQL language extension. SQL:1999 and later define single inheritance using a different syntax and different semantics. SQL:1999-style inheritance is not yet supported by PostgreSQL. Zero-column tables PostgreSQL allows a table of no columns to be created (for example, CREATE TABLE foo();). This is an extension from the SQL standard, which does not allow zero-column tables. Zero-column tables are not in themselves very useful, but disallowing them creates odd special cases for ALTER TABLE DROP COLUMN, so it seems cleaner to ignore this spec restriction. WITH clause The WITH clause is a PostgreSQL extension; neither storage parameters nor OIDs are in the standard. Tablespaces The PostgreSQL concept of tablespaces is not part of the standard. Hence, the clauses TABLESPACE and USING INDEX TABLESPACE are extensions. See Also ALTER_TABLE, DROP_TABLE, CREATE_TABLESPACE ------------------------------------------------------------------------ CREATE TABLE AS Name CREATE TABLE AS -- define a new table from the results of a query Synopsis CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE table_name [ (column_name [, ...] ) ] [ WITH ( storage_parameter [= value] [, ... ] ) | WITH OIDS | WITHOUT OIDS ] [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE tablespace ] AS query Description CREATE TABLE AS creates a table and fills it with data computed by a SELECT command. The table columns have the names and data types associated with the output columns of the SELECT (except that you can override the column names by giving an explicit list of new column names). CREATE TABLE AS bears some resemblance to creating a view, but it is really quite different: it creates a new table and evaluates the query just once to fill the new table initially. The new table will not track subsequent changes to the source tables of the query. In contrast, a view re-evaluates its defining SELECT statement whenever it is queried. Parameters GLOBAL or LOCAL Ignored for compatibility. Refer to CREATE_TABLE for details. PRESERVE ROWS No special action is taken at the ends of transactions. This is the default behavior. DELETE ROWS All rows in the temporary table will be deleted at the end of each transaction block. Essentially, an automatic TRUNCATE is done at each commit. DROP The temporary table will be dropped at the end of the current transaction block. TABLESPACE tablespace The tablespace is the name of the tablespace in which the new table is to be created. If not specified, default_tablespace is consulted, or temp_tablespaces if the table is temporary. query A SELECT or VALUES command, or an EXECUTE command that runs a prepared SELECT or VALUES query. Notes This command is functionally similar to SELECT_INTO, but it is preferred since it is less likely to be confused with other uses of the SELECT INTO syntax. Furthermore, CREATE TABLE AS offers a superset of the functionality offered by SELECT INTO. Prior to PostgreSQL 8.0, CREATE TABLE AS always included OIDs in the table it created. As of PostgreSQL 8.0, the CREATE TABLE AS command allows the user to explicitly specify whether OIDs should be included. If the presence of OIDs is not explicitly specified, the default_with_oids configuration variable is used. As of PostgreSQL 8.1, this variable is false by default, so the default behavior is not identical to pre-8.0 releases. Applications that require OIDs in the table created by CREATE TABLE AS should explicitly specify WITH (OIDS) to ensure proper behavior. Examples Create a new table films_recent consisting of only recent entries from the table films: CREATE TABLE films_recent AS SELECT * FROM films WHERE date_prod >= '2002-01-01'; Create a new temporary table films_recent, consisting of only recent entries from the table films, using a prepared statement. The new table has OIDs and will be dropped at commit: PREPARE recentfilms(date) AS SELECT * FROM films WHERE date_prod > $1; CREATE TEMP TABLE films_recent WITH (OIDS) ON COMMIT DROP AS EXECUTE recentfilms('2002-01-01'); Compatibility CREATE TABLE AS conforms to the SQL standard, with the following exceptions: * The standard requires parentheses around the subquery clause; in PostgreSQL, these parentheses are optional. * The standard defines a WITH [ NO ] DATA clause; this is not currently implemented by PostgreSQL. The behavior provided by PostgreSQL is equivalent to the standard's WITH DATA case. WITH NO DATA can be simulated by appending LIMIT 0 to the query. * PostgreSQL handles temporary tables in a way rather different from the standard; see CREATE_TABLE for details. * The WITH clause is a PostgreSQL extension; neither storage parameters nor OIDs are in the standard. * The PostgreSQL concept of tablespaces is not part of the standard. Hence, the clause TABLESPACE is an extension. See Also CREATE_TABLE, EXECUTE, SELECT, SELECT_INTO, VALUES ------------------------------------------------------------------------ CREATE TABLESPACE Name CREATE TABLESPACE -- define a new tablespace Synopsis CREATE TABLESPACE tablespacename [ OWNER username ] LOCATION 'directory' Description CREATE TABLESPACE registers a new cluster-wide tablespace. The tablespace name must be distinct from the name of any existing tablespace in the database cluster. A tablespace allows superusers to define an alternative location on the file system where the data files containing database objects (such as tables and indexes) can reside. A user with appropriate privileges can pass tablespacename to CREATE DATABASE, CREATE TABLE, CREATE INDEX or ADD CONSTRAINT to have the data files for these objects stored within the specified tablespace. Parameters tablespacename The name of a tablespace to be created. The name cannot begin with pg_, as such names are reserved for system tablespaces. username The name of the user who will own the tablespace. If omitted, defaults to the user executing the command. Only superusers can create tablespaces, but they can assign ownership of tablespaces to non-superusers. directory The directory that will be used for the tablespace. The directory must be empty and must be owned by the PostgreSQL system user. The directory must be specified by an absolute path name. Notes Tablespaces are only supported on systems that support symbolic links. CREATE TABLESPACE cannot be executed inside a transaction block. Examples Create a tablespace dbspace at /data/dbs: CREATE TABLESPACE dbspace LOCATION '/data/dbs'; Create a tablespace indexspace at /data/indexes owned by user genevieve: CREATE TABLESPACE indexspace OWNER genevieve LOCATION '/data/indexes'; Compatibility CREATE TABLESPACE is a PostgreSQL extension. See Also CREATE_DATABASE, CREATE_TABLE, CREATE_INDEX, DROP_TABLESPACE, ALTER TABLESPACE ------------------------------------------------------------------------ CREATE TEXT SEARCH CONFIGURATION Name CREATE TEXT SEARCH CONFIGURATION -- define a new text search configuration Synopsis CREATE TEXT SEARCH CONFIGURATION name ( PARSER = parser_name | COPY = source_config ) Description CREATE TEXT SEARCH CONFIGURATION creates a new text search configuration. A text search configuration specifies a text search parser that can divide a string into tokens, plus dictionaries that can be used to determine which tokens are of interest for searching. If only the parser is specified, then the new text search configuration initially has no mappings from token types to dictionaries, and therefore will ignore all words. Subsequent ALTER TEXT SEARCH CONFIGURATION commands must be used to create mappings to make the configuration useful. Alternatively, an existing text search configuration can be copied. If a schema name is given then the text search configuration is created in the specified schema. Otherwise it is created in the current schema. The user who defines a text search configuration becomes its owner. Refer to Chapter_12 for further information. Parameters name The name of the text search configuration to be created. The name can be schema-qualified. parser_name The name of the text search parser to use for this configuration. source_config The name of an existing text search configuration to copy. Notes The PARSER and COPY options are mutually exclusive, because when an existing configuration is copied, its parser selection is copied too. Compatibility There is no CREATE TEXT SEARCH CONFIGURATION statement in the SQL standard. See Also ALTER_TEXT_SEARCH_CONFIGURATION, DROP_TEXT_SEARCH_CONFIGURATION ------------------------------------------------------------------------ CREATE TEXT SEARCH DICTIONARY Name CREATE TEXT SEARCH DICTIONARY -- define a new text search dictionary Synopsis CREATE TEXT SEARCH DICTIONARY name ( TEMPLATE = template [, option = value [, ... ]] ) Description CREATE TEXT SEARCH DICTIONARY creates a new text search dictionary. A text search dictionary specifies a way of recognizing interesting or uninteresting words for searching. A dictionary depends on a text search template, which specifies the functions that actually perform the work. Typically the dictionary provides some options that control the detailed behavior of the template's functions. If a schema name is given then the text search dictionary is created in the specified schema. Otherwise it is created in the current schema. The user who defines a text search dictionary becomes its owner. Refer to Chapter_12 for further information. Parameters name The name of the text search dictionary to be created. The name can be schema-qualified. template The name of the text search template that will define the basic behavior of this dictionary. option The name of a template-specific option to be set for this dictionary. value The value to use for a template-specific option. If the value is not a simple identifier or number, it must be quoted (but you can always quote it, if you wish). The options can appear in any order. Examples The following example command creates a Snowball-based dictionary with a nonstandard list of stop words. CREATE TEXT SEARCH DICTIONARY my_russian ( template = snowball, language = russian, stopwords = myrussian ); Compatibility There is no CREATE TEXT SEARCH DICTIONARY statement in the SQL standard. See Also ALTER_TEXT_SEARCH_DICTIONARY, DROP_TEXT_SEARCH_DICTIONARY ------------------------------------------------------------------------ CREATE TEXT SEARCH PARSER Name CREATE TEXT SEARCH PARSER -- define a new text search parser Synopsis CREATE TEXT SEARCH PARSER name ( START = start_function , GETTOKEN = gettoken_function , END = end_function , LEXTYPES = lextypes_function [, HEADLINE = headline_function ] ) Description CREATE TEXT SEARCH PARSER creates a new text search parser. A text search parser defines a method for splitting a text string into tokens and assigning types (categories) to the tokens. A parser is not particularly useful by itself, but must be bound into a text search configuration along with some text search dictionaries to be used for searching. If a schema name is given then the text search parser is created in the specified schema. Otherwise it is created in the current schema. You must be a superuser to use CREATE TEXT SEARCH PARSER. (This restriction is made because an erroneous text search parser definition could confuse or even crash the server.) Refer to Chapter_12 for further information. Parameters name The name of the text search parser to be created. The name can be schema-qualified. start_function The name of the start function for the parser. gettoken_function The name of the get-next-token function for the parser. end_function The name of the end function for the parser. lextypes_function The name of the lextypes function for the parser (a function that returns information about the set of token types it produces). headline_function The name of the headline function for the parser (a function that summarizes a set of tokens). The function names can be schema-qualified if necessary. Argument types are not given, since the argument list for each type of function is predetermined. All except the headline function are required. The arguments can appear in any order, not only the one shown above. Compatibility There is no CREATE TEXT SEARCH PARSER statement in the SQL standard. See Also ALTER_TEXT_SEARCH_PARSER, DROP_TEXT_SEARCH_PARSER ------------------------------------------------------------------------ CREATE TEXT SEARCH TEMPLATE Name CREATE TEXT SEARCH TEMPLATE -- define a new text search template Synopsis CREATE TEXT SEARCH TEMPLATE name ( [ INIT = init_function , ] LEXIZE = lexize_function ) Description CREATE TEXT SEARCH TEMPLATE creates a new text search template. Text search templates define the functions that implement text search dictionaries. A template is not useful by itself, but must be instantiated as a dictionary to be used. The dictionary typically specifies parameters to be given to the template functions. If a schema name is given then the text search template is created in the specified schema. Otherwise it is created in the current schema. You must be a superuser to use CREATE TEXT SEARCH TEMPLATE. This restriction is made because an erroneous text search template definition could confuse or even crash the server. The reason for separating templates from dictionaries is that a template encapsulates the "unsafe" aspects of defining a dictionary. The parameters that can be set when defining a dictionary are safe for unprivileged users to set, and so creating a dictionary need not be a privileged operation. Refer to Chapter_12 for further information. Parameters name The name of the text search template to be created. The name can be schema-qualified. init_function The name of the init function for the template. lexize_function The name of the lexize function for the template. The function names can be schema-qualified if necessary. Argument types are not given, since the argument list for each type of function is predetermined. The lexize function is required, but the init function is optional. The arguments can appear in any order, not only the one shown above. Compatibility There is no CREATE TEXT SEARCH TEMPLATE statement in the SQL standard. See Also ALTER_TEXT_SEARCH_TEMPLATE, DROP_TEXT_SEARCH_TEMPLATE ------------------------------------------------------------------------ CREATE TRIGGER Name CREATE TRIGGER -- define a new trigger Synopsis CREATE TRIGGER name { BEFORE | AFTER } { event [ OR ... ] } ON table [ FOR [ EACH ] { ROW | STATEMENT } ] EXECUTE PROCEDURE funcname ( arguments ) Description CREATE TRIGGER creates a new trigger. The trigger will be associated with the specified table and will execute the specified function funcname when certain events occur. The trigger can be specified to fire either before the operation is attempted on a row (before constraints are checked and the INSERT, UPDATE, or DELETE is attempted) or after the operation has completed (after constraints are checked and the INSERT, UPDATE, or DELETE has completed). If the trigger fires before the event, the trigger can skip the operation for the current row, or change the row being inserted (for INSERT and UPDATE operations only). If the trigger fires after the event, all changes, including the last insertion, update, or deletion, are "visible" to the trigger. A trigger that is marked FOR EACH ROW is called once for every row that the operation modifies. For example, a DELETE that affects 10 rows will cause any ON DELETE triggers on the target relation to be called 10 separate times, once for each deleted row. In contrast, a trigger that is marked FOR EACH STATEMENT only executes once for any given operation, regardless of how many rows it modifies (in particular, an operation that modifies zero rows will still result in the execution of any applicable FOR EACH STATEMENT triggers). If multiple triggers of the same kind are defined for the same event, they will be fired in alphabetical order by name. SELECT does not modify any rows so you cannot create SELECT triggers. Rules and views are more appropriate in such cases. Refer to Chapter_35 for more information about triggers. Parameters name The name to give the new trigger. This must be distinct from the name of any other trigger for the same table. BEFORE AFTER Determines whether the function is called before or after the event. event One of INSERT, UPDATE, or DELETE; this specifies the event that will fire the trigger. Multiple events can be specified using OR. table The name (optionally schema-qualified) of the table the trigger is for. FOR EACH ROW FOR EACH STATEMENT This specifies whether the trigger procedure should be fired once for every row affected by the trigger event, or just once per SQL statement. If neither is specified, FOR EACH STATEMENT is the default. funcname A user-supplied function that is declared as taking no arguments and returning type trigger, which is executed when the trigger fires. arguments An optional comma-separated list of arguments to be provided to the function when the trigger is executed. The arguments are literal string constants. Simple names and numeric constants can be written here, too, but they will all be converted to strings. Please check the description of the implementation language of the trigger function about how the trigger arguments are accessible within the function; it might be different from normal function arguments. Notes To create a trigger on a table, the user must have the TRIGGER privilege on the table. In PostgreSQL versions before 7.3, it was necessary to declare trigger functions as returning the placeholder type opaque, rather than trigger. To support loading of old dump files, CREATE TRIGGER will accept a function declared as returning opaque, but it will issue a notice and change the function's declared return type to trigger. Use DROP_TRIGGER to remove a trigger. Examples Section_35.4 contains a complete example. Compatibility The CREATE TRIGGER statement in PostgreSQL implements a subset of the SQL standard. The following functionality is currently missing: * SQL allows triggers to fire on updates to specific columns (e.g., AFTER UPDATE OF col1, col2). * SQL allows you to define aliases for the "old" and "new" rows or tables for use in the definition of the triggered action (e.g., CREATE TRIGGER ... ON tablename REFERENCING OLD ROW AS somename NEW ROW AS othername ...). Since PostgreSQL allows trigger procedures to be written in any number of user-defined languages, access to the data is handled in a language-specific way. * PostgreSQL only allows the execution of a user-defined function for the triggered action. The standard allows the execution of a number of other SQL commands, such as CREATE TABLE as the triggered action. This limitation is not hard to work around by creating a user-defined function that executes the desired commands. SQL specifies that multiple triggers should be fired in time-of-creation order. PostgreSQL uses name order, which was judged to be more convenient. SQL specifies that BEFORE DELETE triggers on cascaded deletes fire after the cascaded DELETE completes. The PostgreSQL behavior is for BEFORE DELETE to always fire before the delete action, even a cascading one. This is considered more consistent. There is also unpredictable behavior when BEFORE triggers modify rows that are later to be modified by referential actions. This can lead to constraint violations or stored data that does not honor the referential constraint. The ability to specify multiple actions for a single trigger using OR is a PostgreSQL extension of the SQL standard. See Also CREATE_FUNCTION, ALTER_TRIGGER, DROP_TRIGGER ------------------------------------------------------------------------ CREATE TYPE Name CREATE TYPE -- define a new data type Synopsis CREATE TYPE name AS ( attribute_name data_type [, ... ] ) CREATE TYPE name AS ENUM ( 'label' [, ... ] ) CREATE TYPE name ( INPUT = input_function, OUTPUT = output_function [ , RECEIVE = receive_function ] [ , SEND = send_function ] [ , TYPMOD_IN = type_modifier_input_function ] [ , TYPMOD_OUT = type_modifier_output_function ] [ , ANALYZE = analyze_function ] [ , INTERNALLENGTH = { internallength | VARIABLE } ] [ , PASSEDBYVALUE ] [ , ALIGNMENT = alignment ] [ , STORAGE = storage ] [ , DEFAULT = default ] [ , ELEMENT = element ] [ , DELIMITER = delimiter ] ) CREATE TYPE name Description CREATE TYPE registers a new data type for use in the current database. The user who defines a type becomes its owner. If a schema name is given then the type is created in the specified schema. Otherwise it is created in the current schema. The type name must be distinct from the name of any existing type or domain in the same schema. (Because tables have associated data types, the type name must also be distinct from the name of any existing table in the same schema.) Composite Types The first form of CREATE TYPE creates a composite type. The composite type is specified by a list of attribute names and data types. This is essentially the same as the row type of a table, but using CREATE TYPE 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 argument or return type of a function. Enumerated Types The second form of CREATE TYPE creates an enumerated (enum) type, as described in Section_8.7. Enum types take a list of one or more quoted labels, each of which must be less than NAMEDATALEN bytes long (64 in a standard PostgreSQL build). Base Types The third form of CREATE TYPE creates a new base type (scalar type). The parameters can appear in any order, not only that illustrated above, and most are optional. You must register two or more functions (using CREATE FUNCTION) before defining the type. The support functions input_function and output_function are required, while the functions receive_function, send_function, type_modifier_input_function, type_modifier_output_function and analyze_function are optional. Generally these functions have to be coded in C or another low-level language. The input_function converts the type's external textual representation to the internal representation used by the operators and functions defined for the type. output_function performs the reverse transformation. The input function can be declared as taking one argument of type cstring, or as taking three arguments of types cstring, oid, integer. The first argument is the input text as a C string, the second argument is the type's own OID (except for array types, which instead receive their element type's OID), and the third is the typmod of the destination column, if known (-1 will be passed if not). The input function must return a value of the data type itself. Usually, an input function should be declared STRICT; if it is not, it will be called with a NULL first parameter when reading a NULL input value. The function must still return NULL in this case, unless it raises an error. (This case is mainly meant to support domain input functions, which might need to reject NULL inputs.) The output function must be declared as taking one argument of the new data type. The output function must return type cstring. Output functions are not invoked for NULL values. The optional receive_function converts the type's external binary representation to the internal representation. If this function is not supplied, the type cannot participate in binary input. The binary representation should be chosen to be cheap to convert to internal form, while being reasonably portable. (For example, the standard integer data types use network byte order as the external binary representation, while the internal representation is in the machine's native byte order.) The receive function should perform adequate checking to ensure that the value is valid. The receive function can be declared as taking one argument of type internal, or as taking three arguments of types internal, oid, integer. The first argument is a pointer to a StringInfo buffer holding the received byte string; the optional arguments are the same as for the text input function. The receive function must return a value of the data type itself. Usually, a receive function should be declared STRICT; if it is not, it will be called with a NULL first parameter when reading a NULL input value. The function must still return NULL in this case, unless it raises an error. (This case is mainly meant to support domain receive functions, which might need to reject NULL inputs.) Similarly, the optional send_function converts from the internal representation to the external binary representation. If this function is not supplied, the type cannot participate in binary output. The send function must be declared as taking one argument of the new data type. The send function must return type bytea. Send functions are not invoked for NULL values. You should at this point be wondering how the input and output functions can be declared to have results or arguments of the new type, when they have to be created before the new type can be created. The answer is that the type should first be defined as a shell type, which is a placeholder type that has no properties except a name and an owner. This is done by issuing the command CREATE TYPE name, with no additional parameters. Then the I/O functions can be defined referencing the shell type. Finally, CREATE TYPE with a full definition replaces the shell entry with a complete, valid type definition, after which the new type can be used normally. The optional type_modifier_input_function and type_modifier_output_function are needed if the type supports modifiers, that is optional constraints attached to a type declaration, such as char(5) or numeric(30,2). PostgreSQL allows user-defined types to take one or more simple constants or identifiers as modifiers. However, this information must be capable of being packed into a single non-negative integer value for storage in the system catalogs. The type_modifier_input_function is passed the declared modifier(s) in the form of a cstring array. It must check the values for validity (throwing an error if they are wrong), and if they are correct, return a single non-negative integer value that will be stored as the column "typmod". Type modifiers will be rejected if the type does not have a type_modifier_input_function. The type_modifier_output_function converts the internal integer typmod value back to the correct form for user display. It must return a cstring value that is the exact string to append to the type name; for example numeric's function might return (30,2). It is allowed to omit the type_modifier_output_function, in which case the default display format is just the stored typmod integer value enclosed in parentheses. The optional analyze_function performs type-specific statistics collection for columns of the data type. By default, ANALYZE will attempt to gather statistics using the type's "equals" and "less-than" operators, if there is a default b-tree operator class for the type. For non-scalar types this behavior is likely to be unsuitable, so it can be overridden by specifying a custom analysis function. The analysis function must be declared to take a single argument of type internal, and return a boolean result. The detailed API for analysis functions appears in src/include/commands/ vacuum.h. While the details of the new type's internal representation are only known to the I/O functions and other functions you create to work with the type, there are several properties of the internal representation that must be declared to PostgreSQL. Foremost of these is internallength. Base data types can be fixed-length, in which case internallength is a positive integer, or variable length, indicated by setting internallength to VARIABLE. (Internally, this is represented by setting typlen to -1.) The internal representation of all variable-length types must start with a 4- byte integer giving the total length of this value of the type. The optional flag PASSEDBYVALUE indicates that values of this data type are passed by value, rather than by reference. You cannot pass by value types whose internal representation is larger than the size of the Datum type (4 bytes on most machines, 8 bytes on a few). The alignment parameter specifies the storage alignment required for the data type. The allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries. Note that variable-length types must have an alignment of at least 4, since they necessarily contain an int4 as their first component. The storage parameter allows selection of storage strategies for variable- length data types. (Only plain is allowed for fixed-length types.) plain specifies that data of the type will always be stored in-line and not compressed. extended specifies that the system will first try to compress a long data value, and will move the value out of the main table row if it's still too long. external allows the value to be moved out of the main table, but the system will not try to compress it. main allows compression, but discourages moving the value out of the main table. (Data items with this storage strategy might still be moved out of the main table if there is no other way to make a row fit, but they will be kept in the main table preferentially over extended and external items.) A default value can be specified, in case a user wants columns of the data type to default to something other than the null value. Specify the default with the DEFAULT key word. (Such a default can be overridden by an explicit DEFAULT clause attached to a particular column.) To indicate that a type is an array, specify the type of the array elements using the ELEMENT key word. For example, to define an array of 4-byte integers (int4), specify ELEMENT = int4. More details about array types appear below. To indicate the delimiter to be used between values in the external representation of arrays of this type, delimiter can be set to a specific character. The default delimiter is the comma (,). Note that the delimiter is associated with the array element type, not the array type itself. Array Types Whenever a user-defined type is created, PostgreSQL automatically creates an associated array type, whose name consists of the base type's name prepended with an underscore, and truncated if necessary to keep it less than NAMEDATALEN bytes long. (If the name so generated collides with an existing type name, the process is repeated until a non-colliding name is found.) This implicitly-created array type is variable length and uses the built-in input and output functions array_in and array_out. The array type tracks any changes in its element type's owner or schema, and is dropped if the element type is. You might reasonably ask why there is an ELEMENT option, if the system makes the correct array type automatically. The only case where it's useful to use ELEMENT is when you are making a fixed-length type that happens to be internally an array of a number of identical things, and you want to allow these things to be accessed directly by subscripting, in addition to whatever operations you plan to provide for the type as a whole. For example, type point is represented as just two floating-point numbers, which it allows to be accessed as point[0] and point[1]. Note that this facility only works for fixed-length types whose internal form is exactly a sequence of identical fixed-length fields. A subscriptable variable-length type must have the generalized internal representation used by array_in and array_out. For historical reasons (i.e., this is clearly wrong but it's far too late to change it), subscripting of fixed-length array types starts from zero, rather than from one as for variable-length arrays. Parameters name The name (optionally schema-qualified) of a type to be created. attribute_name The name of an attribute (column) for the composite type. data_type The name of an existing data type to become a column of the composite type. label A string literal representing the textual label associated with one value of an enum type. input_function The name of a function that converts data from the type's external textual form to its internal form. output_function The name of a function that converts data from the type's internal form to its external textual form. receive_function The name of a function that converts data from the type's external binary form to its internal form. send_function The name of a function that converts data from the type's internal form to its external binary form. type_modifier_input_function The name of a function that converts an array of modifier(s) for the type into internal form. type_modifier_output_function The name of a function that converts the internal form of the type's modifier(s) to external textual form. analyze_function The name of a function that performs statistical analysis for the data type. internallength A numeric constant that specifies the length in bytes of the new type's internal representation. The default assumption is that it is variable-length. alignment The storage alignment requirement of the data type. If specified, it must be char, int2, int4, or double; the default is int4. storage The storage strategy for the data type. If specified, must be plain, external, extended, or main; the default is plain. default The default value for the data type. If this is omitted, the default is null. element The type being created is an array; this specifies the type of the array elements. delimiter The delimiter character to be used between values in arrays made of this type. Notes Because there are no restrictions on use of a data type once it's been created, creating a base type is tantamount to granting public execute permission on the functions mentioned in the type definition. (The creator of the type is therefore required to own these functions.) This is usually not an issue for the sorts of functions that are useful in a type definition. But you might want to think twice before designing a type in a way that would require "secret" information to be used while converting it to or from external form. Before PostgreSQL version 8.3, the name of a generated array type was always exactly the element type's name with one underscore character (_) prepended. (Type names were therefore restricted in length to one less character than other names.) While this is still usually the case, the array type name may vary from this in case of maximum-length names or collisions with user type names that begin with underscore. Writing code that depends on this convention is therefore deprecated. Instead, use pg_type.typarray to locate the array type associated with a given type. It may be advisable to avoid using type and table names that begin with underscore. While the server will change generated array type names to avoid collisions with user-given names, there is still risk of confusion, particularly with old client software that may assume that type names beginning with underscores always represent arrays. Before PostgreSQL version 8.2, the syntax CREATE TYPE name did not exist. The way to create a new base type was to create its input function first. In this approach, PostgreSQL will first see the name of the new data type as the return type of the input function. The shell type is implicitly created in this situation, and then it can be referenced in the definitions of the remaining I/O functions. This approach still works, but is deprecated and might be disallowed in some future release. Also, to avoid accidentally cluttering the catalogs with shell types as a result of simple typos in function definitions, a shell type will only be made this way when the input function is written in C. In PostgreSQL versions before 7.3, it was customary to avoid creating a shell type at all, by replacing the functions' forward references to the type name with the placeholder pseudotype opaque. The cstring arguments and results also had to be declared as opaque before 7.3. To support loading of old dump files, CREATE TYPE will accept I/O functions declared using opaque, but it will issue a notice and change the function declarations to use the correct types. Examples This example creates a composite type and uses it in a function definition: CREATE TYPE compfoo AS (f1 int, f2 text); CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS $$ SELECT fooid, fooname FROM foo $$ LANGUAGE SQL; This example creates an enumerated type and uses it in a table definition: CREATE TYPE bug_status AS ENUM ('new', 'open', 'closed'); CREATE TABLE bug ( id serial, description text, status bug_status ); This example creates the base data type box and then uses the type in a table definition: CREATE TYPE box; CREATE FUNCTION my_box_in_function(cstring) RETURNS box AS ... ; CREATE FUNCTION my_box_out_function(box) RETURNS cstring AS ... ; CREATE TYPE box ( INTERNALLENGTH = 16, INPUT = my_box_in_function, OUTPUT = my_box_out_function ); CREATE TABLE myboxes ( id integer, description box ); If the internal structure of box were an array of four float4 elements, we might instead use: CREATE TYPE box ( INTERNALLENGTH = 16, INPUT = my_box_in_function, OUTPUT = my_box_out_function, ELEMENT = float4 ); which would allow a box value's component numbers to be accessed by subscripting. Otherwise the type behaves the same as before. This example creates a large object type and uses it in a table definition: CREATE TYPE bigobj ( INPUT = lo_filein, OUTPUT = lo_fileout, INTERNALLENGTH = VARIABLE ); CREATE TABLE big_objs ( id integer, obj bigobj ); More examples, including suitable input and output functions, are in Section_34.11. Compatibility This CREATE TYPE command is a PostgreSQL extension. There is a CREATE TYPE statement in the SQL standard that is rather different in detail. See Also CREATE_FUNCTION, DROP_TYPE, ALTER_TYPE, CREATE_DOMAIN ------------------------------------------------------------------------ CREATE USER Name CREATE USER -- define a new database role Synopsis CREATE USER name [ [ WITH ] option [ ... ] ] where option can be: SUPERUSER | NOSUPERUSER | CREATEDB | NOCREATEDB | CREATEROLE | NOCREATEROLE | CREATEUSER | NOCREATEUSER | INHERIT | NOINHERIT | LOGIN | NOLOGIN | CONNECTION LIMIT connlimit | [ ENCRYPTED | UNENCRYPTED ] PASSWORD 'password' | VALID UNTIL 'timestamp' | IN ROLE rolename [, ...] | IN GROUP rolename [, ...] | ROLE rolename [, ...] | ADMIN rolename [, ...] | USER rolename [, ...] | SYSID uid Description CREATE USER is now an alias for CREATE_ROLE. The only difference is that when the command is spelled CREATE USER, LOGIN is assumed by default, whereas NOLOGIN is assumed when the command is spelled CREATE ROLE. Compatibility The CREATE USER statement is a PostgreSQL extension. The SQL standard leaves the definition of users to the implementation. See Also CREATE_ROLE ------------------------------------------------------------------------ CREATE VIEW Name CREATE VIEW -- define a new view Synopsis CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] VIEW name [ ( column_name [, ...] ) ] AS query Description CREATE VIEW defines a view of a query. The view is not physically materialized. Instead, the query is run every time the view is referenced in a query. CREATE OR REPLACE VIEW is similar, but if a view of the same name already exists, it is replaced. You can only replace a view with a new query that generates the identical set of columns (i.e., same column names and data types). If a schema name is given (for example, CREATE VIEW myschema.myview ...) then the view is created in the specified schema. Otherwise it is created in the current schema. Temporary views exist in a special schema, so a schema name cannot be given when creating a temporary view. The name of the view must be distinct from the name of any other view, table, sequence, or index in the same schema. Parameters TEMPORARY or TEMP If specified, the view is created as a temporary view. Temporary views are automatically dropped at the end of the current session. Existing permanent relations with the same name are not visible to the current session while the temporary view exists, unless they are referenced with schema-qualified names. If any of the tables referenced by the view are temporary, the view is created as a temporary view (whether TEMPORARY is specified or not). name The name (optionally schema-qualified) of a view to be created. column_name An optional list of names to be used for columns of the view. If not given, the column names are deduced from the query. query A SELECT or VALUES command which will provide the columns and rows of the view. Notes Currently, views are read only: the system will not allow an insert, update, or delete on a view. You can get the effect of an updatable view by creating rules that rewrite inserts, etc. on the view into appropriate actions on other tables. For more information see CREATE_RULE. Use the DROP_VIEW statement to drop views. Be careful that the names and types of the view's columns will be assigned the way you want. For example: CREATE VIEW vista AS SELECT 'Hello World'; is bad form in two ways: the column name defaults to ?column?, and the column data type defaults to unknown. If you want a string literal in a view's result, use something like: CREATE VIEW vista AS SELECT text 'Hello World' AS hello; Access to tables referenced in the view is determined by permissions of the view owner. However, functions called in the view are treated the same as if they had been called directly from the query using the view. Therefore the user of a view must have permissions to call all functions used by the view. Examples Create a view consisting of all comedy films: CREATE VIEW comedies AS SELECT * FROM films WHERE kind = 'Comedy'; Compatibility The SQL standard specifies some additional capabilities for the CREATE VIEW statement: CREATE VIEW name [ ( column_name [, ...] ) ] AS query [ WITH [ CASCADED | LOCAL ] CHECK OPTION ] The optional clauses for the full SQL command are: CHECK OPTION This option has to do with updatable views. All INSERT and 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 view). If they do not, the update will be rejected. LOCAL Check for integrity on this view. CASCADED Check for integrity on this view and on any dependent view. CASCADED is assumed if neither CASCADED nor LOCAL is specified. CREATE OR REPLACE VIEW is a PostgreSQL language extension. So is the concept of a temporary view. See Also ALTER_VIEW, DROP_VIEW ------------------------------------------------------------------------ DEALLOCATE Name DEALLOCATE -- deallocate a prepared statement Synopsis DEALLOCATE [ PREPARE ] { name | ALL } Description DEALLOCATE is used to deallocate a previously prepared SQL statement. If you do not explicitly deallocate a prepared statement, it is deallocated when the session ends. For more information on prepared statements, see PREPARE. Parameters PREPARE This key word is ignored. name The name of the prepared statement to deallocate. ALL Deallocate all prepared statements. Compatibility The SQL standard includes a DEALLOCATE statement, but it is only for use in embedded SQL. See Also EXECUTE, PREPARE ------------------------------------------------------------------------ DECLARE Name DECLARE -- define a cursor Synopsis DECLARE name [ BINARY ] [ INSENSITIVE ] [ [ NO ] SCROLL ] CURSOR [ { WITH | WITHOUT } HOLD ] FOR query Description DECLARE allows a user to create cursors, which can be used to retrieve a small number of rows at a time out of a larger query. After the cursor is created, rows are fetched from it using FETCH. Parameters name The name of the cursor to be created. BINARY Causes the cursor to return data in binary rather than in text format. INSENSITIVE Indicates that data retrieved from the cursor should be unaffected by updates to the table(s) underlying the cursor that occur after the cursor is created. In PostgreSQL, this is the default behavior; so this key word has no effect and is only accepted for compatibility with the SQL standard. SCROLL NO SCROLL SCROLL specifies that the cursor can be used to retrieve rows in a nonsequential fashion (e.g., backward). Depending upon the complexity of the query's execution plan, specifying SCROLL might impose a performance penalty on the query's execution time. NO SCROLL specifies that the cursor cannot be used to retrieve rows in a nonsequential fashion. The default is to allow scrolling in some cases; this is not the same as specifying SCROLL. See Notes for details. WITH HOLD WITHOUT HOLD WITH HOLD specifies that the cursor can continue to be used after the transaction that created it successfully commits. WITHOUT HOLD specifies that the cursor cannot be used outside of the transaction that created it. If neither WITHOUT HOLD nor WITH HOLD is specified, WITHOUT HOLD is the default. query A SELECT or VALUES command which will provide the rows to be returned by the cursor. The key words BINARY, INSENSITIVE, and SCROLL can appear in any order. Notes Normal cursors return data in text format, the same as a SELECT would produce. The BINARY option specifies that the cursor should return data in binary format. This reduces conversion effort for both the server and client, at the cost of more programmer effort to deal with platform- dependent binary data formats. As an example, if a query returns a value of one from an integer column, you would get a string of 1 with a default cursor, whereas with a binary cursor you would get a 4-byte field containing the internal representation of the value (in big-endian byte order). Binary cursors should be used carefully. Many applications, including psql, are not prepared to handle binary cursors and expect data to come back in the text format. Note: When the client application uses the "extended query" protocol to issue a FETCH command, the Bind protocol message specifies whether data is to be retrieved in text or binary format. This choice overrides the way that the cursor is defined. The concept of a binary cursor as such is thus obsolete when using extended query protocol -- any cursor can be treated as either text or binary. Unless WITH HOLD is specified, the cursor created by this command can only be used within the current transaction. Thus, DECLARE without WITH HOLD is useless outside a transaction block: the cursor would survive only to the completion of the statement. Therefore PostgreSQL reports an error if such a command is used outside a transaction block. Use BEGIN, COMMIT and ROLLBACK to define a transaction block. If WITH HOLD is specified and the transaction that created the cursor successfully commits, the cursor can continue to be accessed by subsequent transactions in the same session. (But if the creating transaction is aborted, the cursor is removed.) A cursor created with WITH HOLD is closed when an explicit CLOSE command is issued on it, or the session ends. In the current implementation, the rows represented by a held cursor are copied into a temporary file or memory area so that they remain available for subsequent transactions. WITH HOLD may not be specified when the query includes FOR UPDATE or FOR SHARE. The SCROLL option should be specified when defining a cursor that will be used to fetch backwards. This is required by the SQL standard. However, for compatibility with earlier versions, PostgreSQL will allow backward fetches without SCROLL, if the cursor's query plan is simple enough that no extra overhead is needed to support it. However, application developers are advised not to rely on using backward fetches from a cursor that has not been created with SCROLL. If NO SCROLL is specified, then backward fetches are disallowed in any case. If the cursor's query includes FOR UPDATE or FOR SHARE, then returned rows are locked at the time they are first fetched, in the same way as for a regular SELECT command with these options. In addition, the returned rows will be the most up-to-date versions; therefore these options provide the equivalent of what the SQL standard calls a "sensitive cursor". It is often wise to use FOR UPDATE if the cursor is intended to be used with UPDATE ... WHERE CURRENT OF or DELETE ... WHERE CURRENT OF, since this will prevent other sessions from changing the rows between the time they are fetched and the time they are updated. Without FOR UPDATE, a subsequent WHERE CURRENT OF command will have no effect if the row was changed meanwhile. SCROLL may not be specified when the query includes FOR UPDATE or FOR SHARE. The SQL standard only makes provisions for cursors in embedded SQL. The PostgreSQL server does not implement an OPEN statement for cursors; a cursor is considered to be open when it is declared. However, ECPG, the embedded SQL preprocessor for PostgreSQL, supports the standard SQL cursor conventions, including those involving DECLARE and OPEN statements. You can see all available cursors by querying the pg_cursors system view. Examples To declare a cursor: DECLARE liahona CURSOR FOR SELECT * FROM films; See FETCH for more examples of cursor usage. Compatibility The SQL standard says that it is implementation-dependent whether cursors are sensitive to concurrent updates of the underlying data by default. In PostgreSQL, cursors are insensitive by default, and can be made sensitive by specifying FOR UPDATE. Other products may work differently. The SQL standard allows cursors only in embedded SQL and in modules. PostgreSQL permits cursors to be used interactively. Binary cursors are a PostgreSQL extension. See Also CLOSE, FETCH, MOVE ------------------------------------------------------------------------ DELETE Name DELETE -- delete rows of a table Synopsis DELETE FROM [ ONLY ] table [ [ AS ] alias ] [ USING usinglist ] [ WHERE condition | WHERE CURRENT OF cursor_name ] [ RETURNING * | output_expression [ AS output_name ] [, ...] ] Description DELETE deletes rows that satisfy the WHERE clause from the specified table. If the WHERE clause is absent, the effect is to delete all rows in the table. The result is a valid, but empty table. Tip: TRUNCATE is a PostgreSQL extension that provides a faster mechanism to remove all rows from a table. By default, DELETE will delete rows in the specified table and all its child tables. If you wish to delete only from the specific table mentioned, you must use the ONLY clause. There are two ways to delete rows in a table using information contained in other tables in the database: using sub-selects, or specifying additional tables in the USING clause. Which technique is more appropriate depends on the specific circumstances. The optional RETURNING clause causes DELETE to compute and return value(s) based on each row actually deleted. Any expression using the table's columns, and/or columns of other tables mentioned in USING, can be computed. The syntax of the RETURNING list is identical to that of the output list of SELECT. You must have the DELETE privilege on the table to delete from it, as well as the SELECT privilege for any table in the USING clause or whose values are read in the condition. Parameters ONLY If specified, delete rows from the named table only. When not specified, any tables inheriting from the named table are also processed. table The name (optionally schema-qualified) of an existing table. alias A substitute name for the target table. When an alias is provided, it completely hides the actual name of the table. For example, given DELETE FROM foo AS f, the remainder of the DELETE statement must refer to this table as f not foo. usinglist A list of table expressions, allowing columns from other tables to appear in the WHERE condition. This is similar to the list of tables that can be specified in the FROM_Clause of a SELECT statement; for example, an alias for the table name can be specified. Do not repeat the target table in the usinglist, unless you wish to set up a self- join. condition An expression that returns a value of type boolean. Only rows for which this expression returns true will be deleted. cursor_name The name of the cursor to use in a WHERE CURRENT OF condition. The row to be deleted is the one most recently fetched from this cursor. The cursor must be a simple (non-join, non-aggregate) query on the DELETE's target table. Note that WHERE CURRENT OF cannot be specified together with a Boolean condition. output_expression An expression to be computed and returned by the DELETE command after each row is deleted. The expression can use any column names of the table or table(s) listed in USING. Write * to return all columns. output_name A name to use for a returned column. Outputs On successful completion, a DELETE command returns a command tag of the form DELETE count The count is the number of rows deleted. If count is 0, no rows matched the condition (this is not considered an error). If the DELETE command contains a RETURNING clause, the result will be similar to that of a SELECT statement containing the columns and values defined in the RETURNING list, computed over the row(s) deleted by the command. Notes PostgreSQL lets you reference columns of other tables in the WHERE condition by specifying the other tables in the USING clause. For example, to delete all films produced by a given producer, one can do: DELETE FROM films USING producers WHERE producer_id = producers.id AND producers.name = 'foo'; What is essentially happening here is a join between films and producers, with all successfully joined films rows being marked for deletion. This syntax is not standard. A more standard way to do it is: DELETE FROM films WHERE producer_id IN (SELECT id FROM producers WHERE name = 'foo'); In some cases the join style is easier to write or faster to execute than the sub-select style. Examples Delete all films but musicals: DELETE FROM films WHERE kind <> 'Musical'; Clear the table films: DELETE FROM films; Delete completed tasks, returning full details of the deleted rows: DELETE FROM tasks WHERE status = 'DONE' RETURNING *; Delete the row of tasks on which the cursor c_tasks is currently positioned: DELETE FROM tasks WHERE CURRENT OF c_tasks; Compatibility This command conforms to the SQL standard, except that the USING and RETURNING clauses are PostgreSQL extensions. ------------------------------------------------------------------------ DISCARD Name DISCARD -- discard session state Synopsis DISCARD { ALL | PLANS | TEMPORARY | TEMP } Description DISCARD releases internal resources associated with a database session. These resources are normally released at the end of the session. DISCARD TEMP drops all temporary tables created in the current session. DISCARD PLANS releases all internally cached query plans. DISCARD ALL resets a session to its original state, discarding temporary resources and resetting session-local configuration changes. Parameters TEMPORARY or TEMP Drops all temporary tables created in the current session. PLANS Releases all cached query plans. ALL Releases all temporary resources associated with the current session and resets the session to its initial state. This has the same effect as executing the following sequence of statements: SET SESSION AUTHORIZATION DEFAULT; RESET ALL; DEALLOCATE ALL; CLOSE ALL; UNLISTEN *; DISCARD PLANS; DISCARD TEMP; Notes DISCARD ALL cannot be executed inside a transaction block. Compatibility DISCARD is a PostgreSQL extension. ------------------------------------------------------------------------ DROP AGGREGATE Name DROP AGGREGATE -- remove an aggregate function Synopsis DROP AGGREGATE [ IF EXISTS ] name ( type [ , ... ] ) [ CASCADE | RESTRICT ] Description DROP AGGREGATE removes an existing aggregate function. To execute this command the current user must be the owner of the aggregate function. Parameters IF EXISTS Do not throw an error if the aggregate does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an existing aggregate function. type An input data type on which the aggregate function operates. To reference a zero-argument aggregate function, write * in place of the list of input data types. CASCADE Automatically drop objects that depend on the aggregate function. RESTRICT Refuse to drop the aggregate function if any objects depend on it. This is the default. Examples To remove the aggregate function myavg for type integer: DROP AGGREGATE myavg(integer); Compatibility There is no DROP AGGREGATE statement in the SQL standard. See Also ALTER_AGGREGATE, CREATE_AGGREGATE ------------------------------------------------------------------------ DROP CAST Name DROP CAST -- remove a cast Synopsis DROP CAST [ IF EXISTS ] (sourcetype AS targettype) [ CASCADE | RESTRICT ] Description DROP CAST removes a previously defined cast. To be able to drop a cast, you must own the source or the target data type. These are the same privileges that are required to create a cast. Parameters IF EXISTS Do not throw an error if the cast does not exist. A notice is issued in this case. sourcetype The name of the source data type of the cast. targettype The name of the target data type of the cast. CASCADE RESTRICT These key words do not have any effect, since there are no dependencies on casts. Examples To drop the cast from type text to type int: DROP CAST (text AS int); Compatibility The DROP CAST command conforms to the SQL standard. See Also CREATE_CAST ------------------------------------------------------------------------ DROP CONVERSION Name DROP CONVERSION -- remove a conversion Synopsis DROP CONVERSION [ IF EXISTS ] name [ CASCADE | RESTRICT ] Description DROP CONVERSION removes a previously defined conversion. To be able to drop a conversion, you must own the conversion. Parameters IF EXISTS Do not throw an error if the conversion does not exist. A notice is issued in this case. name The name of the conversion. The conversion name can be schema- qualified. CASCADE RESTRICT These key words do not have any effect, since there are no dependencies on conversions. Examples To drop the conversion named myname: DROP CONVERSION myname; Compatibility There is no DROP CONVERSION statement in the SQL standard. See Also ALTER_CONVERSION, CREATE_CONVERSION ------------------------------------------------------------------------ DROP DATABASE Name DROP DATABASE -- remove a database Synopsis DROP DATABASE [ IF EXISTS ] name Description DROP DATABASE drops a database. It removes the catalog entries for the database and deletes the directory containing the data. It can only be executed by the database owner. Also, it cannot be executed while you or anyone else are connected to the target database. (Connect to postgres or any other database to issue this command.) DROP DATABASE cannot be undone. Use it with care! Parameters IF EXISTS Do not throw an error if the database does not exist. A notice is issued in this case. name The name of the database to remove. Notes DROP DATABASE cannot be executed inside a transaction block. This command cannot be executed while connected to the target database. Thus, it might be more convenient to use the program dropdb instead, which is a wrapper around this command. Compatibility There is no DROP DATABASE statement in the SQL standard. See Also CREATE_DATABASE ------------------------------------------------------------------------ DROP DOMAIN Name DROP DOMAIN -- remove a domain Synopsis DROP DOMAIN [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ] Description DROP DOMAIN removes a domain. Only the owner of a domain can remove it. Parameters IF EXISTS Do not throw an error if the domain does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an existing domain. CASCADE Automatically drop objects that depend on the domain (such as table columns). RESTRICT Refuse to drop the domain if any objects depend on it. This is the default. Examples To remove the domain box: DROP DOMAIN box; Compatibility This command conforms to the SQL standard, except for the IF EXISTS option, which is a PostgreSQL extension. See Also CREATE_DOMAIN, ALTER_DOMAIN ------------------------------------------------------------------------ DROP FUNCTION Name DROP FUNCTION -- remove a function Synopsis DROP FUNCTION [ IF EXISTS ] name ( [ [ argmode ] [ argname ] argtype [, ...] ] ) [ CASCADE | RESTRICT ] Description DROP FUNCTION removes the definition of an existing function. To execute this command the user must be the owner of the function. The argument types to the function must be specified, since several different functions can exist with the same name and different argument lists. Parameters IF EXISTS Do not throw an error if the function does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an existing function. argmode The mode of an argument: either IN, OUT, or INOUT. If omitted, the default is IN. Note that DROP FUNCTION does not actually pay any attention to OUT arguments, since only the input arguments are needed to determine the function's identity. So it is sufficient to list the IN and INOUT arguments. argname The name of an argument. Note that DROP FUNCTION does not actually pay any attention to argument names, since only the argument data types are needed to determine the function's identity. argtype The data type(s) of the function's arguments (optionally schema- qualified), if any. CASCADE Automatically drop objects that depend on the function (such as operators or triggers). RESTRICT Refuse to drop the function if any objects depend on it. This is the default. Examples This command removes the square root function: DROP FUNCTION sqrt(integer); Compatibility A DROP FUNCTION statement is defined in the SQL standard, but it is not compatible with this command. See Also CREATE_FUNCTION, ALTER_FUNCTION ------------------------------------------------------------------------ DROP GROUP Name DROP GROUP -- remove a database role Synopsis DROP GROUP [ IF EXISTS ] name [, ...] Description DROP GROUP is now an alias for DROP_ROLE. Compatibility There is no DROP GROUP statement in the SQL standard. See Also DROP_ROLE ------------------------------------------------------------------------ DROP INDEX Name DROP INDEX -- remove an index Synopsis DROP INDEX [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ] Description DROP INDEX drops an existing index from the database system. To execute this command you must be the owner of the index. Parameters IF EXISTS Do not throw an error if the index does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an index to remove. CASCADE Automatically drop objects that depend on the index. RESTRICT Refuse to drop the index if any objects depend on it. This is the default. Examples This command will remove the index title_idx: DROP INDEX title_idx; Compatibility DROP INDEX is a PostgreSQL language extension. There are no provisions for indexes in the SQL standard. See Also CREATE_INDEX ------------------------------------------------------------------------ DROP LANGUAGE Name DROP LANGUAGE -- remove a procedural language Synopsis DROP [ PROCEDURAL ] LANGUAGE [ IF EXISTS ] name [ CASCADE | RESTRICT ] Description DROP LANGUAGE removes the definition of a previously registered procedural language. You must be a superuser or the owner of the language to use DROP LANGUAGE. Parameters IF EXISTS Do not throw an error if the language does not exist. A notice is issued in this case. name The name of an existing procedural language. For backward compatibility, the name can be enclosed by single quotes. CASCADE Automatically drop objects that depend on the language (such as functions in the language). RESTRICT Refuse to drop the language if any objects depend on it. This is the default. Examples This command removes the procedural language plsample: DROP LANGUAGE plsample; Compatibility There is no DROP LANGUAGE statement in the SQL standard. See Also ALTER_LANGUAGE, CREATE_LANGUAGE, droplang ------------------------------------------------------------------------ DROP OPERATOR Name DROP OPERATOR -- remove an operator Synopsis DROP OPERATOR [ IF EXISTS ] name ( { lefttype | NONE } , { righttype | NONE } ) [ CASCADE | RESTRICT ] Description DROP OPERATOR drops an existing operator from the database system. To execute this command you must be the owner of the operator. Parameters IF EXISTS Do not throw an error if the operator does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an existing operator. lefttype The data type of the operator's left operand; write NONE if the operator has no left operand. righttype The data type of the operator's right operand; write NONE if the operator has no right operand. CASCADE Automatically drop objects that depend on the operator. RESTRICT Refuse to drop the operator if any objects depend on it. This is the default. Examples Remove the power operator a^b for type integer: DROP OPERATOR ^ (integer, integer); Remove the left unary bitwise complement operator ~b for type bit: DROP OPERATOR ~ (none, bit); Remove the right unary factorial operator x! for type bigint: DROP OPERATOR ! (bigint, none); Compatibility There is no DROP OPERATOR statement in the SQL standard. See Also CREATE_OPERATOR, ALTER_OPERATOR ------------------------------------------------------------------------ DROP OPERATOR CLASS Name DROP OPERATOR CLASS -- remove an operator class Synopsis DROP OPERATOR CLASS [ IF EXISTS ] name USING index_method [ CASCADE | RESTRICT ] Description DROP OPERATOR CLASS drops an existing operator class. To execute this command you must be the owner of the operator class. DROP OPERATOR CLASS does not drop any of the operators or functions referenced by the class. If there are any indexes depending on the operator class, you will need to specify CASCADE for the drop to complete. Parameters IF EXISTS Do not throw an error if the operator class does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an existing operator class. index_method The name of the index access method the operator class is for. CASCADE Automatically drop objects that depend on the operator class. RESTRICT Refuse to drop the operator class if any objects depend on it. This is the default. Notes DROP OPERATOR CLASS will not drop the operator family containing the class, even if there is nothing else left in the family (in particular, in the case where the family was implicitly created by CREATE OPERATOR CLASS). An empty operator family is harmless, but for the sake of tidiness you might wish to remove the family with DROP OPERATOR FAMILY; or perhaps better, use DROP OPERATOR FAMILY in the first place. Examples Remove the B-tree operator class widget_ops: DROP OPERATOR CLASS widget_ops USING btree; This command will not succeed if there are any existing indexes that use the operator class. Add CASCADE to drop such indexes along with the operator class. Compatibility There is no DROP OPERATOR CLASS statement in the SQL standard. See Also ALTER_OPERATOR_CLASS, CREATE_OPERATOR_CLASS, DROP_OPERATOR_FAMILY ------------------------------------------------------------------------ DROP OPERATOR FAMILY Name DROP OPERATOR FAMILY -- remove an operator family Synopsis DROP OPERATOR FAMILY [ IF EXISTS ] name USING index_method [ CASCADE | RESTRICT ] Description DROP OPERATOR FAMILY drops an existing operator family. To execute this command you must be the owner of the operator family. DROP OPERATOR FAMILY includes dropping any operator classes contained in the family, but it does not drop any of the operators or functions referenced by the family. If there are any indexes depending on operator classes within the family, you will need to specify CASCADE for the drop to complete. Parameters IF EXISTS Do not throw an error if the operator family does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an existing operator family. index_method The name of the index access method the operator family is for. CASCADE Automatically drop objects that depend on the operator family. RESTRICT Refuse to drop the operator family if any objects depend on it. This is the default. Examples Remove the B-tree operator family float_ops: DROP OPERATOR FAMILY float_ops USING btree; This command will not succeed if there are any existing indexes that use operator classes within the family. Add CASCADE to drop such indexes along with the operator family. Compatibility There is no DROP OPERATOR FAMILY statement in the SQL standard. See Also ALTER_OPERATOR_FAMILY, CREATE_OPERATOR_FAMILY, ALTER_OPERATOR_CLASS, CREATE OPERATOR_CLASS, DROP_OPERATOR_CLASS ------------------------------------------------------------------------ DROP OWNED Name DROP OWNED -- remove database objects owned by a database role Synopsis DROP OWNED BY name [, ...] [ CASCADE | RESTRICT ] Description DROP OWNED drops all the objects in the current database that are owned by one of the specified roles. Any privileges granted to the given roles on objects in the current database will also be revoked. Parameters name The name of a role whose objects will be dropped, and whose privileges will be revoked. CASCADE Automatically drop objects that depend on the affected objects. RESTRICT Refuse to drop the objects owned by a role if any other database objects depend on one of the affected objects. This is the default. Notes DROP OWNED is often used to prepare for the removal of one or more roles. Because DROP OWNED only affects the objects in the current database, it is usually necessary to execute this command in each database that contains objects owned by a role that is to be removed. Using the CASCADE option might make the command recurse to objects owned by other users. The REASSIGN_OWNED command is an alternative that reassigns the ownership of all the database objects owned by one or more roles. Compatibility The DROP OWNED statement is a PostgreSQL extension. See Also REASSIGN_OWNED, DROP_ROLE ------------------------------------------------------------------------ DROP ROLE Name DROP ROLE -- remove a database role Synopsis DROP ROLE [ IF EXISTS ] name [, ...] Description DROP ROLE removes the specified role(s). To drop a superuser role, you must be a superuser yourself; to drop non-superuser roles, you must have CREATEROLE privilege. A role cannot be removed if it is still referenced in any database of the cluster; an error will be raised if so. Before dropping the role, you must drop all the objects it owns (or reassign their ownership) and revoke any privileges the role has been granted. The REASSIGN_OWNED and DROP_OWNED commands can be useful for this purpose. However, it is not necessary to remove role memberships involving the role; DROP ROLE automatically revokes any memberships of the target role in other roles, and of other roles in the target role. The other roles are not dropped nor otherwise affected. Parameters IF EXISTS Do not throw an error if the role does not exist. A notice is issued in this case. name The name of the role to remove. Notes PostgreSQL includes a program dropuser that has the same functionality as this command (in fact, it calls this command) but can be run from the command shell. Examples To drop a role: DROP ROLE jonathan; Compatibility The SQL standard defines DROP ROLE, but it allows only one role to be dropped at a time, and it specifies different privilege requirements than PostgreSQL uses. See Also CREATE_ROLE, ALTER_ROLE, SET_ROLE ------------------------------------------------------------------------ DROP RULE Name DROP RULE -- remove a rewrite rule Synopsis DROP RULE [ IF EXISTS ] name ON relation [ CASCADE | RESTRICT ] Description DROP RULE drops a rewrite rule. Parameters IF EXISTS Do not throw an error if the rule does not exist. A notice is issued in this case. name The name of the rule to drop. relation The name (optionally schema-qualified) of the table or view that the rule applies to. CASCADE Automatically drop objects that depend on the rule. RESTRICT Refuse to drop the rule if any objects depend on it. This is the default. Examples To drop the rewrite rule newrule: DROP RULE newrule ON mytable; Compatibility There is no DROP RULE statement in the SQL standard. See Also CREATE_RULE ------------------------------------------------------------------------ DROP SCHEMA Name DROP SCHEMA -- remove a schema Synopsis DROP SCHEMA [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ] Description DROP SCHEMA removes schemas from the database. A schema can only be dropped by its owner or a superuser. Note that the owner can drop the schema (and thereby all contained objects) even if he does not own some of the objects within the schema. Parameters IF EXISTS Do not throw an error if the schema does not exist. A notice is issued in this case. name The name of a schema. CASCADE Automatically drop objects (tables, functions, etc.) that are contained in the schema. RESTRICT Refuse to drop the schema if it contains any objects. This is the default. Examples To remove schema mystuff from the database, along with everything it contains: DROP SCHEMA mystuff CASCADE; Compatibility DROP SCHEMA is fully conforming with the SQL standard, except that the standard only allows one schema to be dropped per command, and apart from the IF EXISTS option, which is a PostgreSQL extension. See Also ALTER_SCHEMA, CREATE_SCHEMA ------------------------------------------------------------------------ DROP SEQUENCE Name DROP SEQUENCE -- remove a sequence Synopsis DROP SEQUENCE [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ] Description DROP SEQUENCE removes sequence number generators. A sequence can only be dropped by its owner or a superuser. Parameters IF EXISTS Do not throw an error if the sequence does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of a sequence. CASCADE Automatically drop objects that depend on the sequence. RESTRICT Refuse to drop the sequence if any objects depend on it. This is the default. Examples To remove the sequence serial: DROP SEQUENCE serial; Compatibility DROP SEQUENCE conforms to the SQL standard, except that the standard only allows one sequence to be dropped per command, and apart from the IF EXISTS option, which is a PostgreSQL extension. See Also CREATE_SEQUENCE, ALTER_SEQUENCE ------------------------------------------------------------------------ DROP TABLE Name DROP TABLE -- remove a table Synopsis DROP TABLE [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ] Description DROP TABLE removes tables from the database. Only its owner can drop a table. To empty a table of rows without destroying the table, use DELETE or TRUNCATE. DROP TABLE always removes any indexes, rules, triggers, and constraints that exist for the target table. However, to drop a table that is referenced by a view or a foreign-key constraint of another table, CASCADE must be specified. (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.) Parameters IF EXISTS Do not throw an error if the table does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of the table to drop. CASCADE Automatically drop objects that depend on the table (such as views). RESTRICT Refuse to drop the table if any objects depend on it. This is the default. Examples To destroy two tables, films and distributors: DROP TABLE films, distributors; Compatibility This command conforms to the SQL standard, except that the standard only allows one table to be dropped per command, and apart from the IF EXISTS option, which is a PostgreSQL extension. See Also ALTER_TABLE, CREATE_TABLE ------------------------------------------------------------------------ DROP TABLESPACE Name DROP TABLESPACE -- remove a tablespace Synopsis DROP TABLESPACE [ IF EXISTS ] tablespacename Description DROP TABLESPACE removes a tablespace from the system. A tablespace can only be dropped by its owner or a superuser. The tablespace must be empty of all database objects before it can be dropped. It is possible that objects in other databases might still reside in the tablespace even if no objects in the current database are using the tablespace. Also, if the tablespace is listed in the temp_tablespaces setting of any active session, the DROP might fail due to temporary files residing in the tablespace. Parameters IF EXISTS Do not throw an error if the tablespace does not exist. A notice is issued in this case. tablespacename The name of a tablespace. Notes DROP TABLESPACE cannot be executed inside a transaction block. Examples To remove tablespace mystuff from the system: DROP TABLESPACE mystuff; Compatibility DROP TABLESPACE is a PostgreSQL extension. See Also CREATE_TABLESPACE, ALTER_TABLESPACE ------------------------------------------------------------------------ DROP TEXT SEARCH CONFIGURATION Name DROP TEXT SEARCH CONFIGURATION -- remove a text search configuration Synopsis DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] name [ CASCADE | RESTRICT ] Description DROP TEXT SEARCH CONFIGURATION drops an existing text search configuration. To execute this command you must be the owner of the configuration. Parameters IF EXISTS Do not throw an error if the text search configuration does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an existing text search configuration. CASCADE Automatically drop objects that depend on the text search configuration. RESTRICT Refuse to drop the text search configuration if any objects depend on it. This is the default. Examples Remove the text search configuration my_english: DROP TEXT SEARCH CONFIGURATION my_english; This command will not succeed if there are any existing indexes that reference the configuration in to_tsvector calls. Add CASCADE to drop such indexes along with the text search configuration. Compatibility There is no DROP TEXT SEARCH CONFIGURATION statement in the SQL standard. See Also ALTER_TEXT_SEARCH_CONFIGURATION, CREATE_TEXT_SEARCH_CONFIGURATION ------------------------------------------------------------------------ DROP TEXT SEARCH DICTIONARY Name DROP TEXT SEARCH DICTIONARY -- remove a text search dictionary Synopsis DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] name [ CASCADE | RESTRICT ] Description DROP TEXT SEARCH DICTIONARY drops an existing text search dictionary. To execute this command you must be the owner of the dictionary. Parameters IF EXISTS Do not throw an error if the text search dictionary does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an existing text search dictionary. CASCADE Automatically drop objects that depend on the text search dictionary. RESTRICT Refuse to drop the text search dictionary if any objects depend on it. This is the default. Examples Remove the text search dictionary english: DROP TEXT SEARCH DICTIONARY english; This command will not succeed if there are any existing text search configurations that use the dictionary. Add CASCADE to drop such configurations along with the dictionary. Compatibility There is no DROP TEXT SEARCH DICTIONARY statement in the SQL standard. See Also ALTER_TEXT_SEARCH_DICTIONARY, CREATE_TEXT_SEARCH_DICTIONARY ------------------------------------------------------------------------ DROP TEXT SEARCH PARSER Name DROP TEXT SEARCH PARSER -- remove a text search parser Synopsis DROP TEXT SEARCH PARSER [ IF EXISTS ] name [ CASCADE | RESTRICT ] Description DROP TEXT SEARCH PARSER drops an existing text search parser. You must be a superuser to use this command. Parameters IF EXISTS Do not throw an error if the text search parser does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an existing text search parser. CASCADE Automatically drop objects that depend on the text search parser. RESTRICT Refuse to drop the text search parser if any objects depend on it. This is the default. Examples Remove the text search parser my_parser: DROP TEXT SEARCH PARSER my_parser; This command will not succeed if there are any existing text search configurations that use the parser. Add CASCADE to drop such configurations along with the parser. Compatibility There is no DROP TEXT SEARCH PARSER statement in the SQL standard. See Also ALTER_TEXT_SEARCH_PARSER, CREATE_TEXT_SEARCH_PARSER ------------------------------------------------------------------------ DROP TEXT SEARCH TEMPLATE Name DROP TEXT SEARCH TEMPLATE -- remove a text search template Synopsis DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] name [ CASCADE | RESTRICT ] Description DROP TEXT SEARCH TEMPLATE drops an existing text search template. You must be a superuser to use this command. Parameters IF EXISTS Do not throw an error if the text search template does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of an existing text search template. CASCADE Automatically drop objects that depend on the text search template. RESTRICT Refuse to drop the text search template if any objects depend on it. This is the default. Examples Remove the text search template thesaurus: DROP TEXT SEARCH TEMPLATE thesaurus; This command will not succeed if there are any existing text search dictionaries that use the template. Add CASCADE to drop such dictionaries along with the template. Compatibility There is no DROP TEXT SEARCH TEMPLATE statement in the SQL standard. See Also ALTER_TEXT_SEARCH_TEMPLATE, CREATE_TEXT_SEARCH_TEMPLATE ------------------------------------------------------------------------ DROP TRIGGER Name DROP TRIGGER -- remove a trigger Synopsis DROP TRIGGER [ IF EXISTS ] name ON table [ CASCADE | RESTRICT ] Description DROP TRIGGER removes an existing trigger definition. To execute this command, the current user must be the owner of the table for which the trigger is defined. Parameters IF EXISTS Do not throw an error if the trigger does not exist. A notice is issued in this case. name The name of the trigger to remove. table The name (optionally schema-qualified) of the table for which the trigger is defined. CASCADE Automatically drop objects that depend on the trigger. RESTRICT Refuse to drop the trigger if any objects depend on it. This is the default. Examples Destroy the trigger if_dist_exists on the table films: DROP TRIGGER if_dist_exists ON films; Compatibility The DROP TRIGGER statement in PostgreSQL is incompatible with the SQL standard. In the SQL standard, trigger names are not local to tables, so the command is simply DROP TRIGGER name. See Also CREATE_TRIGGER ------------------------------------------------------------------------ DROP TYPE Name DROP TYPE -- remove a data type Synopsis DROP TYPE [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ] Description DROP TYPE removes a user-defined data type. Only the owner of a type can remove it. Parameters IF EXISTS Do not throw an error if the type does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of the data type to remove. CASCADE Automatically drop objects that depend on the type (such as table columns, functions, operators). RESTRICT Refuse to drop the type if any objects depend on it. This is the default. Examples To remove the data type box: DROP TYPE box; Compatibility This command is similar to the corresponding command in the SQL standard, apart from the IF EXISTS option, which is a PostgreSQL extension. But note that the CREATE TYPE command and the data type extension mechanisms in PostgreSQL differ from the SQL standard. See Also CREATE_TYPE, ALTER_TYPE ------------------------------------------------------------------------ DROP USER Name DROP USER -- remove a database role Synopsis DROP USER [ IF EXISTS ] name [, ...] Description DROP USER is now an alias for DROP_ROLE. Compatibility The DROP USER statement is a PostgreSQL extension. The SQL standard leaves the definition of users to the implementation. See Also DROP_ROLE ------------------------------------------------------------------------ DROP VIEW Name DROP VIEW -- remove a view Synopsis DROP VIEW [ IF EXISTS ] name [, ...] [ CASCADE | RESTRICT ] Description DROP VIEW drops an existing view. To execute this command you must be the owner of the view. Parameters IF EXISTS Do not throw an error if the view does not exist. A notice is issued in this case. name The name (optionally schema-qualified) of the view to remove. CASCADE Automatically drop objects that depend on the view (such as other views). RESTRICT Refuse to drop the view if any objects depend on it. This is the default. Examples This command will remove the view called kinds: DROP VIEW kinds; Compatibility This command conforms to the SQL standard, except that the standard only allows one view to be dropped per command, and apart from the IF EXISTS option, which is a PostgreSQL extension. See Also ALTER_VIEW, CREATE_VIEW ------------------------------------------------------------------------ END Name END -- commit the current transaction Synopsis END [ WORK | TRANSACTION ] Description END commits the current transaction. All changes made by the transaction become visible to others and are guaranteed to be durable if a crash occurs. This command is a PostgreSQL extension that is equivalent to COMMIT. Parameters WORK TRANSACTION Optional key words. They have no effect. Notes Use ROLLBACK to abort a transaction. Issuing END when not inside a transaction does no harm, but it will provoke a warning message. Examples To commit the current transaction and make all changes permanent: END; Compatibility END is a PostgreSQL extension that provides functionality equivalent to COMMIT, which is specified in the SQL standard. See Also BEGIN, COMMIT, ROLLBACK ------------------------------------------------------------------------ EXECUTE Name EXECUTE -- execute a prepared statement Synopsis EXECUTE name [ ( parameter [, ...] ) ] Description EXECUTE is used to execute a previously prepared statement. Since prepared statements only exist for the duration of a session, the prepared statement must have been created by a PREPARE statement executed earlier in the current session. If the PREPARE statement that created the statement specified some parameters, a compatible set of parameters must be passed to the EXECUTE statement, or else an error is raised. Note that (unlike functions) prepared statements are not overloaded based on the type or number of their parameters; the name of a prepared statement must be unique within a database session. For more information on the creation and usage of prepared statements, see PREPARE. Parameters name The name of the prepared statement to execute. parameter The actual value of a parameter to the prepared statement. This must be an expression yielding a value that is compatible with the data type of this parameter, as was determined when the prepared statement was created. Outputs The command tag returned by EXECUTE is that of the prepared statement, and not EXECUTE. Examples Examples are given in the Examples section of the PREPARE documentation. Compatibility The SQL standard includes an EXECUTE statement, but it is only for use in embedded SQL. This version of the EXECUTE statement also uses a somewhat different syntax. See Also DEALLOCATE, PREPARE ------------------------------------------------------------------------ EXPLAIN Name EXPLAIN -- show the execution plan of a statement Synopsis EXPLAIN [ ANALYZE ] [ VERBOSE ] statement Description This command displays the execution plan that the PostgreSQL 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 rows from each input table. The most critical part of the display is the estimated statement execution cost, which is the planner's guess at how long it will take to run the statement (measured in units of disk page fetches). Actually two numbers are shown: the start-up time before the first row can be returned, and the total time to return all the rows. For most queries the total time is what matters, but in contexts such as a subquery in EXISTS, the planner will choose the smallest start-up time instead of the smallest total time (since the executor will stop after getting one row, anyway). Also, if you limit the number of rows to return with a LIMIT clause, the planner makes an appropriate interpolation between the endpoint costs to estimate which plan is really the cheapest. The ANALYZE option causes the statement to be actually executed, not only planned. The total elapsed time expended within each plan node (in milliseconds) and total number of rows it actually returned are added to the display. This is useful for seeing whether the planner's estimates are close to reality. Important: Keep in mind that the statement is actually executed when the ANALYZE option is used. Although EXPLAIN will discard any output that a SELECT would return, other side effects of the statement will happen as usual. If you wish to use EXPLAIN ANALYZE on an INSERT, UPDATE, DELETE, or EXECUTE statement without letting the command affect your data, use this approach: BEGIN; EXPLAIN ANALYZE ...; ROLLBACK; Parameters ANALYZE Carry out the command and show the actual run times. VERBOSE Show the full internal representation of the plan tree, rather than just a summary. Usually this option is only useful for specialized debugging purposes. The VERBOSE output is either pretty-printed or not, depending on the setting of the explain_pretty_print configuration parameter. statement Any SELECT, INSERT, UPDATE, DELETE, VALUES, EXECUTE, or DECLARE statement, whose execution plan you wish to see. Notes There is only sparse documentation on the optimizer's use of cost information in PostgreSQL. Refer to Section_14.1 for more information. In order to allow the PostgreSQL query planner to make reasonably informed decisions when optimizing queries, the ANALYZE statement should be run to record statistics about the distribution of data within the table. If you have not done this (or if the statistical distribution of the data in the table has changed significantly since the last time ANALYZE was run), the estimated costs are unlikely to conform to the real properties of the query, and consequently an inferior query plan might be chosen. Genetic query optimization (GEQO) randomly tests execution plans. Therefore, when the number of join relations exceeds geqo_threshold causing genetic query optimization to be used, the execution plan is likely to change each time the statement is executed. In order to measure the run-time cost of each node in the execution plan, the current implementation of EXPLAIN ANALYZE can add considerable profiling overhead to query execution. As a result, running EXPLAIN ANALYZE on a query can sometimes take significantly longer than executing the query normally. The amount of overhead depends on the nature of the query. Examples To show the plan for a simple query on a table with a single integer column and 10000 rows: EXPLAIN SELECT * FROM foo; QUERY PLAN --------------------------------------------------------- Seq Scan on foo (cost=0.00..155.00 rows=10000 width=4) (1 row) If there is an index and we use a query with an indexable WHERE condition, EXPLAIN might show a different plan: EXPLAIN SELECT * FROM foo WHERE i = 4; QUERY PLAN -------------------------------------------------------------- Index Scan using fi on foo (cost=0.00..5.98 rows=1 width=4) Index Cond: (i = 4) (2 rows) Here is an example of a query plan for a query using an aggregate function: EXPLAIN SELECT sum(i) FROM foo WHERE i < 10; QUERY PLAN ------------------------------------------------------------------------ FETCH Name FETCH -- retrieve rows from a query using a cursor Synopsis FETCH [ direction { FROM | IN } ] cursorname where direction can be empty or one of: NEXT PRIOR FIRST LAST ABSOLUTE count RELATIVE count count ALL FORWARD FORWARD count FORWARD ALL BACKWARD BACKWARD count BACKWARD ALL Description FETCH retrieves rows using a previously-created cursor. A cursor has an associated position, which is used by FETCH. The cursor position can be before the first row of the query result, on any particular row of the result, or after the last row of the result. When created, a cursor is positioned before the first row. After fetching some rows, the cursor is positioned on the row most recently retrieved. If FETCH runs off the end of the available rows then the cursor is left positioned after the last row, or before the first row if fetching backward. FETCH ALL or FETCH BACKWARD ALL will always leave the cursor positioned after the last row or before the first row. The forms NEXT, PRIOR, FIRST, LAST, ABSOLUTE, RELATIVE fetch a single row after moving the cursor appropriately. If there is no such row, an empty result is returned, and the cursor is left positioned before the first row or after the last row as appropriate. The forms using FORWARD and BACKWARD retrieve the indicated number of rows moving in the forward or backward direction, leaving the cursor positioned on the last-returned row (or after/before all rows, if the count exceeds the number of rows available). RELATIVE 0, FORWARD 0, and BACKWARD 0 all request fetching the current row without moving the cursor, that is, re-fetching the most recently fetched row. This will succeed unless the cursor is positioned before the first row or after the last row; in which case, no row is returned. Parameters NEXT Fetch the next row. This is the default if direction is omitted. PRIOR Fetch the prior row. FIRST Fetch the first row of the query (same as ABSOLUTE 1). LAST Fetch the last row of the query (same as ABSOLUTE -1). ABSOLUTE count Fetch the count'th row of the query, or the abs(count)'th row from the end if count is negative. Position before first row or after last row if count is out of range; in particular, ABSOLUTE 0 positions before the first row. RELATIVE count Fetch the count'th succeeding row, or the abs(count)'th prior row if count is negative. RELATIVE 0 re-fetches the current row, if any. count Fetch the next count rows (same as FORWARD count). ALL Fetch all remaining rows (same as FORWARD ALL). FORWARD Fetch the next row (same as NEXT). FORWARD count Fetch the next count rows. FORWARD 0 re-fetches the current row. FORWARD ALL Fetch all remaining rows. BACKWARD Fetch the prior row (same as PRIOR). BACKWARD count Fetch the prior count rows (scanning backwards). BACKWARD 0 re- fetches the current row. BACKWARD ALL Fetch all prior rows (scanning backwards). count count is a possibly-signed integer constant, determining the location or number of rows to fetch. For FORWARD and BACKWARD cases, specifying a negative count is equivalent to changing the sense of FORWARD and BACKWARD. cursorname An open cursor's name. Outputs On successful completion, a FETCH command returns a command tag of the form FETCH count The count is the number of rows fetched (possibly zero). Note that in psql, the command tag will not actually be displayed, since psql displays the fetched rows instead. Notes The cursor should be declared with the SCROLL option if one intends to use any variants of FETCH other than FETCH NEXT or FETCH FORWARD with a positive count. For simple queries PostgreSQL will allow backwards fetch from cursors not declared with SCROLL, but this behavior is best not relied on. If the cursor is declared with NO SCROLL, no backward fetches are allowed. ABSOLUTE fetches are not any faster than navigating to the desired row with a relative move: the underlying implementation must traverse all the intermediate rows anyway. Negative absolute fetches are even worse: the query must be read to the end to find the last row, and then traversed backward from there. However, rewinding to the start of the query (as with FETCH ABSOLUTE 0) is fast. DECLARE is used to define a cursor. Use MOVE to change cursor position without retrieving data. Examples The following example traverses a table using a cursor: BEGIN WORK; -- Set up a cursor: DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films; -- Fetch the first 5 rows in the cursor liahona: FETCH FORWARD 5 FROM liahona; code | title | did | date_prod | kind | len -------+-------------------------+-----+------------+----------+------- BL101 | The Third Man | 101 | 1949-12-23 | Drama | 01:44 BL102 | The African Queen | 101 | 1951-08-11 | Romantic | 01:43 JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic | 01:25 P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08 P_302 | Becket | 103 | 1964-02-03 | Drama | 02:28 -- Fetch the previous row: FETCH PRIOR FROM liahona; code | title | did | date_prod | kind | len -------+---------+-----+------------+--------+------- P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08 -- Close the cursor and end the transaction: CLOSE liahona; COMMIT WORK; Compatibility The SQL standard defines FETCH for use in embedded SQL only. The variant of FETCH described here returns the data as if it were a SELECT result rather than placing it in host variables. Other than this point, FETCH is fully upward-compatible with the SQL standard. The FETCH forms involving FORWARD and BACKWARD, as well as the forms FETCH count and FETCH ALL, in which FORWARD is implicit, are PostgreSQL extensions. The SQL standard allows only FROM preceding the cursor name; the option to use IN is an extension. See Also CLOSE, DECLARE, MOVE ------------------------------------------------------------------------ GRANT Name GRANT -- define access privileges Synopsis GRANT { { SELECT | INSERT | UPDATE | DELETE | REFERENCES | TRIGGER } [,...] | ALL [ PRIVILEGES ] } ON [ TABLE ] tablename [, ...] TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ] GRANT { { USAGE | SELECT | UPDATE } [,...] | ALL [ PRIVILEGES ] } ON SEQUENCE sequencename [, ...] TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ] GRANT { { CREATE | CONNECT | TEMPORARY | TEMP } [,...] | ALL [ PRIVILEGES ] } ON DATABASE dbname [, ...] TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ] GRANT { EXECUTE | ALL [ PRIVILEGES ] } ON FUNCTION funcname ( [ [ argmode ] [ argname ] argtype [, ...] ] ) [, ...] TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ] GRANT { USAGE | ALL [ PRIVILEGES ] } ON LANGUAGE langname [, ...] TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ] GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } ON SCHEMA schemaname [, ...] TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ] GRANT { CREATE | ALL [ PRIVILEGES ] } ON TABLESPACE tablespacename [, ...] TO { [ GROUP ] rolename | PUBLIC } [, ...] [ WITH GRANT OPTION ] GRANT role [, ...] TO rolename [, ...] [ WITH ADMIN OPTION ] Description The GRANT command has two basic variants: one that grants privileges on a database object (table, view, sequence, database, function, procedural language, schema, or tablespace), and one that grants membership in a role. These variants are similar in many ways, but they are different enough to be described separately. As of PostgreSQL 8.1, the concepts of users and groups have been unified into a single kind of entity called a role. It is therefore no longer necessary to use the keyword GROUP to identify whether a grantee is a user or a group. GROUP is still allowed in the command, but it is a noise word. GRANT on Database Objects This variant of the GRANT command gives specific privileges on a database object to one or more roles. These privileges are added to those already granted, if any. The key word PUBLIC indicates that the privileges are to be granted to all roles, including those that might be created later. PUBLIC can be thought of as an implicitly defined group that always includes all roles. Any particular role will have the sum of privileges granted directly to it, privileges granted to any role it is presently a member of, and privileges granted to PUBLIC. If WITH GRANT OPTION is specified, the recipient of the privilege can in turn grant it to others. Without a grant option, the recipient cannot do that. Grant options cannot be granted to PUBLIC. There is no need to grant privileges to the owner of an object (usually the user that created it), as the owner has all privileges by default. (The owner could, however, choose to revoke some of his own privileges for safety.) The right to drop an object, or to alter its definition in any way is not described by a grantable privilege; it is inherent in the owner, and cannot be granted or revoked. The owner implicitly has all grant options for the object, too. Depending on the type of object, the initial default privileges might include granting some privileges to PUBLIC. The default is no public access for tables, schemas, and tablespaces; CONNECT privilege and TEMP table creation privilege for databases; EXECUTE privilege for functions; and USAGE privilege for languages. The object owner can of course revoke these privileges. (For maximum security, issue the REVOKE in the same transaction that creates the object; then there is no window in which another user can use the object.) The possible privileges are: SELECT Allows SELECT from any column of the specified table, view, or sequence. Also allows the use of COPY TO. This privilege is also needed to reference existing column values in UPDATE or DELETE. For sequences, this privilege also allows the use of the currval function. INSERT Allows INSERT of a new row into the specified table. Also allows COPY FROM. UPDATE Allows UPDATE of any column of the specified table. (In practice, any nontrivial UPDATE command will require SELECT privilege as well, since it must reference table columns to determine which rows to update, and/or to compute new values for columns.) SELECT ... FOR UPDATE and SELECT ... FOR SHARE also require this privilege, in addition to the SELECT privilege. For sequences, this privilege allows the use of the nextval and setval functions. DELETE Allows DELETE of a row from the specified table. (In practice, any nontrivial DELETE command will require SELECT privilege as well, since it must reference table columns to determine which rows to delete.) REFERENCES To create a foreign key constraint, it is necessary to have this privilege on both the referencing and referenced tables. TRIGGER Allows the creation of a trigger on the specified table. (See the CREATE_TRIGGER statement.) CREATE For databases, allows new schemas to be created within the database. For schemas, allows new objects to be created within the schema. To rename an existing object, you must own the object and have this privilege for the containing schema. For tablespaces, allows tables, indexes, and temporary files to be created within the tablespace, and allows databases to be created that have the tablespace as their default tablespace. (Note that revoking this privilege will not alter the placement of existing objects.) CONNECT Allows the user to connect to the specified database. This privilege is checked at connection startup (in addition to checking any restrictions imposed by pg_hba.conf). TEMPORARY TEMP Allows temporary tables to be created while using the specified database. EXECUTE Allows the use of the specified function and the use of any operators that are implemented on top of the function. This is the only type of privilege that is applicable to functions. (This syntax works for aggregate functions, as well.) USAGE For procedural languages, allows the use of the specified language for the creation of functions in that language. This is the only type of privilege that is applicable to procedural languages. For schemas, allows access to objects contained in the specified schema (assuming that the objects' own privilege requirements are also met). Essentially this allows the grantee to "look up" objects within the schema. Without this permission, it is still possible to see the object names, e.g. by querying the system tables. Also, after revoking this permission, existing backends might have statements that have previously performed this lookup, so this is not a completely secure way to prevent object access. For sequences, this privilege allows the use of the currval and nextval functions. ALL PRIVILEGES Grant all of the available privileges at once. The PRIVILEGES key word is optional in PostgreSQL, though it is required by strict SQL. The privileges required by other commands are listed on the reference page of the respective command. GRANT on Roles This variant of the GRANT command grants membership in a role to one or more other roles. Membership in a role is significant because it conveys the privileges granted to a role to each of its members. If WITH ADMIN OPTION is specified, the member can in turn grant membership in the role to others, and revoke membership in the role as well. Without the admin option, ordinary users cannot do that. However, database superusers can grant or revoke membership in any role to anyone. Roles having CREATEROLE privilege can grant or revoke membership in any role that is not a superuser. Unlike the case with privileges, membership in a role cannot be granted to PUBLIC. Note also that this form of the command does not allow the noise word GROUP. Notes The REVOKE command is used to revoke access privileges. When a non-owner of an object attempts to GRANT privileges on the object, the command will fail outright if the user has no privileges whatsoever on the object. As long as some privilege is available, the command will proceed, but it will grant only those privileges for which the user has grant options. The GRANT ALL PRIVILEGES forms will issue a warning message if no grant options are held, while the other forms will issue a warning if grant options for any of the privileges specifically named in the command are not held. (In principle these statements apply to the object owner as well, but since the owner is always treated as holding all grant options, the cases can never occur.) It should be noted that database superusers can access all objects regardless of object privilege settings. This is comparable to the rights of root in a Unix system. As with root, it's unwise to operate as a superuser except when absolutely necessary. If a superuser chooses to issue a GRANT or REVOKE command, the command is performed as though it were issued by the owner of the affected object. In particular, privileges granted via such a command will appear to have been granted by the object owner. (For role membership, the membership appears to have been granted by the containing role itself.) GRANT and REVOKE can also be done by a role that is not the owner of the affected object, but is a member of the role that owns the object, or is a member of a role that holds privileges WITH GRANT OPTION on the object. In this case the privileges will be recorded as having been granted by the role that actually owns the object or holds the privileges WITH GRANT OPTION. For example, if table t1 is owned by role g1, of which role u1 is a member, then u1 can grant privileges on t1 to u2, but those privileges will appear to have been granted directly by g1. Any other member of role g1 could revoke them later. If the role executing GRANT holds the required privileges indirectly via more than one role membership path, it is unspecified which containing role will be recorded as having done the grant. In such cases it is best practice to use SET ROLE to become the specific role you want to do the GRANT as. Granting permission on a table does not automatically extend permissions to any sequences used by the table, including sequences tied to SERIAL columns. Permissions on sequence must be set separately. Currently, PostgreSQL does not support granting or revoking privileges for individual columns of a table. One possible workaround is to create a view having just the desired columns and then grant privileges to that view. Use psql's \z command to obtain information about existing privileges, for example: => \z mytable Access privileges for database "lusitania" Schema | Name | Type | Access privileges --------+---------+-------+---------------------------------------------- ----- public | mytable | table | {miriam=arwdxt/miriam,=r/miriam,admin=arw/ miriam} (1 row) The entries shown by \z are interpreted thus: rolename=xxxx -- privileges granted to a role =xxxx -- privileges granted to PUBLIC r -- SELECT ("read") w -- UPDATE ("write") a -- INSERT ("append") d -- DELETE x -- REFERENCES t -- TRIGGER X -- EXECUTE U -- USAGE C -- CREATE c -- CONNECT T -- TEMPORARY arwdxt -- ALL PRIVILEGES (for tables) * -- grant option for preceding privilege /yyyy -- role that granted this privilege The above example display would be seen by user miriam after creating table mytable and doing: GRANT SELECT ON mytable TO PUBLIC; GRANT SELECT, UPDATE, INSERT ON mytable TO admin; If the "Access privileges" column is empty for a given object, it means the object has default privileges (that is, its privileges column is null). Default privileges always include all privileges for the owner, and can include some privileges for PUBLIC depending on the object type, as explained above. The first GRANT or REVOKE on an object will instantiate the default privileges (producing, for example, {miriam=arwdxt/miriam}) and then modify them per the specified request. Notice that the owner's implicit grant options are not marked in the access privileges display. A * will appear only when grant options have been explicitly granted to someone. Examples Grant insert privilege to all users on table films: GRANT INSERT ON films TO PUBLIC; Grant all available privileges to user manuel on view kinds: GRANT ALL PRIVILEGES ON kinds TO manuel; Note that while the above will indeed grant all privileges if executed by a superuser or the owner of kinds, when executed by someone else it will only grant those permissions for which the someone else has grant options. Grant membership in role admins to user joe: GRANT admins TO joe; Compatibility According to the SQL standard, the PRIVILEGES key word in ALL PRIVILEGES is required. The SQL standard does not support setting the privileges on more than one object per command. PostgreSQL allows an object owner to revoke his own ordinary privileges: for example, a table owner can make the table read-only to himself by revoking his own INSERT, UPDATE, and DELETE privileges. This is not possible according to the SQL standard. The reason is that PostgreSQL treats the owner's privileges as having been granted by the owner to himself; therefore he can revoke them too. In the SQL standard, the owner's privileges are granted by an assumed entity "_SYSTEM". Not being "_SYSTEM", the owner cannot revoke these rights. PostgreSQL does not support the SQL-standard functionality of setting privileges for individual columns. The SQL standard provides for a USAGE privilege on other kinds of objects: character sets, collations, translations, domains. Privileges on databases, tablespaces, schemas, and languages are PostgreSQL extensions. See Also REVOKE ------------------------------------------------------------------------ INSERT Name INSERT -- create new rows in a table Synopsis INSERT INTO table [ ( column [, ...] ) ] { DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query } [ RETURNING * | output_expression [ AS output_name ] [, ...] ] Description INSERT inserts new rows into a table. One can insert one or more rows specified by value expressions, or zero or more rows resulting from a query. The target column names can 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 N column names, if there are only N columns supplied by the VALUES clause or query. The values supplied by the VALUES clause or query are associated with the explicit or implicit column list left-to-right. 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. If the expression for any column is not of the correct data type, automatic type conversion will be attempted. The optional RETURNING clause causes INSERT to compute and return value(s) based on each row actually inserted. This is primarily useful for obtaining values that were supplied by defaults, such as a serial sequence number. However, any expression using the table's columns is allowed. The syntax of the RETURNING list is identical to that of the output list of SELECT. You must have INSERT privilege on a table in order to insert into it, and SELECT privilege on it to use RETURNING. If you use the query clause to insert rows from a query, you also need to have SELECT privilege on any table used in the query. Parameters table The name (optionally schema-qualified) of an existing table. column The name of a column in table. The column name can be qualified with a subfield name or array subscript, if needed. (Inserting into only some fields of a composite column leaves the other fields null.) DEFAULT VALUES All columns will be filled with their default values. expression An expression or value to assign to the corresponding column. DEFAULT The corresponding column will be filled with its default value. query A query (SELECT statement) that supplies the rows to be inserted. Refer to the SELECT statement for a description of the syntax. output_expression An expression to be computed and returned by the INSERT command after each row is inserted. The expression can use any column names of the table. Write * to return all columns of the inserted row(s). output_name A name to use for a returned column. Outputs On successful completion, an INSERT command returns a command tag of the form INSERT oid count The count is the number of rows inserted. If count is exactly one, and the target table has OIDs, then oid is the OID assigned to the inserted row. Otherwise oid is zero. If the INSERT command contains a RETURNING clause, the result will be similar to that of a SELECT statement containing the columns and values defined in the RETURNING list, computed over the row(s) inserted by the command. Examples Insert a single row into table films: INSERT INTO films VALUES ('UA502', 'Bananas', 105, '1971-07-13', 'Comedy', '82 minutes'); In this example, the len column is omitted and therefore it will have the default value: INSERT INTO films (code, title, did, date_prod, kind) VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama'); This example uses the DEFAULT clause for the date columns rather than specifying a value: INSERT INTO films VALUES ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes'); INSERT INTO films (code, title, did, date_prod, kind) VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama'); To insert a row consisting entirely of default values: INSERT INTO films DEFAULT VALUES; To insert multiple rows using the multirow VALUES syntax: INSERT INTO films (code, title, did, date_prod, kind) VALUES ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'), ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy'); This example inserts some rows into table films from a table tmp_films with the same column layout as films: INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07'; This example inserts into array columns: -- Create an empty 3x3 gameboard for noughts-and-crosses INSERT INTO tictactoe (game, board[1:3][1:3]) VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}'); -- The subscripts in the above example aren't really needed INSERT INTO tictactoe (game, board) VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}'); Insert a single row into table distributors, returning the sequence number generated by the DEFAULT clause: INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets') RETURNING did; Compatibility INSERT conforms to the SQL standard, except that the RETURNING clause is a PostgreSQL extension. Also, the case in which a column name list is omitted, but not all the columns are filled from the VALUES clause or query, is disallowed by the standard. Possible limitations of the query clause are documented under SELECT. ------------------------------------------------------------------------ LISTEN Name LISTEN -- listen for a notification Synopsis LISTEN name Description LISTEN registers the current session as a listener on the notification condition name. If the current session is already registered as a listener for this notification condition, nothing is done. Whenever the command NOTIFY name is invoked, either by this session or another one connected to the same database, all the sessions currently listening on that notification condition are notified, and each will in turn notify its connected client application. See the discussion of NOTIFY for more information. A session can be unregistered for a given notify condition with the UNLISTEN command. A session's listen registrations are automatically cleared when the session ends. The method a client application must use to detect notification events depends on which PostgreSQL application programming interface it uses. With the libpq library, the application issues LISTEN as an ordinary SQL command, and then must periodically call the function PQnotifies to find out whether any notification events have been received. Other interfaces such as libpgtcl provide higher-level methods for handling notify events; indeed, with libpgtcl the application programmer should not even issue LISTEN or UNLISTEN directly. See the documentation for the interface you are using for more details. NOTIFY contains a more extensive discussion of the use of LISTEN and NOTIFY. Parameters name Name of a notify condition (any identifier). Examples Configure and execute a listen/notify sequence from psql: LISTEN virtual; NOTIFY virtual; Asynchronous notification "virtual" received from server process with PID 8448. Compatibility There is no LISTEN statement in the SQL standard. See Also NOTIFY, UNLISTEN ------------------------------------------------------------------------ LOAD Name LOAD -- load or reload a shared library file Synopsis LOAD 'filename' Description This command loads a shared library file into the PostgreSQL server's address space. If the file had been loaded previously, it is first unloaded. This command is primarily useful to unload and reload a shared library file that has been changed since the server first loaded it. To make use of the shared library, function(s) in it need to be declared using the CREATE_FUNCTION command. The file name is specified in the same way as for shared library names in CREATE_FUNCTION; in particular, one can rely on a search path and automatic addition of the system's standard shared library file name extension. See Section_34.9 for more information on this topic. Non-superusers can only apply LOAD to library files located in $libdir/ plugins/ -- the specified filename must begin with exactly that string. (It is the database administrator's responsibility to ensure that only "safe" libraries are installed there.) Compatibility LOAD is a PostgreSQL extension. See Also CREATE_FUNCTION ------------------------------------------------------------------------ LOCK Name LOCK -- lock a table Synopsis LOCK [ TABLE ] name [, ...] [ IN lockmode MODE ] [ NOWAIT ] where lockmode is one of: ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE | SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE Description LOCK TABLE obtains a table-level lock, waiting if necessary for any conflicting locks to be released. If NOWAIT is specified, LOCK TABLE does not wait to acquire the desired lock: if it cannot be acquired immediately, the command is aborted and an error is emitted. Once obtained, the lock is held for the remainder of the current transaction. (There is no UNLOCK TABLE command; locks are always released at transaction end.) When acquiring locks automatically for commands that reference tables, PostgreSQL always uses the least restrictive lock mode possible. LOCK TABLE provides for cases when you might need more restrictive locking. For example, suppose an application runs a transaction at the 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 SHARE lock mode over the table before querying. This will prevent concurrent data changes and ensure subsequent reads of the table see a stable view of committed data, because SHARE lock mode conflicts with the ROW EXCLUSIVE lock acquired by writers, and your LOCK TABLE name IN SHARE MODE statement will wait until any concurrent holders of ROW EXCLUSIVE mode locks commit or roll back. Thus, once you obtain the lock, there are no uncommitted writes outstanding; furthermore none can begin until you release the lock. To achieve a similar effect when running a transaction at the Serializable isolation level, you have to execute the LOCK TABLE statement before executing any SELECT or data modification statement. A serializable transaction's view of data will be frozen when its first SELECT or data modification statement begins. A 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. If a transaction of this sort is going to change the data in the table, then it should use SHARE ROW EXCLUSIVE lock mode instead of SHARE mode. This ensures that only one transaction of this type runs at a time. Without this, a deadlock is possible: two transactions might both acquire SHARE mode, and then be unable to also acquire ROW EXCLUSIVE mode to actually perform their updates. (Note that a transaction's own locks never conflict, so a transaction can acquire ROW EXCLUSIVE mode when it holds SHARE mode - - but not if anyone else holds SHARE mode.) To avoid deadlocks, make sure all transactions acquire locks on the same objects in the same order, and if multiple lock modes are involved for a single object, then transactions should always acquire the most restrictive mode first. More information about the lock modes and locking strategies can be found in Section_13.3. Parameters name The name (optionally schema-qualified) of an existing table to lock. The command LOCK TABLE a, b; is equivalent to LOCK TABLE a; LOCK TABLE b;. The tables are locked one-by-one in the order specified in the LOCK TABLE command. lockmode The lock mode specifies which locks this lock conflicts with. Lock modes are described in Section_13.3. If no lock mode is specified, then ACCESS EXCLUSIVE, the most restrictive mode, is used. NOWAIT Specifies that LOCK TABLE should not wait for any conflicting locks to be released: if the specified lock(s) cannot be acquired immediately without waiting, the transaction is aborted. Notes LOCK TABLE ... IN ACCESS SHARE MODE requires SELECT privileges on the target table. All other forms of LOCK require UPDATE and/or DELETE privileges. LOCK TABLE is useful only inside a transaction block (BEGIN/COMMIT pair), since the lock is dropped as soon as the transaction ends. A LOCK TABLE command appearing outside any transaction block forms a self-contained transaction, so the lock will be dropped as soon as it is obtained. LOCK TABLE only deals with table-level locks, and so the mode names involving ROW are all misnomers. These mode names should generally be read as indicating the intention of the user to acquire row-level locks within the locked table. Also, ROW EXCLUSIVE mode is a sharable table lock. Keep in mind that all the lock modes have identical semantics so far as LOCK TABLE is concerned, differing only in the rules about which modes conflict with which. For information on how to acquire an actual row-level lock, see Section_13.3.2 and the FOR_UPDATE/FOR_SHARE_Clause in the SELECT reference documentation. Examples Obtain a SHARE lock on a primary key table when going to perform inserts into a foreign key table: BEGIN WORK; LOCK TABLE films IN SHARE MODE; SELECT id FROM films WHERE name = 'Star Wars: Episode I - The Phantom Menace'; -- Do ROLLBACK if record was not returned INSERT INTO films_user_comments VALUES (_id_, 'GREAT! I was waiting for it for so long!'); COMMIT WORK; Take a SHARE ROW EXCLUSIVE lock on a primary key table when going to perform a delete operation: BEGIN WORK; LOCK TABLE films IN SHARE ROW EXCLUSIVE MODE; DELETE FROM films_user_comments WHERE id IN (SELECT id FROM films WHERE rating < 5); DELETE FROM films WHERE rating < 5; COMMIT WORK; Compatibility There is no LOCK TABLE in the SQL standard, which instead uses SET TRANSACTION to specify concurrency levels on transactions. PostgreSQL supports that too; see SET_TRANSACTION for details. Except for ACCESS SHARE, ACCESS EXCLUSIVE, and SHARE UPDATE EXCLUSIVE lock modes, the PostgreSQL lock modes and the LOCK TABLE syntax are compatible with those present in Oracle. ------------------------------------------------------------------------ MOVE Name MOVE -- position a cursor Synopsis MOVE [ direction { FROM | IN } ] cursorname Description MOVE repositions a cursor without retrieving any data. MOVE works exactly like the FETCH command, except it only positions the cursor and does not return rows. Refer to FETCH for details on syntax and usage. Outputs On successful completion, a MOVE command returns a command tag of the form MOVE count The count is the number of rows that a FETCH command with the same parameters would have returned (possibly zero). Examples BEGIN WORK; DECLARE liahona CURSOR FOR SELECT * FROM films; -- Skip the first 5 rows: MOVE FORWARD 5 IN liahona; MOVE 5 -- Fetch the 6th row from the cursor liahona: FETCH 1 FROM liahona; code | title | did | date_prod | kind | len -------+--------+-----+------------+--------+------- P_303 | 48 Hrs | 103 | 1982-10-22 | Action | 01:37 (1 row) -- Close the cursor liahona and end the transaction: CLOSE liahona; COMMIT WORK; Compatibility There is no MOVE statement in the SQL standard. See Also CLOSE, DECLARE, FETCH ------------------------------------------------------------------------ NOTIFY Name NOTIFY -- generate a notification Synopsis NOTIFY name Description The NOTIFY command sends a notification event to each client application that has previously executed LISTEN name for the specified notification name in the current database. NOTIFY provides a simple form of signal or interprocess communication mechanism for a collection of processes accessing the same PostgreSQL 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). The information passed to the client for a notification event includes the notification name and the notifying session's server process PID. It is up to the database designer to define the notification names that will be used in a given database and what each one means. Commonly, the notification name is the same as the name of some table in the database, and the notify event essentially means, "I changed this table, take a look at it to see what's new". But no such association is enforced by the NOTIFY and LISTEN commands. For example, a database designer could use several different notification names to signal different sorts of changes to a single table. When NOTIFY is used to signal the occurrence of changes to a particular table, a useful programming technique is to put the NOTIFY in a rule that is triggered by table updates. In this way, notification happens automatically when the table is changed, and the application programmer cannot accidentally forget to do it. NOTIFY interacts with SQL transactions in some important ways. Firstly, if a NOTIFY is executed inside a transaction, the notify events are not delivered until and unless the transaction is committed. This is appropriate, since if the transaction is aborted, all the commands within it have had no effect, including NOTIFY. But it can be disconcerting if one is expecting the notification events to be delivered immediately. Secondly, if a listening session receives a notification signal while it is within a transaction, 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 the server cannot "take back" 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 NOTIFY for real-time signaling should try to keep their transactions short. NOTIFY behaves like Unix signals in one important respect: if the same notification name is signaled multiple times in quick succession, recipients might get only one notification event for several executions of NOTIFY. So it is a bad idea to depend on the number of notifications received. Instead, use NOTIFY to wake up applications that need to pay attention to something, and use a database object (such as a sequence) to keep track of what happened or how many times it happened. It is common for a client that executes NOTIFY to be listening on the same notification name itself. In that case it will get back a notification event, just like all the other listening sessions. Depending on the application logic, this could result in useless work, for example, reading a database table to find the same updates that that session just wrote out. It is possible to avoid such extra work by noticing whether the notifying session's server process PID (supplied in the notification event message) is the same as one's own session's PID (available from libpq). When they are the same, the notification event is one's own work bouncing back, and can be ignored. (Despite what was said in the preceding paragraph, this is a safe technique. PostgreSQL keeps self-notifications separate from notifications arriving from other sessions, so you cannot miss an outside notification by ignoring your own notifications.) Parameters name Name of the notification to be signaled (any identifier). Examples Configure and execute a listen/notify sequence from psql: LISTEN virtual; NOTIFY virtual; Asynchronous notification "virtual" received from server process with PID 8448. Compatibility There is no NOTIFY statement in the SQL standard. See Also LISTEN, UNLISTEN ------------------------------------------------------------------------ PREPARE Name PREPARE -- prepare a statement for execution Synopsis PREPARE name [ ( datatype [, ...] ) ] AS statement Description PREPARE creates a prepared statement. A prepared statement is a server-side object that can be used to optimize performance. When the PREPARE statement is executed, the specified statement is parsed, rewritten, and planned. When an EXECUTE command is subsequently issued, the prepared statement need only be executed. Thus, the parsing, rewriting, and planning stages are only performed once, instead of every time the statement is executed. Prepared statements can take parameters: values that are substituted into the statement when it is executed. When creating the prepared statement, refer to parameters by position, using $1, $2, etc. A corresponding list of parameter data types can optionally be specified. When a parameter's data type is not specified or is declared as unknown, the type is inferred from the context in which the parameter is used (if possible). When executing the statement, specify the actual values for these parameters in the EXECUTE statement. Refer to EXECUTE for more information about that. Prepared statements only last for the duration of the current database session. When the session ends, the prepared statement is forgotten, so it must be recreated before being used again. This also means that a single prepared statement cannot be used by multiple simultaneous database clients; however, each client can create their own prepared statement to use. The prepared statement can be manually cleaned up using the DEALLOCATE command. Prepared statements have the largest performance advantage when a single session is being used to execute a large number of similar statements. The performance difference will be particularly significant if the statements are complex to plan or rewrite, for example, if the query involves a join of many tables or requires the application of several rules. If the statement is relatively simple to plan and rewrite but relatively expensive to execute, the performance advantage of prepared statements will be less noticeable. Parameters name An arbitrary name given to this particular prepared statement. It must be unique within a single session and is subsequently used to execute or deallocate a previously prepared statement. datatype The data type of a parameter to the prepared statement. If the data type of a particular parameter is unspecified or is specified as unknown, it will be inferred from the context in which the parameter is used. To refer to the parameters in the prepared statement itself, use $1, $2, etc. statement Any SELECT, INSERT, UPDATE, DELETE, or VALUES statement. Notes In some situations, the query plan produced for a prepared statement will be inferior to the query plan that would have been chosen if the statement had been submitted and executed normally. This is because when the statement is planned and the planner attempts to determine the optimal query plan, the actual values of any parameters specified in the statement are unavailable. PostgreSQL collects statistics on the distribution of data in the table, and can use constant values in a statement to make guesses about the likely result of executing the statement. Since this data is unavailable when planning prepared statements with parameters, the chosen plan might be suboptimal. To examine the query plan PostgreSQL has chosen for a prepared statement, use EXPLAIN. For more information on query planning and the statistics collected by PostgreSQL for that purpose, see the ANALYZE documentation. You can see all available prepared statements of a session by querying the pg_prepared_statements system view. Examples Create a prepared statement for an INSERT statement, and then execute it: PREPARE fooplan (int, text, bool, numeric) AS INSERT INTO foo VALUES($1, $2, $3, $4); EXECUTE fooplan(1, 'Hunter Valley', 't', 200.00); Create a prepared statement for a SELECT statement, and then execute it: PREPARE usrrptplan (int) AS SELECT * FROM users u, logs l WHERE u.usrid=$1 AND u.usrid=l.usrid AND l.date = $2; EXECUTE usrrptplan(1, current_date); Note that the data type of the second parameter is not specified, so it is inferred from the context in which $2 is used. Compatibility The SQL standard includes a PREPARE statement, but it is only for use in embedded SQL. This version of the PREPARE statement also uses a somewhat different syntax. See Also DEALLOCATE, EXECUTE ------------------------------------------------------------------------ PREPARE TRANSACTION Name PREPARE TRANSACTION -- prepare the current transaction for two-phase commit Synopsis PREPARE TRANSACTION transaction_id Description PREPARE TRANSACTION prepares the current transaction for two-phase commit. After this command, the transaction is no longer associated with the current session; instead, its state is fully stored on disk, and there is a very high probability that it can be committed successfully, even if a database crash occurs before the commit is requested. Once prepared, a transaction can later be committed or rolled back with COMMIT_PREPARED or ROLLBACK_PREPARED, respectively. Those commands can be issued from any session, not only the one that executed the original transaction. From the point of view of the issuing session, PREPARE TRANSACTION is not unlike a ROLLBACK command: after executing it, there is no active current transaction, and the effects of the prepared transaction are no longer visible. (The effects will become visible again if the transaction is committed.) If the PREPARE TRANSACTION command fails for any reason, it becomes a ROLLBACK: the current transaction is canceled. Parameters transaction_id An arbitrary identifier that later identifies this transaction for COMMIT PREPARED or ROLLBACK PREPARED. The identifier must be written as a string literal, and must be less than 200 bytes long. It must not be the same as the identifier used for any currently prepared transaction. Notes This command must be used inside a transaction block. Use BEGIN to start one. It is not currently allowed to PREPARE a transaction that has executed any operations involving temporary tables, created any cursors WITH HOLD, or executed LISTEN or UNLISTEN. Those features are too tightly tied to the current session to be useful in a transaction to be prepared. If the transaction modified any run-time parameters with SET (without the LOCAL option), those effects persist after PREPARE TRANSACTION, and will not be affected by any later COMMIT PREPARED or ROLLBACK PREPARED. Thus, in this one respect PREPARE TRANSACTION acts more like COMMIT than ROLLBACK. All currently available prepared transactions are listed in the pg_prepared_xacts system view. From a performance standpoint, it is unwise to leave transactions in the prepared state for a long time: this will for instance interfere with the ability of VACUUM to reclaim storage. Keep in mind also that the transaction continues to hold whatever locks it held. The intended usage of the feature is that a prepared transaction will normally be committed or rolled back as soon as an external transaction manager has verified that other databases are also prepared to commit. If you make any serious use of prepared transactions, you will probably want to increase the value of max_prepared_transactions, as the default setting is quite small (to avoid wasting resources for those who don't use it). It is recommendable to make it at least equal to max_connections, so that every session can have a prepared transaction pending. Examples Prepare the current transaction for two-phase commit, using foobar as the transaction identifier: PREPARE TRANSACTION 'foobar'; See Also COMMIT_PREPARED, ROLLBACK_PREPARED ------------------------------------------------------------------------ REASSIGN OWNED Name REASSIGN OWNED -- change the ownership of database objects owned by a database role Synopsis REASSIGN OWNED BY old_role [, ...] TO new_role Description REASSIGN OWNED instructs the system to change the ownership of the database objects owned by one of the old_roles, to new_role. Parameters old_role The name of a role. The ownership of all the objects in the current database owned by this role will be reassigned to new_role. new_role The name of the role that will be made the new owner of the affected objects. Notes REASSIGN OWNED is often used to prepare for the removal of one or more roles. Because REASSIGN OWNED only affects the objects in the current database, it is usually necessary to execute this command in each database that contains objects owned by a role that is to be removed. The DROP_OWNED command is an alternative that drops all the database objects owned by one or more roles. The REASSIGN OWNED command does not affect the privileges granted to the old_roles in objects that are not owned by them. Use DROP OWNED to revoke those privileges. Compatibility The REASSIGN OWNED statement is a PostgreSQL extension. See Also DROP_OWNED, DROP_ROLE ------------------------------------------------------------------------ REINDEX Name REINDEX -- rebuild indexes Synopsis REINDEX { INDEX | TABLE | DATABASE | SYSTEM } name [ FORCE ] Description REINDEX rebuilds an index using the data stored in the index's table, replacing the old copy of the index. There are several scenarios in which to use REINDEX: * An index has become corrupted, and no longer contains valid data. Although in theory this should never happen, in practice indexes can become corrupted due to software bugs or hardware failures. REINDEX provides a recovery method. * An index has become "bloated", that it is contains many empty or nearly- empty pages. This can occur with B-tree indexes in PostgreSQL under certain uncommon access patterns. REINDEX provides a way to reduce the space consumption of the index by writing a new version of the index without the dead pages. See Section_23.2 for more information. * You have altered a storage parameter (such as fillfactor) for an index, and wish to ensure that the change has taken full effect. * An index build with the CONCURRENTLY option failed, leaving an "invalid" index. Such indexes are useless but it can be convenient to use REINDEX to rebuild them. Note that REINDEX will not perform a concurrent build. To build the index without interfering with production you should drop the index and reissue the CREATE INDEX CONCURRENTLY command. Parameters INDEX Recreate the specified index. TABLE Recreate all indexes of the specified table. If the table has a secondary "TOAST" table, that is reindexed as well. DATABASE Recreate all indexes within the current database. Indexes on shared system catalogs are skipped except in stand-alone mode (see below). This form of REINDEX cannot be executed inside a transaction block. SYSTEM Recreate all indexes on system catalogs within the current database. Indexes on user tables are not processed. Also, indexes on shared system catalogs are skipped except in stand-alone mode (see below). This form of REINDEX cannot be executed inside a transaction block. name The name of the specific index, table, or database to be reindexed. Index and table names can be schema-qualified. Presently, REINDEX DATABASE and REINDEX SYSTEM can only reindex the current database, so their parameter must match the current database's name. FORCE This is an obsolete option; it is ignored if specified. Notes If you suspect corruption of an index on a user table, you can simply rebuild that index, or all indexes on the table, using REINDEX INDEX or REINDEX TABLE. Things are more difficult if you need to recover from corruption of an index on a system table. In this case it's important for the system to not have used any of the suspect indexes itself. (Indeed, in this sort of scenario you might find that server processes are crashing immediately at start-up, due to reliance on the corrupted indexes.) To recover safely, the server must be started with the -P option, which prevents it from using indexes for system catalog lookups. One way to do this is to shut down the server and start a single-user PostgreSQL server with the -P option included on its command line. Then, REINDEX DATABASE, REINDEX SYSTEM, REINDEX TABLE, or REINDEX INDEX can be issued, depending on how much you want to reconstruct. If in doubt, use REINDEX SYSTEM to select reconstruction of all system indexes in the database. Then quit the single-user server session and restart the regular server. See the postgres reference page for more information about how to interact with the single-user server interface. Alternatively, a regular server session can be started with -P included in its command line options. The method for doing this varies across clients, but in all libpq-based clients, it is possible to set the PGOPTIONS environment variable to -P before starting the client. Note that while this method does not require locking out other clients, it might still be wise to prevent other users from connecting to the damaged database until repairs have been completed. If corruption is suspected in the indexes of any of the shared system catalogs (which are pg_authid, pg_auth_members, pg_database, pg_pltemplate, pg_shdepend, pg_shdescription, and pg_tablespace), then a standalone server must be used to repair it. REINDEX will not process shared catalogs in multiuser mode. For all indexes except the shared system catalogs, REINDEX is crash-safe and transaction-safe. REINDEX is not crash-safe for shared indexes, which is why this case is disallowed during normal operation. If a failure occurs while reindexing one of these catalogs in standalone mode, it will not be possible to restart the regular server until the problem is rectified. (The typical symptom of a partially rebuilt shared index is "index is not a btree" errors.) REINDEX is similar to a drop and recreate of the index in that the index contents are rebuilt from scratch. However, the locking considerations are rather different. REINDEX locks out writes but not reads of the index's parent table. It also takes an exclusive lock on the specific index being processed, which will block reads that attempt to use that index. In contrast, DROP INDEX momentarily takes exclusive lock on the parent table, blocking both writes and reads. The subsequent CREATE INDEX locks out writes but not reads; since the index is not there, no read will attempt to use it, meaning that there will be no blocking but reads might be forced into expensive sequential scans. Reindexing a single index or table requires being the owner of that index or table. Reindexing a database requires being the owner of the database (note that the owner can therefore rebuild indexes of tables owned by other users). Of course, superusers can always reindex anything. Prior to PostgreSQL 8.1, REINDEX DATABASE processed only system indexes, not all indexes as one would expect from the name. This has been changed to reduce the surprise factor. The old behavior is available as REINDEX SYSTEM. Prior to PostgreSQL 7.4, REINDEX TABLE did not automatically process TOAST tables, and so those had to be reindexed by separate commands. This is still possible, but redundant. Examples Rebuild a single index: REINDEX INDEX my_index; Rebuild all the indexes on the table my_table: REINDEX TABLE my_table; Rebuild all indexes in a particular database, without trusting the system indexes to be valid already: $ export PGOPTIONS="-P" $ psql broken_db ... broken_db=> REINDEX DATABASE broken_db; broken_db=> \q Compatibility There is no REINDEX command in the SQL standard. ------------------------------------------------------------------------ RELEASE SAVEPOINT Name RELEASE SAVEPOINT -- destroy a previously defined savepoint Synopsis RELEASE [ SAVEPOINT ] savepoint_name Description RELEASE SAVEPOINT destroys a savepoint previously defined in the current transaction. Destroying a savepoint makes it unavailable as a rollback point, but it has no other user visible behavior. It does not undo the effects of commands executed after the savepoint was established. (To do that, see ROLLBACK_TO SAVEPOINT.) Destroying a savepoint when it is no longer needed allows the system to reclaim some resources earlier than transaction end. RELEASE SAVEPOINT also destroys all savepoints that were established after the named savepoint was established. Parameters savepoint_name The name of the savepoint to destroy. Notes Specifying a savepoint name that was not previously defined is an error. It is not possible to release a savepoint when the transaction is in an aborted state. If multiple savepoints have the same name, only the one that was most recently defined is released. Examples To establish and later destroy a savepoint: BEGIN; INSERT INTO table1 VALUES (3); SAVEPOINT my_savepoint; INSERT INTO table1 VALUES (4); RELEASE SAVEPOINT my_savepoint; COMMIT; The above transaction will insert both 3 and 4. Compatibility This command conforms to the SQL standard. The standard specifies that the key word SAVEPOINT is mandatory, but PostgreSQL allows it to be omitted. See Also BEGIN, COMMIT, ROLLBACK, ROLLBACK_TO_SAVEPOINT, SAVEPOINT ------------------------------------------------------------------------ RESET Name RESET -- restore the value of a run-time parameter to the default value Synopsis RESET configuration_parameter RESET ALL Description RESET restores run-time parameters to their default values. RESET is an alternative spelling for SET configuration_parameter TO DEFAULT Refer to SET for details. The default value is defined as the value that the parameter would have had, if no SET had ever been issued for it in the current session. The actual source of this value might be a compiled-in default, the configuration file, command-line options, or per-database or per-user default settings. This is subtly different from defining it as "the value that the parameter had at session start", because if the value came from the configuration file, it will be reset to whatever is specified by the configuration file now. See Chapter_18 for details. The transactional behavior of RESET is the same as SET: its effects will be undone by transaction rollback. Parameters configuration_parameter Name of a settable run-time parameter. Available parameters are documented in Chapter_18 and on the SET reference page. ALL Resets all settable run-time parameters to default values. Examples Set the timezone configuration variable to its default value: RESET timezone; Compatibility RESET is a PostgreSQL extension. See Also SET, SHOW ------------------------------------------------------------------------ REVOKE Name REVOKE -- remove access privileges Synopsis REVOKE [ GRANT OPTION FOR ] { { SELECT | INSERT | UPDATE | DELETE | REFERENCES | TRIGGER } [,...] | ALL [ PRIVILEGES ] } ON [ TABLE ] tablename [, ...] FROM { [ GROUP ] rolename | PUBLIC } [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { { USAGE | SELECT | UPDATE } [,...] | ALL [ PRIVILEGES ] } ON SEQUENCE sequencename [, ...] FROM { [ GROUP ] rolename | PUBLIC } [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { { CREATE | CONNECT | TEMPORARY | TEMP } [,...] | ALL [ PRIVILEGES ] } ON DATABASE dbname [, ...] FROM { [ GROUP ] rolename | PUBLIC } [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { EXECUTE | ALL [ PRIVILEGES ] } ON FUNCTION funcname ( [ [ argmode ] [ argname ] argtype [, ...] ] ) [, ...] FROM { [ GROUP ] rolename | PUBLIC } [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { USAGE | ALL [ PRIVILEGES ] } ON LANGUAGE langname [, ...] FROM { [ GROUP ] rolename | PUBLIC } [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] } ON SCHEMA schemaname [, ...] FROM { [ GROUP ] rolename | PUBLIC } [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { CREATE | ALL [ PRIVILEGES ] } ON TABLESPACE tablespacename [, ...] FROM { [ GROUP ] rolename | PUBLIC } [, ...] [ CASCADE | RESTRICT ] REVOKE [ ADMIN OPTION FOR ] role [, ...] FROM rolename [, ...] [ CASCADE | RESTRICT ] Description The REVOKE command revokes previously granted privileges from one or more roles. The key word PUBLIC refers to the implicitly defined group of all roles. See the description of the GRANT command for the meaning of the privilege types. Note that any particular role will have the sum of privileges granted directly to it, privileges granted to any role it is presently a member of, and privileges granted to PUBLIC. Thus, for example, revoking SELECT privilege from PUBLIC does not necessarily mean that all roles have lost SELECT privilege on the object: those who have it granted directly or via another role will still have it. If GRANT OPTION FOR is specified, only the grant option for the privilege is revoked, not the privilege itself. Otherwise, both the privilege and the grant option are revoked. If a user holds a privilege with grant option and has granted it to other users then the privileges held by those other users are called dependent privileges. If the privilege or the grant option held by the first user is being revoked and dependent privileges exist, those dependent privileges are also revoked if CASCADE is specified; if it is not, the revoke action will fail. This recursive revocation only affects privileges that were granted through a chain of users that is traceable to the user that is the subject of this REVOKE command. Thus, the affected users might effectively keep the privilege if it was also granted through other users. When revoking membership in a role, GRANT OPTION is instead called ADMIN OPTION, but the behavior is similar. Note also that this form of the command does not allow the noise word GROUP. Notes Use psql's \z command to display the privileges granted on existing objects. See GRANT for information about the format. A user can only revoke privileges that were granted directly by that user. If, for example, user A has granted a privilege with grant option to user B, and user B has in turned granted it to user C, then user A cannot revoke the privilege directly from C. Instead, user A could revoke the grant option from user B and use the CASCADE option so that the privilege is in turn revoked from user C. For another example, if both A and B have granted the same privilege to C, A can revoke his own grant but not B's grant, so C will still effectively have the privilege. When a non-owner of an object attempts to REVOKE privileges on the object, the command will fail outright if the user has no privileges whatsoever on the object. As long as some privilege is available, the command will proceed, but it will revoke only those privileges for which the user has grant options. The REVOKE ALL PRIVILEGES forms will issue a warning message if no grant options are held, while the other forms will issue a warning if grant options for any of the privileges specifically named in the command are not held. (In principle these statements apply to the object owner as well, but since the owner is always treated as holding all grant options, the cases can never occur.) If a superuser chooses to issue a GRANT or REVOKE command, the command is performed as though it were issued by the owner of the affected object. Since all privileges ultimately come from the object owner (possibly indirectly via chains of grant options), it is possible for a superuser to revoke all privileges, but this might require use of CASCADE as stated above. REVOKE can also be done by a role that is not the owner of the affected object, but is a member of the role that owns the object, or is a member of a role that holds privileges WITH GRANT OPTION on the object. In this case the command is performed as though it were issued by the containing role that actually owns the object or holds the privileges WITH GRANT OPTION. For example, if table t1 is owned by role g1, of which role u1 is a member, then u1 can revoke privileges on t1 that are recorded as being granted by g1. This would include grants made by u1 as well as by other members of role g1. If the role executing REVOKE holds privileges indirectly via more than one role membership path, it is unspecified which containing role will be used to perform the command. In such cases it is best practice to use SET ROLE to become the specific role you want to do the REVOKE as. Failure to do so might lead to revoking privileges other than the ones you intended, or not revoking anything at all. Examples Revoke insert privilege for the public on table films: REVOKE INSERT ON films FROM PUBLIC; Revoke all privileges from user manuel on view kinds: REVOKE ALL PRIVILEGES ON kinds FROM manuel; Note that this actually means "revoke all privileges that I granted". Revoke membership in role admins from user joe: REVOKE admins FROM joe; Compatibility The compatibility notes of the GRANT command apply analogously to REVOKE. The keyword RESTRICT or CASCADE is required according to the standard, but PostgreSQL assumes RESTRICT by default. See Also GRANT ------------------------------------------------------------------------ ROLLBACK Name ROLLBACK -- abort the current transaction Synopsis ROLLBACK [ WORK | TRANSACTION ] Description ROLLBACK rolls back the current transaction and causes all the updates made by the transaction to be discarded. Parameters WORK TRANSACTION Optional key words. They have no effect. Notes Use COMMIT to successfully terminate a transaction. Issuing ROLLBACK when not inside a transaction does no harm, but it will provoke a warning message. Examples To abort all changes: ROLLBACK; Compatibility The SQL standard only specifies the two forms ROLLBACK and ROLLBACK WORK. Otherwise, this command is fully conforming. See Also BEGIN, COMMIT, ROLLBACK_TO_SAVEPOINT ------------------------------------------------------------------------ ROLLBACK PREPARED Name ROLLBACK PREPARED -- cancel a transaction that was earlier prepared for two-phase commit Synopsis ROLLBACK PREPARED transaction_id Description ROLLBACK PREPARED rolls back a transaction that is in prepared state. Parameters transaction_id The transaction identifier of the transaction that is to be rolled back. Notes To roll back a prepared transaction, you must be either the same user that executed the transaction originally, or a superuser. But you do not have to be in the same session that executed the transaction. This command cannot be executed inside a transaction block. The prepared transaction is rolled back immediately. All currently available prepared transactions are listed in the pg_prepared_xacts system view. Examples Roll back the transaction identified by the transaction identifier foobar: ROLLBACK PREPARED 'foobar'; See Also PREPARE_TRANSACTION, COMMIT_PREPARED ------------------------------------------------------------------------ ROLLBACK TO SAVEPOINT Name ROLLBACK TO SAVEPOINT -- roll back to a savepoint Synopsis ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] savepoint_name Description Roll back all commands that were executed after the savepoint was established. The savepoint remains valid and can be rolled back to again later, if needed. ROLLBACK TO SAVEPOINT implicitly destroys all savepoints that were established after the named savepoint. Parameters savepoint_name The savepoint to roll back to. Notes Use RELEASE_SAVEPOINT to destroy a savepoint without discarding the effects of commands executed after it was established. Specifying a savepoint name that has not been established is an error. Cursors have somewhat non-transactional behavior with respect to savepoints. Any cursor that is opened inside a savepoint will be closed when the savepoint is rolled back. If a previously opened cursor is affected by a FETCH command inside a savepoint that is later rolled back, the cursor position remains at the position that FETCH left it pointing to (that is, FETCH is not rolled back). Closing a cursor is not undone by rolling back, either. A cursor whose execution causes a transaction to abort is put in a cannot-execute state, so while the transaction can be restored using ROLLBACK TO SAVEPOINT, the cursor can no longer be used. Examples To undo the effects of the commands executed after my_savepoint was established: ROLLBACK TO SAVEPOINT my_savepoint; Cursor positions are not affected by savepoint rollback: BEGIN; DECLARE foo CURSOR FOR SELECT 1 UNION SELECT 2; SAVEPOINT foo; FETCH 1 FROM foo; ?column? ---------- 1 ROLLBACK TO SAVEPOINT foo; FETCH 1 FROM foo; ?column? ---------- 2 COMMIT; Compatibility The SQL standard specifies that the key word SAVEPOINT is mandatory, but PostgreSQL and Oracle allow it to be omitted. SQL allows only WORK, not TRANSACTION, as a noise word after ROLLBACK. Also, SQL has an optional clause AND [ NO ] CHAIN which is not currently supported by PostgreSQL. Otherwise, this command conforms to the SQL standard. See Also BEGIN, COMMIT, RELEASE_SAVEPOINT, ROLLBACK, SAVEPOINT ------------------------------------------------------------------------ SAVEPOINT Name SAVEPOINT -- define a new savepoint within the current transaction Synopsis SAVEPOINT savepoint_name Description SAVEPOINT establishes a new savepoint within the current transaction. A savepoint is a special mark inside a transaction that allows all commands that are executed after it was established to be rolled back, restoring the transaction state to what it was at the time of the savepoint. Parameters savepoint_name The name to give to the new savepoint. Notes Use ROLLBACK_TO_SAVEPOINT to rollback to a savepoint. Use RELEASE_SAVEPOINT to destroy a savepoint, keeping the effects of commands executed after it was established. Savepoints can only be established when inside a transaction block. There can be multiple savepoints defined within a transaction. Examples To establish a savepoint and later undo the effects of all commands executed after it was established: BEGIN; INSERT INTO table1 VALUES (1); SAVEPOINT my_savepoint; INSERT INTO table1 VALUES (2); ROLLBACK TO SAVEPOINT my_savepoint; INSERT INTO table1 VALUES (3); COMMIT; The above transaction will insert the values 1 and 3, but not 2. To establish and later destroy a savepoint: BEGIN; INSERT INTO table1 VALUES (3); SAVEPOINT my_savepoint; INSERT INTO table1 VALUES (4); RELEASE SAVEPOINT my_savepoint; COMMIT; The above transaction will insert both 3 and 4. Compatibility SQL requires a savepoint to be destroyed automatically when another savepoint with the same name is established. In PostgreSQL, the old savepoint is kept, though only the more recent one will be used when rolling back or releasing. (Releasing the newer savepoint will cause the older one to again become accessible to ROLLBACK TO SAVEPOINT and RELEASE SAVEPOINT.) Otherwise, SAVEPOINT is fully SQL conforming. See Also BEGIN, COMMIT, RELEASE_SAVEPOINT, ROLLBACK, ROLLBACK_TO_SAVEPOINT ------------------------------------------------------------------------ SELECT Name SELECT -- retrieve rows from a table or view Synopsis SELECT [ ALL | DISTINCT [ ON ( expression [, ...] ) ] ] * | expression [ AS output_name ] [, ...] [ FROM from_item [, ...] ] [ WHERE condition ] [ GROUP BY expression [, ...] ] [ HAVING condition [, ...] ] [ { UNION | INTERSECT | EXCEPT } [ ALL ] select ] [ ORDER BY expression [ ASC | DESC | USING operator ] [ NULLS { FIRST | LAST } ] [, ...] ] [ LIMIT { count | ALL } ] [ OFFSET start ] [ FOR { UPDATE | SHARE } [ OF table_name [, ...] ] [ NOWAIT ] [...] ] where from_item can be one of: [ ONLY ] table_name [ * ] [ [ AS ] alias [ ( column_alias [, ...] ) ] ] ( select ) [ AS ] alias [ ( column_alias [, ...] ) ] function_name ( [ argument [, ...] ] ) [ AS ] alias [ ( column_alias [, ...] | column_definition [, ...] ) ] function_name ( [ argument [, ...] ] ) AS ( column_definition [, ...] ) from_item [ NATURAL ] join_type from_item [ ON join_condition | USING ( join_column [, ...] ) ] Description SELECT retrieves rows from zero or more tables. The general processing of SELECT is as follows: 1. All elements in the FROM list are computed. (Each element in the FROM list is a real or virtual table.) If more than one element is specified in the FROM list, they are cross-joined together. (See FROM Clause below.) 2. If the WHERE clause is specified, all rows that do not satisfy the condition are eliminated from the output. (See WHERE_Clause below.) 3. If the GROUP BY clause is specified, the output is divided into groups of rows that match on one or more values. If the HAVING clause is present, it eliminates groups that do not satisfy the given condition. (See GROUP_BY_Clause and HAVING_Clause below.) 4. The actual output rows are computed using the SELECT output expressions for each selected row. (See SELECT_List below.) 5. Using the operators UNION, INTERSECT, and EXCEPT, the output of more than one SELECT statement can be combined to form a single result set. The UNION operator returns all rows that are in one or both of the result sets. The INTERSECT operator returns all rows that are strictly in both result sets. The EXCEPT operator returns the rows that are in the first result set but not in the second. In all three cases, duplicate rows are eliminated unless ALL is specified. (See UNION Clause, INTERSECT_Clause, and EXCEPT_Clause below.) 6. If the ORDER BY clause is specified, the returned rows are sorted in the specified order. If ORDER BY is not given, the rows are returned in whatever order the system finds fastest to produce. (See ORDER_BY Clause below.) 7. DISTINCT eliminates duplicate rows from the result. DISTINCT ON eliminates rows that match on all the specified expressions. ALL (the default) will return all candidate rows, including duplicates. (See DISTINCT_Clause below.) 8. If the LIMIT or OFFSET clause is specified, the SELECT statement only returns a subset of the result rows. (See LIMIT_Clause below.) 9. If FOR UPDATE or FOR SHARE is specified, the SELECT statement locks the selected rows against concurrent updates. (See FOR_UPDATE/FOR SHARE_Clause below.) You must have SELECT privilege on a table to read its values. The use of FOR UPDATE or FOR SHARE requires UPDATE privilege as well. Parameters FROM Clause The FROM clause specifies one or more source tables for the SELECT. If multiple sources are specified, the result is the Cartesian product (cross join) of all the sources. But usually qualification conditions are added to restrict the returned rows to a small subset of the Cartesian product. The FROM clause can contain the following elements: ON join_condition join_condition is an expression resulting in a value of type boolean (similar to a WHERE clause) that specifies which rows in a join are considered to match. USING ( join_column [, ...] ) A clause of the form USING ( a, b, ... ) is shorthand for ON left_table.a = right_table.a AND left_table.b = right_table.b .... Also, USING implies that only one of each pair of equivalent columns will be included in the join output, not both. NATURAL NATURAL is shorthand for a USING list that mentions all columns in the two tables that have the same names. WHERE Clause The optional WHERE clause has the general form WHERE condition where condition is any expression that evaluates to a result of type boolean. Any row that does not satisfy this condition will be eliminated from the output. A row satisfies the condition if it returns true when the actual row values are substituted for any variable references. GROUP BY Clause The optional GROUP BY clause has the general form GROUP BY expression [, ...] GROUP BY will condense into a single row all selected rows that share the same values for the grouped expressions. expression can be an input column name, or the name or ordinal number of an output column (SELECT list item), or an arbitrary expression formed from input-column values. In case of ambiguity, a GROUP BY name will be interpreted as an input-column name rather than an output column name. Aggregate functions, if any are used, are computed across all rows making up each group, producing a separate value for each group (whereas without GROUP BY, an aggregate produces a single value computed across all the selected rows). When GROUP BY is present, it is not valid for the SELECT list expressions to refer to ungrouped columns except within aggregate functions, since there would be more than one possible value to return for an ungrouped column. HAVING Clause The optional HAVING clause has the general form HAVING condition where condition is the same as specified for the WHERE clause. HAVING eliminates group rows that do not satisfy the condition. HAVING is different from WHERE: WHERE filters individual rows before the application of GROUP BY, while HAVING filters group rows created by GROUP BY. Each column referenced in condition must unambiguously reference a grouping column, unless the reference appears within an aggregate function. The presence of HAVING turns a query into a grouped query even if there is no GROUP BY clause. This is the same as what happens when the query contains aggregate functions but no GROUP BY clause. All the selected rows are considered to form a single group, and the SELECT list and HAVING clause can only reference table columns from within aggregate functions. Such a query will emit a single row if the HAVING condition is true, zero rows if it is not true. SELECT List The SELECT list (between the key words SELECT and FROM) specifies expressions that form the output rows of the SELECT statement. The expressions can (and usually do) refer to columns computed in the FROM clause. Using the clause AS output_name, another name can be specified for an output column. This name is primarily used to label the column for display. It can also be used to refer to the column's value in ORDER BY and GROUP BY clauses, but not in the WHERE or HAVING clauses; there you must write out the expression instead. Instead of an expression, * can be written in the output list as a shorthand for all the columns of the selected rows. Also, one can write table_name.* as a shorthand for the columns coming from just that table. UNION Clause The UNION clause has this general form: select_statement UNION [ ALL ] select_statement select_statement is any SELECT statement without an ORDER BY, LIMIT, FOR UPDATE, or FOR SHARE clause. (ORDER BY and LIMIT can be attached to a subexpression if it is enclosed in parentheses. Without parentheses, these clauses will be taken to apply to the result of the UNION, not to its right-hand input expression.) The UNION operator computes the set union of the rows returned by the involved SELECT statements. A row is in the set union of two result sets if it appears in at least one of the result sets. The two SELECT statements that represent the direct operands of the UNION must produce the same number of columns, and corresponding columns must be of compatible data types. The result of UNION does not contain any duplicate rows unless the ALL option is specified. ALL prevents elimination of duplicates. (Therefore, UNION ALL is usually significantly quicker than UNION; use ALL when you can.) Multiple UNION operators in the same SELECT statement are evaluated left to right, unless otherwise indicated by parentheses. Currently, FOR UPDATE and FOR SHARE cannot be specified either for a UNION result or for any input of a UNION. INTERSECT Clause The INTERSECT clause has this general form: select_statement INTERSECT [ ALL ] select_statement select_statement is any SELECT statement without an ORDER BY, LIMIT, FOR UPDATE, or FOR SHARE clause. The INTERSECT operator computes the set intersection of the rows returned by the involved SELECT statements. A row is in the intersection of two result sets if it appears in both result sets. The result of INTERSECT does not contain any duplicate rows unless the ALL option is specified. With ALL, a row that has m duplicates in the left table and n duplicates in the right table will appear min(m,n) times in the result set. Multiple INTERSECT operators in the same SELECT statement are evaluated left to right, unless parentheses dictate otherwise. INTERSECT binds more tightly than UNION. That is, A UNION B INTERSECT C will be read as A UNION (B INTERSECT C). Currently, FOR UPDATE and FOR SHARE cannot be specified either for an INTERSECT result or for any input of an INTERSECT. EXCEPT Clause The EXCEPT clause has this general form: select_statement EXCEPT [ ALL ] select_statement select_statement is any SELECT statement without an ORDER BY, LIMIT, FOR UPDATE, or FOR SHARE clause. The EXCEPT operator computes the set of rows that are in the result of the left SELECT statement but not in the result of the right one. The result of EXCEPT does not contain any duplicate rows unless the ALL option is specified. With ALL, a row that has m duplicates in the left table and n duplicates in the right table will appear max(m-n,0) times in the result set. Multiple EXCEPT operators in the same SELECT statement are evaluated left to right, unless parentheses dictate otherwise. EXCEPT binds at the same level as UNION. Currently, FOR UPDATE and FOR SHARE cannot be specified either for an EXCEPT result or for any input of an EXCEPT. ORDER BY Clause The optional ORDER BY clause has this general form: ORDER BY expression [ ASC | DESC | USING operator ] [ NULLS { FIRST | LAST } ] [, ...] The ORDER BY clause causes the result rows to be sorted according to the specified expression(s). If two rows are equal according to the leftmost expression, they are compared according to the next expression and so on. If they are equal according to all specified expressions, they are returned in an implementation-dependent order. Each expression can be the name or ordinal number of an output column (SELECT list item), or it can be an arbitrary expression formed from input- column values. The ordinal number refers to the ordinal (left-to-right) position of the result column. This feature makes it possible to define an ordering on the basis of a column that does not have a unique name. This is never absolutely necessary because it is always possible to assign a name to a result column using the AS clause. It is also possible to use arbitrary expressions in the ORDER BY clause, including columns that do not appear in the SELECT result list. Thus the following statement is valid: SELECT name FROM distributors ORDER BY code; A limitation of this feature is that an ORDER BY clause applying to the result of a UNION, INTERSECT, or EXCEPT clause can only specify an output column name or number, not an expression. If an ORDER BY expression is a simple name that matches both a result column name and an input column name, ORDER BY will interpret it as the result column name. This is the opposite of the choice that GROUP BY will make in the same situation. This inconsistency is made to be compatible with the SQL standard. Optionally one can add the key word ASC (ascending) or DESC (descending) after any expression in the ORDER BY clause. If not specified, ASC is assumed by default. Alternatively, a specific ordering operator name can be specified in the USING clause. An ordering operator must be a less-than or greater-than member of some B-tree operator family. ASC is usually equivalent to USING < and DESC is usually equivalent to USING >. (But the creator of a user-defined data type can define exactly what the default sort ordering is, and it might correspond to operators with other names.) If NULLS LAST is specified, null values sort after all non-null values; if NULLS FIRST is specified, null values sort before all non-null values. If neither is specified, the default behavior is NULLS LAST when ASC is specified or implied, and NULLS FIRST when DESC is specified (thus, the default is to act as though nulls are larger than non-nulls). When USING is specified, the default nulls ordering depends on whether the operator is a less-than or greater-than operator. Note that ordering options apply only to the expression they follow; for example ORDER BY x, y DESC does not mean the same thing as ORDER BY x DESC, y DESC. Character-string data is sorted according to the locale-specific collation order that was established when the database cluster was initialized. DISTINCT Clause If DISTINCT is specified, all duplicate rows are removed from the result set (one row is kept from each group of duplicates). ALL specifies the opposite: all rows are kept; that is the default. DISTINCT ON ( expression [, ...] ) keeps only the first row of each set of rows where the given expressions evaluate to equal. The DISTINCT ON expressions are interpreted using the same rules as for ORDER BY (see above). Note that the "first row" of each set is unpredictable unless ORDER BY is used to ensure that the desired row appears first. For example: SELECT DISTINCT ON (location) location, time, report FROM weather_reports ORDER BY location, time DESC; retrieves the most recent weather report for each location. But if we had not used ORDER BY to force descending order of time values for each location, we'd have gotten a report from an unpredictable time for each location. The DISTINCT ON expression(s) must match the leftmost ORDER BY expression (s). The ORDER BY clause will normally contain additional expression(s) that determine the desired precedence of rows within each DISTINCT ON group. LIMIT Clause The LIMIT clause consists of two independent sub-clauses: LIMIT { count | ALL } OFFSET start count specifies the maximum number of rows to return, while start specifies the number of rows to skip before starting to return rows. When both are specified, start rows are skipped before starting to count the count rows to be returned. When using LIMIT, it is a good idea to use an ORDER BY clause that constrains the result rows into a unique order. Otherwise you will get an unpredictable subset of the query's rows -- you might be asking for the tenth through twentieth rows, but tenth through twentieth in what ordering? You don't know what ordering unless you specify ORDER BY. The query planner takes LIMIT into account when generating a query plan, so you are very likely to get different plans (yielding different row orders) depending on what you use for LIMIT and OFFSET. Thus, using different LIMIT/OFFSET values to select different subsets of a query result will give inconsistent results unless you enforce a predictable result ordering with ORDER BY. This is not a bug; it is an inherent consequence of the fact that SQL does not promise to deliver the results of a query in any particular order unless ORDER BY is used to constrain the order. It is even possible for repeated executions of the same LIMIT query to return different subsets of the rows of a table, if there is not an ORDER BY to enforce selection of a deterministic subset. Again, this is not a bug; determinism of the results is simply not guaranteed in such a case. FOR UPDATE/FOR SHARE Clause The FOR UPDATE clause has this form: FOR UPDATE [ OF table_name [, ...] ] [ NOWAIT ] The closely related FOR SHARE clause has this form: FOR SHARE [ OF table_name [, ...] ] [ NOWAIT ] FOR UPDATE causes the rows retrieved by the SELECT statement to be locked as though for update. This prevents them from being modified or deleted by other transactions until the current transaction ends. That is, other transactions that attempt UPDATE, DELETE, or SELECT FOR UPDATE of these rows will be blocked until the current transaction ends. Also, if an UPDATE, DELETE, or SELECT FOR UPDATE from another transaction has already locked a selected row or rows, SELECT FOR UPDATE will wait for the other transaction to complete, and will then lock and return the updated row (or no row, if the row was deleted). For further discussion see Chapter_13. To prevent the operation from waiting for other transactions to commit, use the NOWAIT option. SELECT FOR UPDATE NOWAIT reports an error, rather than waiting, if a selected row cannot be locked immediately. Note that NOWAIT applies only to the row-level lock(s) -- the required ROW SHARE table-level lock is still taken in the ordinary way (see Chapter_13). You can use the NOWAIT option of LOCK if you need to acquire the table-level lock without waiting. FOR SHARE behaves similarly, except that it acquires a shared rather than exclusive lock on each retrieved row. A shared lock blocks other transactions from performing UPDATE, DELETE, or SELECT FOR UPDATE on these rows, but it does not prevent them from performing SELECT FOR SHARE. If specific tables are named in FOR UPDATE or FOR SHARE, then only rows coming from those tables are locked; any other tables used in the SELECT are simply read as usual. A FOR UPDATE or FOR SHARE clause without a table list affects all tables used in the command. If FOR UPDATE or FOR SHARE is applied to a view or sub-query, it affects all tables used in the view or sub-query. Multiple FOR UPDATE and FOR SHARE clauses can be written if it is necessary to specify different locking behavior for different tables. If the same table is mentioned (or implicitly affected) by both FOR UPDATE and FOR SHARE clauses, then it is processed as FOR UPDATE. Similarly, a table is processed as NOWAIT if that is specified in any of the clauses affecting it. FOR UPDATE and FOR SHARE cannot be used in contexts where returned rows cannot be clearly identified with individual table rows; for example they cannot be used with aggregation. _________________________________________________________________________ |_________________________________________________Caution_________________| |Avoid locking a row and then modifying it within a later savepoint or PL/| |pgSQL exception block. A subsequent rollback would cause the lock to be | |lost. For example: | | | | BEGIN; | | SELECT * FROM mytable WHERE key = 1 FOR UPDATE; | | SAVEPOINT s; | | UPDATE mytable SET ... WHERE key = 1; | | ROLLBACK TO s; | | | |After the ROLLBACK, the row is effectively unlocked, rather than returned| |to its pre-savepoint state of being locked but not modified. This hazard | |occurs if a row locked in the current transaction is updated or deleted, | |or if a shared lock is upgraded to exclusive: in all these cases, the | |former lock state is forgotten. If the transaction is then rolled back to| |a state between the original locking command and the subsequent change, | |the row will appear not to be locked at all. This is an implementation | |deficiency_which_will_be_addressed_in_a_future_release_of_PostgreSQL.____| _________________________________________________________________________ |_________________________________________________Caution_________________| |It is possible for a SELECT command using both LIMIT and FOR UPDATE/SHARE| |clauses to return fewer rows than specified by LIMIT. This is because | |LIMIT is applied first. The command selects the specified number of rows,| |but might then block trying to obtain lock on one or more of them. Once | |the SELECT unblocks, the row might have been deleted or updated so that | |it does not meet the query WHERE condition anymore, in which case it will| |not_be_returned._________________________________________________________| Examples To join the table films with the table distributors: SELECT f.title, f.did, d.name, f.date_prod, f.kind FROM distributors d, films f WHERE f.did = d.did title | did | name | date_prod | kind -------------------+-----+--------------+------------+---------- The Third Man | 101 | British Lion | 1949-12-23 | Drama The African Queen | 101 | British Lion | 1951-08-11 | Romantic ... To sum the column len of all films and group the results by kind: SELECT kind, sum(len) AS total FROM films GROUP BY kind; kind | total ----------+------- Action | 07:34 Comedy | 02:58 Drama | 14:28 Musical | 06:42 Romantic | 04:38 To sum the column len of all films, group the results by kind and show those group totals that are less than 5 hours: SELECT kind, sum(len) AS total FROM films GROUP BY kind HAVING sum(len) < interval '5 hours'; kind | total ----------+------- Comedy | 02:58 Romantic | 04:38 The following two examples are identical ways of sorting the individual results according to the contents of the second column (name): SELECT * FROM distributors ORDER BY name; SELECT * FROM distributors ORDER BY 2; did | name -----+------------------ 109 | 20th Century Fox 110 | Bavaria Atelier 101 | British Lion 107 | Columbia 102 | Jean Luc Godard 113 | Luso films 104 | Mosfilm 103 | Paramount 106 | Toho 105 | United Artists 111 | Walt Disney 112 | Warner Bros. 108 | Westward The next example shows how to obtain the union of the tables distributors and actors, restricting the results to those that begin with the letter W in each table. Only distinct rows are wanted, so the key word ALL is omitted. distributors: actors: did | name id | name -----+-------------- ----+---------------- 108 | Westward 1 | Woody Allen 111 | Walt Disney 2 | Warren Beatty 112 | Warner Bros. 3 | Walter Matthau ... ... SELECT distributors.name FROM distributors WHERE distributors.name LIKE 'W%' UNION SELECT actors.name FROM actors WHERE actors.name LIKE 'W%'; name ---------------- Walt Disney Walter Matthau Warner Bros. Warren Beatty Westward Woody Allen This example shows how to use a function in the FROM clause, both with and without a column definition list: CREATE FUNCTION distributors(int) RETURNS SETOF distributors AS $$ SELECT * FROM distributors WHERE did = $1; $$ LANGUAGE SQL; SELECT * FROM distributors(111); did | name -----+------------- 111 | Walt Disney CREATE FUNCTION distributors_2(int) RETURNS SETOF record AS $$ SELECT * FROM distributors WHERE did = $1; $$ LANGUAGE SQL; SELECT * FROM distributors_2(111) AS (f1 int, f2 text); f1 | f2 -----+------------- 111 | Walt Disney Compatibility Of course, the SELECT statement is compatible with the SQL standard. But there are some extensions and some missing features. Omitted FROM Clauses PostgreSQL allows one to omit the FROM clause. It has a straightforward use to compute the results of simple expressions: SELECT 2+2; ?column? ---------- 4 Some other SQL databases cannot do this except by introducing a dummy one- row table from which to do the SELECT. Note that if a FROM clause is not specified, the query cannot reference any database tables. For example, the following query is invalid: SELECT distributors.* WHERE distributors.name = 'Westward'; PostgreSQL releases prior to 8.1 would accept queries of this form, and add an implicit entry to the query's FROM clause for each table referenced by the query. This is no longer the default behavior, because it does not comply with the SQL standard, and is considered by many to be error-prone. For compatibility with applications that rely on this behavior the add_missing_from configuration variable can be enabled. The AS Key Word In the SQL standard, the optional key word AS is just noise and can be omitted without affecting the meaning. The PostgreSQL parser requires this key word when renaming output columns because the type extensibility features lead to parsing ambiguities without it. AS is optional in FROM items, however. Namespace Available to GROUP BY and ORDER BY In the SQL-92 standard, an ORDER BY clause can only use result column names or numbers, while a GROUP BY clause can only use expressions based on input column names. PostgreSQL extends each of these clauses to allow the other choice as well (but it uses the standard's interpretation if there is ambiguity). PostgreSQL also allows both clauses to specify arbitrary expressions. Note that names appearing in an expression will always be taken as input-column names, not as result-column names. SQL:1999 and later use a slightly different definition which is not entirely upward compatible with SQL-92. In most cases, however, PostgreSQL will interpret an ORDER BY or GROUP BY expression the same way SQL:1999 does. Nonstandard Clauses The clauses DISTINCT ON, LIMIT, and OFFSET are not defined in the SQL standard. ------------------------------------------------------------------------ SELECT INTO Name SELECT INTO -- define a new table from the results of a query Synopsis SELECT [ ALL | DISTINCT [ ON ( expression [, ...] ) ] ] * | expression [ AS output_name ] [, ...] INTO [ TEMPORARY | TEMP ] [ TABLE ] new_table [ FROM from_item [, ...] ] [ WHERE condition ] [ GROUP BY expression [, ...] ] [ HAVING condition [, ...] ] [ { UNION | INTERSECT | EXCEPT } [ ALL ] select ] [ ORDER BY expression [ ASC | DESC | USING operator ] [ NULLS { FIRST | LAST } ] [, ...] ] [ LIMIT { count | ALL } ] [ OFFSET start ] [ FOR { UPDATE | SHARE } [ OF table_name [, ...] ] [ NOWAIT ] [...] ] Description SELECT INTO creates a new table and fills it with data computed by a query. The data is not returned to the client, as it is with a normal SELECT. The new table's columns have the names and data types associated with the output columns of the SELECT. Parameters TEMPORARY or TEMP If specified, the table is created as a temporary table. Refer to CREATE_TABLE for details. new_table The name (optionally schema-qualified) of the table to be created. All other parameters are described in detail under SELECT. Notes CREATE_TABLE_AS is functionally similar to SELECT INTO. CREATE TABLE AS is the recommended syntax, since this form of SELECT INTO is not available in ECPG or PL/pgSQL, because they interpret the INTO clause differently. Furthermore, CREATE TABLE AS offers a superset of the functionality provided by SELECT INTO. Prior to PostgreSQL 8.1, the table created by SELECT INTO included OIDs by default. In PostgreSQL 8.1, this is not the case -- to include OIDs in the new table, the default_with_oids configuration variable must be enabled. Alternatively, CREATE TABLE AS can be used with the WITH OIDS clause. Examples Create a new table films_recent consisting of only recent entries from the table films: SELECT * INTO films_recent FROM films WHERE date_prod >= '2002-01-01'; Compatibility The SQL standard uses SELECT INTO to represent selecting values into scalar variables of a host program, rather than creating a new table. This indeed is the usage found in ECPG (see Chapter_32) and PL/pgSQL (see Chapter_38). The PostgreSQL usage of SELECT INTO to represent table creation is historical. It is best to use CREATE TABLE AS for this purpose in new code. See Also CREATE_TABLE_AS ------------------------------------------------------------------------ SET Name SET -- change a run-time parameter Synopsis SET [ SESSION | LOCAL ] configuration_parameter { TO | = } { value | 'value' | DEFAULT } SET [ SESSION | LOCAL ] TIME ZONE { timezone | LOCAL | DEFAULT } Description The SET command changes run-time configuration parameters. Many of the run- time parameters listed in Chapter_18 can be changed on-the-fly with SET. (But some require superuser privileges to change, and others cannot be changed after server or session start.) SET only affects the value used by the current session. If SET (or equivalently SET SESSION) is issued within a transaction that is later aborted, the effects of the SET command disappear when the transaction is rolled back. Once the surrounding transaction is committed, the effects will persist until the end of the session, unless overridden by another SET. The effects of SET LOCAL last only till the end of the current transaction, whether committed or not. A special case is SET followed by SET LOCAL within a single transaction: the SET LOCAL value will be seen until the end of the transaction, but afterwards (if the transaction is committed) the SET value will take effect. The effects of SET or SET LOCAL are also canceled by rolling back to a savepoint that is earlier than the command. If SET LOCAL is used within a function that has a SET option for the same variable (see CREATE_FUNCTION), the effects of the SET LOCAL command disappear at function exit; that is, the value in effect when the function was called is restored anyway. This allows SET LOCAL to be used for dynamic or repeated changes of a parameter within a function, while still having the convenience of using the SET option to save and restore the caller's value. However, a regular SET command overrides any surrounding function's SET option; its effects will persist unless rolled back. Note: In PostgreSQL versions 8.0 through 8.2, the effects of a SET LOCAL would be canceled by releasing an earlier savepoint, or by successful exit from a PL/pgSQL exception block. This behavior has been changed because it was deemed unintuitive. Parameters SESSION Specifies that the command takes effect for the current session. (This is the default if neither SESSION nor LOCAL appears.) LOCAL Specifies that the command takes effect for only the current transaction. After COMMIT or ROLLBACK, the session-level setting takes effect again. Note that SET LOCAL will appear to have no effect if it is executed outside a BEGIN block, since the transaction will end immediately. configuration_parameter Name of a settable run-time parameter. Available parameters are documented in Chapter_18 and below. value New value of parameter. Values can be specified as string constants, identifiers, numbers, or comma-separated lists of these, as appropriate for the particular parameter. DEFAULT can be written to specify resetting the parameter to its default value (that is, whatever value it would have had if no SET had been executed in the current session). Besides the configuration parameters documented in Chapter_18, there are a few that can only be adjusted using the SET command or that have a special syntax: 'PST8PDT' The time zone for Berkeley, California. 'Europe/Rome' The time zone for Italy. -7 The time zone 7 hours west from UTC (equivalent to PDT). Positive values are east from UTC. INTERVAL '-08:00' HOUR TO MINUTE The time zone 8 hours west from UTC (equivalent to PST). LOCAL DEFAULT Set the time zone to your local time zone (that is, the server's default value of timezone; if this has not been explicitly set anywhere, it will be the zone that the server's operating system defaults to). See Section_8.5.3 for more information about time zones. Notes The function set_config provides equivalent functionality; see Section 9.23. Also, it is possible to UPDATE the pg_settings system view to perform the equivalent of SET. Examples Set the schema search path: SET search_path TO my_schema, public; Set the style of date to traditional POSTGRES with "day before month" input convention: SET datestyle TO postgres, dmy; Set the time zone for Berkeley, California: SET TIME ZONE 'PST8PDT'; Set the time zone for Italy: SET TIME ZONE 'Europe/Rome'; Compatibility SET TIME ZONE extends syntax defined in the SQL standard. The standard allows only numeric time zone offsets while PostgreSQL allows more flexible time-zone specifications. All other SET features are PostgreSQL extensions. See Also RESET, SHOW ------------------------------------------------------------------------ SET CONSTRAINTS Name SET CONSTRAINTS -- set constraint checking modes for the current transaction Synopsis SET CONSTRAINTS { ALL | name [, ...] } { DEFERRED | IMMEDIATE } Description SET CONSTRAINTS sets the behavior of constraint checking within the current transaction. IMMEDIATE constraints are checked at the end of each statement. DEFERRED constraints are not checked until transaction commit. Each constraint has its own IMMEDIATE or DEFERRED mode. Upon creation, a constraint is given one of three characteristics: DEFERRABLE INITIALLY DEFERRED, DEFERRABLE INITIALLY IMMEDIATE, or NOT DEFERRABLE. The third class is always IMMEDIATE and is not affected by the SET CONSTRAINTS command. The first two classes start every transaction in the indicated mode, but their behavior can be changed within a transaction by SET CONSTRAINTS. SET CONSTRAINTS with a list of constraint names changes the mode of just those constraints (which must all be deferrable). The current schema search path is used to find the first matching name if no schema name is specified. SET CONSTRAINTS ALL changes the mode of all deferrable constraints. When SET CONSTRAINTS changes the mode of a constraint from DEFERRED to IMMEDIATE, the new mode takes effect retroactively: any outstanding data modifications that would have been checked at the end of the transaction are instead checked during the execution of the SET CONSTRAINTS command. If any such constraint is violated, the SET CONSTRAINTS fails (and does not change the constraint mode). Thus, SET CONSTRAINTS can be used to force checking of constraints to occur at a specific point in a transaction. Currently, only foreign key constraints are affected by this setting. Check and unique constraints are always effectively not deferrable. Triggers that are declared as "constraint triggers" are also affected. Notes This command only alters the behavior of constraints within the current transaction. Thus, if you execute this command outside of a transaction block (BEGIN/COMMIT pair), it will not appear to have any effect. Compatibility This command complies with the behavior defined in the SQL standard, except for the limitation that, in PostgreSQL, it only applies to foreign-key constraints. ------------------------------------------------------------------------ SET ROLE Name SET ROLE -- set the current user identifier of the current session Synopsis SET [ SESSION | LOCAL ] ROLE rolename SET [ SESSION | LOCAL ] ROLE NONE RESET ROLE Description This command sets the current user identifier of the current SQL session to be rolename. The role name can be written as either an identifier or a string literal. After SET ROLE, permissions checking for SQL commands is carried out as though the named role were the one that had logged in originally. The specified rolename must be a role that the current session user is a member of. (If the session user is a superuser, any role can be selected.) The SESSION and LOCAL modifiers act the same as for the regular SET command. The NONE and RESET forms reset the current user identifier to be the current session user identifier. These forms can be executed by any user. Notes Using this command, it is possible to either add privileges or restrict one's privileges. If the session user role has the INHERITS attribute, then it automatically has all the privileges of every role that it could SET ROLE to; in this case SET ROLE effectively drops all the privileges assigned directly to the session user and to the other roles it is a member of, leaving only the privileges available to the named role. On the other hand, if the session user role has the NOINHERITS attribute, SET ROLE drops the privileges assigned directly to the session user and instead acquires the privileges available to the named role. In particular, when a superuser chooses to SET ROLE to a non-superuser role, she loses her superuser privileges. SET ROLE has effects comparable to SET_SESSION_AUTHORIZATION, but the privilege checks involved are quite different. Also, SET SESSION AUTHORIZATION determines which roles are allowable for later SET ROLE commands, whereas changing roles with SET ROLE does not change the set of roles allowed to a later SET ROLE. SET ROLE cannot be used within a SECURITY DEFINER function. Examples SELECT SESSION_USER, CURRENT_USER; session_user | current_user --------------+-------------- peter | peter SET ROLE 'paul'; SELECT SESSION_USER, CURRENT_USER; session_user | current_user --------------+-------------- peter | paul Compatibility PostgreSQL allows identifier syntax ("rolename"), while the SQL standard requires the role name to be written as a string literal. SQL does not allow this command during a transaction; PostgreSQL does not make this restriction because there is no reason to. The SESSION and LOCAL modifiers are a PostgreSQL extension, as is the RESET syntax. See Also SET_SESSION_AUTHORIZATION ------------------------------------------------------------------------ SET SESSION AUTHORIZATION Name SET SESSION AUTHORIZATION -- set the session user identifier and the current user identifier of the current session Synopsis SET [ SESSION | LOCAL ] SESSION AUTHORIZATION username SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT RESET SESSION AUTHORIZATION Description This command sets the session user identifier and the current user identifier of the current SQL session to be username. The user name can be written as either an identifier or a string literal. Using this command, it is possible, for example, to temporarily become an unprivileged user and later switch back to being a superuser. The session user identifier is initially set to be the (possibly authenticated) user name provided by the client. The current user identifier is normally equal to the session user identifier, but might change temporarily in the context of SECURITY DEFINER functions and similar mechanisms; it can also be changed by SET_ROLE. The current user identifier is relevant for permission checking. The session user identifier can be changed only if the initial session user (the authenticated user) had the superuser privilege. Otherwise, the command is accepted only if it specifies the authenticated user name. The SESSION and LOCAL modifiers act the same as for the regular SET command. The DEFAULT and RESET forms reset the session and current user identifiers to be the originally authenticated user name. These forms can be executed by any user. Notes SET SESSION AUTHORIZATION cannot be used within a SECURITY DEFINER function. Examples SELECT SESSION_USER, CURRENT_USER; session_user | current_user --------------+-------------- peter | peter SET SESSION AUTHORIZATION 'paul'; SELECT SESSION_USER, CURRENT_USER; session_user | current_user --------------+-------------- paul | paul Compatibility The SQL standard allows some other expressions to appear in place of the literal username, but these options are not important in practice. PostgreSQL allows identifier syntax ("username"), which SQL does not. SQL does not allow this command during a transaction; PostgreSQL does not make this restriction because there is no reason to. The SESSION and LOCAL modifiers are a PostgreSQL extension, as is the RESET syntax. The privileges necessary to execute this command are left implementation- defined by the standard. See Also SET_ROLE ------------------------------------------------------------------------ SET TRANSACTION Name SET TRANSACTION -- set the characteristics of the current transaction Synopsis SET TRANSACTION transaction_mode [, ...] SET SESSION CHARACTERISTICS AS TRANSACTION transaction_mode [, ...] where transaction_mode is one of: ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } READ WRITE | READ ONLY Description The SET TRANSACTION command sets the characteristics of the current transaction. It has no effect on any subsequent transactions. SET SESSION CHARACTERISTICS sets the default transaction characteristics for subsequent transactions of a session. These defaults can be overridden by SET TRANSACTION for an individual transaction. The available transaction characteristics are the transaction isolation level and the transaction access mode (read/write or read-only). The isolation level of a transaction determines what data the transaction can see when other transactions are running concurrently: READ COMMITTED A statement can only see rows committed before it began. This is the default. SERIALIZABLE All statements of the current transaction can only see rows committed before the first query or data-modification statement was executed in this transaction. The SQL standard defines two additional levels, READ UNCOMMITTED and REPEATABLE READ. In PostgreSQL READ UNCOMMITTED is treated as READ COMMITTED, while REPEATABLE READ is treated as SERIALIZABLE. The transaction isolation level cannot be changed after the first query or data-modification statement (SELECT, INSERT, DELETE, UPDATE, FETCH, or COPY) of a transaction has been executed. See Chapter_13 for more information about transaction isolation and concurrency control. The transaction access mode determines whether the transaction is read/ write or read-only. Read/write is the default. When a transaction is read- only, the following SQL commands are disallowed: INSERT, UPDATE, DELETE, and COPY FROM if the table they would write to is not a temporary table; all CREATE, ALTER, and DROP commands; COMMENT, GRANT, REVOKE, TRUNCATE; and EXPLAIN ANALYZE and EXECUTE if the command they would execute is among those listed. This is a high-level notion of read-only that does not prevent all writes to disk. Notes If SET TRANSACTION is executed without a prior START TRANSACTION or BEGIN, it will appear to have no effect, since the transaction will immediately end. It is possible to dispense with SET TRANSACTION by instead specifying the desired transaction_modes in BEGIN or START TRANSACTION. The session default transaction modes can also be set by setting the configuration parameters default_transaction_isolation and default_transaction_read_only. (In fact SET SESSION CHARACTERISTICS is just a verbose equivalent for setting these variables with SET.) This means the defaults can be set in the configuration file, via ALTER DATABASE, etc. Consult Chapter_18 for more information. Compatibility Both commands are defined in the SQL standard. SERIALIZABLE is the default transaction isolation level in the standard. In PostgreSQL the default is ordinarily READ COMMITTED, but you can change it as mentioned above. Because of lack of predicate locking, the SERIALIZABLE level is not truly serializable. See Chapter_13 for details. In the SQL standard, there is one other transaction characteristic that can be set with these commands: the size of the diagnostics area. This concept is specific to embedded SQL, and therefore is not implemented in the PostgreSQL server. The SQL standard requires commas between successive transaction_modes, but for historical reasons PostgreSQL allows the commas to be omitted. ------------------------------------------------------------------------ SHOW Name SHOW -- show the value of a run-time parameter Synopsis SHOW name SHOW ALL Description SHOW will display the current setting of run-time parameters. These variables can be set using the SET statement, by editing the postgresql.conf configuration file, through the PGOPTIONS environmental variable (when using libpq or a libpq-based application), or through command-line flags when starting the postgres server. See Chapter_18 for details. Parameters SERVER_VERSION Shows the server's version number. SERVER_ENCODING Shows the server-side character set encoding. At present, this parameter can be shown but not set, because the encoding is determined at database creation time. LC_COLLATE Shows the database's locale setting for collation (text ordering). At present, this parameter can be shown but not set, because the setting is determined at initdb time. LC_CTYPE Shows the database's locale setting for character classification. At present, this parameter can be shown but not set, because the setting is determined at initdb time. IS_SUPERUSER True if the current role has superuser privileges. ALL Show the values of all configuration parameters, with descriptions. Notes The function current_setting produces equivalent output; see Section_9.23. Also, the pg_settings system view produces the same information. Examples Show the current setting of the parameter DateStyle: SHOW DateStyle; DateStyle ----------- ISO, MDY (1 row) Show the current setting of the parameter geqo: SHOW geqo; geqo ------ on (1 row) Show all settings: SHOW ALL; name | setting | description --------------------------------+--------------------------------+------- ------------------------------------------------------------------------ START TRANSACTION Name START TRANSACTION -- start a transaction block Synopsis START TRANSACTION [ transaction_mode [, ...] ] where transaction_mode is one of: ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } READ WRITE | READ ONLY Description This command begins a new transaction block. If the isolation level or read/write mode is specified, the new transaction has those characteristics, as if SET_TRANSACTION was executed. This is the same as the BEGIN command. Parameters Refer to SET_TRANSACTION for information on the meaning of the parameters to this statement. Compatibility In the standard, it is not necessary to issue START TRANSACTION to start a transaction block: any SQL command implicitly begins a block. PostgreSQL's behavior can be seen as implicitly issuing a COMMIT after each command that does not follow START TRANSACTION (or BEGIN), and it is therefore often called "autocommit". Other relational database systems might offer an autocommit feature as a convenience. The SQL standard requires commas between successive transaction_modes, but for historical reasons PostgreSQL allows the commas to be omitted. See also the compatibility section of SET_TRANSACTION. See Also BEGIN, COMMIT, ROLLBACK, SAVEPOINT, SET_TRANSACTION ------------------------------------------------------------------------ TRUNCATE Name TRUNCATE -- empty a table or set of tables Synopsis TRUNCATE [ TABLE ] name [, ...] [ CASCADE | RESTRICT ] Description TRUNCATE quickly removes all rows from a set of tables. It has the same effect as an unqualified DELETE on each table, but since it does not actually scan the tables it is faster. Furthermore, it reclaims disk space immediately, rather than requiring a subsequent VACUUM operation. This is most useful on large tables. Parameters name The name (optionally schema-qualified) of a table to be truncated. CASCADE Automatically truncate all tables that have foreign-key references to any of the named tables, or to any tables added to the group due to CASCADE. RESTRICT Refuse to truncate if any of the tables have foreign-key references from tables that are not to be truncated. This is the default. Notes Only the owner of a table can TRUNCATE it. TRUNCATE cannot be used on a table that has foreign-key references from other tables, unless all such tables are also truncated in the same command. Checking validity in such cases would require table scans, and the whole point is not to do one. The CASCADE option can be used to automatically include all dependent tables -- but be very careful when using this option, or else you might lose data you did not intend to! TRUNCATE will not run any ON DELETE triggers that might exist for the tables. ________________________________________________________________________ |________________________________________________Warning_________________| |TRUNCATE is not MVCC-safe (see Chapter_13 for general information about | |MVCC). After truncation, the table will appear empty to all concurrent | |transactions, even if they are using a snapshot taken before the | |truncation occurred. This will only be an issue for a transaction that | |did not access the truncated table before the truncation happened -- any| |transaction that has done so would hold at least an ACCESS SHARE lock, | |which would block TRUNCATE until that transaction completes. So | |truncation will not cause any apparent inconsistency in the table | |contents for successive queries on the same table, but it could cause | |visible inconsistency between the contents of the truncated table and | |other tables in the database. | |TRUNCATE is transaction-safe, however: the truncation will be safely | |rolled_back_if_the_surrounding_transaction_does_not_commit._____________| Examples Truncate the tables bigtable and fattable: TRUNCATE bigtable, fattable; Truncate the table othertable, and cascade to any tables that reference othertable via foreign-key constraints: TRUNCATE othertable CASCADE; Compatibility There is no TRUNCATE command in the SQL standard. ------------------------------------------------------------------------ UNLISTEN Name UNLISTEN -- stop listening for a notification Synopsis UNLISTEN { name | * } Description UNLISTEN is used to remove an existing registration for NOTIFY events. UNLISTEN cancels any existing registration of the current PostgreSQL session as a listener on the notification name. The special wildcard * cancels all listener registrations for the current session. NOTIFY contains a more extensive discussion of the use of LISTEN and NOTIFY. Parameters name Name of a notification (any identifier). * All current listen registrations for this session are cleared. Notes You can unlisten something you were not listening for; no warning or error will appear. At the end of each session, UNLISTEN * is automatically executed. Examples To make a registration: LISTEN virtual; NOTIFY virtual; Asynchronous notification "virtual" received from server process with PID 8448. Once UNLISTEN has been executed, further NOTIFY commands will be ignored: UNLISTEN virtual; NOTIFY virtual; -- no NOTIFY event is received Compatibility There is no UNLISTEN command in the SQL standard. See Also LISTEN, NOTIFY ------------------------------------------------------------------------ UPDATE Name UPDATE -- update rows of a table Synopsis UPDATE [ ONLY ] table [ [ AS ] alias ] SET { column = { expression | DEFAULT } | ( column [, ...] ) = ( { expression | DEFAULT } [, ...] ) } [, ...] [ FROM fromlist ] [ WHERE condition | WHERE CURRENT OF cursor_name ] [ RETURNING * | output_expression [ AS output_name ] [, ...] ] Description UPDATE changes the values of the specified columns in all rows that satisfy the condition. Only the columns to be modified need be mentioned in the SET clause; columns not explicitly modified retain their previous values. By default, UPDATE will update rows in the specified table and all its subtables. If you wish to only update the specific table mentioned, you must use the ONLY clause. There are two ways to modify a table using information contained in other tables in the database: using sub-selects, or specifying additional tables in the FROM clause. Which technique is more appropriate depends on the specific circumstances. The optional RETURNING clause causes UPDATE to compute and return value(s) based on each row actually updated. Any expression using the table's columns, and/or columns of other tables mentioned in FROM, can be computed. The new (post-update) values of the table's columns are used. The syntax of the RETURNING list is identical to that of the output list of SELECT. You must have the UPDATE privilege on the table to update it, as well as the SELECT privilege to any table whose values are read in the expressions or condition. Parameters table The name (optionally schema-qualified) of the table to update. alias A substitute name for the target table. When an alias is provided, it completely hides the actual name of the table. For example, given UPDATE foo AS f, the remainder of the UPDATE statement must refer to this table as f not foo. column The name of a column in table. The column name can be qualified with a subfield name or array subscript, if needed. Do not include the table's name in the specification of a target column -- for example, UPDATE tab SET tab.col = 1 is invalid. expression An expression to assign to the column. The expression can use the old values of this and other columns in the table. DEFAULT Set the column to its default value (which will be NULL if no specific default expression has been assigned to it). fromlist A list of table expressions, allowing columns from other tables to appear in the WHERE condition and the update expressions. This is similar to the list of tables that can be specified in the FROM Clause of a SELECT statement. Note that the target table must not appear in the fromlist, unless you intend a self-join (in which case it must appear with an alias in the fromlist). condition An expression that returns a value of type boolean. Only rows for which this expression returns true will be updated. cursor_name The name of the cursor to use in a WHERE CURRENT OF condition. The row to be updated is the one most recently fetched from this cursor. The cursor must be a simple (non-join, non-aggregate) query on the UPDATE's target table. Note that WHERE CURRENT OF cannot be specified together with a Boolean condition. output_expression An expression to be computed and returned by the UPDATE command after each row is updated. The expression can use any column names of the table or table(s) listed in FROM. Write * to return all columns. output_name A name to use for a returned column. Outputs On successful completion, an UPDATE command returns a command tag of the form UPDATE count The count is the number of rows updated. If count is 0, no rows matched the condition (this is not considered an error). If the UPDATE command contains a RETURNING clause, the result will be similar to that of a SELECT statement containing the columns and values defined in the RETURNING list, computed over the row(s) updated by the command. Notes When a FROM clause is present, what essentially happens is that the target table is joined to the tables mentioned in the fromlist, and each output row of the join represents an update operation for the target table. When using FROM you should ensure that the join produces at most one output row for each row to be modified. In other words, a target row shouldn't join to more than one row from the other table(s). If it does, then only one of the join rows will be used to update the target row, but which one will be used is not readily predictable. Because of this indeterminacy, referencing other tables only within sub- selects is safer, though often harder to read and slower than using a join. Examples Change the word Drama to Dramatic in the column kind of the table films: UPDATE films SET kind = 'Dramatic' WHERE kind = 'Drama'; Adjust temperature entries and reset precipitation to its default value in one row of the table weather: UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT WHERE city = 'San Francisco' AND date = '2003-07-03'; Perform the same operation and return the updated entries: UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT WHERE city = 'San Francisco' AND date = '2003-07-03' RETURNING temp_lo, temp_hi, prcp; Use the alternative column-list syntax to do the same update: UPDATE weather SET (temp_lo, temp_hi, prcp) = (temp_lo+1, temp_lo+15, DEFAULT) WHERE city = 'San Francisco' AND date = '2003-07-03'; Increment the sales count of the salesperson who manages the account for Acme Corporation, using the FROM clause syntax: UPDATE employees SET sales_count = sales_count + 1 FROM accounts WHERE accounts.name = 'Acme Corporation' AND employees.id = accounts.sales_person; Perform the same operation, using a sub-select in the WHERE clause: UPDATE employees SET sales_count = sales_count + 1 WHERE id = (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation'); Attempt to insert a new stock item along with the quantity of stock. If the item already exists, instead update the stock count of the existing item. To do this without failing the entire transaction, use savepoints: BEGIN; -- other operations SAVEPOINT sp1; INSERT INTO wines VALUES('Chateau Lafite 2003', '24'); -- Assume the above fails because of a unique key violation, -- so now we issue these commands: ROLLBACK TO sp1; UPDATE wines SET stock = stock + 24 WHERE winename = 'Chateau Lafite 2003'; -- continue with other operations, and eventually COMMIT; Change the kind column of the table films in the row on which the cursor c_films is currently positioned: UPDATE films SET kind = 'Dramatic' WHERE CURRENT OF c_films; Compatibility This command conforms to the SQL standard, except that the FROM and RETURNING clauses are PostgreSQL extensions. According to the standard, the column-list syntax should allow a list of columns to be assigned from a single row-valued expression, such as a sub- select: UPDATE accounts SET (contact_last_name, contact_first_name) = (SELECT last_name, first_name FROM salesmen WHERE salesmen.id = accounts.sales_id); This is not currently implemented -- the source must be a list of independent expressions. Some other database systems offer a FROM option in which the target table is supposed to be listed again within FROM. That is not how PostgreSQL interprets FROM. Be careful when porting applications that use this extension. ------------------------------------------------------------------------ VACUUM Name VACUUM -- garbage-collect and optionally analyze a database Synopsis VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ table ] VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ table [ (column [, ...] ) ] ] Description VACUUM reclaims storage occupied by dead tuples. In normal PostgreSQL operation, tuples that are deleted or obsoleted by an update are not physically removed from their table; they remain present until a VACUUM is done. Therefore it's necessary to do VACUUM periodically, especially on frequently-updated tables. With no parameter, VACUUM processes every table in the current database. With a parameter, VACUUM processes only that table. VACUUM ANALYZE performs a VACUUM and then an ANALYZE for each selected table. This is a handy combination form for routine maintenance scripts. See ANALYZE for more details about its processing. Plain VACUUM (without FULL) simply reclaims space and makes it available for re-use. This form of the command can operate in parallel with normal reading and writing of the table, as an exclusive lock is not obtained. VACUUM FULL does more extensive processing, including moving of tuples across blocks to try to compact the table to the minimum number of disk blocks. This form is much slower and requires an exclusive lock on each table while it is being processed. Parameters FULL Selects "full" vacuum, which can reclaim more space, but takes much longer and exclusively locks the table. FREEZE Selects aggressive "freezing" of tuples. Specifying FREEZE is equivalent to performing VACUUM with the vacuum_freeze_min_age parameter set to zero. The FREEZE option is deprecated and will be removed in a future release; set the parameter instead. VERBOSE Prints a detailed vacuum activity report for each table. Can be used to help determine appropriate settings for max_fsm_pages, max_fsm_relations, and default_statistics_target. ANALYZE Updates statistics used by the planner to determine the most efficient way to execute a query. table The name (optionally schema-qualified) of a specific table to vacuum. Defaults to all tables in the current database. column The name of a specific column to analyze. Defaults to all columns. Outputs When VERBOSE is specified, VACUUM emits progress messages to indicate which table is currently being processed. Various statistics about the tables are printed as well. Notes VACUUM cannot be executed inside a transaction block. We recommend that active production databases be vacuumed frequently (at least nightly), in order to remove dead rows. After adding or deleting a large number of rows, it might be a good idea to issue a VACUUM ANALYZE command for the affected table. This will update the system catalogs with the results of all recent changes, and allow the PostgreSQL query planner to make better choices in planning queries. The FULL option is not recommended for routine use, but might be useful in special cases. An example is when you have deleted or updated most of the rows in a table and would like the table to physically shrink to occupy less disk space and allow faster table scans. VACUUM FULL will usually shrink the table more than a plain VACUUM would. The FULL option does not shrink indexes; a periodic REINDEX is still recommended. In fact, it is often faster to drop all indexes, VACUUM FULL, and recreate the indexes. VACUUM causes a substantial increase in I/O traffic, which might cause poor performance for other active sessions. Therefore, it is sometimes advisable to use the cost-based vacuum delay feature. See Section_18.4.4 for details. PostgreSQL includes an "autovacuum" facility which can automate routine vacuum maintenance. For more information about automatic and manual vacuuming, see Section_23.1. Examples The following is an example from running VACUUM on a table in the regression database: regression=# VACUUM VERBOSE ANALYZE onek; INFO: vacuuming "public.onek" INFO: index "onek_unique1" now contains 1000 tuples in 14 pages DETAIL: 3000 index tuples were removed. 0 index pages have been deleted, 0 are currently reusable. CPU 0.01s/0.08u sec elapsed 0.18 sec. INFO: index "onek_unique2" now contains 1000 tuples in 16 pages DETAIL: 3000 index tuples were removed. 0 index pages have been deleted, 0 are currently reusable. CPU 0.00s/0.07u sec elapsed 0.23 sec. INFO: index "onek_hundred" now contains 1000 tuples in 13 pages DETAIL: 3000 index tuples were removed. 0 index pages have been deleted, 0 are currently reusable. CPU 0.01s/0.08u sec elapsed 0.17 sec. INFO: index "onek_stringu1" now contains 1000 tuples in 48 pages DETAIL: 3000 index tuples were removed. 0 index pages have been deleted, 0 are currently reusable. CPU 0.01s/0.09u sec elapsed 0.59 sec. INFO: "onek": removed 3000 tuples in 108 pages DETAIL: CPU 0.01s/0.06u sec elapsed 0.07 sec. INFO: "onek": found 3000 removable, 1000 nonremovable tuples in 143 pages DETAIL: 0 dead tuples cannot be removed yet. There were 0 unused item pointers. 0 pages are entirely empty. CPU 0.07s/0.39u sec elapsed 1.56 sec. INFO: analyzing "public.onek" INFO: "onek": 36 pages, 1000 rows sampled, 1000 estimated total rows VACUUM Compatibility There is no VACUUM statement in the SQL standard. See Also vacuumdb, Cost-Based_Vacuum_Delay, The_Auto-Vacuum_Daemon ------------------------------------------------------------------------ VALUES Name VALUES -- compute a set of rows Synopsis VALUES ( expression [, ...] ) [, ...] [ ORDER BY sort_expression [ ASC | DESC | USING operator ] [, ...] ] [ LIMIT { count | ALL } ] [ OFFSET start ] Description VALUES computes a row value or set of row values specified by value expressions. It is most commonly used to generate a "constant table" within a larger command, but it can be used on its own. When more than one row is specified, all the rows must have the same number of elements. The data types of the resulting table's columns are determined by combining the explicit or inferred types of the expressions appearing in that column, using the same rules as for UNION (see Section_10.5). Within larger commands, VALUES is syntactically allowed anywhere that SELECT is. Because it is treated like a SELECT by the grammar, it is possible to use the ORDER BY, LIMIT, and OFFSET clauses with a VALUES command. Parameters expression A constant or expression to compute and insert at the indicated place in the resulting table (set of rows). In a VALUES list appearing at the top level of an INSERT, an expression can be replaced by DEFAULT to indicate that the destination column's default value should be inserted. DEFAULT cannot be used when VALUES appears in other contexts. sort_expression An expression or integer constant indicating how to sort the result rows. This expression can refer to the columns of the VALUES result as column1, column2, etc. For more details see ORDER_BY_Clause. operator A sorting operator. For details see ORDER_BY_Clause. count The maximum number of rows to return. For details see LIMIT_Clause. start The number of rows to skip before starting to return rows. For details see LIMIT_Clause. Notes VALUES lists with very large numbers of rows should be avoided, as you might encounter out-of-memory failures or poor performance. VALUES appearing within INSERT is a special case (because the desired column types are known from the INSERT's target table, and need not be inferred by scanning the VALUES list), so it can handle larger lists than are practical in other contexts. Examples A bare VALUES command: VALUES (1, 'one'), (2, 'two'), (3, 'three'); This will return a table of two columns and three rows. It's effectively equivalent to: SELECT 1 AS column1, 'one' AS column2 UNION ALL SELECT 2, 'two' UNION ALL SELECT 3, 'three'; More usually, VALUES is used within a larger SQL command. The most common use is in INSERT: INSERT INTO films (code, title, did, date_prod, kind) VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama'); In the context of INSERT, entries of a VALUES list can be DEFAULT to indicate that the column default should be used here instead of specifying a value: INSERT INTO films VALUES ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes'), ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama', DEFAULT); VALUES can also be used where a sub-SELECT might be written, for example in a FROM clause: SELECT f.* FROM films f, (VALUES('MGM', 'Horror'), ('UA', 'Sci-Fi')) AS t (studio, kind) WHERE f.studio = t.studio AND f.kind = t.kind; UPDATE employees SET salary = salary * v.increase FROM (VALUES(1, 200000, 1.2), (2, 400000, 1.4)) AS v (depno, target, increase) WHERE employees.depno = v.depno AND employees.sales >= v.target; Note that an AS clause is required when VALUES is used in a FROM clause, just as is true for SELECT. It is not required that the AS clause specify names for all the columns, but it's good practice to do so. (The default column names for VALUES are column1, column2, etc in PostgreSQL, but these names might be different in other database systems.) When VALUES is used in INSERT, the values are all automatically coerced to the data type of the corresponding destination column. When it's used in other contexts, it might be necessary to specify the correct data type. If the entries are all quoted literal constants, coercing the first is sufficient to determine the assumed type for all: SELECT * FROM machines WHERE ip_address IN (VALUES('192.168.0.1'::inet), ('192.168.0.10'), ('192.168.1.43')); Tip: For simple IN tests, it's better to rely on the list-of- scalars form of IN than to write a VALUES query as shown above. The list of scalars method requires less writing and is often more efficient. Compatibility VALUES conforms to the SQL standard, except that LIMIT and OFFSET are PostgreSQL extensions. See Also INSERT, SELECT ------------------------------------------------------------------------ ------------------------------------------------------------------------ II. PostgreSQL Client Applications This part contains reference information for PostgreSQL client applications and utilities. Not all of these commands are of general utility, some might require special privileges. The common feature of these applications is that they can be run on any host, independent of where the database server resides. Table of Contents clusterdb -- cluster a PostgreSQL database createdb -- create a new PostgreSQL database createlang -- define a new PostgreSQL procedural language createuser -- define a new PostgreSQL user account dropdb -- remove a PostgreSQL database droplang -- remove a PostgreSQL procedural language dropuser -- remove a PostgreSQL user account ecpg -- embedded SQL C preprocessor pg_config -- retrieve information about the installed version of PostgreSQL pg_dump -- extract a PostgreSQL database into a script file or other archive file pg_dumpall -- extract a PostgreSQL database cluster into a script file pg_restore -- restore a PostgreSQL database from an archive file created by pg_dump psql -- PostgreSQL interactive terminal reindexdb -- reindex a PostgreSQL database vacuumdb -- garbage-collect and analyze a PostgreSQL database ------------------------------------------------------------------------ clusterdb Name clusterdb -- cluster a PostgreSQL database Synopsis clusterdb [connection-option...] [--table | -t table ] [dbname] clusterdb [connection-option...] [--all | -a] Description clusterdb is a utility for reclustering tables in a PostgreSQL database. It finds tables that have previously been clustered, and clusters them again on the same index that was last used. Tables that have never been clustered are not affected. clusterdb is a wrapper around the SQL command CLUSTER. There is no effective difference between clustering databases via this utility and via other methods for accessing the server. Options clusterdb accepts the following command-line arguments: -a --all Cluster all databases. [-d] dbname [--dbname] dbname Specifies the name of the database to be clustered. If this is not specified and -a (or --all) is not used, the database name is read from the environment variable PGDATABASE. If that is not set, the user name specified for the connection is used. -e --echo Echo the commands that clusterdb generates and sends to the server. -q --quiet Do not display progress messages. -t table --table table Cluster table only. clusterdb also accepts the following command-line arguments for connection parameters: -h host --host host Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. -p port --port port Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections. -U username --username username User name to connect as. -W --password Force clusterdb to prompt for a password before connecting to a database. This option is never essential, since clusterdb will automatically prompt for a password if the server demands password authentication. However, clusterdb will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Environment PGDATABASE PGHOST PGPORT PGUSER Default connection parameters This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics In case of difficulty, see CLUSTER and psql for discussions of potential problems and error messages. The database server must be running at the targeted host. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Examples To cluster the database test: $ clusterdb test To cluster a single table foo in a database named xyzzy: $ clusterdb --table foo xyzzy See Also CLUSTER ------------------------------------------------------------------------ createdb Name createdb -- create a new PostgreSQL database Synopsis createdb [option...] [dbname] [description] Description createdb creates a new PostgreSQL database. Normally, the database user who executes this command becomes the owner of the new database. However a different owner can be specified via the - O option, if the executing user has appropriate privileges. createdb is a wrapper around the SQL command CREATE_DATABASE. There is no effective difference between creating databases via this utility and via other methods for accessing the server. Options createdb accepts the following command-line arguments: dbname Specifies the name of the database to be created. The name must be unique among all PostgreSQL databases in this cluster. The default is to create a database with the same name as the current system user. description Specifies a comment to be associated with the newly created database. -D tablespace --tablespace tablespace Specifies the default tablespace for the database. -e --echo Echo the commands that createdb generates and sends to the server. -E encoding --encoding encoding Specifies the character encoding scheme to be used in this database. The character sets supported by the PostgreSQL server are described in Section_22.2.1. -O owner --owner owner Specifies the database user who will own the new database. -T template --template template Specifies the template database from which to build this database. The options -D, -E, -O, and -T correspond to options of the underlying SQL command CREATE_DATABASE; see there for more information about them. createdb also accepts the following command-line arguments for connection parameters: -h host --host host Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. -p port --port port Specifies the TCP port or the local Unix domain socket file extension on which the server is listening for connections. -U username --username username User name to connect as. -W --password Force createdb to prompt for a password before connecting to a database. This option is never essential, since createdb will automatically prompt for a password if the server demands password authentication. However, createdb will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Environment PGDATABASE If set, the name of the database to create, unless overridden on the command line. PGHOST PGPORT PGUSER Default connection parameters. PGUSER also determines the name of the database to create, if it is not specified on the command line or by PGDATABASE. This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics In case of difficulty, see CREATE_DATABASE and psql for discussions of potential problems and error messages. The database server must be running at the targeted host. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Examples To create the database demo using the default database server: $ createdb demo To create the database demo using the server on host eden, port 5000, using the LATIN1 encoding scheme with a look at the underlying command: $ createdb -p 5000 -h eden -E LATIN1 -e demo CREATE DATABASE demo ENCODING 'LATIN1'; See Also dropdb, CREATE_DATABASE ------------------------------------------------------------------------ createlang Name createlang -- define a new PostgreSQL procedural language Synopsis createlang [connection-option...] langname [dbname] createlang [connection-option...] --list | -l dbname Description createlang is a utility for adding a new programming language to a PostgreSQL database. createlang is just a wrapper around the CREATE LANGUAGE command. Options createlang accepts the following command-line arguments: langname Specifies the name of the procedural programming language to be defined. [-d] dbname [--dbname] dbname Specifies to which database the language should be added. The default is to use the database with the same name as the current system user. -e --echo Display SQL commands as they are executed. -l --list Show a list of already installed languages in the target database. createlang also accepts the following command-line arguments for connection parameters: -h host --host host Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. -p port --port port Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections. -U username --username username User name to connect as. -W --password Force createlang to prompt for a password before connecting to a database. This option is never essential, since createlang will automatically prompt for a password if the server demands password authentication. However, createlang will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Environment PGDATABASE PGHOST PGPORT PGUSER Default connection parameters This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics Most error messages are self-explanatory. If not, run createlang with the - -echo option and see under the respective SQL command for details. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Notes Use droplang to remove a language. Examples To install the language pltcl into the database template1: $ createlang pltcl template1 Note that installing the language into template1 will cause it to be automatically installed into subsequently-created databases as well. See Also droplang, CREATE_LANGUAGE ------------------------------------------------------------------------ createuser Name createuser -- define a new PostgreSQL user account Synopsis createuser [option...] [username] Description createuser creates a new PostgreSQL user (or more precisely, a role). Only superusers and users with CREATEROLE privilege can create new users, so createuser must be invoked by someone who can connect as a superuser or a user with CREATEROLE privilege. If you wish to create a new superuser, you must connect as a superuser, not merely with CREATEROLE privilege. Being a superuser implies the ability to bypass all access permission checks within the database, so superuserdom should not be granted lightly. createuser is a wrapper around the SQL command CREATE_ROLE. There is no effective difference between creating users via this utility and via other methods for accessing the server. Options createuser accepts the following command-line arguments: username Specifies the name of the PostgreSQL user to be created. This name must be different from all existing roles in this PostgreSQL installation. -s --superuser The new user will be a superuser. -S --no-superuser The new user will not be a superuser. This is the default. -d --createdb The new user will be allowed to create databases. -D --no-createdb The new user will not be allowed to create databases. This is the default. -r --createrole The new user will be allowed to create new roles (that is, this user will have CREATEROLE privilege). -R --no-createrole The new user will not be allowed to create new roles. This is the default. -l --login The new user will be allowed to log in (that is, the user name can be used as the initial session user identifier). This is the default. -L --no-login The new user will not be allowed to log in. (A role without login privilege is still useful as a means of managing database permissions.) -i --inherit The new role will automatically inherit privileges of roles it is a member of. This is the default. -I --no-inherit The new role will not automatically inherit privileges of roles it is a member of. -c number --connection-limit number Set a maximum number of connections for the new user. The default is to set no limit. -P --pwprompt If given, createuser will issue a prompt for the password of the new user. This is not necessary if you do not plan on using password authentication. -E --encrypted Encrypts the user's password stored in the database. If not specified, the default password behavior is used. -N --unencrypted Does not encrypt the user's password stored in the database. If not specified, the default password behavior is used. -e --echo Echo the commands that createuser generates and sends to the server. You will be prompted for a name and other missing information if it is not specified on the command line. createuser also accepts the following command-line arguments for connection parameters: -h host --host host Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. -p port --port port Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections. -U username --username username User name to connect as (not the user name to create). -W --password Force createuser to prompt for a password (for connecting to the server, not for the password of the new user). This option is never essential, since createuser will automatically prompt for a password if the server demands password authentication. However, createuser will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Environment PGHOST PGPORT PGUSER Default connection parameters This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics In case of difficulty, see CREATE_ROLE and psql for discussions of potential problems and error messages. The database server must be running at the targeted host. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Examples To create a user joe on the default database server: $ createuser joe Shall the new role be a superuser? (y/n) n Shall the new role be allowed to create databases? (y/n) n Shall the new role be allowed to create more new roles? (y/n) n To create the same user joe using the server on host eden, port 5000, avoiding the prompts and taking a look at the underlying command: $ createuser -h eden -p 5000 -S -D -R -e joe CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN; To create the user joe as a superuser, and assign a password immediately: $ createuser -P -s -e joe Enter password for new role: xyzzy Enter it again: xyzzy CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN; In the above example, the new password isn't actually echoed when typed, but we show what was typed for clarity. As you see, the password is encrypted before it is sent to the client. If the option --unencrypted is used, the password will appear in the echoed command (and possibly also in the server log and elsewhere), so you don't want to use -e in that case, if anyone else can see your screen. See Also dropuser, CREATE_ROLE ------------------------------------------------------------------------ dropdb Name dropdb -- remove a PostgreSQL database Synopsis dropdb [option...] dbname Description dropdb destroys an existing PostgreSQL database. The user who executes this command must be a database superuser or the owner of the database. dropdb is a wrapper around the SQL command DROP_DATABASE. There is no effective difference between dropping databases via this utility and via other methods for accessing the server. Options dropdb accepts the following command-line arguments: dbname Specifies the name of the database to be removed. -e --echo Echo the commands that dropdb generates and sends to the server. -i --interactive Issues a verification prompt before doing anything destructive. dropdb also accepts the following command-line arguments for connection parameters: -h host --host host Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. -p port --port port Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections. -U username --username username User name to connect as. -W --password Force dropdb to prompt for a password before connecting to a database. This option is never essential, since dropdb will automatically prompt for a password if the server demands password authentication. However, dropdb will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Environment PGHOST PGPORT PGUSER Default connection parameters This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics In case of difficulty, see DROP_DATABASE and psql for discussions of potential problems and error messages. The database server must be running at the targeted host. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Examples To destroy the database demo on the default database server: $ dropdb demo To destroy the database demo using the server on host eden, port 5000, with verification and a peek at the underlying command: $ dropdb -p 5000 -h eden -i -e demo Database "demo" will be permanently deleted. Are you sure? (y/n) y DROP DATABASE demo; See Also createdb, DROP_DATABASE ------------------------------------------------------------------------ droplang Name droplang -- remove a PostgreSQL procedural language Synopsis droplang [connection-option...] langname [dbname] droplang [connection-option...] --list | -l dbname Description droplang is a utility for removing an existing programming language from a PostgreSQL database. droplang can drop any procedural language, even those not supplied by the PostgreSQL distribution. Although backend programming languages can be removed directly using several SQL commands, it is recommended to use droplang because it performs a number of checks and is much easier to use. See DROP_LANGUAGE for more. Options droplang accepts the following command line arguments: langname Specifies the name of the backend programming language to be removed. [-d] dbname [--dbname] dbname Specifies from which database the language should be removed. The default is to use the database with the same name as the current system user. -e --echo Display SQL commands as they are executed. -l --list Show a list of already installed languages in the target database. droplang also accepts the following command line arguments for connection parameters: -h host --host host Specifies the host name of the machine on which the server is running. If host begins with a slash, it is used as the directory for the Unix domain socket. -p port --port port Specifies the Internet TCP/IP port or local Unix domain socket file extension on which the server is listening for connections. -U username --username username User name to connect as. -W --password Force droplang to prompt for a password before connecting to a database. This option is never essential, since droplang will automatically prompt for a password if the server demands password authentication. However, droplang will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Environment PGDATABASE PGHOST PGPORT PGUSER Default connection parameters This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics Most error messages are self-explanatory. If not, run droplang with the -- echo option and see under the respective SQL command for details. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Notes Use createlang to add a language. Examples To remove the language pltcl: $ droplang pltcl dbname See Also createlang, DROP_LANGUAGE ------------------------------------------------------------------------ dropuser Name dropuser -- remove a PostgreSQL user account Synopsis dropuser [option...] [username] Description dropuser removes an existing PostgreSQL user. Only superusers and users with the CREATEROLE privilege can remove PostgreSQL users. (To remove a superuser, you must yourself be a superuser.) dropuser is a wrapper around the SQL command DROP_ROLE. There is no effective difference between dropping users via this utility and via other methods for accessing the server. Options dropuser accepts the following command-line arguments: username Specifies the name of the PostgreSQL user to be removed. You will be prompted for a name if none is specified on the command line. -e --echo Echo the commands that dropuser generates and sends to the server. -i --interactive Prompt for confirmation before actually removing the user. dropuser also accepts the following command-line arguments for connection parameters: -h host --host host Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. -p port --port port Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections. -U username --username username User name to connect as (not the user name to drop). -W --password Force dropuser to prompt for a password before connecting to a database. This option is never essential, since dropuser will automatically prompt for a password if the server demands password authentication. However, dropuser will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Environment PGHOST PGPORT PGUSER Default connection parameters This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics In case of difficulty, see DROP_ROLE and psql for discussions of potential problems and error messages. The database server must be running at the targeted host. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Examples To remove user joe from the default database server: $ dropuser joe To remove user joe using the server on host eden, port 5000, with verification and a peek at the underlying command: $ dropuser -p 5000 -h eden -i -e joe Role "joe" will be permanently removed. Are you sure? (y/n) y DROP ROLE joe; See Also createuser, DROP_ROLE ------------------------------------------------------------------------ ecpg Name ecpg -- embedded SQL C preprocessor Synopsis ecpg [option...] file... Description ecpg is the embedded SQL preprocessor for C programs. It converts C programs with embedded SQL statements to normal C code by replacing the SQL invocations with special function calls. The output files can then be processed with any C compiler tool chain. ecpg will convert each input file given on the command line to the corresponding C output file. Input files preferably have the extension .pgc, in which case the extension will be replaced by .c to determine the output file name. If the extension of the input file is not .pgc, then the output file name is computed by appending .c to the full file name. The output file name can also be overridden using the -o option. This reference page does not describe the embedded SQL language. See Chapter_32 for more information on that topic. Options ecpg accepts the following command-line arguments: -c Automatically generate certain C code from SQL code. Currently, this works for EXEC SQL TYPE. -C mode Set a compatibility mode. mode can be INFORMIX or INFORMIX_SE. -D symbol Define a C preprocessor symbol. -i Parse system include files as well. -I directory Specify an additional include path, used to find files included via EXEC SQL INCLUDE. Defaults are . (current directory), /usr/local/ include, the PostgreSQL include directory which is defined at compile time (default: /usr/local/pgsql/include), and /usr/include, in that order. -o filename Specifies that ecpg should write all its output to the given filename. -r option Selects a run-time behavior. Currently, option can only be no_indicator. -t Turn on autocommit of transactions. In this mode, each SQL command is automatically committed unless it is inside an explicit transaction block. In the default mode, commands are committed only when EXEC SQL COMMIT is issued. -v Print additional information including the version and the include path. --help Show a brief summary of the command usage, then exit. --version Output version information, then exit. Notes When compiling the preprocessed C code files, the compiler needs to be able to find the ECPG header files in the PostgreSQL include directory. Therefore, one might have to use the -I option when invoking the compiler (e.g., -I/usr/local/pgsql/include). Programs using C code with embedded SQL have to be linked against the libecpg library, for example using the linker options -L/usr/local/pgsql/ lib -lecpg. The value of either of these directories that is appropriate for the installation can be found out using pg_config. Examples If you have an embedded SQL C source file named prog1.pgc, you can create an executable program using the following sequence of commands: ecpg prog1.pgc cc -I/usr/local/pgsql/include -c prog1.c cc -o prog1 prog1.o -L/usr/local/pgsql/lib -lecpg ------------------------------------------------------------------------ pg_config Name pg_config -- retrieve information about the installed version of PostgreSQL Synopsis pg_config [option...] Description The pg_config utility prints configuration parameters of the currently installed version of PostgreSQL. It is intended, for example, to be used by software packages that want to interface to PostgreSQL to facilitate finding the required header files and libraries. Options To use pg_config, supply one or more of the following options: --bindir Print the location of user executables. Use this, for example, to find the psql program. This is normally also the location where the pg_config program resides. --docdir Print the location of documentation files. (This will be an empty string if --without-docdir was specified when PostgreSQL was built.) --includedir Print the location of C header files of the client interfaces. --pkgincludedir Print the location of other C header files. --includedir-server Print the location of C header files for server programming. --libdir Print the location of object code libraries. --pkglibdir Print the location of dynamically loadable modules, or where the server would search for them. (Other architecture-dependent data files might also be installed in this directory.) --localedir Print the location of locale support files. (This will be an empty string if locale support was not configured when PostgreSQL was built.) --mandir Print the location of manual pages. --sharedir Print the location of architecture-independent support files. --sysconfdir Print the location of system-wide configuration files. --pgxs Print the location of extension makefiles. --configure Print the options that were given to the configure script when PostgreSQL was configured for building. This can be used to reproduce the identical configuration, or to find out with what options a binary package was built. (Note however that binary packages often contain vendor-specific custom patches.) See also the examples below. --cc Print the value of the CC variable that was used for building PostgreSQL. This shows the C compiler used. --cppflags Print the value of the CPPFLAGS variable that was used for building PostgreSQL. This shows C compiler switches needed at preprocessing time (typically, -I switches). --cflags Print the value of the CFLAGS variable that was used for building PostgreSQL. This shows C compiler switches. --cflags_sl Print the value of the CFLAGS_SL variable that was used for building PostgreSQL. This shows extra C compiler switches used for building shared libraries. --ldflags Print the value of the LDFLAGS variable that was used for building PostgreSQL. This shows linker switches. --ldflags_sl Print the value of the LDFLAGS_SL variable that was used for building PostgreSQL. This shows linker switches used for building shared libraries. --libs Print the value of the LIBS variable that was used for building PostgreSQL. This normally contains -l switches for external libraries linked into PostgreSQL. --version Print the version of PostgreSQL. If more than one option is given, the information is printed in that order, one item per line. If no options are given, all available information is printed, with labels. Notes The option --includedir-server was new in PostgreSQL 7.2. In prior releases, the server include files were installed in the same location as the client headers, which could be queried with the option --includedir. To make your package handle both cases, try the newer option first and test the exit status to see whether it succeeded. The options --docdir, --pkgincludedir, --localedir, --mandir, --sharedir, - -sysconfdir, --cc, --cppflags, --cflags, --cflags_sl, --ldflags, -- ldflags_sl, and --libs are new in PostgreSQL 8.1. In releases prior to PostgreSQL 7.1, before pg_config came to be, a method for finding the equivalent configuration information did not exist. Example To reproduce the build configuration of the current PostgreSQL installation, run the following command: eval ./configure `pg_config --configure` The output of pg_config --configure contains shell quotation marks so arguments with spaces are represented correctly. Therefore, using eval is required for proper results. ------------------------------------------------------------------------ pg_dump Name pg_dump -- extract a PostgreSQL database into a script file or other archive file Synopsis pg_dump [option...] [dbname] Description pg_dump is a utility for backing up a PostgreSQL database. It makes consistent backups even if the database is being used concurrently. pg_dump does not block other users accessing the database (readers or writers). Dumps can be output in script or archive file formats. Script dumps are plain-text files containing the SQL commands required to reconstruct the database to the state it was in at the time it was saved. To restore from such a script, feed it to psql. Script files can be used to reconstruct the database even on other machines and other architectures; with some modifications even on other SQL database products. The alternative archive file formats must be used with pg_restore to rebuild the database. They allow pg_restore to be selective about what is restored, or even to reorder the items prior to being restored. The archive file formats are designed to be portable across architectures. When used with one of the archive file formats and combined with pg_restore, pg_dump provides a flexible archival and transfer mechanism. pg_dump can be used to backup an entire database, then pg_restore can be used to examine the archive and/or select which parts of the database are to be restored. The most flexible output file format is the "custom" format (-Fc). It allows for selection and reordering of all archived items, and is compressed by default. The tar format (-Ft) is not compressed and it is not possible to reorder data when loading, but it is otherwise quite flexible; moreover, it can be manipulated with standard Unix tools such as tar. While running pg_dump, one should examine the output for any warnings (printed on standard error), especially in light of the limitations listed below. Options The following command-line options control the content and format of the output. p plain Output a plain-text SQL script file (the default). c custom Output a custom archive suitable for input into pg_restore. This is the most flexible format in that it allows reordering of loading data as well as object definitions. This format is also compressed by default. t tar Output a tar archive suitable for input into pg_restore. Using this archive format allows reordering and/or exclusion of database objects at the time the database is restored. It is also possible to limit which data is reloaded at restore time. -i --ignore-version Ignore version mismatch between pg_dump and the database server. pg_dump can dump from servers running previous releases of PostgreSQL, but very old versions are not supported anymore (currently, those prior to 7.0). Dumping from a server newer than pg_dump is likely not to work at all. Use this option if you need to override the version check (and if pg_dump then fails, don't say you weren't warned). -n schema --schema=schema Dump only schemas matching schema; this selects both the schema itself, and all its contained objects. When this option is not specified, all non- system schemas in the target database will be dumped. Multiple schemas can be selected by writing multiple -n switches. Also, the schema parameter is interpreted as a pattern according to the same rules used by psql's \d commands (see Patterns), so multiple schemas can also be selected by writing wildcard characters in the pattern. When using wildcards, be careful to quote the pattern if needed to prevent the shell from expanding the wildcards. Note: When -n is specified, pg_dump makes no attempt to dump any other database objects that the selected schema(s) might depend upon. Therefore, there is no guarantee that the results of a specific-schema dump can be successfully restored by themselves into a clean database. Note: Non-schema objects such as blobs are not dumped when -n is specified. You can add blobs back to the dump with the --blobs switch. -N schema --exclude-schema=schema Do not dump any schemas matching the schema pattern. The pattern is interpreted according to the same rules as for -n. -N can be given more than once to exclude schemas matching any of several patterns. When both -n and -N are given, the behavior is to dump just the schemas that match at least one -n switch but no -N switches. If -N appears without -n, then schemas matching -N are excluded from what is otherwise a normal dump. -o --oids Dump object identifiers (OIDs) as part of the data for every table. Use this option if your application references the OID columns in some way (e.g., in a foreign key constraint). Otherwise, this option should not be used. -O --no-owner Do not output commands to set ownership of objects to match the original database. By default, pg_dump issues ALTER OWNER or SET SESSION AUTHORIZATION statements to set ownership of created database objects. These statements will fail when the script is run unless it is started by a superuser (or the same user that owns all of the objects in the script). To make a script that can be restored by any user, but will give that user ownership of all the objects, specify -O. This option is only meaningful for the plain-text format. For the archive formats, you can specify the option when you call pg_restore. -R --no-reconnect This option is obsolete but still accepted for backwards compatibility. -s --schema-only Dump only the object definitions (schema), not data. -S username --superuser=username Specify the superuser user name to use when disabling triggers. This is only relevant if --disable-triggers is used. (Usually, it's better to leave this out, and instead start the resulting script as superuser.) -t table --table=table Dump only tables (or views or sequences) matching table. Multiple tables can be selected by writing multiple -t switches. Also, the table parameter is interpreted as a pattern according to the same rules used by psql's \d commands (see Patterns), so multiple tables can also be selected by writing wildcard characters in the pattern. When using wildcards, be careful to quote the pattern if needed to prevent the shell from expanding the wildcards. The -n and -N switches have no effect when -t is used, because tables selected by -t will be dumped regardless of those switches, and non-table objects will not be dumped. Note: When -t is specified, pg_dump makes no attempt to dump any other database objects that the selected table(s) might depend upon. Therefore, there is no guarantee that the results of a specific-table dump can be successfully restored by themselves into a clean database. Note: The behavior of the -t switch is not entirely upward compatible with pre-8.2 PostgreSQL versions. Formerly, writing - t tab would dump all tables named tab, but now it just dumps whichever one is visible in your default search path. To get the old behavior you can write -t '*.tab'. Also, you must write something like -t sch.tab to select a table in a particular schema, rather than the old locution of -n sch -t tab. -T table --exclude-table=table Do not dump any tables matching the table pattern. The pattern is interpreted according to the same rules as for -t. -T can be given more than once to exclude tables matching any of several patterns. When both -t and -T are given, the behavior is to dump just the tables that match at least one -t switch but no -T switches. If -T appears without -t, then tables matching -T are excluded from what is otherwise a normal dump. -v --verbose Specifies verbose mode. This will cause pg_dump to output detailed object comments and start/stop times to the dump file, and progress messages to standard error. -x --no-privileges --no-acl Prevent dumping of access privileges (grant/revoke commands). --disable-dollar-quoting This option disables the use of dollar quoting for function bodies, and forces them to be quoted using SQL standard string syntax. --disable-triggers This option is only relevant when creating a data-only dump. It instructs pg_dump to include commands to temporarily disable triggers on the target tables while the data is reloaded. Use this if you have referential integrity checks or other triggers on the tables that you do not want to invoke during data reload. Presently, the commands emitted for --disable-triggers must be done as superuser. So, you should also specify a superuser name with -S, or preferably be careful to start the resulting script as a superuser. This option is only meaningful for the plain-text format. For the archive formats, you can specify the option when you call pg_restore. --use-set-session-authorization Output SQL-standard SET SESSION AUTHORIZATION commands instead of ALTER OWNER commands to determine object ownership. This makes the dump more standards compatible, but depending on the history of the objects in the dump, might not restore properly. Also, a dump using SET SESSION AUTHORIZATION will certainly require superuser privileges to restore correctly, whereas ALTER OWNER requires lesser privileges. -Z 0..9 --compress=0..9 Specify the compression level to use. Zero means no compression. For the custom archive format, this specifies compression of individual table-data segments, and the default is to compress at a moderate level. For plain text output, setting a nonzero compression level causes the entire output file to be compressed, as though it had been fed through gzip; but the default is not to compress. The tar archive format currently does not support compression at all. The following command-line options control the database connection parameters. -h host --host=host Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. The default is taken from the PGHOST environment variable, if set, else a Unix domain socket connection is attempted. -p port --port=port Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections. Defaults to the PGPORT environment variable, if set, or a compiled-in default. -U username --username=username User name to connect as. -W --password Force pg_dump to prompt for a password before connecting to a database. This option is never essential, since pg_dump will automatically prompt for a password if the server demands password authentication. However, pg_dump will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Environment PGDATABASE PGHOST PGPORT PGUSER Default connection parameters. This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics pg_dump internally executes SELECT statements. If you have problems running pg_dump, make sure you are able to select information from the database using, for example, psql. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Notes If your database cluster has any local additions to the template1 database, be careful to restore the output of pg_dump into a truly empty database; otherwise you are likely to get errors due to duplicate definitions of the added objects. To make an empty database without any local additions, copy from template0 not template1, for example: CREATE DATABASE foo WITH TEMPLATE template0; pg_dump has a limitation; when a data-only dump is chosen and the option -- disable-triggers is used, pg_dump emits commands to disable triggers on user tables before inserting the data and commands to re-enable them after the data has been inserted. If the restore is stopped in the middle, the system catalogs might be left in the wrong state. Members of tar archives are limited to a size less than 8 GB. (This is an inherent limitation of the tar file format.) Therefore this format cannot be used if the textual representation of any one table exceeds that size. The total size of a tar archive and any of the other output formats is not limited, except possibly by the operating system. The dump file produced by pg_dump does not contain the statistics used by the optimizer to make query planning decisions. Therefore, it is wise to run ANALYZE after restoring from a dump file to ensure good performance. The dump file also does not contain any ALTER DATABASE ... SET commands; these settings are dumped by pg_dumpall, along with database users and other installation-wide settings. Because pg_dump is used to transfer data to newer versions of PostgreSQL, the output of pg_dump can be loaded into newer PostgreSQL databases. It also can read older PostgreSQL databases. However, it usually cannot read newer PostgreSQL databases or produce dump output that can be loaded into older database versions. To do this, manual editing of the dump file might be required. Examples To dump a database called mydb into a SQL-script file: $ pg_dump mydb > db.sql To reload such a script into a (freshly created) database named newdb: $ psql -d newdb -f db.sql To dump a database into a custom-format archive file: $ pg_dump -Fc mydb > db.dump To reload an archive file into a (freshly created) database named newdb: $ pg_restore -d newdb db.dump To dump a single table named mytab: $ pg_dump -t mytab mydb > db.sql To dump all tables whose names start with emp in the detroit schema, except for the table named employee_log: $ pg_dump -t 'detroit.emp*' -T detroit.employee_log mydb > db.sql To dump all schemas whose names start with east or west and end in gsm, excluding any schemas whose names contain the word test: $ pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql The same, using regular expression notation to consolidate the switches: $ pg_dump -n '(east|west)*gsm' -N '*test*' mydb > db.sql To dump all database objects except for tables whose names begin with ts_: $ pg_dump -T 'ts_*' mydb > db.sql To specify an upper-case or mixed-case name in -t and related switches, you need to double-quote the name; else it will be folded to lower case (see Patterns). But double quotes are special to the shell, so in turn they must be quoted. Thus, to dump a single table with a mixed-case name, you need something like $ pg_dump -t '"MixedCaseName"' mydb > mytab.sql See Also pg_dumpall, pg_restore, psql ------------------------------------------------------------------------ pg_dumpall Name pg_dumpall -- extract a PostgreSQL database cluster into a script file Synopsis pg_dumpall [option...] Description pg_dumpall is a utility for writing out ("dumping") all PostgreSQL databases of a cluster into one script file. The script file contains SQL commands that can be used as input to psql to restore the databases. It does this by calling pg_dump for each database in a cluster. pg_dumpall also dumps global objects that are common to all databases. (pg_dump does not save these objects.) This currently includes information about database users and groups, and access permissions that apply to databases as a whole. Since pg_dumpall reads tables from all databases you will most likely have to connect as a database superuser in order to produce a complete dump. Also you will need superuser privileges to execute the saved script in order to be allowed to add users and groups, and to create databases. The SQL script will be written to the standard output. Shell operators should be used to redirect it into a file. pg_dumpall needs to connect several times to the PostgreSQL server (once per database). If you use password authentication it will ask for a password each time. It is convenient to have a ~/.pgpass file in such cases. See Section_30.13 for more information. Options The following command-line options control the content and format of the output. -a --data-only Dump only the data, not the schema (data definitions). -c --clean Include SQL commands to clean (drop) databases before recreating them. DROP commands for roles and tablespaces are added as well. -d --inserts Dump data as INSERT commands (rather than COPY). This will make restoration very slow; it is mainly useful for making dumps that can be loaded into non-PostgreSQL databases. Note that the restore might fail altogether if you have rearranged column order. The -D option is safer, though even slower. -D --column-inserts --attribute-inserts Dump data as INSERT commands with explicit column names (INSERT INTO table (column, ...) VALUES ...). This will make restoration very slow; it is mainly useful for making dumps that can be loaded into non-PostgreSQL databases. -f filename --file=filename Send output to the specified file. If this is omitted, the standard output is used. -g --globals-only Dump only global objects (roles and tablespaces), no databases. -i --ignore-version Ignore version mismatch between pg_dumpall and the database server. pg_dumpall can handle databases from previous releases of PostgreSQL, but very old versions are not supported anymore (currently prior to 7.0). Use this option if you need to override the version check (and if pg_dumpall then fails, don't say you weren't warned). -o --oids Dump object identifiers (OIDs) as part of the data for every table. Use this option if your application references the OID columns in some way (e.g., in a foreign key constraint). Otherwise, this option should not be used. -O --no-owner Do not output commands to set ownership of objects to match the original database. By default, pg_dumpall issues ALTER OWNER or SET SESSION AUTHORIZATION statements to set ownership of created schema elements. These statements will fail when the script is run unless it is started by a superuser (or the same user that owns all of the objects in the script). To make a script that can be restored by any user, but will give that user ownership of all the objects, specify - O. -r --roles-only Dump only roles, no databases or tablespaces. -s --schema-only Dump only the object definitions (schema), not data. -S username --superuser=username Specify the superuser user name to use when disabling triggers. This is only relevant if --disable-triggers is used. (Usually, it's better to leave this out, and instead start the resulting script as superuser.) -t --tablespaces-only Dump only tablespaces, no databases or roles. -v --verbose Specifies verbose mode. This will cause pg_dumpall to output start/ stop times to the dump file, and progress messages to standard error. It will also enable verbose output in pg_dump. -x --no-privileges --no-acl Prevent dumping of access privileges (grant/revoke commands). --disable-dollar-quoting This option disables the use of dollar quoting for function bodies, and forces them to be quoted using SQL standard string syntax. --disable-triggers This option is only relevant when creating a data-only dump. It instructs pg_dumpall to include commands to temporarily disable triggers on the target tables while the data is reloaded. Use this if you have referential integrity checks or other triggers on the tables that you do not want to invoke during data reload. Presently, the commands emitted for --disable-triggers must be done as superuser. So, you should also specify a superuser name with -S, or preferably be careful to start the resulting script as a superuser. --use-set-session-authorization Output SQL-standard SET SESSION AUTHORIZATION commands instead of ALTER OWNER commands to determine object ownership. This makes the dump more standards compatible, but depending on the history of the objects in the dump, might not restore properly. The following command-line options control the database connection parameters. -h host --host=host Specifies the host name of the machine on which the database server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. The default is taken from the PGHOST environment variable, if set, else a Unix domain socket connection is attempted. -l dbname --database=dbname Specifies the name of the database to connect to to dump global objects and discover what other databases should be dumped. If not specified, the "postgres" database will be used, and if that does not exist, "template1" will be used. -p port --port=port Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections. Defaults to the PGPORT environment variable, if set, or a compiled-in default. -U username --username=username User name to connect as. -W --password Force pg_dumpall to prompt for a password before connecting to a database. This option is never essential, since pg_dumpall will automatically prompt for a password if the server demands password authentication. However, pg_dumpall will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Note that the password prompt will occur again for each database to be dumped. Usually, it's better to set up a ~/.pgpass file than to rely on manual password entry. Environment PGHOST PGPORT PGUSER Default connection parameters This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Notes Since pg_dumpall calls pg_dump internally, some diagnostic messages will refer to pg_dump. Once restored, it is wise to run ANALYZE on each database so the optimizer has useful statistics. You can also run vacuumdb -a -z to analyze all databases. pg_dumpall requires all needed tablespace directories to exist before the restore or database creation will fail for databases in non-default locations. Examples To dump all databases: $ pg_dumpall > db.out To reload this database use, for example: $ psql -f db.out postgres (It is not important to which database you connect here since the script file created by pg_dumpall will contain the appropriate commands to create and connect to the saved databases.) See Also Check pg_dump for details on possible error conditions. ------------------------------------------------------------------------ pg_restore Name pg_restore -- restore a PostgreSQL database from an archive file created by pg_dump Synopsis pg_restore [option...] [filename] Description pg_restore is a utility for restoring a PostgreSQL database from an archive created by pg_dump in one of the non-plain-text formats. It will issue the commands necessary to reconstruct the database to the state it was in at the time it was saved. The archive files also allow pg_restore to be selective about what is restored, or even to reorder the items prior to being restored. The archive files are designed to be portable across architectures. pg_restore can operate in two modes. If a database name is specified, the archive is restored directly into the database. Otherwise, a script containing the SQL commands necessary to rebuild the database is created and written to a file or standard output. The script output is equivalent to the plain text output format of pg_dump. Some of the options controlling the output are therefore analogous to pg_dump options. Obviously, pg_restore cannot restore information that is not present in the archive file. For instance, if the archive was made using the "dump data as INSERT commands" option, pg_restore will not be able to load the data using COPY statements. Options pg_restore accepts the following command line arguments. t tar The archive is a tar archive. Using this archive format allows reordering and/or exclusion of schema elements at the time the database is restored. It is also possible to limit which data is reloaded at restore time. c custom The archive is in the custom format of pg_dump. This is the most flexible format in that it allows reordering of data load as well as schema elements. This format is also compressed by default. -i --ignore-version Ignore database version checks. -I index --index=index Restore definition of named index only. -l --list List the contents of the archive. The output of this operation can be used with the -L option to restrict and reorder the items that are restored. -L list-file --use-list=list-file Restore elements in list-file only, and in the order they appear in the file. Lines can be moved and can also be commented out by placing a ; at the start of the line. (See below for examples.) -n namespace --schema=schema Restore only objects that are in the named schema. This can be combined with the -t option to restore just a specific table. -O --no-owner Do not output commands to set ownership of objects to match the original database. By default, pg_restore issues ALTER OWNER or SET SESSION AUTHORIZATION statements to set ownership of created schema elements. These statements will fail unless the initial connection to the database is made by a superuser (or the same user that owns all of the objects in the script). With -O, any user name can be used for the initial connection, and this user will own all the created objects. -P function-name(argtype [, ...]) --function=function-name(argtype [, ...]) Restore the named function only. Be careful to spell the function name and arguments exactly as they appear in the dump file's table of contents. -R --no-reconnect This option is obsolete but still accepted for backwards compatibility. -s --schema-only Restore only the schema (data definitions), not the data (table contents). Sequence current values will not be restored, either. (Do not confuse this with the --schema option, which uses the word "schema" in a different meaning.) -S username --superuser=username Specify the superuser user name to use when disabling triggers. This is only relevant if --disable-triggers is used. -t table --table=table Restore definition and/or data of named table only. -T trigger --trigger=trigger Restore named trigger only. -v --verbose Specifies verbose mode. -x --no-privileges --no-acl Prevent restoration of access privileges (grant/revoke commands). --disable-triggers This option is only relevant when performing a data-only restore. It instructs pg_restore to execute commands to temporarily disable triggers on the target tables while the data is reloaded. Use this if you have referential integrity checks or other triggers on the tables that you do not want to invoke during data reload. Presently, the commands emitted for --disable-triggers must be done as superuser. So, you should also specify a superuser name with -S, or preferably run pg_restore as a PostgreSQL superuser. --use-set-session-authorization Output SQL-standard SET SESSION AUTHORIZATION commands instead of ALTER OWNER commands to determine object ownership. This makes the dump more standards compatible, but depending on the history of the objects in the dump, might not restore properly. --no-data-for-failed-tables By default, table data is restored even if the creation command for the table failed (e.g., because it already exists). With this option, data for such a table is skipped. This behavior is useful if the target database already contains the desired table contents. For example, auxiliary tables for PostgreSQL extensions such as PostGIS might already be loaded in the target database; specifying this option prevents duplicate or obsolete data from being loaded into them. This option is effective only when restoring directly into a database, not when producing SQL script output. pg_restore also accepts the following command line arguments for connection parameters: -h host --host=host Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. The default is taken from the PGHOST environment variable, if set, else a Unix domain socket connection is attempted. -p port --port=port Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections. Defaults to the PGPORT environment variable, if set, or a compiled-in default. -U username --username=username User name to connect as. -W --password Force pg_restore to prompt for a password before connecting to a database. This option is never essential, since pg_restore will automatically prompt for a password if the server demands password authentication. However, pg_restore will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. -1 --single-transaction Execute the restore as a single transaction (that is, wrap the emitted commands in BEGIN/COMMIT). This ensures that either all the commands complete successfully, or no changes are applied. This option implies --exit-on-error. Environment PGHOST PGPORT PGUSER Default connection parameters This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics When a direct database connection is specified using the -d option, pg_restore internally executes SQL statements. If you have problems running pg_restore, make sure you are able to select information from the database using, for example, psql. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Notes If your installation has any local additions to the template1 database, be careful to load the output of pg_restore into a truly empty database; otherwise you are likely to get errors due to duplicate definitions of the added objects. To make an empty database without any local additions, copy from template0 not template1, for example: CREATE DATABASE foo WITH TEMPLATE template0; The limitations of pg_restore are detailed below. * When restoring data to a pre-existing table and the option --disable- triggers is used, pg_restore emits commands to disable triggers on user tables before inserting the data then emits commands to re-enable them after the data has been inserted. If the restore is stopped in the middle, the system catalogs might be left in the wrong state. * pg_restore will not restore large objects for a single table. If an archive contains large objects, then all large objects will be restored. See also the pg_dump documentation for details on limitations of pg_dump. Once restored, it is wise to run ANALYZE on each restored table so the optimizer has useful statistics. Examples Assume we have dumped a database called mydb into a custom-format dump file: $ pg_dump -Fc mydb > db.dump To drop the database and recreate it from the dump: $ dropdb mydb $ pg_restore -C -d postgres db.dump The database named in the -d switch can be any database existing in the cluster; pg_restore only uses it to issue the CREATE DATABASE command for mydb. With -C, data is always restored into the database name that appears in the dump file. To reload the dump into a new database called newdb: $ createdb -T template0 newdb $ pg_restore -d newdb db.dump Notice we don't use -C, and instead connect directly to the database to be restored into. Also note that we clone the new database from template0 not template1, to ensure it is initially empty. To reorder database items, it is first necessary to dump the table of contents of the archive: $ pg_restore -l db.dump > db.list The listing file consists of a header and one line for each item, e.g.: ; ; Archive created at Fri Jul 28 22:28:36 2000 ; dbname: mydb ; TOC Entries: 74 ; Compression: 0 ; Dump Version: 1.4-0 ; Format: CUSTOM ; ; ; Selected TOC Entries: ; 2; 145344 TABLE species postgres 3; 145344 ACL species 4; 145359 TABLE nt_header postgres 5; 145359 ACL nt_header 6; 145402 TABLE species_records postgres 7; 145402 ACL species_records 8; 145416 TABLE ss_old postgres 9; 145416 ACL ss_old 10; 145433 TABLE map_resolutions postgres 11; 145433 ACL map_resolutions 12; 145443 TABLE hs_old postgres 13; 145443 ACL hs_old Semicolons start a comment, and the numbers at the start of lines refer to the internal archive ID assigned to each item. Lines in the file can be commented out, deleted, and reordered. For example: 10; 145433 TABLE map_resolutions postgres ;2; 145344 TABLE species postgres ;4; 145359 TABLE nt_header postgres 6; 145402 TABLE species_records postgres ;8; 145416 TABLE ss_old postgres could be used as input to pg_restore and would only restore items 10 and 6, in that order: $ pg_restore -L db.list db.dump See Also pg_dump, pg_dumpall, psql ------------------------------------------------------------------------ psql Name psql -- PostgreSQL interactive terminal Synopsis psql [option...] [dbname [username]] Description psql is a terminal-based front-end to PostgreSQL. It enables you to type in queries interactively, issue them to PostgreSQL, and see the query results. Alternatively, input can be from a file. In addition, it provides a number of meta-commands and various shell-like features to facilitate writing scripts and automating a wide variety of tasks. Options -a --echo-all Print all input lines to standard output as they are read. This is more useful for script processing rather than interactive mode. This is equivalent to setting the variable ECHO to all. -A --no-align Switches to unaligned output mode. (The default output mode is otherwise aligned.) -c command --command command Specifies that psql is to execute one command string, command, and then exit. This is useful in shell scripts. command must be either a command string that is completely parsable by the server (i.e., it contains no psql specific features), or a single backslash command. Thus you cannot mix SQL and psql meta- commands with this option. To achieve that, you could pipe the string into psql, like this: echo '\x \\ SELECT * FROM foo;' | psql. (\\ is the separator meta-command.) If the command string contains multiple SQL commands, they are processed in a single transaction, unless there are explicit BEGIN/ COMMIT commands included in the string to divide it into multiple transactions. This is different from the behavior when the same string is fed to psql's standard input. -d dbname --dbname dbname Specifies the name of the database to connect to. This is equivalent to specifying dbname as the first non-option argument on the command line. If this parameter contains an = sign, it is treated as a conninfo string. See Section_30.1 for more information. -e --echo-queries Copy all SQL commands sent to the server to standard output as well. This is equivalent to setting the variable ECHO to queries. -E --echo-hidden Echo the actual queries generated by \d and other backslash commands. You can use this to study psql's internal operations. This is equivalent to setting the variable ECHO_HIDDEN from within psql. -f filename --file filename Use the file filename as the source of commands instead of reading commands interactively. After the file is processed, psql terminates. This is in many ways equivalent to the internal command \i. If filename is - (hyphen), then standard input is read. Using this option is subtly different from writing psql < filename. In general, both will do what you expect, but using -f enables some nice features such as error messages with line numbers. There is also a slight chance that using this option will reduce the start-up overhead. On the other hand, the variant using the shell's input redirection is (in theory) guaranteed to yield exactly the same output that you would have gotten had you entered everything by hand. -F separator --field-separator separator Use separator as the field separator for unaligned output. This is equivalent to \pset fieldsep or \f. -h hostname --host hostname Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix-domain socket. -H --html Turn on HTML tabular output. This is equivalent to \pset format html or the \H command. -l --list List all available databases, then exit. Other non-connection options are ignored. This is similar to the internal command \list. -L filename --log-file filename Write all query output into file filename, in addition to the normal output destination. -o filename --output filename Put all query output into file filename. This is equivalent to the command \o. -p port --port port Specifies the TCP port or the local Unix-domain socket file extension on which the server is listening for connections. Defaults to the value of the PGPORT environment variable or, if not set, to the port specified at compile time, usually 5432. -P assignment --pset assignment Allows you to specify printing options in the style of \pset on the command line. Note that here you have to separate name and value with an equal sign instead of a space. Thus to set the output format to LaTeX, you could write -P format=latex. -q --quiet Specifies that psql should do its work quietly. By default, it prints welcome messages and various informational output. If this option is used, none of this happens. This is useful with the -c option. Within psql you can also set the QUIET variable to achieve the same effect. -R separator --record-separator separator Use separator as the record separator for unaligned output. This is equivalent to the \pset recordsep command. -s --single-step Run in single-step mode. That means the user is prompted before each command is sent to the server, with the option to cancel execution as well. Use this to debug scripts. -S --single-line Runs in single-line mode where a newline terminates an SQL command, as a semicolon does. Note: This mode is provided for those who insist on it, but you are not necessarily encouraged to use it. In particular, if you mix SQL and meta-commands on a line the order of execution might not always be clear to the inexperienced user. -t --tuples-only Turn off printing of column names and result row count footers, etc. This is equivalent to the \t command. -T table_options --table-attr table_options Allows you to specify options to be placed within the HTML table tag. See \pset for details. -U username --username username Connect to the database as the user username instead of the default. (You must have permission to do so, of course.) -v assignment --set assignment --variable assignment Perform a variable assignment, like the \set internal command. Note that you must separate name and value, if any, by an equal sign on the command line. To unset a variable, leave off the equal sign. To just set a variable without a value, use the equal sign but leave off the value. These assignments are done during a very early stage of start-up, so variables reserved for internal purposes might get overwritten later. -V --version Print the psql version and exit. -W --password Force psql to prompt for a password before connecting to a database. This option is never essential, since psql will automatically prompt for a password if the server demands password authentication. However, psql will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Note that this option will remain set for the entire session, and so it affects uses of the meta-command \connect as well as the initial connection attempt. -x --expanded Turn on the expanded table formatting mode. This is equivalent to the \x command. -X, --no-psqlrc Do not read the start-up file (neither the system-wide psqlrc file nor the user's ~/.psqlrc file). -1 --single-transaction When psql executes a script with the -f option, adding this option wraps BEGIN/COMMIT around the script to execute it as a single transaction. This ensures that either all the commands complete successfully, or no changes are applied. If the script itself uses BEGIN, COMMIT, or ROLLBACK, this option will not have the desired effects. Also, if the script contains any command that cannot be executed inside a transaction block, specifying this option will cause that command (and hence the whole transaction) to fail. -? --help Show help about psql command line arguments, and exit. Exit Status psql returns 0 to the shell if it finished normally, 1 if a fatal error of its own (out of memory, file not found) occurs, 2 if the connection to the server went bad and the session was not interactive, and 3 if an error occurred in a script and the variable ON_ERROR_STOP was set. Usage Connecting To A Database psql is a regular PostgreSQL client application. In order to connect to a database you need to know the name of your target database, the host name and port number of the server and what user name you want to connect as. psql can be told about those parameters via command line options, namely - d, -h, -p, and -U respectively. If an argument is found that does not belong to any option it will be interpreted as the database name (or the user name, if the database name is already given). Not all these options are required; there are useful defaults. If you omit the host name, psql will connect via a Unix-domain socket to a server on the local host, or via TCP/IP to localhost on machines that don't have Unix-domain sockets. The default port number is determined at compile time. Since the database server uses the same default, you will not have to specify the port in most cases. The default user name is your Unix user name, as is the default database name. Note that you cannot just connect to any database under any user name. Your database administrator should have informed you about your access rights. When the defaults aren't quite right, you can save yourself some typing by setting the environment variables PGDATABASE, PGHOST, PGPORT and/or PGUSER to appropriate values. (For additional environment variables, see Section 30.12.) It is also convenient to have a ~/.pgpass file to avoid regularly having to type in passwords. See Section_30.13 for more information. An alternative way to specify connection parameters is in a conninfo string, which is used instead of a database name. This mechanism give you very wide control over the connection. For example: $ psql "service=myservice sslmode=require" This way you can also use LDAP for connection parameter lookup as described in Section_30.15. See Section_30.1 for more information on all the available connection options. If the connection could not be made for any reason (e.g., insufficient privileges, server is not running on the targeted host, etc.), psql will return an error and terminate. Entering SQL Commands In normal operation, psql provides a prompt with the name of the database to which psql is currently connected, followed by the string =>. For example: $ psql testdb Welcome to psql 8.3.4, the PostgreSQL interactive terminal. Type: \copyright for distribution terms \h for help with SQL commands \? for help with psql commands \g or terminate with semicolon to execute query \q to quit testdb=> At the prompt, the user can type in SQL commands. Ordinarily, input lines are sent to the server when a command-terminating semicolon is reached. An end of line does not terminate a command. Thus commands can be spread over several lines for clarity. If the command was sent and executed without error, the results of the command are displayed on the screen. Whenever a command is executed, psql also polls for asynchronous notification events generated by LISTEN and NOTIFY. Meta-Commands Anything you enter in psql that begins with an unquoted backslash is a psql meta-command that is processed by psql itself. These commands help make psql more useful for administration or scripting. Meta-commands are more commonly called slash or backslash commands. The format of a psql command is the backslash, followed immediately by a command verb, then any arguments. The arguments are separated from the command verb and each other by any number of whitespace characters. To include whitespace into an argument you can quote it with a single quote. To include a single quote into such an argument, use two single quotes. Anything contained in single quotes is furthermore subject to C- like substitutions for \n (new line), \t (tab), \digits (octal), and \xdigits (hexadecimal). If an unquoted argument begins with a colon (:), it is taken as a psql variable and the value of the variable is used as the argument instead. Arguments that are enclosed in backquotes (`) are taken as a command line that is passed to the shell. The output of the command (with any trailing newline removed) is taken as the argument value. The above escape sequences also apply in backquotes. Some commands take an SQL identifier (such as a table name) as argument. These arguments follow the syntax rules of SQL: Unquoted letters are forced to lowercase, while double quotes (") protect letters from case conversion and allow incorporation of whitespace into the identifier. Within double quotes, paired double quotes reduce to a single double quote in the resulting name. For example, FOO"BAR"BAZ is interpreted as fooBARbaz, and "A weird"" name" becomes A weird" name. Parsing for arguments stops when another unquoted backslash occurs. This is taken as the beginning of a new meta-command. The special sequence \\ (two backslashes) marks the end of arguments and continues parsing SQL commands, if any. That way SQL and psql commands can be freely mixed on a line. But in any case, the arguments of a meta-command cannot continue beyond the end of the line. The following meta-commands are defined: format Sets the output format to one of unaligned, aligned, html, latex, or troff-ms. Unique abbreviations are allowed. (That would mean one letter is enough.) "Unaligned" writes all columns of a row on a line, separated by the currently active field separator. This is intended to create output that might be intended to be read in by other programs (tab- separated, comma-separated). "Aligned" mode is the standard, human- readable, nicely formatted text output that is default. The "HTML" and "LaTeX" modes put out tables that are intended to be included in documents using the respective mark-up language. They are not complete documents! (This might not be so dramatic in HTML, but in LaTeX you must have a complete document wrapper.) border The second argument must be a number. In general, the higher the number the more borders and lines the tables will have, but this depends on the particular format. In HTML mode, this will translate directly into the border=... attribute, in the others only values 0 (no border), 1 (internal dividing lines), and 2 (table frame) make sense. expanded (or x) You can specify an optional second argument, if it is provided it may be either on or off which will enable or disable expanded mode. If the second argument is not provided then we will toggle between regular and expanded format. When expanded format is enabled, query results are displayed in two columns, with the column name on the left and the data on the right. This mode is useful if the data wouldn't fit on the screen in the normal "horizontal" mode. Expanded mode is supported by all four output formats. null The second argument is a string that should be printed whenever a column is null. The default is not to print anything, which can easily be mistaken for, say, an empty string. Thus, one might choose to write \pset null '(null)'. fieldsep Specifies the field separator to be used in unaligned output mode. That way one can create, for example, tab- or comma-separated output, which other programs might prefer. To set a tab as field separator, type \pset fieldsep '\t'. The default field separator is '|' (a vertical bar). footer You can specify an optional second argument, if it is provided it may be either on or off which will enable or disable display of the default footer (x rows). If the second argument is not provided then we will toggle between on and off. numericlocale You can specify an optional second argument, if it is provided it may be either on or off which will enable or disable display of a locale- aware character to seperate groups of digits to the left of the decimal marker. If the second argument is not provided then we will toggle between on and off. recordsep Specifies the record (line) separator to use in unaligned output mode. The default is a newline character. tuples_only (or t) You can specify an optional second argument, if it is provided it may be either on or off which will enable or disable the tuples only mode. If the second argument is not provided then we will toggle between tuples only and full display. Full display shows extra information such as column headers, titles, and various footers. In tuples only mode, only actual table data is shown. title [ text ] Sets the table title for any subsequently printed tables. This can be used to give your output descriptive tags. If no argument is given, the title is unset. tableattr (or T) [ text ] Allows you to specify any attributes to be placed inside the HTML table tag. This could for example be cellpadding or bgcolor. Note that you probably don't want to specify border here, as that is already taken care of by \pset border. pager Controls use of a pager for query and psql help output. If the environment variable PAGER is set, the output is piped to the specified program. Otherwise a platform-dependent default (such as more) is used. When the pager is off, the pager is not used. When the pager is on, the pager is used only when appropriate, i.e. the output is to a terminal and will not fit on the screen. (psql does not do a perfect job of estimating when to use the pager.) \pset pager turns the pager on and off. Pager can also be set to always, which causes the pager to be always used, or you can set the pager to on which will enable the usage of the pager when appropriate, or you can set the pager to off which will disable the pager. Illustrations on how these different formats look can be seen in the Examples section. Tip: There are various shortcut commands for \pset. See \a, \C, \H, \t, \T, and \x. Note: It is an error to call \pset without arguments. In the future this call might show the current status of all printing options. \q Quits the psql program. \qecho text [ ... ] This command is identical to \echo except that the output will be written to the query output channel, as set by \o. \r Resets (clears) the query buffer. \s [ filename ] Print or save the command line history to filename. If filename is omitted, the history is written to the standard output. This option is only available if psql is configured to use the GNU Readline library. \set [ name [ value [ ... ] ] ] Sets the internal variable name to value or, if more than one value is given, to the concatenation of all of them. If no second argument is given, the variable is just set with no value. To unset a variable, use the \unset command. Valid variable names can contain characters, digits, and underscores. See the section Variables below for details. Variable names are case-sensitive. Although you are welcome to set any variable to anything you want, psql treats several variables as special. They are documented in the section about variables. Note: This command is totally separate from the SQL command SET. \t Toggles the display of output column name headings and row count footer. This command is equivalent to \pset tuples_only and is provided for convenience. \T table_options Allows you to specify attributes to be placed within the table tag in HTML tabular output mode. This command is equivalent to \pset tableattr table_options. \timing Toggles a display of how long each SQL statement takes, in milliseconds. \w {filename | |command} Outputs the current query buffer to the file filename or pipes it to the Unix command command. \x Toggles expanded table formatting mode. As such it is equivalent to \pset expanded. \z [ pattern ] Produces a list of all available tables, views and sequences with their associated access privileges. If a pattern is specified, only tables,views and sequences whose names match the pattern are listed. The GRANT and REVOKE commands are used to set access privileges. This is an alias for \dp ("display privileges"). \! [ command ] Escapes to a separate Unix shell or executes the Unix command command. The arguments are not further interpreted, the shell will see them as is. \? Shows help information about the backslash commands. Patterns The various \d commands accept a pattern parameter to specify the object name(s) to be displayed. In the simplest case, a pattern is just the exact name of the object. The characters within a pattern are normally folded to lower case, just as in SQL names; for example, \dt FOO will display the table named foo. As in SQL names, placing double quotes around a pattern stops folding to lower case. Should you need to include an actual double quote character in a pattern, write it as a pair of double quotes within a double-quote sequence; again this is in accord with the rules for SQL quoted identifiers. For example, \dt "FOO""BAR" will display the table named FOO"BAR (not foo"bar). Unlike the normal rules for SQL names, you can put double quotes around just part of a pattern, for instance \dt FOO"FOO"BAR will display the table named fooFOObar. Within a pattern, * matches any sequence of characters (including no characters) and ? matches any single character. (This notation is comparable to Unix shell file name patterns.) For example, \dt int* displays all tables whose names begin with int. But within double quotes, * and ? lose these special meanings and are just matched literally. A pattern that contains a dot (.) is interpreted as a schema name pattern followed by an object name pattern. For example, \dt foo*.*bar* displays all tables whose table name includes bar that are in schemas whose schema name starts with foo. When no dot appears, then the pattern matches only objects that are visible in the current schema search path. Again, a dot within double quotes loses its special meaning and is matched literally. Advanced users can use regular-expression notations such as character classes, for example [0-9] to match any digit. All regular expression special characters work as specified in Section_9.7.3, except for . which is taken as a separator as mentioned above, * which is translated to the regular-expression notation .*, ? which is translated to ., and $ which is matched literally. You can emulate these pattern characters at need by writing ? for ., (R+|) for R*, or (R|) for R?. $ is not needed as a regular-expression character since the pattern must match the whole name, unlike the usual interpretation of regular expressions (in other words, $ is automatically appended to your pattern). Write * at the beginning and/or end if you don't wish the pattern to be anchored. Note that within double quotes, all regular expression special characters lose their special meanings and are matched literally. Also, the regular expression special characters are matched literally in operator name patterns (i.e., the argument of \do). Whenever the pattern parameter is omitted completely, the \d commands display all objects that are visible in the current schema search path - - this is equivalent to using the pattern *. To see all objects in the database, use the pattern *.*. Advanced features Variables psql provides variable substitution features similar to common Unix command shells. Variables are simply name/value pairs, where the value can be any string of any length. To set variables, use the psql meta-command \set: testdb=> \set foo bar sets the variable foo to the value bar. To retrieve the content of the variable, precede the name with a colon and use it as the argument of any slash command: testdb=> \echo :foo bar Note: The arguments of \set are subject to the same substitution rules as with other commands. Thus you can construct interesting references such as \set :foo 'something' and get "soft links" or "variable variables" of Perl or PHP fame, respectively. Unfortunately (or fortunately?), there is no way to do anything useful with these constructs. On the other hand, \set bar :foo is a perfectly valid way to copy a variable. If you call \set without a second argument, the variable is set, with an empty string as value. To unset (or delete) a variable, use the command \unset. psql's internal variable names can consist of letters, numbers, and underscores in any order and any number of them. A number of these variables are treated specially by psql. They indicate certain option settings that can be changed at run time by altering the value of the variable or represent some state of the application. Although you can use these variables for any other purpose, this is not recommended, as the program behavior might grow really strange really quickly. By convention, all specially treated variables consist of all upper-case letters (and possibly numbers and underscores). To ensure maximum compatibility in the future, avoid using such variable names for your own purposes. A list of all specially treated variables follows. AUTOCOMMIT When on (the default), each SQL command is automatically committed upon successful completion. To postpone commit in this mode, you must enter a BEGIN or START TRANSACTION SQL command. When off or unset, SQL commands are not committed until you explicitly issue COMMIT or END. The autocommit-off mode works by issuing an implicit BEGIN for you, just before any command that is not already in a transaction block and is not itself a BEGIN or other transaction-control command, nor a command that cannot be executed inside a transaction block (such as VACUUM). Note: In autocommit-off mode, you must explicitly abandon any failed transaction by entering ABORT or ROLLBACK. Also keep in mind that if you exit the session without committing, your work will be lost. Note: The autocommit-on mode is PostgreSQL's traditional behavior, but autocommit-off is closer to the SQL spec. If you prefer autocommit-off, you might wish to set it in the system-wide psqlrc file or your ~/.psqlrc file. DBNAME The name of the database you are currently connected to. This is set every time you connect to a database (including program start-up), but can be unset. ECHO If set to all, all lines entered from the keyboard or from a script are written to the standard output before they are parsed or executed. To select this behavior on program start-up, use the switch -a. If set to queries, psql merely prints all queries as they are sent to the server. The switch for this is -e. ECHO_HIDDEN When this variable is set and a backslash command queries the database, the query is first shown. This way you can study the PostgreSQL internals and provide similar functionality in your own programs. (To select this behavior on program start-up, use the switch -E.) If you set the variable to the value noexec, the queries are just shown but are not actually sent to the server and executed. ENCODING The current client character set encoding. FETCH_COUNT If this variable is set to an integer value > 0, the results of SELECT queries are fetched and displayed in groups of that many rows, rather than the default behavior of collecting the entire result set before display. Therefore only a limited amount of memory is used, regardless of the size of the result set. Settings of 100 to 1000 are commonly used when enabling this feature. Keep in mind that when using this feature, a query might fail after having already displayed some rows. Tip: Although you can use any output format with this feature, the default aligned format tends to look bad because each group of FETCH_COUNT rows will be formatted separately, leading to varying column widths across the row groups. The other output formats work better. HISTCONTROL If this variable is set to ignorespace, lines which begin with a space are not entered into the history list. If set to a value of ignoredups, lines matching the previous history line are not entered. A value of ignoreboth combines the two options. If unset, or if set to any other value than those above, all lines read in interactive mode are saved on the history list. Note: This feature was shamelessly plagiarized from Bash. HISTFILE The file name that will be used to store the history list. The default value is ~/.psql_history. For example, putting: \set HISTFILE ~/.psql_history- :DBNAME in ~/.psqlrc will cause psql to maintain a separate history for each database. Note: This feature was shamelessly plagiarized from Bash. HISTSIZE The number of commands to store in the command history. The default value is 500. Note: This feature was shamelessly plagiarized from Bash. HOST The database server host you are currently connected to. This is set every time you connect to a database (including program start-up), but can be unset. IGNOREEOF If unset, sending an EOF character (usually Control+D) to an interactive session of psql will terminate the application. If set to a numeric value, that many EOF characters are ignored before the application terminates. If the variable is set but has no numeric value, the default is 10. Note: This feature was shamelessly plagiarized from Bash. LASTOID The value of the last affected OID, as returned from an INSERT or lo_insert command. This variable is only guaranteed to be valid until after the result of the next SQL command has been displayed. ON_ERROR_ROLLBACK When on, if a statement in a transaction block generates an error, the error is ignored and the transaction continues. When interactive, such errors are only ignored in interactive sessions, and not when reading script files. When off (the default), a statement in a transaction block that generates an error aborts the entire transaction. The on_error_rollback-on mode works by issuing an implicit SAVEPOINT for you, just before each command that is in a transaction block, and rolls back to the savepoint on error. ON_ERROR_STOP By default, if non-interactive scripts encounter an error, such as a malformed SQL command or internal meta-command, processing continues. This has been the traditional behavior of psql but it is sometimes not desirable. If this variable is set, script processing will immediately terminate. If the script was called from another script it will terminate in the same fashion. If the outermost script was not called from an interactive psql session but rather using the - f option, psql will return error code 3, to distinguish this case from fatal error conditions (error code 1). PORT The database server port to which you are currently connected. This is set every time you connect to a database (including program start- up), but can be unset. PROMPT1 PROMPT2 PROMPT3 These specify what the prompts psql issues should look like. See Prompting below. QUIET This variable is equivalent to the command line option -q. It is probably not too useful in interactive mode. SINGLELINE This variable is equivalent to the command line option -S. SINGLESTEP This variable is equivalent to the command line option -s. USER The database user you are currently connected as. This is set every time you connect to a database (including program start-up), but can be unset. VERBOSITY This variable can be set to the values default, verbose, or terse to control the verbosity of error reports. SQL Interpolation An additional useful feature of psql variables is that you can substitute ("interpolate") them into regular SQL statements. The syntax for this is again to prepend the variable name with a colon (:): testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo; would then query the table my_table. The value of the variable is copied literally, so it can even contain unbalanced quotes or backslash commands. You must make sure that it makes sense where you put it. Variable interpolation will not be performed into quoted SQL entities. A popular application of this facility is to refer to the last inserted OID in subsequent statements to build a foreign key scenario. Another possible use of this mechanism is to copy the contents of a file into a table column. First load the file into a variable and then proceed as above: testdb=> \set content '''' `cat my_file.txt` '''' testdb=> INSERT INTO my_table VALUES (:content); One problem with this approach is that my_file.txt might contain single quotes. These need to be escaped so that they don't cause a syntax error when the second line is processed. This could be done with the program sed: testdb=> \set content '''' `sed -e "s/'/''/g" < my_file.txt` '''' If you are using non-standard-conforming strings then you'll also need to double backslashes. This is a bit tricky: testdb=> \set content '''' `sed -e "s/'/''/g" -e 's/\\/\\\\/g' < my_file.txt` '''' Note the use of different shell quoting conventions so that neither the single quote marks nor the backslashes are special to the shell. Backslashes are still special to sed, however, so we need to double them. (Perhaps at one point you thought it was great that all Unix commands use the same escape character.) Since colons can legally appear in SQL commands, the following rule applies: the character sequence ":name" is not changed unless "name" is the name of a variable that is currently set. In any case you can escape a colon with a backslash to protect it from substitution. (The colon syntax for variables is standard SQL for embedded query languages, such as ECPG. The colon syntax for array slices and type casts are PostgreSQL extensions, hence the conflict.) Prompting The prompts psql issues can be customized to your preference. The three variables PROMPT1, PROMPT2, and PROMPT3 contain strings and special escape sequences that describe the appearance of the prompt. Prompt 1 is the normal prompt that is issued when psql requests a new command. Prompt 2 is issued when more input is expected during command input because the command was not terminated with a semicolon or a quote was not closed. Prompt 3 is issued when you run an SQL COPY command and you are expected to type in the row values on the terminal. The value of the selected prompt variable is printed literally, except where a percent sign (%) is encountered. Depending on the next character, certain other text is substituted instead. Defined substitutions are: %M The full host name (with domain name) of the database server, or [local] if the connection is over a Unix domain socket, or [local:/ dir/name], if the Unix domain socket is not at the compiled in default location. %m The host name of the database server, truncated at the first dot, or [local] if the connection is over a Unix domain socket. %> The port number at which the database server is listening. %n The database session user name. (The expansion of this value might change during a database session as the result of the command SET SESSION AUTHORIZATION.) %/ The name of the current database. %~ Like %/, but the output is ~ (tilde) if the database is your default database. %# If the session user is a database superuser, then a #, otherwise a >. (The expansion of this value might change during a database session as the result of the command SET SESSION AUTHORIZATION.) %R In prompt 1 normally =, but ^ if in single-line mode, and ! if the session is disconnected from the database (which can happen if \connect fails). In prompt 2 the sequence is replaced by -, *, a single quote, a double quote, or a dollar sign, depending on whether psql expects more input because the command wasn't terminated yet, because you are inside a /* ... */ comment, or because you are inside a quoted or dollar-escaped string. In prompt 3 the sequence doesn't produce anything. %x Transaction status: an empty string when not in a transaction block, or * when in a transaction block, or ! when in a failed transaction block, or ? when the transaction state is indeterminate (for example, because there is no connection). %digits The character with the indicated octal code is substituted. %:name: The value of the psql variable name. See the section Variables for details. %`command` The output of command, similar to ordinary "back-tick" substitution. %[ ... %] Prompts can contain terminal control characters which, for example, change the color, background, or style of the prompt text, or change the title of the terminal window. In order for the line editing features of Readline to work properly, these non-printing control characters must be designated as invisible by surrounding them with % [ and %]. Multiple pairs of these can occur within the prompt. For example: testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# ' results in a boldfaced (1;) yellow-on-black (33;40) prompt on VT100- compatible, color-capable terminals. To insert a percent sign into your prompt, write %%. The default prompts are '%/%R%# ' for prompts 1 and 2, and '>> ' for prompt 3. Note: This feature was shamelessly plagiarized from tcsh. Command-Line Editing psql supports the Readline library for convenient line editing and retrieval. The command history is automatically saved when psql exits and is reloaded when psql starts up. Tab-completion is also supported, although the completion logic makes no claim to be an SQL parser. If for some reason you do not like the tab completion, you can turn it off by putting this in a file named .inputrc in your home directory: $if psql set disable-completion on $endif (This is not a psql but a Readline feature. Read its documentation for further details.) Environment PAGER If the query results do not fit on the screen, they are piped through this command. Typical values are more or less. The default is platform-dependent. The use of the pager can be disabled by using the \pset command. PGDATABASE Default connection database PGHOST PGPORT PGUSER Default connection parameters PSQL_EDITOR EDITOR VISUAL Editor used by the \e command. The variables are examined in the order listed; the first that is set is used. SHELL Command executed by the \! command. TMPDIR Directory for storing temporary files. The default is /tmp. This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Files * Before starting up, psql attempts to read and execute commands from the system-wide psqlrc file and the user's ~/.psqlrc file. (On Windows, the user's startup file is named %APPDATA%\postgresql\psqlrc.conf.) See PREFIX/share/psqlrc.sample for information on setting up the system-wide file. It could be used to set up the client or the server to taste (using the \set and SET commands). * Both the system-wide psqlrc file and the user's ~/.psqlrc file can be made version-specific by appending a dash and the PostgreSQL release number, for example ~/.psqlrc-8.3.4. A matching version-specific file will be read in preference to a non-version-specific file. * The command-line history is stored in the file ~/.psql_history, or %APPDATA%\postgresql\psql_history on Windows. Notes * In an earlier life psql allowed the first argument of a single-letter backslash command to start directly after the command, without intervening whitespace. For compatibility this is still supported to some extent, but we are not going to explain the details here as this use is discouraged. If you get strange messages, keep this in mind. For example: testdb=> \foo Field separator is "oo". which is perhaps not what one would expect. * psql only works smoothly with servers of the same version. That does not mean other combinations will fail outright, but subtle and not-so-subtle problems might come up. Backslash commands are particularly likely to fail if the server is of a different version. Notes for Windows users psql is built as a "console application". Since the Windows console windows use a different encoding than the rest of the system, you must take special care when using 8-bit characters within psql. If psql detects a problematic console code page, it will warn you at startup. To change the console code page, two things are necessary: * Set the code page by entering cmd.exe /c chcp 1252. (1252 is a code page that is appropriate for German; replace it with your value.) If you are using Cygwin, you can put this command in /etc/profile. * Set the console font to Lucida Console, because the raster font does not work with the ANSI code page. Examples The first example shows how to spread a command over several lines of input. Notice the changing prompt: testdb=> CREATE TABLE my_table ( testdb(> first integer not null default 0, testdb(> second text) testdb-> ; CREATE TABLE Now look at the table definition again: testdb=> \d my_table Table "my_table" Attribute | Type | Modifier -----------+---------+-------------------- first | integer | not null default 0 second | text | Now we change the prompt to something more interesting: testdb=> \set PROMPT1 '%n@%m %~%R%# ' peter@localhost testdb=> Let's assume you have filled the table with data and want to take a look at it: peter@localhost testdb=> SELECT * FROM my_table; first | second -------+-------- 1 | one 2 | two 3 | three 4 | four (4 rows) You can display tables in different ways by using the \pset command: peter@localhost testdb=> \pset border 2 Border style is 2. peter@localhost testdb=> SELECT * FROM my_table; +-------+--------+ | first | second | +-------+--------+ | 1 | one | | 2 | two | | 3 | three | | 4 | four | +-------+--------+ (4 rows) peter@localhost testdb=> \pset border 0 Border style is 0. peter@localhost testdb=> SELECT * FROM my_table; first second ----- ------ 1 one 2 two 3 three 4 four (4 rows) peter@localhost testdb=> \pset border 1 Border style is 1. peter@localhost testdb=> \pset format unaligned Output format is unaligned. peter@localhost testdb=> \pset fieldsep "," Field separator is ",". peter@localhost testdb=> \pset tuples_only Showing only tuples. peter@localhost testdb=> SELECT second, first FROM my_table; one,1 two,2 three,3 four,4 Alternatively, use the short commands: peter@localhost testdb=> \a \t \x Output format is aligned. Tuples only is off. Expanded display is on. peter@localhost testdb=> SELECT * FROM my_table; -[ RECORD 1 ]- first | 1 second | one -[ RECORD 2 ]- first | 2 second | two -[ RECORD 3 ]- first | 3 second | three -[ RECORD 4 ]- first | 4 second | four ------------------------------------------------------------------------ reindexdb Name reindexdb -- reindex a PostgreSQL database Synopsis reindexdb [connection-option...] [--table | -t table ] [--index | -i index ] [dbname] reindexdb [connection-option...] [--all | -a] reindexdb [connection-option...] [--system | -s] [dbname] Description reindexdb is a utility for rebuilding indexes in a PostgreSQL database. reindexdb is a wrapper around the SQL command REINDEX. There is no effective difference between reindexing databases via this utility and via other methods for accessing the server. Options reindexdb accepts the following command-line arguments: -a --all Reindex all databases. [-d] dbname [--dbname] dbname Specifies the name of the database to be reindexed. If this is not specified and -a (or --all) is not used, the database name is read from the environment variable PGDATABASE. If that is not set, the user name specified for the connection is used. -e --echo Echo the commands that reindexdb generates and sends to the server. -i index --index index Recreate index only. -q --quiet Do not display progress messages. -s --system Reindex database's system catalogs. -t table --table table Reindex table only. reindexdb also accepts the following command-line arguments for connection parameters: -h host --host host Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. -p port --port port Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections. -U username --username username User name to connect as. -W --password Force reindexdb to prompt for a password before connecting to a database. This option is never essential, since reindexdb will automatically prompt for a password if the server demands password authentication. However, reindexdb will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Environment PGDATABASE PGHOST PGPORT PGUSER Default connection parameters This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics In case of difficulty, see REINDEX and psql for discussions of potential problems and error messages. The database server must be running at the targeted host. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Notes reindexdb might need to connect several times to the PostgreSQL server, asking for a password each time. It is convenient to have a ~/.pgpass file in such cases. See Section_30.13 for more information. Examples To reindex the database test: $ reindexdb test To reindex the table foo and the index bar in a database named abcd: $ reindexdb --table foo --index bar abcd See Also REINDEX ------------------------------------------------------------------------ vacuumdb Name vacuumdb -- garbage-collect and analyze a PostgreSQL database Synopsis vacuumdb [connection-option...] [--full | -f] [--verbose | -v] [--analyze | -z] [--table | -t table [( column [,...] )] ] [dbname] vacuumdb [connection-options...] [--all | -a] [--full | -f] [--verbose | - v] [--analyze | -z] Description vacuumdb is a utility for cleaning a PostgreSQL database. vacuumdb will also generate internal statistics used by the PostgreSQL query optimizer. vacuumdb is a wrapper around the SQL command VACUUM. There is no effective difference between vacuuming databases via this utility and via other methods for accessing the server. Options vacuumdb accepts the following command-line arguments: -a --all Vacuum all databases. [-d] dbname [--dbname] dbname Specifies the name of the database to be cleaned or analyzed. If this is not specified and -a (or --all) is not used, the database name is read from the environment variable PGDATABASE. If that is not set, the user name specified for the connection is used. -e --echo Echo the commands that vacuumdb generates and sends to the server. -f --full Perform "full" vacuuming. -q --quiet Do not display progress messages. -t table [ (column [,...]) ] --table table [ (column [,...]) ] Clean or analyze table only. Column names can be specified only in conjunction with the --analyze option. Tip: If you specify columns, you probably have to escape the parentheses from the shell. (See examples below.) -v --verbose Print detailed information during processing. -z --analyze Calculate statistics for use by the optimizer. vacuumdb also accepts the following command-line arguments for connection parameters: -h host --host host Specifies the host name of the machine on which the server is running. If the value begins with a slash, it is used as the directory for the Unix domain socket. -p port --port port Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections. -U username --username username User name to connect as. -W --password Force vacuumdb to prompt for a password before connecting to a database. This option is never essential, since vacuumdb will automatically prompt for a password if the server demands password authentication. However, vacuumdb will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt. Environment PGDATABASE PGHOST PGPORT PGUSER Default connection parameters This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Diagnostics In case of difficulty, see VACUUM and psql for discussions of potential problems and error messages. The database server must be running at the targeted host. Also, any default connection settings and environment variables used by the libpq front-end library will apply. Notes vacuumdb might need to connect several times to the PostgreSQL server, asking for a password each time. It is convenient to have a ~/.pgpass file in such cases. See Section_30.13 for more information. Examples To clean the database test: $ vacuumdb test To clean and analyze for the optimizer a database named bigdb: $ vacuumdb --analyze bigdb To clean a single table foo in a database named xyzzy, and analyze a single column bar of the table for the optimizer: $ vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy See Also VACUUM ------------------------------------------------------------------------ ------------------------------------------------------------------------ III. PostgreSQL Server Applications This part contains reference information for PostgreSQL server applications and support utilities. These commands can only be run usefully on the host where the database server resides. Other utility programs are listed in Reference_II,_PostgreSQL_Client_Applications. Table of Contents initdb -- create a new PostgreSQL database cluster ipcclean -- remove shared memory and semaphores from a failed PostgreSQL server pg_controldata -- display control information of a PostgreSQL database cluster pg_ctl -- start, stop, or restart a PostgreSQL server pg_resetxlog -- reset the write-ahead log and other control information of a PostgreSQL database cluster postgres -- PostgreSQL database server postmaster -- PostgreSQL database server ------------------------------------------------------------------------ initdb Name initdb -- create a new PostgreSQL database cluster Synopsis initdb [option...] --pgdata | -D directory Description initdb creates a new PostgreSQL database cluster. A database cluster is a collection of databases that are managed by a single server instance. Creating a database cluster consists of creating the directories in which the database data will live, generating the shared catalog tables (tables that belong to the whole cluster rather than to any particular database), and creating the template1 and postgres databases. When you later create a new database, everything in the template1 database is copied. (Therefore, anything installed in template1 is automatically copied into each database created later.) The postgres database is a default database meant for use by users, utilities and third party applications. Although initdb will attempt to create the specified data directory, it might not have permission if the parent directory of the desired data directory is root-owned. To initialize in such a setup, create an empty data directory as root, then use chown to assign ownership of that directory to the database user account, then su to become the database user to run initdb. initdb must be run as the user that will own the server process, because the server needs to have access to the files and directories that initdb creates. Since the server cannot be run as root, you must not run initdb as root either. (It will in fact refuse to do so.) initdb initializes the database cluster's default locale and character set encoding. The collation order (LC_COLLATE) and character set classes (LC_CTYPE, e.g. upper, lower, digit) are fixed for all databases and cannot be changed. Collation orders other than C or POSIX also have a performance penalty. For these reasons it is important to choose the right locale when running initdb. The remaining locale categories can be changed later when the server is started. All server locale values (lc_*) can be displayed via SHOW ALL. More details can be found in Section_22.1. The character set encoding can be set separately for a database when it is created. initdb determines the encoding for the template1 database, which will serve as the default for all other databases. To alter the default encoding use the --encoding option. More details can be found in Section 22.2. Options -A authmethod --auth=authmethod This option specifies the authentication method for local users used in pg_hba.conf. Do not use trust unless you trust all local users on your system. Trust is the default for ease of installation. -D directory --pgdata=directory This option specifies the directory where the database cluster should be stored. This is the only information required by initdb, but you can avoid writing it by setting the PGDATA environment variable, which can be convenient since the database server (postgres) can find the database directory later by the same variable. -E encoding --encoding=encoding Selects the encoding of the template database. This will also be the default encoding of any database you create later, unless you override it there. The default is derived from the locale, or SQL_ASCII if that does not work. The character sets supported by the PostgreSQL server are described in Section_22.2.1. --locale=locale Sets the default locale for the database cluster. If this option is not specified, the locale is inherited from the environment that initdb runs in. Locale support is described in Section_22.1. --lc-collate=locale --lc-ctype=locale --lc-messages=locale --lc-monetary=locale --lc-numeric=locale --lc-time=locale Like --locale, but only sets the locale in the specified category. -X directory --xlogdir=directory This option specifies the directory where the transaction log should be stored. -U username --username=username Selects the user name of the database superuser. This defaults to the name of the effective user running initdb. It is really not important what the superuser's name is, but one might choose to keep the customary name postgres, even if the operating system user's name is different. -W --pwprompt Makes initdb prompt for a password to give the database superuser. If you don't plan on using password authentication, this is not important. Otherwise you won't be able to use password authentication until you have a password set up. --pwfile=filename Makes initdb read the database superuser's password from a file. The first line of the file is taken as the password. Other, less commonly used, parameters are also available: -d --debug Print debugging output from the bootstrap backend and a few other messages of lesser interest for the general public. The bootstrap backend is the program initdb uses to create the catalog tables. This option generates a tremendous amount of extremely boring output. -L directory Specifies where initdb should find its input files to initialize the database cluster. This is normally not necessary. You will be told if you need to specify their location explicitly. -n --noclean By default, when initdb determines that an error prevented it from completely creating the database cluster, it removes any files it might have created before discovering that it cannot finish the job. This option inhibits tidying-up and is thus useful for debugging. Environment PGDATA Specifies the directory where the database cluster is to be stored; can be overridden using the -D option. This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). See Also postgres ------------------------------------------------------------------------ ipcclean Name ipcclean -- remove shared memory and semaphores from a failed PostgreSQL server Synopsis ipcclean Description ipcclean removes all shared memory segments and semaphore sets owned by the current user. It is intended to be used for cleaning up after a crashed PostgreSQL server (postgres). Note that immediately restarting the server will also clean up shared memory and semaphores, so this command is of little real utility. Only the database administrator should execute this program as it can cause bizarre behavior (i.e., crashes) if run during multiuser execution. If this command is executed while a server is running, the shared memory and semaphores allocated by that server will be deleted, which would have rather severe consequences for that server. Notes This script is a hack, but in the many years since it was written, no one has come up with an equally effective and portable solution. Since postgres can now clean up by itself, it is unlikely that ipcclean will be improved upon in the future. The script makes assumptions about the output format of the ipcs utility which might not be true across different operating systems. Therefore, it might not work on your particular OS. It's wise to look at the script before trying it. ------------------------------------------------------------------------ pg_controldata Name pg_controldata -- display control information of a PostgreSQL database cluster Synopsis pg_controldata [datadir] Description pg_controldata prints information initialized during initdb, such as the catalog version and server locale. It also shows information about write- ahead logging and checkpoint processing. This information is cluster-wide, and not specific to any one database. This utility can only be run by the user who initialized the cluster because it requires read access to the data directory. You can specify the data directory on the command line, or use the environment variable PGDATA. Environment PGDATA Default data directory location ------------------------------------------------------------------------ pg_ctl Name pg_ctl -- start, stop, or restart a PostgreSQL server Synopsis pg_ctl start [-w] [-t seconds] [-s] [-D datadir] [-l filename] [-o options] [-p path] [-c] pg_ctl stop [-W] [-t seconds] [-s] [-D datadir] [-m s[mart] | f[ast] | i [mmediate] ] pg_ctl restart [-w] [-t seconds] [-s] [-D datadir] [-c] [-m s[mart] | f [ast] | i[mmediate] ] [-o options] pg_ctl reload [-s] [-D datadir] pg_ctl status [-D datadir] pg_ctl kill [signal_name] [process_id] pg_ctl register [-N servicename] [-U username] [-P password] [-D datadir] [-w] [-t seconds] [-o options] pg_ctl unregister [-N servicename] Description pg_ctl is a utility for starting, stopping, or restarting the PostgreSQL backend server (postgres), or displaying the status of a running server. Although the server can be started manually, pg_ctl encapsulates tasks such as redirecting log output and properly detaching from the terminal and process group. It also provides convenient options for controlled shutdown. In start mode, a new server is launched. The server is started in the background, and standard input is attached to /dev/null. The standard output and standard error are either appended to a log file (if the - l option is used), or redirected to pg_ctl's standard output (not standard error). If no log file is chosen, the standard output of pg_ctl should be redirected to a file or piped to another process such as a log rotating program like rotatelogs; otherwise postgres will write its output to the controlling terminal (from the background) and will not leave the shell's process group. In stop mode, the server that is running in the specified data directory is shut down. Three different shutdown methods can be selected with the - m option: "Smart" mode waits for all the clients to disconnect. This is the default. "Fast" mode does not wait for clients to disconnect. All active transactions are rolled back and clients are forcibly disconnected, then the server is shut down. "Immediate" mode will abort all server processes without a clean shutdown. This will lead to a recovery run on restart. restart mode effectively executes a stop followed by a start. This allows changing the postgres command-line options. reload mode simply sends the postgres process a SIGHUP signal, causing it to reread its configuration files (postgresql.conf, pg_hba.conf, etc.). This allows changing of configuration-file options that do not require a complete restart to take effect. status mode checks whether a server is running in the specified data directory. If it is, the PID and the command line options that were used to invoke it are displayed. kill mode allows you to send a signal to a specified process. This is particularly valuable for Microsoft Windows which does not have a kill command. Use --help to see a list of supported signal names. register mode allows you to register a system service on Microsoft Windows. unregister mode allows you to unregister a system service on Microsoft Windows, previously registered with the register command. Options -c Attempt to allow server crashes to produce core files, on platforms where this available, by lifting any soft resource limit placed on them. This is useful in debugging or diagnosing problems by allowing a stack trace to be obtained from a failed server process. -D datadir Specifies the file system location of the database files. If this is omitted, the environment variable PGDATA is used. -l filename Append the server log output to filename. If the file does not exist, it is created. The umask is set to 077, so access to the log file from other users is disallowed by default. -m mode Specifies the shutdown mode. mode can be smart, fast, or immediate, or the first letter of one of these three. -o options Specifies options to be passed directly to the postgres command. The options are usually surrounded by single or double quotes to ensure that they are passed through as a group. -p path Specifies the location of the postgres executable. By default the postgres executable is taken from the same directory as pg_ctl, or failing that, the hard-wired installation directory. It is not necessary to use this option unless you are doing something unusual and get errors that the postgres executable was not found. -s Only print errors, no informational messages. -t The number of seconds to wait when waiting for start or shutdown to complete. -w Wait for the start or shutdown to complete. The default wait time is 60 seconds. This is the default option for shutdowns. A successful shutdown is indicated by removal of the PID file. For starting up, a successful psql -l indicates success. pg_ctl will attempt to use the proper port for psql. If the environment variable PGPORT exists, that is used. Otherwise, it will see if a port has been set in the postgresql.conf file. If neither of those is used, it will use the default port that PostgreSQL was compiled with (5432 by default). When waiting, pg_ctl will return an accurate exit code based on the success of the startup or shutdown. -W Do not wait for start or shutdown to complete. This is the default for starts and restarts. Options for Windows -N servicename Name of the system service to register. The name will be used as both the service name and the display name. -P password Password for the user to start the service. -U username User name for the user to start the service. For domain users, use the format DOMAIN\username. Environment PGDATA Default data directory location. PGPORT Default port for psql (used by the -w option). For additional server variables, see postgres. This utility, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section_30.12). Files postmaster.pid The existence of this file in the data directory is used to help pg_ctl determine if the server is currently running or not. postmaster.opts.default If this file exists in the data directory, pg_ctl (in start mode) will pass the contents of the file as options to the postgres command, unless overridden by the -o option. postmaster.opts If this file exists in the data directory, pg_ctl (in restart mode) will pass the contents of the file as options to postgres, unless overridden by the -o option. The contents of this file are also displayed in status mode. postgresql.conf This file, located in the data directory, is parsed to find the proper port to use with psql when the -w is given in start mode. Notes Waiting for complete start is not a well-defined operation and might fail if access control is set up so that a local client cannot connect without manual interaction (e.g., password authentication). For additional connection variables, see Section_30.12, and for passwords, also see Section_30.13. Examples Starting the Server To start up a server: $ pg_ctl start An example of starting the server, blocking until the server has come up is: $ pg_ctl -w start For a server using port 5433, and running without fsync, use: $ pg_ctl -o "-F -p 5433" start Stopping the Server $ pg_ctl stop stops the server. Using the -m switch allows one to control how the backend shuts down. Restarting the Server Restarting the server is almost equivalent to stopping the server and starting it again except that pg_ctl saves and reuses the command line options that were passed to the previously running instance. To restart the server in the simplest form, use: $ pg_ctl restart To restart server, waiting for it to shut down and to come up: $ pg_ctl -w restart To restart using port 5433 and disabling fsync after restarting: $ pg_ctl -o "-F -p 5433" restart Showing the Server Status Here is a sample status output from pg_ctl: $ pg_ctl status pg_ctl: server is running (pid: 13718) Command line was: /usr/local/pgsql/bin/postgres '-D' '/usr/local/pgsql/data' '-p' '5433' '- B' '128' This is the command line that would be invoked in restart mode. See Also postgres ------------------------------------------------------------------------ pg_resetxlog Name pg_resetxlog -- reset the write-ahead log and other control information of a PostgreSQL database cluster Synopsis pg_resetxlog [-f] [-n] [-ooid ] [-x xid ] [-e xid_epoch ] [-m mxid ] [- O mxoff ] [-l timelineid,fileid,seg ] datadir Description pg_resetxlog clears the write-ahead log (WAL) and optionally resets some other control information stored in the pg_control file. This function is sometimes needed if these files have become corrupted. It should be used only as a last resort, when the server will not start due to such corruption. After running this command, it should be possible to start the server, but bear in mind that the database might contain inconsistent data due to partially-committed transactions. You should immediately dump your data, run initdb, and reload. After reload, check for inconsistencies and repair as needed. This utility can only be run by the user who installed the server, because it requires read/write access to the data directory. For safety reasons, you must specify the data directory on the command line. pg_resetxlog does not use the environment variable PGDATA. If pg_resetxlog complains that it cannot determine valid data for pg_control, you can force it to proceed anyway by specifying the -f (force) switch. In this case plausible values will be substituted for the missing data. Most of the fields can be expected to match, but manual assistance might be needed for the next OID, next transaction ID and epoch, next multitransaction ID and offset, WAL starting address, and database locale fields. The first six of these can be set using the switches discussed below. pg_resetxlog's own environment is the source for its guess at the locale fields; take care that LANG and so forth match the environment that initdb was run in. If you are not able to determine correct values for all these fields, -f can still be used, but the recovered database must be treated with even more suspicion than usual: an immediate dump and reload is imperative. Do not execute any data-modifying operations in the database before you dump, as any such action is likely to make the corruption worse. The -o, -x, -e, -m, -O, and -l switches allow the next OID, next transaction ID, next transaction ID's epoch, next multitransaction ID, next multitransaction offset, and WAL starting address values to be set manually. These are only needed when pg_resetxlog is unable to determine appropriate values by reading pg_control. Safe values can be determined as follows: * A safe value for the next transaction ID (-x) can be determined by looking for the numerically largest file name in the directory pg_clog under the data directory, adding one, and then multiplying by 1048576. Note that the file names are in hexadecimal. It is usually easiest to specify the switch value in hexadecimal too. For example, if 0011 is the largest entry in pg_clog, -x 0x1200000 will work (five trailing zeroes provide the proper multiplier). * A safe value for the next multitransaction ID (-m) can be determined by looking for the numerically largest file name in the directory pg_multixact/offsets under the data directory, adding one, and then multiplying by 65536. As above, the file names are in hexadecimal, so the easiest way to do this is to specify the switch value in hexadecimal and add four zeroes. * A safe value for the next multitransaction offset (-O) can be determined by looking for the numerically largest file name in the directory pg_multixact/members under the data directory, adding one, and then multiplying by 65536. As above, the file names are in hexadecimal, so the easiest way to do this is to specify the switch value in hexadecimal and add four zeroes. * The WAL starting address (-l) should be larger than any WAL segment file name currently existing in the directory pg_xlog under the data directory. These names are also in hexadecimal and have three parts. The first part is the "timeline ID" and should usually be kept the same. Do not choose a value larger than 255 (0xFF) for the third part; instead increment the second part and reset the third part to 0. For example, if 00000001000000320000004A is the largest entry in pg_xlog, - l 0x1,0x32,0x4B will work; but if the largest entry is 000000010000003A000000FF, choose -l 0x1,0x3B,0x0 or more. Note: pg_resetxlog itself looks at the files in pg_xlog and chooses a default -l setting beyond the last existing file name. Therefore, manual adjustment of -l should only be needed if you are aware of WAL segment files that are not currently present in pg_xlog, such as entries in an offline archive; or if the contents of pg_xlog have been lost entirely. * There is no comparably easy way to determine a next OID that's beyond the largest one in the database, but fortunately it is not critical to get the next-OID setting right. * The transaction ID epoch is not actually stored anywhere in the database except in the field that is set by pg_resetxlog, so any value will work so far as the database itself is concerned. You might need to adjust this value to ensure that replication systems such as Slony-I work correctly - - if so, an appropriate value should be obtainable from the state of the downstream replicated database. The -n (no operation) switch instructs pg_resetxlog to print the values reconstructed from pg_control and then exit without modifying anything. This is mainly a debugging tool, but can be useful as a sanity check before allowing pg_resetxlog to proceed for real. Notes This command must not be used when the server is running. pg_resetxlog will refuse to start up if it finds a server lock file in the data directory. If the server crashed then a lock file might have been left behind; in that case you can remove the lock file to allow pg_resetxlog to run. But before you do so, make doubly certain that there is no server process still alive. ------------------------------------------------------------------------ postgres Name postgres -- PostgreSQL database server Synopsis postgres [option...] Description postgres is the PostgreSQL database server. In order for a client application to access a database it connects (over a network or locally) to a running postgres instance. The postgres instance then starts a separate server process to handle the connection. One postgres instance always manages the data of exactly one database cluster. A database cluster is a collection of databases that is stored at a common file system location (the "data area"). More than one postgres instance can run on a system at one time, so long as they use different data areas and different communication ports (see below). When postgres starts it needs to know the location of the data area. The location must be specified by the -D option or the PGDATA environment variable; there is no default. Typically, -D or PGDATA points directly to the data area directory created by initdb. Other possible file layouts are discussed in Section 18.2. By default postgres starts in the foreground and prints log messages to the standard error stream. In practical applications postgres should be started as a background process, perhaps at boot time. The postgres command can also be called in single-user mode. The primary use for this mode is during bootstrapping by initdb. Sometimes it is used for debugging or disaster recovery (but note that running a single-user server is not truly suitable for debugging the server, since no realistic interprocess communication and locking will happen). When invoked in single-user mode from the shell, the user can enter queries and the results will be printed to the screen, but in a form that is more useful for developers than end users. In the single-user mode, the session user will be set to the user with ID 1, and implicit superuser powers are granted to this user. This user does not actually have to exist, so the single-user mode can be used to manually recover from certain kinds of accidental damage to the system catalogs. Options postgres accepts the following command-line arguments. For a detailed discussion of the options consult Chapter_18. You can save typing most of these options by setting up a configuration file. Some (safe) options can also be set from the connecting client in an application-dependent way to apply only for that session. For example, if the environment variable PGOPTIONS is set, then libpq-based clients will pass that string to the server, which will interpret it as postgres command-line options. General Purpose -A 0|1 Enables run-time assertion checks, which is a debugging aid to detect programming mistakes. This option is only available if assertions were enabled when PostgreSQL was compiled. If so, the default is on. -B nbuffers Sets the number of shared buffers for use by the server processes. The default value of this parameter is chosen automatically by initdb. Specifying this option is equivalent to setting the shared_buffers configuration parameter. -c name=value Sets a named run-time parameter. The configuration parameters supported by PostgreSQL are described in Chapter_18. Most of the other command line options are in fact short forms of such a parameter assignment. -c can appear multiple times to set multiple parameters. -d debug-level Sets the debug level. The higher this value is set, the more debugging output is written to the server log. Values are from 1 to 5. It is also possible to pass -d 0 for a specific session, which will prevent the server log level of the parent postgres process from being propagated to this session. -D datadir Specifies the file system location of the data directory or configuration file(s). See Section_18.2 for details. -e Sets the default date style to "European", that is DMY ordering of input date fields. This also causes the day to be printed before the month in certain date output formats. See Section_8.5 for more information. -F Disables fsync calls for improved performance, at the risk of data corruption in the event of a system crash. Specifying this option is equivalent to disabling the fsync configuration parameter. Read the detailed documentation before using this! -h hostname Specifies the IP host name or address on which postgres is to listen for TCP/IP connections from client applications. The value can also be a comma-separated list of addresses, or * to specify listening on all available interfaces. An empty value specifies not listening on any IP addresses, in which case only Unix-domain sockets can be used to connect to the server. Defaults to listening only on localhost. Specifying this option is equivalent to setting the listen_addresses configuration parameter. -i Allows remote clients to connect via TCP/IP (Internet domain) connections. Without this option, only local connections are accepted. This option is equivalent to setting listen_addresses to * in postgresql.conf or via -h. This option is deprecated since it does not allow access to the full functionality of listen_addresses. It's usually better to set listen_addresses directly. -k directory Specifies the directory of the Unix-domain socket on which postgres is to listen for connections from client applications. The default is normally /tmp, but can be changed at build time. -l Enables secure connections using SSL. PostgreSQL must have been compiled with support for SSL for this option to be available. For more information on using SSL, refer to Section_17.8. -N max-connections Sets the maximum number of client connections that this server will accept. The default value of this parameter is chosen automatically by initdb. Specifying this option is equivalent to setting the max_connections configuration parameter. -o extra-options The command-line-style options specified in extra-options are passed to all server processes started by this postgres process. If the option string contains any spaces, the entire string must be quoted. The use of this option is obsolete; all command-line options for server processes can be specified directly on the postgres command line. -p port Specifies the TCP/IP port or local Unix domain socket file extension on which postgres is to listen for connections from client applications. Defaults to the value of the PGPORT environment variable, or if PGPORT is not set, then defaults to the value established during compilation (normally 5432). If you specify a port other than the default port, then all client applications must specify the same port using either command-line options or PGPORT. -s Print time information and other statistics at the end of each command. This is useful for benchmarking or for use in tuning the number of buffers. -S work-mem Specifies the amount of memory to be used by internal sorts and hashes before resorting to temporary disk files. See the description of the work_mem configuration parameter in Section_18.4.1. --name=value Sets a named run-time parameter; a shorter form of -c. --describe-config This option dumps out the server's internal configuration variables, descriptions, and defaults in tab-delimited COPY format. It is designed primarily for use by administration tools. Semi-internal Options The options described here are used mainly for debugging purposes, and in some cases to assist with recovery of severely damaged databases. There should be no reason to use them in a production database setup. They are listed here only for use by PostgreSQL system developers. Furthermore, these options might change or be removed in a future release without notice. -f { s | i | m | n | h } Forbids the use of particular scan and join methods: s and i disable sequential and index scans respectively, while n, m, and h disable nested-loop, merge and hash joins respectively. Neither sequential scans nor nested-loop joins can be disabled completely; the -fs and -fn options simply discourage the optimizer from using those plan types if it has any other alternative. -n This option is for debugging problems that cause a server process to die abnormally. The ordinary strategy in this situation is to notify all other server processes that they must terminate and then reinitialize the shared memory and semaphores. This is because an errant server process could have corrupted some shared state before terminating. This option specifies that postgres will not reinitialize shared data structures. A knowledgeable system programmer can then use a debugger to examine shared memory and semaphore state. -O Allows the structure of system tables to be modified. This is used by initdb. -P Ignore system indexes when reading system tables (but still update the indexes when modifying the tables). This is useful when recovering from damaged system indexes. -t pa[rser] | pl[anner] | e[xecutor] Print timing statistics for each query relating to each of the major system modules. This option cannot be used together with the - s option. -T This option is for debugging problems that cause a server process to die abnormally. The ordinary strategy in this situation is to notify all other server processes that they must terminate and then reinitialize the shared memory and semaphores. This is because an errant server process could have corrupted some shared state before terminating. This option specifies that postgres will stop all other server processes by sending the signal SIGSTOP, but will not cause them to terminate. This permits system programmers to collect core dumps from all server processes by hand. -v protocol Specifies the version number of the frontend/backend protocol to be used for a particular session. This option is for internal use only. -W seconds A delay of this many seconds occurs when a new server process is started, after it conducts the authentication procedure. This is intended to give an opportunity to attach to the server process with a debugger. Options for single-user mode The following options only apply to the single-user mode. --single Selects the single-user mode. This must be the first argument on the command line. database Specifies the name of the database to be accessed. This must be the last argument on the command line. If it is omitted it defaults to the user name. -E Echo all commands. -j Disables use of newline as a statement delimiter. -r filename Send all server log output to filename. In normal multiuser mode, this option is ignored, and stderr is used by all processes. Environment PGCLIENTENCODING Default character encoding used by clients. (The clients can override this individually.) This value can also be set in the configuration file. PGDATA Default data directory location PGDATESTYLE Default value of the DateStyle run-time parameter. (The use of this environment variable is deprecated.) PGPORT Default port (preferably set in the configuration file) TZ Server time zone Diagnostics A failure message mentioning semget or shmget probably indicates you need to configure your kernel to provide adequate shared memory and semaphores. For more discussion see Section_17.4. You might be able to postpone reconfiguring your kernel by decreasing shared_buffers to reduce the shared memory consumption of PostgreSQL, and/or by reducing max_connections to reduce the semaphore consumption. A failure message suggesting that another server is already running should be checked carefully, for example by using the command $ ps ax | grep postgres or $ ps -ef | grep postgres depending on your system. If you are certain that no conflicting server is running, you can remove the lock file mentioned in the message and try again. A failure message indicating inability to bind to a port might indicate that that port is already in use by some non-PostgreSQL process. You might also get this error if you terminate postgres and immediately restart it using the same port; in this case, you must simply wait a few seconds until the operating system closes the port before trying again. Finally, you might get this error if you specify a port number that your operating system considers to be reserved. For example, many versions of Unix consider port numbers under 1024 to be "trusted" and only permit the Unix superuser to access them. Notes The utility command pg_ctl can be used to start and shut down the postgres server safely and comfortably. If at all possible, do not use SIGKILL to kill the main postgres server. Doing so will prevent postgres from freeing the system resources (e.g., shared memory and semaphores) that it holds before terminating. This might cause problems for starting a fresh postgres run. To terminate the postgres server normally, the signals SIGTERM, SIGINT, or SIGQUIT can be used. The first will wait for all clients to terminate before quitting, the second will forcefully disconnect all clients, and the third will quit immediately without proper shutdown, resulting in a recovery run during restart. The SIGHUP signal will reload the server configuration files. It is also possible to send SIGHUP to an individual server process, but that is usually not sensible. To cancel a running query, send the SIGINT signal to the process running that command. The postgres server uses SIGTERM to tell subordinate server processes to quit normally and SIGQUIT to terminate without the normal cleanup. These signals should not be used by users. It is also unwise to send SIGKILL to a server process -- the main postgres process will interpret this as a crash and will force all the sibling processes to quit as part of its standard crash-recovery procedure. Bugs The -- options will not work on FreeBSD or OpenBSD. Use -c instead. This is a bug in the affected operating systems; a future release of PostgreSQL will provide a workaround if this is not fixed. Usage To start a single-user mode server, use a command like postgres --single -D /usr/local/pgsql/data other-options my_database Provide the correct path to the database directory with -D, or make sure that the environment variable PGDATA is set. Also specify the name of the particular database you want to work in. Normally, the single-user mode server treats newline as the command entry terminator; there is no intelligence about semicolons, as there is in psql. To continue a command across multiple lines, you must type backslash just before each newline except the last one. But if you use the -j command line switch, then newline does not terminate command entry. In this case, the server will read the standard input until the end-of-file (EOF) marker, then process the input as a single command string. Backslash-newline is not treated specially in this case. To quit the session, type EOF (Control+D, usually). If you've used -j, two consecutive EOFs are needed to exit. Note that the single-user mode server does not provide sophisticated line- editing features (no command history, for example). Examples To start postgres in the background using default values, type: $ nohup postgres >logfile 2>&1