Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit aaad011

Browse files
bmomjianbmomjian
committed
1. In keeping with the recent discussion that there should be more
said about views, stored procedures, and triggers, in the tutorial, I have added a bit of verbiage to that end. 2. Some formatting changes to the datetime discussion, as well as addition of a citation of a relevant book on calendars. Christopher Browne
1 parent cf9c2be commit aaad011

File tree

2 files changed

+211
-29
lines changed

2 files changed

+211
-29
lines changed

‎doc/src/sgml/advanced.sgml

Lines changed: 180 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.38 2003/11/29 19:51:36 pgsql Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.39 2004/03/30 21:58:20 momjian Exp $
33
-->
44

55
<chapter id="tutorial-advanced">
@@ -65,10 +65,24 @@ SELECT * FROM myview;
6565

6666
<para>
6767
Views can be used in almost any place a real table can be used.
68-
Building views upon other views is not uncommon.
68+
Building views upon other views is not uncommon. You may cut down
69+
on the difficulty of building complex queries by constructing them
70+
in smaller, easier-to-verify pieces, using views. Views may be
71+
used to reveal specific table columns to users that legitimately
72+
need access to some of the data, but who shouldn't be able to look
73+
at the whole table.
6974
</para>
70-
</sect1>
7175

76+
<para>
77+
Views differ from <quote> real tables </quote> in that they are
78+
not, by default, updatable. If they join together several tables,
79+
it may be troublesome to update certain columns since the
80+
<emphasis>real</emphasis> update that must take place requires
81+
identifying the relevant rows in the source tables. This is
82+
discussed further in <xref linkend="rules-views-update">.
83+
</para>
84+
85+
</sect1>
7286

7387
<sect1 id="tutorial-fk">
7488
<title>Foreign Keys</title>
@@ -387,6 +401,169 @@ SELECT name, altitude
387401
</para>
388402
</sect1>
389403

