Skip to content

Commit ac9f254

Browse files
bmomjianbmomjian
committed
Improve PL/Perl documentation of database access functions.
Alexey Klyukin
1 parent cb4bd52 commit ac9f254

File tree

1 file changed

+105
-22
lines changed

1 file changed

+105
-22
lines changed

‎doc/src/sgml/plperl.sgml‎

Lines changed: 105 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.78 2010/02/01 15:48:35 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.79 2010/02/05 18:11:46 momjian Exp $ -->
22

33
<chapter id="plperl">
44
<title>PL/Perl - Perl Procedural Language</title>
@@ -338,16 +338,36 @@ use strict;
338338
<primary>spi_exec_query</primary>
339339
<secondary>in PL/Perl</secondary>
340340
</indexterm>
341+
<indexterm>
342+
<primary>spi_query</primary>
343+
<secondary>in PL/Perl</secondary>
344+
</indexterm>
345+
<indexterm>
346+
<primary>spi_fetchrow</primary>
347+
<secondary>in PL/Perl</secondary>
348+
</indexterm>
349+
<indexterm>
350+
<primary>spi_prepare</primary>
351+
<secondary>in PL/Perl</secondary>
352+
</indexterm>
353+
<indexterm>
354+
<primary>spi_exec_prepared</primary>
355+
<secondary>in PL/Perl</secondary>
356+
</indexterm>
357+
<indexterm>
358+
<primary>spi_query_prepared</primary>
359+
<secondary>in PL/Perl</secondary>
360+
</indexterm>
361+
<indexterm>
362+
<primary>spi_cursor_close</primary>
363+
<secondary>in PL/Perl</secondary>
364+
</indexterm>
365+
<indexterm>
366+
<primary>spi_freeplan</primary>
367+
<secondary>in PL/Perl</secondary>
368+
</indexterm>
341369

342370
<term><literal><function>spi_exec_query</>(<replaceable>query</replaceable> [, <replaceable>max-rows</replaceable>])</literal></term>
343-
<term><literal><function>spi_query</>(<replaceable>command</replaceable>)</literal></term>
344-
<term><literal><function>spi_fetchrow</>(<replaceable>cursor</replaceable>)</literal></term>
345-
<term><literal><function>spi_prepare</>(<replaceable>command</replaceable>, <replaceable>argument types</replaceable>)</literal></term>
346-
<term><literal><function>spi_exec_prepared</>(<replaceable>plan</replaceable>, <replaceable>arguments</replaceable>)</literal></term>
347-
<term><literal><function>spi_query_prepared</>(<replaceable>plan</replaceable> [, <replaceable>attributes</replaceable>], <replaceable>arguments</replaceable>)</literal></term>
348-
<term><literal><function>spi_cursor_close</>(<replaceable>cursor</replaceable>)</literal></term>
349-
<term><literal><function>spi_freeplan</>(<replaceable>plan</replaceable>)</literal></term>
350-
351371
<listitem>
352372
<para>
353373
<literal>spi_exec_query</literal> executes an SQL command and
@@ -420,7 +440,15 @@ $$ LANGUAGE plperl;
420440
SELECT * FROM test_munge();
421441
</programlisting>
422442
</para>
443+
</listitem>
444+
</varlistentry>
423445

446+
<varlistentry>
447+
<term><literal><function>spi_query</>(<replaceable>command</replaceable>)</literal></term>
448+
<term><literal><function>spi_fetchrow</>(<replaceable>cursor</replaceable>)</literal></term>
449+
<term><literal><function>spi_cursor_close</>(<replaceable>cursor</replaceable>)</literal></term>
450+
451+
<listitem>
424452
<para>
425453
<literal>spi_query</literal> and <literal>spi_fetchrow</literal>
426454
work together as a pair for row sets which might be large, or for cases
@@ -459,13 +487,41 @@ SELECT * from lotsa_md5(500);
459487
</programlisting>
460488
</para>
461489

