| MG Mud User | 88f1247 | 2016-06-24 23:31:02 +0200 | [diff] [blame^] | 1 | CONCEPT |
| 2 | pgsql - PostgreSQL support |
| 3 | |
| 4 | DESCRIPTION |
| 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 | |
| 79 | AUTHOR |
| 80 | Florian Heinz and others. |
| 81 | |
| 82 | HISTORY |
| 83 | Added as package in LDMud 3.3.445. |
| 84 | LDMud 3.3.640 added a privilege_violation() call for each efun. |
| 85 | |
| 86 | SEE ALSO |
| 87 | mysql(C), pg_connect(E), pg_conv_string(E), pg_query(E), pg_pending(E), |
| 88 | pg_close(E), privilege_violation(M) |