404+
<sect1 id="tutorial-storedprocs">
405+
<title> Stored Procedures </title>
406+
407+
<indexterm zone="tutorial-storedprocs">
408+
<primary>stored procedures</primary>
409+
</indexterm>
410+
411+
<para> Stored procedures are code that runs inside the database
412+
system. Numerous languages may be used to implement functions and
413+
procedures; most built-in code is implemented in C. The
414+
<quote>basic</quote> loadable procedural language for
415+
<productname>PostgreSQL</productname> is <xref linkid="plpgsql">.
416+
Numerous other languages may also be used, including <xref
417+
linkid="plperl">, <xref linkid="pltcl">, and <xref
418+
linkid="plpython">.
419+
</para>
420+
421+
<para> There are several ways that stored procedures are really
422+
helpful:
423+
424+
<itemizedlist>
425+
426+
<listitem><para> To centralize data validation code into the
427+
database </para>
428+
429+
<para> Your system may use client software written in several
430+
languages, perhaps with a <quote>web application</quote>
431+
implemented in PHP, a <quote>server application</quote> implemented
432+
in Java, and a <quote> report writer</quote> implemented in Perl.
433+
In the absence of stored procedures, you will likely find that data
434+
validation code must be implemented multiple times, in multiple
435+
languages, once for each application.</para>
436+
437+
<para> By implementing data validation in stored procedures,
438+
running in the database, it can behave uniformly for all these
439+
systems, and you do not need to worry about synchronizing
440+
validation procedures across the languages.</para>
441+
442+
</listitem>
443+
444+
<listitem><para> Reducing round trips between client and server
445+
</para>
446+
447+
<para>A stored procedure may submit multiple queries, looking up
448+
information and adding in links to additional tables. This takes
449+
place without requiring that the client submit multiple queries,
450+
and without requiring any added network traffic.
451+
</para>
452+
453+
<para> As a matter of course, the queries share a single
454+
transaction context, and there may also be savings in the
455+
evaluation of query plans, that will be similar between invocations
456+
of a given stored procedure. </para></listitem>
457+
458+
<listitem><para> To simplify queries. </para>
459+
460+
<para> For instance, if you are commonly checking the TLD on domain
461+
names, you might create a stored procedure for this purpose, and so
462+
be able to use queries such as <command> select domain, tld(domain)
463+
from domains; </command> instead of having to put verbose code
464+
using <function>substr()</function> into each query.
465+
</para>
466+
467+
<para> It is particularly convenient to use scripting languages
468+
like Perl, Tcl, and Python to <quote>grovel through strings</quote>
469+
since they are designed for <quote>text processing.</quote></para>
470+
471+
<para> The binding to the R statistical language allows
472+
implementing complex statistical queries inside the database,
473+
instead of having to draw the data out.
474+
</listitem>
475+
476+
<listitem><para> Increasing the level of abstraction</para>
477+
478+
<para> If data is accessed exclusively through stored procedures,
479+
then the structures of tables may be changed without there needing
480+
to be any visible change in the API used by programmers. In some
481+
systems, users are <emphasis>only</emphasis> allowed access to
482+
stored procedures to update data, and cannot do direct updates to
483+
tables.
484+
</para>
485+
486+
</listitem>
487+
488+
</itemizedlist>
489+
</para>
490+
491+
<para> These benefits build on one another: careful use of stored
492+
procedures can simultaneously improve reliability and performance,
493+
whilst simplifying database access code and improving portability
494+
across client platforms and languages. For instance, consider that
495+
a stored procedure can cheaply query tables in the database to
496+
validate the correctness of data provided as input. </para>
497+
498+
<para> Instead of requiring a whole series of queries to create an
499+
object, and to look up parent/subsidiary objects to link it to, a
500+
stored procedure can do all of this efficiently in the database
501+
server, improving performance, and eliminating whole classes of
502+
errors. </para>
503+
504+
</sect1>
505+
506+
<sect1 id="tutorial-triggers">
507+
<title> Triggers </title>
508+
509+
<indexterm zone="tutorial-triggers">
510+
<primary>triggers</primary>
511+
</indexterm>
512+
513+
<para> Triggers allow running a function either before or after
514+
update (<command>INSERT</command>, <command>DELETE</command>,
515+
<command>UPDATE</command>) operations, which can allow you to do
516+
some very clever things. </para>
517+
518+
<itemizedlist>
519+
520+
<listitem><para> Data Validation </para>
521+
522+
<para> Instead of explicitly coding validation checks as part of a
523+
stored procedure, they may be introduced as <command>BEFORE</command>
524+
triggers. The trigger function checks the input values, raising an
525+
exception if it finds invalid input.</para>
526+
527+
<para> Note that this is how foreign key checks are implemented in
528+
<productname>PostgreSQL</productname>; when you define a foreign
529+
key, you will see a message similar to the following:
530+
<screen>
531+
NOTICE: CREATE TABLE will create implicit trigger(s) for FOREIGN KEY check(s)
532+
</screen></para>
533+
534+
<para> In some cases, it may be appropriate for a trigger function
535+
to insert data in order to <emphasis>make</emphasis> the input valid. For
536+
instance, if a newly created object needs a status code in a status
537+
table, the trigger might automatically do that.</para>
538+
</listitem>
539+
540+
<listitem><para> Audit logs </para>
541+
542+
<para> One may use <command>AFTER</command> triggers to monitor updates to
543+
vital tables, and <command>INSERT</command> entries into log tables to
544+
provide a more permanent record of those updates. </para>
545+
</listitem>
546+
547+
<listitem><para> Replication </para>
548+
549+
<para> The <application>RServ</application> replication system uses
550+
<command>AFTER</command> triggers to track which rows have changed on the
551+
<quote>master</quote> system and therefore need to be copied over to
552+
<quote>slave</quote> systems.</para>
553+
554+
<para> <command>
555+
CREATE TRIGGER "_rserv_trigger_t_" AFTER INSERT OR DELETE OR UPDATE ON "my_table"
556+
FOR EACH ROW EXECUTE PROCEDURE "_rserv_log_" ('10');
557+
</command></para>
558+
</listitem>
559+
560+
</itemizedlist>
561+
562+
<para> Notice that there are strong parallels between what can be
563+
accomplished using triggers and stored procedures, particularly in
564+
regards to data validation. </para>
565+
566+
</sect1>
390567

