1

2 --[[--

3 db_handle, -- database handle, or nil in case of error

4 errmsg, -- error message

5 db_error = -- error object

6 mondelefant.connect{

7 conninfo = conninfo, -- string passed directly to PostgreSQL's libpq

8 host = host, -- hostname or directory with leading slash where Unix-domain socket resides

9 hostaddr = hostaddr, -- IPv4, or IPv6 address if supported

10 port = port, -- TCP port or socket file name extension

11 dbname = dbname, -- name of database to connect with

12 user = user, -- login name

13 password = password, -- password

14 connect_timeout = connect_timeout, -- seconds to wait for connection to be established. Zero or nil means infinite

15 ...

16 }

17

18 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. In the latter case, the "conninfo" string may also be passed directly as first argument to the connect function without supplying a table.

19

20 --]]--

21 -- implemented in mondelefant_native.c as

22 -- static int mondelefant_connect(lua_State *L)

23 --//--

24

25

26 --[[--

27 <db_handle>.fd -- file descriptor of underlaying database connection

28

29 The file descriptor number of the underlaying database connection. This value may be used in conjunction with :wait(0) and a select/poll system call to wait for several events at once.

30

31 --]]--

32 -- set/unset in mondelefant_native.c in

33 -- static int mondelefant_connect(lua_State *L) and

34 -- static int mondelefant_close(lua_State *L)

35 --//--

36

37

38 --[[--

39 <db_handle>:close()

40

41 Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected.

42

43 --]]--

44 -- implemented in mondelefant_native.c as

45 -- static int mondelefant_conn_close(lua_State *L)

46 --//--

47

48

49 --[[--

50 status = -- true, if database connection has no malfunction

51 <db_handle>:is_ok()

52

53 Returns false, if the database connection has a malfunction, otherwise true.

54

55 --]]--

56 -- implemented in mondelefant_native.c as

57 -- static int mondelefant_conn_is_ok(lua_State *L)

58 --//--

59

60

61 --[[--

62 status = -- status string

63 <db_handle>:get_transaction_status()

64

65 Depending on the transaction status of the connection a string is returned:

66 - idle

67 - active

68 - intrans

69 - inerror

70 - unknown

71

72 --]]--

73 -- implemented in mondelefant_native.c as

74 -- static int mondelefant_conn_get_transaction_status(lua_State *L)

75 --//--

76

77

78 --[[--

79 db_error, -- error object, or nil in case of success or timeout

80 channel, -- notification channel name, or nil in case of timeout or no pending notify

81 payload, -- notification payload string

82 pid = -- process ID of notifying server process

83 <db_handle>:try_wait(

84 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely

85 )

86

87 Waits for any NOTIFY event that is being LISTENed for. One or more LISTEN commands must have been sent previously with <db_handle>:query("LISTEN channel_name").

88

89 --]]--

90 -- implemented in mondelefant_native.c as

91 -- static int mondelefant_conn_try_wait(lua_State *L)

92 --//--

93

94

95 --[[--

96 db_list = -- database result being an empty list (or filled list)

97 <db_handle>:create_list(

98 tbl -- optional table to be converted to a filled list

99 )

100

101 Creates a 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". The attribute "_class" is initialized to the default class prototype "class_prototype" of the module.

102

103 --]]--

104 -- implemented in mondelefant_native.c as

105 -- static int mondelefant_conn_create_list(lua_State *L)

106 --//--

107

108

109 --[[--

110 db_object = -- database result being an empty object (row)

111 <db_handle>:create_object()

112

113 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". The attribute "_class" is initialized to the default class prototype "class_prototype" of the module. Additionally the attribute "_col" is set to a proxy table, and the attributes "_data", "_dirty" and "_ref" are initialized with an empty table. TODO: Documentation of _data, _dirty and _ref.

114

115 --]]--

116 -- implemented in mondelefant_native.c as

117 -- static int mondelefant_conn_create_object(lua_State *L)

118 --//--

119

120

121 --[[--

122 quoted_encoded_string = -- encoded and quoted string

123 <db_handle>:quote_string(

124 unencoded_string -- string to encode and quote

125 )

126

127 Prepares a string to be used safely within SQL queries. This function is database dependent (see "backslash_quote" server configuration option for PostgreSQL).

128

129 --]]--

130 -- implemented in mondelefant_native.c as

131 -- static int mondelefant_conn_quote_string(lua_State *L)

132 --//--

133

134

135 --[[--

136 quoted_encoded_data = -- encoded and quoted data (as Lua string)

137 <db_handle>:quote_binary(

138 raw_data -- data (as Lua string) to encode and quote

139 )

140

141 Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent.

142

143 --]]--

144 -- implemented in mondelefant_native.c as

145 -- static int mondelefant_conn_quote_binary(lua_State *L)

146 --//--

147

148

149 --[[--

150 sql_string =

151 <db_handle>:assemble_command{

152 template, -- template string

153 arg1, -- value to be inserted

154 arg2, -- another value to be inserted

155 key1 = named_arg3, -- named value

156 key2 = named_arg4, -- another named value

157 ...

158 }

159

160 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.

161

162 TODO: documentation of input-converters

163

164 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.

165

166 --]]--

167 -- implemented in mondelefant_native.c as

168 -- static int mondelefant_conn_assemble_command(lua_State *L)

169 --//--

170

171

