2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/postgres.sgml -->
|
2000-03-31 05:26:21 +02:00
|
|
|
|
2003-11-24 20:08:02 +01:00
|
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
|
1998-05-13 07:33:32 +02:00
|
|
|
|
2011-04-04 22:07:53 +02:00
|
|
|
<!ENTITY % version SYSTEM "version.sgml">
|
2000-11-24 18:44:22 +01:00
|
|
|
%version;
|
2011-04-04 22:07:53 +02:00
|
|
|
<!ENTITY % filelist SYSTEM "filelist.sgml">
|
2000-11-24 18:44:22 +01:00
|
|
|
%filelist;
|
2000-07-21 02:44:13 +02:00
|
|
|
|
2011-04-04 22:07:53 +02:00
|
|
|
<!ENTITY reference SYSTEM "reference.sgml">
|
2000-07-21 02:44:13 +02:00
|
|
|
|
1998-03-01 09:16:16 +01:00
|
|
|
]>
|
2000-05-02 22:02:03 +02:00
|
|
|
|
2003-03-25 17:15:44 +01:00
|
|
|
<book id="postgres">
|
2000-11-24 18:44:22 +01:00
|
|
|
<title>PostgreSQL &version; Documentation</title>
|
|
|
|
|
2003-03-25 17:15:44 +01:00
|
|
|
<bookinfo>
|
2000-11-24 18:44:22 +01:00
|
|
|
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
|
2009-08-05 00:04:37 +02:00
|
|
|
<productname>PostgreSQL</productname>
|
|
|
|
<productnumber>&version;</productnumber>
|
2001-02-03 20:03:27 +01:00
|
|
|
&legal;
|
2003-03-25 17:15:44 +01:00
|
|
|
</bookinfo>
|
|
|
|
|
2003-09-09 01:02:28 +02:00
|
|
|
&intro;
|
2003-03-25 17:15:44 +01:00
|
|
|
|
|
|
|
<part id="tutorial">
|
|
|
|
<title>Tutorial</title>
|
|
|
|
|
|
|
|
<partintro>
|
|
|
|
<para>
|
2003-09-13 00:17:24 +02:00
|
|
|
Welcome to the <productname>PostgreSQL</productname> Tutorial. The
|
2003-03-25 17:15:44 +01:00
|
|
|
following few chapters are intended to give a simple introduction
|
|
|
|
to <productname>PostgreSQL</productname>, relational database
|
|
|
|
concepts, and the SQL language to those who are new to any one of
|
|
|
|
these aspects. We only assume some general knowledge about how to
|
|
|
|
use computers. No particular Unix or programming experience is
|
2003-09-13 00:17:24 +02:00
|
|
|
required. This part is mainly intended to give you some hands-on
|
2003-03-25 17:15:44 +01:00
|
|
|
experience with important aspects of the
|
|
|
|
<productname>PostgreSQL</productname> system. It makes no attempt
|
|
|
|
to be a complete or thorough treatment of the topics it covers.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
After you have worked through this tutorial you might want to move
|
|
|
|
on to reading <xref linkend="sql"> to gain a more formal knowledge
|
|
|
|
of the SQL language, or <xref linkend="client-interfaces"> for
|
|
|
|
information about developing applications for
|
|
|
|
<productname>PostgreSQL</productname>. Those who set up and
|
|
|
|
manage their own server should also read <xref linkend="admin">.
|
|
|
|
</para>
|
|
|
|
</partintro>
|
|
|
|
|
|
|
|
&start;
|
|
|
|
&query;
|
|
|
|
&advanced;
|
|
|
|
|
|
|
|
</part>
|
|
|
|
|
|
|
|
<part id="sql">
|
|
|
|
<title>The SQL Language</title>
|
|
|
|
|
|
|
|
<partintro>
|
|
|
|
<para>
|
|
|
|
This part describes the use of the <acronym>SQL</acronym> language
|
|
|
|
in <productname>PostgreSQL</productname>. We start with
|
|
|
|
describing the general syntax of <acronym>SQL</acronym>, then
|
|
|
|
explain how to create the structures to hold data, how to populate
|
|
|
|
the database, and how to query it. The middle part lists the
|
|
|
|
available data types and functions for use in
|
2004-12-23 06:37:40 +01:00
|
|
|
<acronym>SQL</acronym> commands. The rest treats several
|
2003-03-25 17:15:44 +01:00
|
|
|
aspects that are important for tuning a database for optimal
|
|
|
|
performance.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The information in this part is arranged so that a novice user can
|
|
|
|
follow it start to end to gain a full understanding of the topics
|
|
|
|
without having to refer forward too many times. The chapters are
|
|
|
|
intended to be self-contained, so that advanced users can read the
|
|
|
|
chapters individually as they choose. The information in this
|
|
|
|
part is presented in a narrative fashion in topical units.
|
|
|
|
Readers looking for a complete description of a particular command
|
2009-04-27 18:27:36 +02:00
|
|
|
should see <xref linkend="reference">.
|
2003-03-25 17:15:44 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-11-04 10:55:39 +01:00
|
|
|
Readers of this part should know how to connect to a
|
2003-03-25 17:15:44 +01:00
|
|
|
<productname>PostgreSQL</> database and issue
|
|
|
|
<acronym>SQL</acronym> commands. Readers that are unfamiliar with
|
|
|
|
these issues are encouraged to read <xref linkend="tutorial">
|
|
|
|
first. <acronym>SQL</acronym> commands are typically entered
|
|
|
|
using the <productname>PostgreSQL</> interactive terminal
|
|
|
|
<application>psql</application>, but other programs that have
|
|
|
|
similar functionality can be used as well.
|
|
|
|
</para>
|
|
|
|
</partintro>
|
|
|
|
|
|
|
|
&syntax;
|
|
|
|
&ddl;
|
|
|
|
&dml;
|
|
|
|
&queries;
|
|
|
|
&datatype;
|
|
|
|
&func;
|
|
|
|
&typeconv;
|
|
|
|
&indices;
|
2007-08-21 23:08:47 +02:00
|
|
|
&textsearch;
|
2003-03-25 17:15:44 +01:00
|
|
|
&mvcc;
|
|
|
|
&perform;
|
|
|
|
|
|
|
|
</part>
|
|
|
|
|
|
|
|
<part id="admin">
|
|
|
|
<title>Server Administration</title>
|
|
|
|
|
|
|
|
<partintro>
|
|
|
|
<para>
|
|
|
|
This part covers topics that are of interest to a
|
|
|
|
<productname>PostgreSQL</> database administrator. This includes
|
|
|
|
installation of the software, set up and configuration of the
|
|
|
|
server, management of users and databases, and maintenance tasks.
|
2004-12-24 20:12:37 +01:00
|
|
|
Anyone who runs a <productname>PostgreSQL</> server, even for
|
2003-03-25 17:15:44 +01:00
|
|
|
personal use, but especially in production, should be familiar
|
|
|
|
with the topics covered in this part.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The information in this part is arranged approximately in the
|
|
|
|
order in which a new user should read it. But the chapters are
|
|
|
|
self-contained and can be read individually as desired. The
|
|
|
|
information in this part is presented in a narrative fashion in
|
|
|
|
topical units. Readers looking for a complete description of a
|
2009-04-27 18:27:36 +02:00
|
|
|
particular command should see <xref linkend="reference">.
|
2003-03-25 17:15:44 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2009-04-27 18:27:36 +02:00
|
|
|
The first few chapters are written so they can be understood
|
|
|
|
without prerequisite knowledge, so new users who need to set
|
2003-03-25 17:15:44 +01:00
|
|
|
up their own server can begin their exploration with this part.
|
2009-06-17 23:58:49 +02:00
|
|
|
The rest of this part is about tuning and management; that material
|
2004-12-24 20:12:37 +01:00
|
|
|
assumes that the reader is familiar with the general use of
|
2003-03-25 17:15:44 +01:00
|
|
|
the <productname>PostgreSQL</> database system. Readers are
|
|
|
|
encouraged to look at <xref linkend="tutorial"> and <xref
|
|
|
|
linkend="sql"> for additional information.
|
|
|
|
</para>
|
|
|
|
</partintro>
|
|
|
|
|
|
|
|
&installation;
|
|
|
|
&installw;
|
|
|
|
&runtime;
|
2005-09-13 00:11:38 +02:00
|
|
|
&config;
|
2008-05-07 18:36:43 +02:00
|
|
|
&client-auth;
|
2003-03-25 17:15:44 +01:00
|
|
|
&user-manag;
|
|
|
|
&manage-ag;
|
|
|
|
&charset;
|
|
|
|
&maintenance;
|
|
|
|
&backup;
|
2006-11-17 17:38:44 +01:00
|
|
|
&high-availability;
|
2010-02-22 12:47:30 +01:00
|
|
|
&recovery-config;
|
2003-03-25 17:15:44 +01:00
|
|
|
&monitoring;
|
|
|
|
&diskusage;
|
|
|
|
&wal;
|
|
|
|
®ress;
|
|
|
|
|
|
|
|
</part>
|
|
|
|
|
|
|
|
<part id="client-interfaces">
|
|
|
|
<title>Client Interfaces</title>
|
|
|
|
|
|
|
|
<partintro>
|
|
|
|
<para>
|
|
|
|
This part describes the client programming interfaces distributed
|
|
|
|
with <productname>PostgreSQL</>. Each of these chapters can be
|
|
|
|
read independently. Note that there are many other programming
|
|
|
|
interfaces for client programs that are distributed separately and
|
2004-12-30 00:36:47 +01:00
|
|
|
contain their own documentation (<xref linkend="external-projects">
|
|
|
|
lists some of the more popular ones). Readers of this part should be
|
2003-03-25 17:15:44 +01:00
|
|
|
familiar with using <acronym>SQL</acronym> commands to manipulate
|
|
|
|
and query the database (see <xref linkend="sql">) and of course
|
|
|
|
with the programming language that the interface uses.
|
|
|
|
</para>
|
|
|
|
</partintro>
|
|
|
|
|
|
|
|
&libpq;
|
|
|
|
&lobj;
|
|
|
|
&ecpg;
|
2003-05-18 22:55:57 +02:00
|
|
|
&infoschema;
|
2003-03-25 17:15:44 +01:00
|
|
|
|
|
|
|
</part>
|
|
|
|
|
|
|
|
<part id="server-programming">
|
|
|
|
<title>Server Programming</title>
|
|
|
|
|
|
|
|
<partintro>
|
|
|
|
<para>
|
|
|
|
This part is about extending the server functionality with
|
|
|
|
user-defined functions, data types, triggers, etc. These are
|
|
|
|
advanced topics which should probably be approached only after all
|
|
|
|
the other user documentation about <productname>PostgreSQL</> has
|
2004-12-30 04:13:56 +01:00
|
|
|
been understood. Later chapters in this part describe the server-side
|
2003-03-25 17:15:44 +01:00
|
|
|
programming languages available in the
|
|
|
|
<productname>PostgreSQL</productname> distribution as well as
|
2004-12-30 04:13:56 +01:00
|
|
|
general issues concerning server-side programming languages. It
|
|
|
|
is essential to read at least the earlier sections of <xref
|
|
|
|
linkend="extend"> (covering functions) before diving into the
|
|
|
|
material about server-side programming languages.
|
2003-03-25 17:15:44 +01:00
|
|
|
</para>
|
|
|
|
</partintro>
|
|
|
|
|
|
|
|
&extend;
|
|
|
|
&trigger;
|
2012-07-18 16:16:16 +02:00
|
|
|
&event-trigger;
|
2004-12-30 04:13:56 +01:00
|
|
|
&rules;
|
2003-03-25 17:15:44 +01:00
|
|
|
|
|
|
|
&xplang;
|
|
|
|
&plsql;
|
|
|
|
&pltcl;
|
|
|
|
&plperl;
|
|
|
|
&plpython;
|
|
|
|
|
2003-10-23 00:28:10 +02:00
|
|
|
&spi;
|
Background worker processes
Background workers are postmaster subprocesses that run arbitrary
user-specified code. They can request shared memory access as well as
backend database connections; or they can just use plain libpq frontend
database connections.
Modules listed in shared_preload_libraries can register background
workers in their _PG_init() function; this is early enough that it's not
necessary to provide an extra GUC option, because the necessary extra
resources can be allocated early on. Modules can install more than one
bgworker, if necessary.
Care is taken that these extra processes do not interfere with other
postmaster tasks: only one such process is started on each ServerLoop
iteration. This means a large number of them could be waiting to be
started up and postmaster is still able to quickly service external
connection requests. Also, shutdown sequence should not be impacted by
a worker process that's reasonably well behaved (i.e. promptly responds
to termination signals.)
The current implementation lets worker processes specify their start
time, i.e. at what point in the server startup process they are to be
started: right after postmaster start (in which case they mustn't ask
for shared memory access), when consistent state has been reached
(useful during recovery in a HOT standby server), or when recovery has
terminated (i.e. when normal backends are allowed).
In case of a bgworker crash, actions to take depend on registration
data: if shared memory was requested, then all other connections are
taken down (as well as other bgworkers), just like it were a regular
backend crashing. The bgworker itself is restarted, too, within a
configurable timeframe (which can be configured to be never).
More features to add to this framework can be imagined without much
effort, and have been discussed, but this seems good enough as a useful
unit already.
An elementary sample module is supplied.
Author: Álvaro Herrera
This patch is loosely based on prior patches submitted by KaiGai Kohei,
and unsubmitted code by Simon Riggs.
Reviewed by: KaiGai Kohei, Markus Wanner, Andres Freund,
Heikki Linnakangas, Simon Riggs, Amit Kapila
2012-12-06 18:57:52 +01:00
|
|
|
&bgworker;
|
2003-10-23 00:28:10 +02:00
|
|
|
|
2003-03-25 17:15:44 +01:00
|
|
|
</part>
|
2000-11-24 18:44:22 +01:00
|
|
|
|
|
|
|
&reference;
|
2003-03-25 17:15:44 +01:00
|
|
|
|
|
|
|
<part id="internals">
|
|
|
|
<title>Internals</title>
|
|
|
|
|
|
|
|
<partintro>
|
|
|
|
<para>
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
This part contains assorted information that might be of use to
|
2003-03-25 17:15:44 +01:00
|
|
|
<productname>PostgreSQL</> developers.
|
|
|
|
</para>
|
|
|
|
</partintro>
|
|
|
|
|
|
|
|
&arch-dev;
|
|
|
|
&catalogs;
|
|
|
|
&protocol;
|
2003-10-23 00:28:10 +02:00
|
|
|
&sources;
|
|
|
|
&nls;
|
|
|
|
&plhandler;
|
2011-02-20 06:17:18 +01:00
|
|
|
&fdwhandler;
|
2003-03-25 17:15:44 +01:00
|
|
|
&geqo;
|
2005-02-13 04:04:15 +01:00
|
|
|
&indexam;
|
2003-03-25 17:15:44 +01:00
|
|
|
&gist;
|
2011-12-17 22:41:16 +01:00
|
|
|
&spgist;
|
2006-09-14 15:40:28 +02:00
|
|
|
&gin;
|
2005-01-10 01:04:43 +01:00
|
|
|
&storage;
|
2003-06-22 18:16:44 +02:00
|
|
|
&bki;
|
2005-02-27 01:49:28 +01:00
|
|
|
&planstats;
|
2003-03-25 17:15:44 +01:00
|
|
|
|
|
|
|
</part>
|
|
|
|
|
|
|
|
<part id="appendixes">
|
|
|
|
<title>Appendixes</title>
|
|
|
|
|
2003-10-17 20:57:01 +02:00
|
|
|
&errcodes;
|
2003-03-25 17:15:44 +01:00
|
|
|
&datetime;
|
|
|
|
&keywords;
|
|
|
|
&features;
|
|
|
|
&release;
|
2007-11-14 03:36:43 +01:00
|
|
|
&contrib;
|
|
|
|
&external-projects;
|
2010-09-22 20:10:28 +02:00
|
|
|
&sourcerepo;
|
2003-03-25 17:15:44 +01:00
|
|
|
&docguide;
|
2007-11-01 18:00:46 +01:00
|
|
|
&acronyms;
|
2003-03-25 17:15:44 +01:00
|
|
|
|
|
|
|
</part>
|
|
|
|
|
|
|
|
&biblio;
|
Rearrangement of the HTML docs build rules
Set up proper makefile dependencies in the documentation build rules,
especially around the HTML/index build. The problem we've had with all
previous solutions is that we have used the same file name, such as HTML.index
or bookindex.sgml, to mean different things at different stages of the build,
and make can't distinguish that. The solution here is that the first jade run
produces HTML.index, but does not require bookindex.sgml at all, and produces
no other html output (the latter an idea from Alvaro). The second jade run
includes bookindex.sgml, but does not recreate HTML.index. That way, when you
change an sgml file, jade is run twice and at the end all dependencies are
satisfied. Omitting the html output in the first stage also makes the full
build a lot faster.
When you run one of the print format targets, only the first jade run is run,
then the print target-specific commands. If an HTML build has completed
previously, the first jade run is skipped because the dependencies have
already been satisfied.
The draft and check targets for quick builds and syntax verification are still
there.
2009-07-15 00:16:38 +02:00
|
|
|
<![%include-index;[&bookindex;]]>
|
2013-10-16 04:54:36 +02:00
|
|
|
<![%include-xslt-index;[<index></index>]]>
|
2003-03-25 17:15:44 +01:00
|
|
|
|
|
|
|
</book>
|