391568
<sect1 id="tutorial-conclusion">
392569
<title>Conclusion</title>

‎doc/src/sgml/datetime.sgml

Lines changed: 31 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.39 2003/12/01 20:34:53 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.40 2004/03/30 21:58:20 momjian Exp $
33
-->
44

55
<appendix id="datetime-appendix">
@@ -11,8 +11,8 @@ $PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.39 2003/12/01 20:34:53 tgl Exp
1111
strings, and are broken up into distinct fields with a preliminary
1212
determination of what kind of information may be in the
1313
field. Each field is interpreted and either assigned a numeric
14-
value, ignored, or rejected.
15-
The parser contains internal lookup tables for all textual fields,
14+
value, ignored, or rejected.</para>
15+
<para> The parser contains internal lookup tables for all textual fields,
1616
including months, days of the week, and time
1717
zones.
1818
</para>
@@ -1056,21 +1056,21 @@ $PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.39 2003/12/01 20:34:53 tgl Exp
10561056
years.
10571057
</para>
10581058

1059-
<para>
1060-
The papal bull of February 1582 decreed that 10 days should be dropped
1061-
from October 1582 so that 15 October should follow immediately after
1062-
4 October.
1063-
This was observed in Italy, Poland, Portugal, and Spain. Other Catholic
1064-
countries followed shortly after, but Protestant countries were
1065-
reluctant to change, and the Greek orthodox countries didn't change
1066-
until the start of the 20th century.
1059+
<para> The papal bull of February 1582 decreed that 10 days should
1060+
be dropped from October 1582 so that 15 October should follow
1061+
immediately after 4 October.</para>
1062+
1063+
<para> This was observed in Italy, Poland, Portugal, and Spain.
1064+
Other Catholic countries followed shortly after, but Protestant
1065+
countries were reluctant to change, and the Greek orthodox countries
1066+
didn't change until the start of the 20th century.</para>
10671067

1068-
The reform was observed by Great Britain and Dominions (including what is
1069-
now the USA) in 1752.
1070-
Thus 2 September 1752 was followed by 14 September 1752.
1068+
<para> The reform was observed by Great Britain and Dominions
1069+
(including what is now the USA) in 1752. Thus 2 September 1752 was
1070+
followed by 14 September 1752.</para>
10711071

1072-
This is why Unix systems have the <command>cal</command> program
1073-
produce the following:
1072+
<para> This is why Unix systems have the <command>cal</command>
1073+
program produce the following:
10741074

10751075
<screen>
10761076
$ <userinput>cal 9 1752</userinput>
@@ -1094,19 +1094,24 @@ $ <userinput>cal 9 1752</userinput>
10941094
</para>
10951095
</note>
10961096

1097-
<para>
1098-
Different calendars have been developed in various parts of the
1099-
world, many predating the Gregorian system.
1097+
<para> Different calendars have been developed in various parts of
1098+
the world, many predating the Gregorian system.</para>
11001099

1101-
For example,
1102-
the beginnings of the Chinese calendar can be traced back to the 14th
1103-
century BC. Legend has it that the Emperor Huangdi invented the
1104-
calendar in 2637 BC.
1100+
<para> For example, the beginnings of the Chinese calendar can be
1101+
traced back to the 14th century BC. Legend has it that the Emperor
1102+
Huangdi invented the calendar in 2637 BC.</para>
11051103

1106-
The People's Republic of China uses the Gregorian calendar
1107-
for civil purposes. The Chinese calendar is used for determining
1108-
festivals.
1104+
<para> The People's Republic of China uses the Gregorian calendar
1105+
for civil purposes. The Chinese calendar is used for determining
1106+
festivals.
11091107
</para>
1108+
1109+
<para> If you are interested in this sort of thing, <citation>
1110+
Calendrical Calculations: The Millennium Edition </citation> by by
1111+
Edward M. Reingold and Nachum Dershowitz is an excellent reference,
1112+
describing some 25 calendars, and providing software for displaying
1113+
them and converting between them.</para>
1114+
11101115
</sect1>
11111116
</appendix>
11121117

0 commit comments

Comments
 (0)