172 --[[--

173 db_error, -- error object, or nil in case of success

174 result1, -- result of first command

175 result2, -- result of second command

176 ... =

177 <db_handle>:try_query(

178 command1, -- first command (to be processed by "assemble_command" method)

179 mode1, -- mode for first command: "list", "object" or "opt_object"

180 command2, -- second command (to be processed by "assemble_command" method)

181 mode2, -- mode for second command: "list", "object" or "opt_object"

182 ..

183 )

184

185 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.

186

187 The mode of the last command may be ommitted and default to "list".

188

189 --]]--

190 -- implemented in mondelefant_native.c as

191 -- static int mondelefant_conn_try_query(lua_State *L)

192 --//--

193

194

195 --[[--

196 <db_error>:escalate()

197

198 Deprecated alias for error(<db_error>).

199

200 Note: Previous versions converted the error object to a string unless the database connection had "error_objects" set to true. The current implementation simply calls error(...). It is deprecated to use this method, use error(...) instead.

201

202 --]]--

203 -- implemented in mondelefant_native.c as

204 -- static int mondelefant_errorobject_escalate(lua_State *L)

205 --//--

206

207

208 --[[--

209 bool = -- true or false

210 <db_error>:is_kind_of(

211 error_code -- error code as used by this library

212 )

213

214 Checks, if a given error is of a given kind.

215

216 Example:

217 db_error:is_kind_of("IntegrityConstraintViolation")

218

219 --]]--

220 -- implemented in mondelefant_native.c as

221 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)

222 --//--

223

224

225 --[[--

226 <db_error>.code -- hierarchical error code (separated by dots) in camel case

227

228 An error code in camel case notation with dots to separate hierarchy levels, e.g. "IntegrityConstraintViolation.UniqueViolation". See also <db_error>:is_kind_of(...).

229

230 --]]--

231 -- implemented in mondelefant_native.c as

232 -- static const char *mondelefant_translate_errcode(const char *pgcode)

233 --//--

234

235

236 --[[--

237 <db_error>.message -- string which summarizes the error

238

239 A string consisting of a single line (without CR/LF) describing the error. For more detailed information on a particular error, additional fields may be set in the <db_error> object. Refer to the source code of the mondelefant_translate_errcode C function in mondelefant_native.c.

240

241 --]]--

242 -- implemented in mondelefant_native.c

243 --//--

244

245

246 --[[--

247 channel, -- notification channel name, or nil in case of timeout or no pending notify

248 payload, -- notification payload string

249 pid = -- process ID of notifying server process

250 <db_handle>:wait(

251 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely

252 )

253

254 Same as "try_wait" but raises an error, if a connection error occurred. Timeouts are reported by returning nil as first argument.

255

256 --]]--

257 -- implemented in mondelefant_native.c as

258 -- static int mondelefant_conn_wait(lua_State *L)

259 --//--

260

261

262 --[[--

263 result1, -- result of first command

264 result2, -- result of second command

265 ... =

266 <db_handle>:query(

267 command1, -- first command (to be processed by "assemble_command" method)

268 mode1, -- mode for first command: "list", "object" or "opt_object"

269 command2, -- second command (to be processed by "assemble_command" method)

270 mode2, -- mode for second command: "list", "object" or "opt_object"

271 ..

272 )

273

274 Same as "try_query" but raises error, when occurring.

275

276 --]]--

277 -- implemented in mondelefant_native.c as

278 -- static int mondelefant_conn_query(lua_State *L)

279 --//--

280

281

282 --[[--

283 db_list_or_object = -- first argument is returned

284 mondelefant.set_class(

285 db_list_or_object, -- database result list or object

286 db_class -- database class (model)

287 )

288

289 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.

290

291 --]]--

292 -- implemented in mondelefant_native.c as

293 -- static int mondelefant_set_class(lua_State *L)

294 --//--

295

296

297 --[[--

298 db_class = -- new database class (model)

299 mondelefant.new_class()

300

301 This function creates a new class (model) used for database result lists or objects.

302

303 --]]--

304 -- implemented in mondelefant_native.c as

305 -- static int mondelefant_new_class(lua_State *L)

306 --//--

307

308

309 --[[--

310 reference_data = -- table with reference information

311 <db_class>:get_reference(

312 name -- reference name

313 )

314

315 This function performs a lookup for the given name in the "reference" table. Prototypes are used when lookup was unsuccessful.

316

317 --]]--

318 -- implemented in mondelefant_native.c as

319 -- static int mondelefant_class_get_reference(lua_State *L)

320 --//--

321

322

323 --[[--

324 reference_name = -- reference name

325 <db_class>:get_foreign_key_reference_name(

326 foreign_key -- foreign key

327 )

328

329 This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used when lookup was unsuccessful.

330

331 --]]--

332 -- implemented in mondelefant_native.c as

333 -- static int mondelefant_class_get_reference(lua_State *L)

334 --//--

335

336

337 --[[--

338 <db_object>._col -- proxy table mapping column names to their values

339

340 This attribute can be used to access column values directly (helpful if <db_class>:document_column is set).

341

342 NOTE: Neither pairs(...) nor ipairs(...) are implemented on this proxy table. Use <db_object>._column_info instead.

343

344 --]]--

345 -- implemented in mondelefant_native.c as

346 -- static const struct luaL_Reg mondelefant_columns_mt_functions[]

347 --//--

348