database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-11-03 09:13:20 +03:00
Code Activity

Add more information about schemas. Combines some previously existing

Browse Source 
material into the new location.
This commit is contained in:
Peter Eisentraut
2002-09-12 22:05:36 +00:00
parent feb202193d
commit 6d77f6e5fb
4 changed files with 614 additions and 308 deletions
Download Patch File Download Diff File Expand all files Collapse all files

305
doc/src/sgml/syntax.sgml
View File

@@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.68 2002/08/23 04:27:19 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.69 2002/09/12 22:05:36 petere Exp $
-->
<chapter id="sql-syntax">
@@ -581,7 +581,7 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
<listitem>
<para>
The period (<literal>.</literal>) is used in floating-point
constants, and to separate table and column names.
constants, and to separate schema, table, and column names.
</para>
</listitem>
</itemizedlist>
@@ -815,307 +815,6 @@ SELECT 3 OPERATOR(pg_catalog.+) 4;
</sect2>
</sect1>
<sect1 id="sql-naming">
<title>Schemas and Naming Conventions</title>
<indexterm>
<primary>schemas</primary>
</indexterm>
<indexterm>
<primary>search path</primary>
</indexterm>
<indexterm>
<primary>namespaces</primary>
</indexterm>
<para>
A <productname>PostgreSQL</productname> database cluster (installation)
contains one or more named databases. Users and groups of users are
shared across the entire cluster, but no other data is shared across
databases. Any given client connection to the server can access
only the data in a single database, the one specified in the connection
request.
</para>
<note>
<para>
Users of a cluster do not necessarily have the privilege to access every
database in the cluster. Sharing of user names means that there
cannot be different users named, say, <literal>joe</> in two databases
in the same cluster; but the system can be configured to allow
<literal>joe</> access to only some of the databases.
</para>
</note>
<sect2>
<title>Schema Object Names</title>
<para>
A database contains one or more named <firstterm>schemas</>, which
in turn contain tables. Schemas also contain other kinds of named
objects, including datatypes, functions, and operators. The same
object name can be used in different schemas without conflict; for
example, both <literal>schema1</> and <literal>myschema</> may
contain tables named <literal>mytable</>. Unlike databases, schemas
are not rigidly separated: a user may access objects in any of the
schemas in the database he is connected to, if he has privileges
to do so.
</para>
<indexterm>
<primary>qualified names</primary>
</indexterm>
<indexterm>
<primary>names</primary>
<secondary>qualified</secondary>
</indexterm>
<para>
To name a table precisely, write a <firstterm>qualified name</> consisting
of the schema name and table name separated by a dot:
<synopsis>
<replaceable>schema</><literal>.</><replaceable>table</>
</synopsis>
Actually, the even more general syntax
<synopsis>
<replaceable>database</><literal>.</><replaceable>schema</><literal>.</><replaceable>table</>
</synopsis>
can be used too, but at present this is just for pro-forma compliance
with the SQL standard; if you write a database name it must be the
same as the database you are connected to.
</para>
<indexterm>
<primary>unqualified names</primary>
</indexterm>
<indexterm>
<primary>names</primary>
<secondary>unqualified</secondary>
</indexterm>
<para>
Qualified names are tedious to write, and it's often best not to
wire a particular schema name into applications anyway. Therefore
tables are often referred to by <firstterm>unqualified names</>,
which consist of just the table name. The system determines which table
is meant by following a <firstterm>search path</>, which is a list
of schemas to look in. The first matching table in the search path
is taken to be the one wanted. If there is no match in the search
path, an error is reported, even if matching table names exist
in other schemas in the database.
</para>
<para>
The first schema named in the search path is called the current schema.
Aside from being the first schema searched, it is also the schema in
which new tables will be created if the <command>CREATE TABLE</>
command does not specify a schema name.
</para>
<para>
The search path works in the same way for datatype names, function names,
and operator names as it does for table names. Datatype and function
names can be qualified in exactly the same way as table names. If you
need to write a qualified operator name in an expression, there is a
special provision: you must write
<synopsis>
<literal>OPERATOR(</><replaceable>schema</><literal>.</><replaceable>operator</><literal>)</>
</synopsis>
This is needed to avoid syntactic ambiguity. An example is
<programlisting>
SELECT 3 OPERATOR(pg_catalog.+) 4;
</programlisting>
In practice one usually relies on the search path for operators,
so as not to have to write anything so ugly as that.
</para>
<para>
The standard search path in <productname>PostgreSQL</productname>
contains first the schema having the same name as the session user
(if it exists), and second the schema named <literal>public</>
(if it exists, which it does by default). This arrangement allows
a flexible combination of private and shared tables. If no per-user
schemas are created then all user tables will exist in the shared
<literal>public</> schema, providing behavior that is backwards-compatible
with pre-7.3 <productname>PostgreSQL</productname> releases.
</para>
<note>
<para>
There is no concept of a <literal>public</> schema in the SQL standard.
To achieve closest conformance to the standard, the DBA should
create per-user schemas for every user, and not use (perhaps even
remove) the <literal>public</> schema.
</para>
</note>
<para>
In addition to <literal>public</> and user-created schemas, each database
contains a
<literal>pg_catalog</> schema, which contains the system tables
and all the built-in datatypes, functions, and operators.
<literal>pg_catalog</> is always effectively part of the search path.
If it is not named explicitly in the path then it is implicitly searched
<emphasis>before</> searching the path's schemas. This ensures that
built-in names will always be findable. However, you may explicitly
place <literal>pg_catalog</> at the end of your search path if you
prefer to have user-defined names override built-in names.
</para>
<para>
The search path is determined by the GUC variable SEARCH_PATH and
may be changed at any time. See <xref linkend="set-search-path">.
</para>
</sect2>
<sect2 id="sql-reserved-names">
<title>Reserved names</title>
<indexterm>
<primary>reserved names</primary>
</indexterm>
<indexterm>
<primary>names</primary>
<secondary>reserved</secondary>
</indexterm>
<para>
There are several restrictions on the names that can be chosen for
user-defined database objects. These restrictions vary depending
on the kind of object. (Note that these restrictions are
separate from whether the name is a key word or not; quoting a
name will not allow you to escape these restrictions.)
</para>
<para>
Schema names beginning with <literal>pg_</> are reserved for system
purposes and may not be created by users.
</para>
<para>
In <productname>PostgreSQL</productname> versions before 7.3, table
names beginning with <literal>pg_</> were reserved. This is no longer
true: you may create such a table name if you wish, in any non-system
schema. However, it's best to continue to avoid such names,
to ensure that you won't suffer a conflict if some future version
defines a system catalog named the same as your table. (With the
default search path, an unqualified reference to your table name
would be resolved as the system catalog instead.) System catalogs will
continue to follow the convention of having names beginning with
<literal>pg_</>, so that they will not conflict with unqualified
user-table names so long as users avoid the <literal>pg_</> prefix.
</para>
<para>
Every table has several <firstterm>system columns</> that are
implicitly defined by the system. Therefore, these names cannot
be used as names of user-defined columns:
<indexterm>
<primary>columns</primary>
<secondary>system columns</secondary>
</indexterm>
<variablelist>
<varlistentry>
<term><structfield>oid</></term>
<listitem>
<para>
<indexterm>
<primary>OID</primary>
</indexterm>
The object identifier (object ID) of a row. This is a serial number
that is automatically added by <productname>PostgreSQL</productname> to all table rows (unless
the table was created WITHOUT OIDS, in which case this column is
not present). See <xref linkend="datatype-oid"> for more info.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><structfield>tableoid</></term>
<listitem>
<para>
The OID of the table containing this row. This attribute is
particularly handy for queries that select from inheritance
hierarchies, since without it, it's difficult to tell which
individual table a row came from. The
<structfield>tableoid</structfield> can be joined against the
<structfield>oid</structfield> column of
<classname>pg_class</classname> to obtain the table name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><structfield>xmin</></term>
<listitem>
<para>
The identity (transaction ID) of the inserting transaction for
this tuple. (Note: A tuple is an individual state of a row;
each update of a row creates a new tuple for the same logical row.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><structfield>cmin</></term>
<listitem>
<para>
The command identifier (starting at zero) within the inserting
transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><structfield>xmax</></term>
<listitem>
<para>
The identity (transaction ID) of the deleting transaction,
or zero for an undeleted tuple. It is possible for this field
to be nonzero in a visible tuple: that usually indicates that the
deleting transaction hasn't committed yet, or that an attempted
deletion was rolled back.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><structfield>cmax</></term>
<listitem>
<para>
The command identifier within the deleting transaction, or zero.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><structfield>ctid</></term>
<listitem>
<para>
The physical location of the tuple within its table.
Note that although the <structfield>ctid</structfield>
can be used to locate the tuple very quickly, a row's
<structfield>ctid</structfield> will change each time it is updated
or moved by <command>VACUUM FULL</>.
Therefore <structfield>ctid</structfield> is useless as a long-term
row identifier.
The OID, or even better a user-defined serial number, should
be used to identify logical rows.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
</sect1>
<sect1 id="sql-expressions">
<title>Value Expressions</title>