blob: 12f2cc42ad9ab0c3b927d267dbced5e500fc83dd [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001CONCEPT
2 pgsql - PostgreSQL support
3
4DESCRIPTION
5 On hosts with the PostgreSQL package installed, the driver can be
6 configured to interface with the PostgreSQL database. If that is done,
7 the driver defines the macro __PGSQL__ for LPC programs and
8 activates a number of related efuns.
9
10 -- Usage --
11
12 The interface to the PostgreSQL database is implemented
13 through the concept of a controlling object: when opening a
14 database connection, the LPC code has to provide a callback
15 function. The object this function is bound to is the
16 controlling object: all queries to the database will be issued
17 by this object, and the responses will be sent to the callback
18 function.
19
20 The interface is also asynchronous: the pg_query() efun just
21 queues the query with the database connection, and returns
22 immediately. When the database has finished working the query,
23 the callback function is called with the results.
24
25 The callback function can be defined by name or by closure,
26 and can be defined with extra parameters:
27
28
29 #include <pgsql.h>
30
31 void <callback>(int type, mixed ret, int id [, mixed extra...])
32
33 <type> is the type of the call, <id> identifies the query
34 for which this call is executed:
35
36 PGRES_TUPLES_OK: <ret> is the result from a query.
37 It is either a mapping (field name as
38 key, indexing <n> values for n returned
39 tuples), or an array of arrays (one per
40 row).
41
42 PGRES_COMMAND_OK: <ret> is a string which contains the
43 server response (e.g. on INSERT or DELETE)
44
45 PGRES_BAD_RESPONSE,
46 PGRES_NONFATAL_ERROR,
47 PGRES_FATAL_ERROR: ret is the error-string
48
49
50 void <callback>(int type, mixed ret [, mixed extra...])
51
52 <type> is the type of the call, which is not related a
53 specific query:
54
55 PGCONN_SUCCESS: The database-connection was established,
56 <ret> is a dummy string.
57 PGCONN_FAILED: The database-connection failed, <ret> is
58 the error message.
59 The first message to the callback after a call to
60 pg_connect() is always one of these two.
61
62 PGRES_NOTICE: <ret> is a informational text.
63
64 PGCONN_ABORTED: If the connection to the backend fails
65 we try to re-establish (reset) it. If the
66 reset fails, the connection is closed and
67 this value is returned. Consider the
68 connection gone and don't try to close or
69 otherwise operate further on it.
70 <ret> is a dummy string.
71
72 -- Security --
73
74 All SQL efuns (unless execute by the master or the simul-efun object)
75 trigger a privilege_violation ("pgsql", "<efun_name>"). If a more
76 finegrained control is desired, overload the individual efuns with a
77 nomask simul-efun.
78
79AUTHOR
80 Florian Heinz and others.
81
82HISTORY
83 Added as package in LDMud 3.3.445.
84 LDMud 3.3.640 added a privilege_violation() call for each efun.
85
86SEE ALSO
87 mysql(C), pg_connect(E), pg_conv_string(E), pg_query(E), pg_pending(E),
88 pg_close(E), privilege_violation(M)