From 337b22cb473f1c5cca011a511c488d20e153eec4 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 20 Mar 2002 19:45:13 +0000 Subject: Code review for DOMAIN patch. --- doc/src/sgml/catalogs.sgml | 85 +++++++++++++++++++++++-------------- doc/src/sgml/ref/create_domain.sgml | 44 ++++++++++--------- doc/src/sgml/ref/drop_domain.sgml | 30 ++++++++++--- doc/src/sgml/ref/psql-ref.sgml | 19 ++------- 4 files changed, 105 insertions(+), 73 deletions(-) (limited to 'doc/src/sgml') diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 451c9dcaa8a..5db408f6d0f 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1,6 +1,6 @@ @@ -2274,7 +2274,8 @@ This catalog stores information about datatypes. Scalar types (base types) are created with CREATE TYPE. A complex type is also created for each table in the database, to - represent the row structure of the table. + represent the row structure of the table. It is also possible to create + derived types with CREATE DOMAIN. @@ -2345,11 +2346,10 @@ typtype is b for - a base type and c for a complex type (i.e., - a table's row type). If typtype is - c, typrelid is - the OID of the type's entry in - pg_class. + a base type, c for a complex type (i.e., + a table's row type), or d for a derived type (i.e., + a domain). See also typrelid + and typbasetype. @@ -2382,6 +2382,7 @@ the pg_class entry that defines the corresponding table. A table could theoretically be used as a composite data type, but this is not fully functional. + Zero for non-complex types. @@ -2511,38 +2512,53 @@ - typbasetype - oid + typnotnull + bool - typbasetype is the type that this one is based - on. Normally references the domains parent type, and is 0 otherwise. + typnotnull represents a NOT NULL + constraint on a type. Presently used for domains only. - - typnotnull - boolean - - - typnotnull represents a NOT NULL - constraint on a type. Used for domains only. - - + + typbasetype + oid + pg_type.oid + + If this is a derived type (see typtype), + then typbasetype identifies + the type that this one is based on. Zero if not a derived type. + + - typmod - integer + typtypmod + int4 - typmod records type-specific data + typtypmod records type-specific data supplied at table creation time (for example, the maximum length of a varchar column). It is passed to type-specific input and output functions as the third argument. The value will generally be -1 for types that do not - need typmod. This data is copied to - pg_attribute.atttypmod on creation - of a table using a domain as it's field type. + need typmod. This value is copied to + pg_attribute.atttypmod when + creating a column of a domain type. + + + + + typndims + int4 + + + typndims is the number of array dimensions + for a domain that is an array. (The array element type is + typbasetype.) Zero for non-domains and non-array domains. + This value is copied to + pg_attribute.attndims when + creating a column of a domain type. @@ -2551,9 +2567,9 @@ text - typdefaultbin is NULL for types without a - default value. If it's not NULL, it contains the internal string - representation of the default expression node. + If typdefaultbin is not NULL, it is the nodeToString + representation of a default expression for the type. Currently this is + only used for domains. @@ -2562,9 +2578,14 @@ text - typdefault is NULL for types without a - default value. If it's not NULL, it contains the external string - representation of the type's default value. + typdefault is NULL if the type has no associated + default value. If typdefaultbin is not NULL, + typdefault must contain a human-readable version of the + default expression represented by typdefaultbin. If + typdefaultbin is NULL and typdefault is + not, then typdefault is the external representation of + the type's default value, which may be fed to the type's input + converter to produce a constant. diff --git a/doc/src/sgml/ref/create_domain.sgml b/doc/src/sgml/ref/create_domain.sgml index 5f79dc63b53..222d49da5d1 100644 --- a/doc/src/sgml/ref/create_domain.sgml +++ b/doc/src/sgml/ref/create_domain.sgml @@ -1,5 +1,5 @@ @@ -23,13 +23,14 @@ PostgreSQL documentation 2002-02-24 -CREATE DOMAIN domainname data_type [ DEFAULT default_expr ] [ column_constraint [, ... ] ] +CREATE DOMAIN domainname [AS] data_type + [ DEFAULT default_expr ] + [ constraint [, ... ] ] + +where constraint is: + [ CONSTRAINT constraint_name ] -{ NOT NULL | NULL } - +{ NOT NULL | NULL } @@ -67,23 +68,26 @@ CREATE DOMAIN domainname default_expr - The DEFAULT clause assigns a default data value for - the column whose column definition it appears within. The value - is any variable-free expression (subselects and cross-references - to other columns in the current table are not allowed). The + The DEFAULT clause specifies a default value for + columns of the domain data type. The value + is any variable-free expression (but subselects are not allowed). + The data type of the default expression must match the data type of the domain. The default expression will be used in any insert operation that - does not specify a value for the domain. If there is no default + does not specify a value for the column. If there is no default for a domain, then the default is NULL. - The default of a column will be tested before that of the domain. + If a default value is specified 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. @@ -93,7 +97,7 @@ CREATE DOMAIN domainname CONSTRAINT constraint_name - An optional name for a domain. If not specified, + An optional name for a constraint. If not specified, the system generates a name. @@ -103,7 +107,7 @@ CREATE DOMAIN domainname NOT NULL - The column is not allowed to contain NULL values. This is + Values of this domain are not allowed to be NULL. This is equivalent to the column constraint CHECK (column NOT NULL). @@ -114,7 +118,7 @@ CREATE DOMAIN domainname NULL - The column is allowed to contain NULL values. This is the default. + Values of this domain are allowed to be NULL. This is the default. @@ -175,7 +179,7 @@ CREATE DOMAIN Domains are useful for abstracting common fields between tables into a single location for maintenance. An email address column may be used in several tables, all with the same properties. Define a domain and - use that rather than setting up each tables constraints individually. + use that rather than setting up each table's constraints individually. @@ -195,9 +199,9 @@ CREATE TABLE countrylist (id INT4, country country_code); Compatibility - This CREATE DOMAIN command is a - PostgreSQL extension. CHECK and FOREIGN KEY - constraints are currently unsupported. + SQL99 defines CREATE DOMAIN, but says that the only allowed constraint + type is CHECK constraints. CHECK constraints for domains are not yet + supported by PostgreSQL. diff --git a/doc/src/sgml/ref/drop_domain.sgml b/doc/src/sgml/ref/drop_domain.sgml index e9bc38ad28c..63eb0dc057e 100644 --- a/doc/src/sgml/ref/drop_domain.sgml +++ b/doc/src/sgml/ref/drop_domain.sgml @@ -1,5 +1,5 @@ @@ -23,7 +23,7 @@ PostgreSQL documentation 1999-07-20 -DROP DOMAIN domainname [, ...] +DROP DOMAIN domainname [, ...] [ CASCADE | RESTRICT ] @@ -43,6 +43,25 @@ DROP DOMAIN domainname [, ...] + + + CASCADE + + + Automatically drop objects that depend on the domain. This + behavior is not currently supported. + + + + + + RESTRICT + + + Do not drop dependent objects. This is the default. + + + @@ -117,7 +136,7 @@ ERROR: RemoveDomain: type 'domainnamebox domain: -DROP DOMAIN box RESTRICT; +DROP DOMAIN box; @@ -134,9 +153,8 @@ DROP DOMAIN box RESTRICT; DROP DOMAIN name { CASCADE | RESTRICT } - PostgreSQL enforces the existance of - RESTRICT or CASCADE but ignores their enforcement against the - system tables. + PostgreSQL accepts only the RESTRICT + option, and currently does not check for existence of dependent objects. diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 350128fa724..40ba18716c2 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,5 +1,5 @@ @@ -419,21 +419,10 @@ testdb=> \dD [ pattern ] - Lists all database domains. - - - - Descriptions for objects can be generated with the COMMENT ON - SQL command. - - - - - PostgreSQL stores the object descriptions in the - pg_description system table. + Lists all available domains (derived types). + If pattern + (a regular expression) is specified, only matching domains are shown. - - -- cgit v1.2.3