rev |
line source |
jbe@23
|
1
|
jbe@23
|
2 --[[--
|
jbe@23
|
3 db_handle, -- database handle, or nil in case of error
|
jbe@23
|
4 errmsg, -- error message
|
jbe@23
|
5 errcode = -- error code
|
jbe@23
|
6 mondelefant.connect{
|
jbe@23
|
7 engine = "postgresql", -- no other engine is supported
|
jbe@40
|
8 conninfo = conninfo, -- string passed directly to PostgreSQL's libpq
|
jbe@23
|
9 host = host, -- hostname or directory with leading slash where Unix-domain socket resides
|
jbe@23
|
10 hostaddr = hostaddr, -- IPv4, or IPv6 address if supported
|
jbe@23
|
11 port = port, -- TCP port or socket file name extension
|
jbe@23
|
12 dbname = dbname, -- name of database to connect with
|
jbe@23
|
13 user = user, -- login name
|
jbe@23
|
14 password = password, -- password
|
jbe@23
|
15 connect_timeout = connect_timeout, -- seconds to wait for connection to be established. Zero or nil means infinite
|
jbe@23
|
16 ...
|
jbe@23
|
17 }
|
jbe@23
|
18
|
jbe@40
|
19 Opens a new database connection and returns a handle for that connection. You may chose to specify host, port, dbname, etc. as seperated arguments, or to use a "conninfo" string, which is directly passed to PostgreSQL's libpq.
|
jbe@23
|
20
|
jbe@23
|
21 --]]--
|
jbe@23
|
22 -- implemented in mondelefant_native.c as
|
jbe@23
|
23 -- static int mondelefant_connect(lua_State *L)
|
jbe@23
|
24 --//--
|
jbe@23
|
25
|
jbe@23
|
26
|
jbe@23
|
27 --[[--
|
jbe@23
|
28 <db_handle>:close()
|
jbe@23
|
29
|
jbe@23
|
30 Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected.
|
jbe@23
|
31
|
jbe@23
|
32 --]]--
|
jbe@23
|
33 -- implemented in mondelefant_native.c as
|
jbe@23
|
34 -- static int mondelefant_conn_close(lua_State *L)
|
jbe@23
|
35 --//--
|
jbe@23
|
36
|
jbe@23
|
37
|
jbe@23
|
38 --[[--
|
jbe@23
|
39 status = -- true, if database connection has no malfunction
|
jbe@23
|
40 <db_handle>:is_ok()
|
jbe@23
|
41
|
jbe@23
|
42 Returns false, if the database connection has a malfunction, otherwise true.
|
jbe@23
|
43
|
jbe@23
|
44 --]]--
|
jbe@23
|
45 -- implemented in mondelefant_native.c as
|
jbe@23
|
46 -- static int mondelefant_conn_is_ok(lua_State *L)
|
jbe@23
|
47 --//--
|
jbe@23
|
48
|
jbe@23
|
49
|
jbe@23
|
50 --[[--
|
jbe@23
|
51 status = -- status string
|
jbe@23
|
52 <db_handle>:get_transaction_status()
|
jbe@23
|
53
|
jbe@23
|
54 Depending on the transaction status of the connection a string is returned:
|
jbe@23
|
55 - idle
|
jbe@23
|
56 - active
|
jbe@23
|
57 - intrans
|
jbe@23
|
58 - inerror
|
jbe@23
|
59 - unknown
|
jbe@23
|
60
|
jbe@23
|
61 --]]--
|
jbe@23
|
62 -- implemented in mondelefant_native.c as
|
jbe@23
|
63 -- static int mondelefant_conn_get_transaction_status(lua_State *L)
|
jbe@23
|
64 --//--
|
jbe@23
|
65
|
jbe@23
|
66
|
jbe@23
|
67 --[[--
|
jbe@23
|
68 db_list = -- database result being an empty list
|
jbe@23
|
69 <db_handle>:create_list()
|
jbe@23
|
70
|
jbe@23
|
71 Creates an empty database result representing a list. The used meta-table is "result_metatable". The attribute "_connection" is set to the database handle, and the attribute "_type" is set to "list".
|
jbe@23
|
72
|
jbe@23
|
73 --]]--
|
jbe@23
|
74 -- implemented in mondelefant_native.c as
|
jbe@23
|
75 -- static int mondelefant_conn_create_list(lua_State *L)
|
jbe@23
|
76 --//--
|
jbe@23
|
77
|
jbe@23
|
78
|
jbe@23
|
79 --[[--
|
jbe@23
|
80 db_object = -- database result being an empty object (row)
|
jbe@23
|
81 <db_handle>:create_object()
|
jbe@23
|
82
|
jbe@23
|
83 Creates an empty database result representing an object (row). The used meta-table is "result_metatable". The attribute "_connection" is set to the database handle, and the attribute "_type" is set to "object". Additionally the attributes "_data", "_dirty" and "_ref" are initialized with an empty table. TODO: Documentation of _data, _dirty and _ref.
|
jbe@23
|
84
|
jbe@23
|
85 --]]--
|
jbe@23
|
86 -- implemented in mondelefant_native.c as
|
jbe@23
|
87 -- static int mondelefant_conn_create_object(lua_State *L)
|
jbe@23
|
88 --//--
|
jbe@23
|
89
|
jbe@23
|
90
|
jbe@23
|
91 --[[--
|
jbe@23
|
92 quoted_encoded_string = -- encoded and quoted string
|
jbe@23
|
93 <db_handle>:quote_string(
|
jbe@23
|
94 unencoded_string -- string to encode and quote
|
jbe@23
|
95 )
|
jbe@23
|
96
|
jbe@23
|
97 Prepares a string to be used safely within SQL queries. This function is database dependent (see "backslash_quote" server configuration option for PostgreSQL).
|
jbe@23
|
98
|
jbe@23
|
99 --]]--
|
jbe@23
|
100 -- implemented in mondelefant_native.c as
|
jbe@23
|
101 -- static int mondelefant_conn_quote_string(lua_State *L)
|
jbe@23
|
102 --//--
|
jbe@23
|
103
|
jbe@23
|
104
|
jbe@23
|
105 --[[--
|
jbe@23
|
106 quoted_encoded_data = -- encoded and quoted data (as Lua string)
|
jbe@23
|
107 <db_handle>:quote_string(
|
jbe@23
|
108 raw_data -- data (as Lua string) to encode and quote
|
jbe@23
|
109 )
|
jbe@23
|
110
|
jbe@23
|
111 Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent.
|
jbe@23
|
112
|
jbe@23
|
113 --]]--
|
jbe@23
|
114 -- implemented in mondelefant_native.c as
|
jbe@23
|
115 -- static int mondelefant_conn_quote_binary(lua_State *L)
|
jbe@23
|
116 --//--
|
jbe@23
|
117
|
jbe@23
|
118
|
jbe@23
|
119 --[[--
|
jbe@23
|
120 sql_string =
|
jbe@23
|
121 <db_handle>:assemble_command{
|
jbe@23
|
122 template, -- template string
|
jbe@23
|
123 arg1, -- value to be inserted
|
jbe@23
|
124 arg2, -- another value to be inserted
|
jbe@23
|
125 key1 = named_arg3, -- named value
|
jbe@23
|
126 key2 = named_arg4, -- another named value
|
jbe@23
|
127 ...
|
jbe@23
|
128 }
|
jbe@23
|
129
|
jbe@23
|
130 This method returns a SQL command by inserting the given values into the template string. Placeholders are "?" or "$", optionally followed by alphanumeric characters (including underscores). Placeholder characters can be escaped by writing them twice. A question-mark ("?") denotes a single value to be inserted, a dollar-sign ("$") denotes a list of sub-structures to be inserted. If alphanumeric characters are following the placeholder character, then these characters form a key, which is used to lookup the value to be used, otherwise values of numeric indicies are used.
|
jbe@23
|
131
|
jbe@23
|
132 TODO: documentation of input-converters
|
jbe@23
|
133
|
jbe@23
|
134 List of sub-structures are tables with an optional "sep" value, which is used as seperator. Each (numerically indexed) entry of this table is passed to a recursive call of "assemble_command" and concatenated with the given seperator, or ", ", if no seperator is given.
|
jbe@23
|
135
|
jbe@23
|
136 --]]--
|
jbe@23
|
137 -- implemented in mondelefant_native.c as
|
jbe@23
|
138 -- static int mondelefant_conn_assemble_command(lua_State *L)
|
jbe@23
|
139 --//--
|
jbe@23
|
140
|
jbe@23
|
141
|
jbe@23
|
142 --[[--
|
jbe@23
|
143 db_error, -- error object, or nil in case of success
|
jbe@23
|
144 result1, -- result of first command
|
jbe@23
|
145 result2, -- result of second command
|
jbe@23
|
146 ... =
|
jbe@23
|
147 <db_handle>:try_query(
|
jbe@23
|
148 command1, -- first command (to be processed by "assemble_command" method)
|
jbe@23
|
149 mode1, -- mode for first command: "list", "object" or "opt_object"
|
jbe@23
|
150 command2, -- second command (to be processed by "assemble_command" method)
|
jbe@23
|
151 mode2, -- mode for second command: "list", "object" or "opt_object"
|
jbe@23
|
152 ..
|
jbe@23
|
153 )
|
jbe@23
|
154
|
jbe@23
|
155 This method executes one or multiple SQL commands and returns its results. Each command is pre-processed by the "assemble_command" method of the database handle. A mode can be selected for each command: "list" for normal queries, "object" for queries which have exactly one result row, or "opt_object" which have one or zero result rows. If an error occurs, an error object is returned as first result value.
|
jbe@23
|
156
|
jbe@23
|
157 The mode of the last command may be ommitted and default to "list".
|
jbe@23
|
158
|
jbe@23
|
159 --]]--
|
jbe@23
|
160 -- implemented in mondelefant_native.c as
|
jbe@23
|
161 -- static int mondelefant_conn_try_query(lua_State *L)
|
jbe@23
|
162 --//--
|
jbe@23
|
163
|
jbe@23
|
164
|
jbe@23
|
165 --[[--
|
jbe@23
|
166 <db_error>:escalate()
|
jbe@23
|
167
|
jbe@23
|
168 Causes a Lua error to be thrown. If the database connection has "error_objects" set to true, then the object is thrown itself, otherwise a string is thrown.
|
jbe@23
|
169
|
jbe@23
|
170 --]]--
|
jbe@23
|
171 -- implemented in mondelefant_native.c as
|
jbe@23
|
172 -- static int mondelefant_errorobject_escalate(lua_State *L)
|
jbe@23
|
173 --//--
|
jbe@23
|
174
|
jbe@23
|
175
|
jbe@23
|
176 --[[--
|
jbe@23
|
177 bool = -- true or false
|
jbe@23
|
178 <db_error>:is_kind_of(
|
jbe@23
|
179 error_code -- error code as used by this library
|
jbe@23
|
180 )
|
jbe@23
|
181
|
jbe@23
|
182 Checks, if a given error is of a given kind.
|
jbe@23
|
183
|
jbe@23
|
184 Example:
|
jbe@23
|
185 db_error:is_kind_of("IntegrityConstraintViolation")
|
jbe@23
|
186
|
jbe@23
|
187 --]]--
|
jbe@23
|
188 -- implemented in mondelefant_native.c as
|
jbe@23
|
189 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)
|
jbe@23
|
190 --//--
|
jbe@23
|
191
|
jbe@23
|
192
|
jbe@23
|
193 --[[--
|
jbe@23
|
194 result1, -- result of first command
|
jbe@23
|
195 result2, -- result of second command
|
jbe@23
|
196 ... =
|
jbe@23
|
197 <db_handle>:query(
|
jbe@23
|
198 command1, -- first command (to be processed by "assemble_command" method)
|
jbe@23
|
199 mode1, -- mode for first command: "list", "object" or "opt_object"
|
jbe@23
|
200 command2, -- second command (to be processed by "assemble_command" method)
|
jbe@23
|
201 mode2, -- mode for second command: "list", "object" or "opt_object"
|
jbe@23
|
202 ..
|
jbe@23
|
203 )
|
jbe@23
|
204
|
jbe@23
|
205 Same as "try_query" but raises error, when occurring.
|
jbe@23
|
206
|
jbe@23
|
207 --]]--
|
jbe@23
|
208 -- implemented in mondelefant_native.c as
|
jbe@23
|
209 -- static int mondelefant_conn_query(lua_State *L)
|
jbe@23
|
210 --//--
|
jbe@23
|
211
|
jbe@23
|
212
|
jbe@23
|
213 --[[--
|
jbe@23
|
214 db_list_or_object = -- first argument is returned
|
jbe@23
|
215 mondelefant.set_class(
|
jbe@23
|
216 db_list_or_object, -- database result list or object
|
jbe@23
|
217 db_class -- database class (model)
|
jbe@23
|
218 )
|
jbe@23
|
219
|
jbe@23
|
220 This function sets a class for a given database result list or object. If a result list is given as first argument, the class is also set for all elements of the list.
|
jbe@23
|
221
|
jbe@23
|
222 --]]--
|
jbe@23
|
223 -- implemented in mondelefant_native.c as
|
jbe@23
|
224 -- static int mondelefant_set_class(lua_State *L)
|
jbe@23
|
225 --//--
|
jbe@23
|
226
|
jbe@23
|
227
|
jbe@23
|
228 --[[--
|
jbe@23
|
229 db_class = -- new database class (model)
|
jbe@23
|
230 mondelefant.new_class()
|
jbe@23
|
231
|
jbe@23
|
232 This function creates a new class (model) used for database result lists or objects.
|
jbe@23
|
233
|
jbe@23
|
234 --]]--
|
jbe@23
|
235 -- implemented in mondelefant_native.c as
|
jbe@23
|
236 -- static int mondelefant_new_class(lua_State *L)
|
jbe@23
|
237 --//--
|
jbe@23
|
238
|
jbe@23
|
239
|
jbe@23
|
240 --[[--
|
jbe@23
|
241 reference_data = -- table with reference information
|
jbe@23
|
242 <db_class>:get_reference(
|
jbe@23
|
243 name -- reference name
|
jbe@23
|
244 )
|
jbe@23
|
245
|
jbe@23
|
246 This function performs a lookup for the given name in the "reference" table. Prototypes are used, when lookup was unsuccessful.
|
jbe@23
|
247
|
jbe@23
|
248 --]]--
|
jbe@23
|
249 -- implemented in mondelefant_native.c as
|
jbe@23
|
250 -- static int mondelefant_class_get_reference(lua_State *L)
|
jbe@23
|
251 --//--
|
jbe@23
|
252
|
jbe@23
|
253
|
jbe@23
|
254 --[[--
|
jbe@23
|
255 reference_name = -- reference name
|
jbe@23
|
256 <db_class>:get_foreign_key_reference_name(
|
jbe@23
|
257 foreign_key -- foreign key
|
jbe@23
|
258 )
|
jbe@23
|
259
|
jbe@23
|
260 This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used, when lookup was unsuccessful.
|
jbe@23
|
261
|
jbe@23
|
262 --]]--
|
jbe@23
|
263 -- implemented in mondelefant_native.c as
|
jbe@23
|
264 -- static int mondelefant_class_get_reference(lua_State *L)
|
jbe@23
|
265 --//--
|
jbe@23
|
266
|