490+
<para>
491+
Normally, <function>spi_fetchrow</> should be repeated until it
492+
returns <literal>undef</literal>, indicating that there are no more
493+
rows to read. The cursor returned by <literal>spi_query</literal>
494+
is automatically freed when
495+
<function>spi_fetchrow</> returns <literal>undef</literal>.
496+
If you do not wish to read all the rows, instead call
497+
<function>spi_cursor_close</> to free the cursor.
498+
Failure to do so will result in memory leaks.
499+
</para>
500+
501+
</listitem>
502+
</varlistentry>
503+
504+
<varlistentry>
505+
<term><literal><function>spi_prepare</>(<replaceable>command</replaceable>, <replaceable>argument types</replaceable>)</literal></term>
506+
<term><literal><function>spi_query_prepared</>(<replaceable>plan</replaceable>, <replaceable>arguments</replaceable>)</literal></term>
507+
<term><literal><function>spi_exec_prepared</>(<replaceable>plan</replaceable> [, <replaceable>attributes</replaceable>], <replaceable>arguments</replaceable>)</literal></term>
508+
<term><literal><function>spi_freeplan</>(<replaceable>plan</replaceable>)</literal></term>
509+
510+
<listitem>
462511
<para>
463512
<literal>spi_prepare</literal>, <literal>spi_query_prepared</literal>, <literal>spi_exec_prepared</literal>,
464-
and <literal>spi_freeplan</literal> implement the same functionality but for prepared queries. Once
465-
a query plan is prepared by a call to <literal>spi_prepare</literal>, the plan can be used instead
513+
and <literal>spi_freeplan</literal> implement the same functionality but for prepared queries.
514+
<literal>spi_prepare</literal> accepts a query string with numbered argument placeholders ($1, $2, etc)
515+
and a string list of argument types:
516+
<programlisting>
517+
$plan = spi_prepare('SELECT * FROM test WHERE id &gt; $1 AND name = $2', 'INTEGER', 'TEXT');
518+
</programlisting>
519+
Once a query plan is prepared by a call to <literal>spi_prepare</literal>, the plan can be used instead
466520
of the string query, either in <literal>spi_exec_prepared</literal>, where the result is the same as returned
467521
by <literal>spi_exec_query</literal>, or in <literal>spi_query_prepared</literal> which returns a cursor
468522
exactly as <literal>spi_query</literal> does, which can be later passed to <literal>spi_fetchrow</literal>.
523+
The optional second parameter to <literal>spi_exec_prepared</literal> is a hash reference of attributes;
524+
the only attribute currently supported is <literal>limit</literal>, which sets the maximum number of rows returned by a query.
469525
</para>
470526

471527
<para>
@@ -476,18 +532,18 @@ SELECT * from lotsa_md5(500);
476532

477533
<para>
478534
<programlisting>
479-
CREATE OR REPLACE FUNCTION init() RETURNS INTEGER AS $$
535+
CREATE OR REPLACE FUNCTION init() RETURNS VOID AS $$
480536
$_SHARED{my_plan} = spi_prepare( 'SELECT (now() + $1)::date AS now', 'INTERVAL');
481537
$$ LANGUAGE plperl;
482538

483539
CREATE OR REPLACE FUNCTION add_time( INTERVAL ) RETURNS TEXT AS $$
484540
return spi_exec_prepared(
485541
$_SHARED{my_plan},
486-
$_[0],
542+
$_[0]
487543
)->{rows}->[0]->{now};
488544
$$ LANGUAGE plperl;
489545

490-
CREATE OR REPLACE FUNCTION done() RETURNS INTEGER AS $$
546+
CREATE OR REPLACE FUNCTION done() RETURNS VOID AS $$
491547
spi_freeplan( $_SHARED{my_plan});
492548
undef $_SHARED{my_plan};
493549
$$ LANGUAGE plperl;
@@ -509,15 +565,42 @@ SELECT done();
509565
</para>
510566

511567
<para>
512-
Normally, <function>spi_fetchrow</> should be repeated until it
513-
returns <literal>undef</literal>, indicating that there are no more
514-
rows to read. The cursor is automatically freed when
515-
<function>spi_fetchrow</> returns <literal>undef</literal>.
516-
If you do not wish to read all the rows, instead call
517-
<function>spi_cursor_close</> to free the cursor.
518-
Failure to do so will result in memory leaks.
568+
Another example illustrates usage of an optional parameter in <literal>spi_exec_prepared</literal>:
519569
</para>
520-
</listitem>
570+
571+
<para>
572+
<programlisting>
573+
CREATE TABLE hosts AS SELECT id, ('192.168.1.'||id)::inet AS address FROM generate_series(1,3) AS id;
574+
575+
CREATE OR REPLACE FUNCTION init_hosts_query() RETURNS VOID AS $$
576+
$_SHARED{plan} = spi_prepare('SELECT * FROM hosts WHERE address &lt;&lt; $1', 'inet');
577+
$$ LANGUAGE plperl;
578+
579+
CREATE OR REPLACE FUNCTION query_hosts(inet) RETURNS SETOF hosts AS $$
580+
return spi_exec_prepared(
581+
$_SHARED{plan},
582+
{limit =&gt; 2},
583+
$_[0]
584+
)->{rows};
585+
$$ LANGUAGE plperl;
586+
587+
CREATE OR REPLACE FUNCTION release_hosts_query() RETURNS VOID AS $$
588+
spi_freeplan($_SHARED{plan});
589+
undef $_SHARED{plan};
590+
$$ LANGUAGE plperl;
591+
592+
SELECT init_hosts_query();
593+
SELECT query_hosts('192.168.1.0/30');
594+
SELECT release_hosts_query();
595+
596+
query_hosts
597+
-----------------
598+
(1,192.168.1.1)
599+
(2,192.168.1.2)
600+
(2 rows)
601+
</programlisting>
602+
</para>
603+
</listitem>
521604
</varlistentry>
522605
</variablelist>
523606
</sect2>

0 commit comments

Comments
 (0)