1

2 --[[--

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

4 errmsg, -- error message

5 errcode = -- error code

6 mondelefant.connect{

7 engine = "postgresql", -- no other engine is supported

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

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

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

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

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

13 user = user, -- login name

14 password = password, -- password

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

16 ...

17 }

18

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.

20

21 --]]--

22 -- implemented in mondelefant_native.c as

23 -- static int mondelefant_connect(lua_State *L)

24 --//--

25

26

27 --[[--

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

29

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

31

32 --]]--

33 -- set/unset in mondelefant_native.c in

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

35 -- static int mondelefant_close(lua_State *L)

36 --//--

37

38

39 --[[--

40 <db_handle>:close()

41

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

43

44 --]]--

45 -- implemented in mondelefant_native.c as

46 -- static int mondelefant_conn_close(lua_State *L)

47 --//--

48

49

50 --[[--

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

52 <db_handle>:is_ok()

53

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

55

56 --]]--

57 -- implemented in mondelefant_native.c as

58 -- static int mondelefant_conn_is_ok(lua_State *L)

59 --//--

60

61

62 --[[--

63 status = -- status string

64 <db_handle>:get_transaction_status()

65

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

67 - idle

68 - active

69 - intrans

70 - inerror

71 - unknown

72

73 --]]--

74 -- implemented in mondelefant_native.c as

75 -- static int mondelefant_conn_get_transaction_status(lua_State *L)

76 --//--

77

78

79 --[[--

80 channel, -- notification channel name

81 payload, -- notification payload string

82 pid = -- process ID of notifying server process

83 <db_handle>: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_wait(lua_State *L)

92 --//--

93

94

95 --[[--

96 db_list = -- database result being an empty list

97 <db_handle>:create_list()

98

99 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".

100

101 --]]--

102 -- implemented in mondelefant_native.c as

103 -- static int mondelefant_conn_create_list(lua_State *L)

104 --//--

105

106

107 --[[--

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

109 <db_handle>:create_object()

110

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

112

113 --]]--

114 -- implemented in mondelefant_native.c as

115 -- static int mondelefant_conn_create_object(lua_State *L)

116 --//--

117

118

119 --[[--

120 quoted_encoded_string = -- encoded and quoted string

121 <db_handle>:quote_string(

122 unencoded_string -- string to encode and quote

123 )

124

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

126

127 --]]--

128 -- implemented in mondelefant_native.c as

129 -- static int mondelefant_conn_quote_string(lua_State *L)

130 --//--

131

132

133 --[[--

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

135 <db_handle>:quote_string(

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

137 )

138

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

140

141 --]]--

142 -- implemented in mondelefant_native.c as

143 -- static int mondelefant_conn_quote_binary(lua_State *L)

144 --//--

145

146

147 --[[--

148 sql_string =

149 <db_handle>:assemble_command{

150 template, -- template string

151 arg1, -- value to be inserted

152 arg2, -- another value to be inserted

153 key1 = named_arg3, -- named value

154 key2 = named_arg4, -- another named value

155 ...

156 }

157

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

159

160 TODO: documentation of input-converters

161

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

163

164 --]]--

165 -- implemented in mondelefant_native.c as

166 -- static int mondelefant_conn_assemble_command(lua_State *L)

167 --//--

168

169

170 --[[--

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

172 result1, -- result of first command

173 result2, -- result of second command

174 ... =

175 <db_handle>:try_query(

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

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

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

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

180 ..

181 )

182

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

184

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

186

187 --]]--

188 -- implemented in mondelefant_native.c as

189 -- static int mondelefant_conn_try_query(lua_State *L)

190 --//--

191

192

193 --[[--

194 <db_error>:escalate()

195

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

197

198 --]]--

199 -- implemented in mondelefant_native.c as

200 -- static int mondelefant_errorobject_escalate(lua_State *L)

201 --//--

202

203

204 --[[--

205 bool = -- true or false

206 <db_error>:is_kind_of(

207 error_code -- error code as used by this library

208 )

209

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

211

212 Example:

213 db_error:is_kind_of("IntegrityConstraintViolation")

214

215 --]]--

216 -- implemented in mondelefant_native.c as

217 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)

218 --//--

219

220

221 --[[--

222 result1, -- result of first command

223 result2, -- result of second command

224 ... =

225 <db_handle>:query(

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

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

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

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

230 ..

231 )

232

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

234

235 --]]--

236 -- implemented in mondelefant_native.c as

237 -- static int mondelefant_conn_query(lua_State *L)

238 --//--

239

240

241 --[[--

242 db_list_or_object = -- first argument is returned

243 mondelefant.set_class(

244 db_list_or_object, -- database result list or object

245 db_class -- database class (model)

246 )

247

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

249

250 --]]--

251 -- implemented in mondelefant_native.c as

252 -- static int mondelefant_set_class(lua_State *L)

253 --//--

254

255

256 --[[--

257 db_class = -- new database class (model)

258 mondelefant.new_class()

259

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

261

262 --]]--

263 -- implemented in mondelefant_native.c as

264 -- static int mondelefant_new_class(lua_State *L)

265 --//--

266

267

268 --[[--

269 reference_data = -- table with reference information

270 <db_class>:get_reference(

271 name -- reference name

272 )

273

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

275

276 --]]--

277 -- implemented in mondelefant_native.c as

278 -- static int mondelefant_class_get_reference(lua_State *L)

279 --//--

280

281

282 --[[--

283 reference_name = -- reference name

284 <db_class>:get_foreign_key_reference_name(

285 foreign_key -- foreign key

286 )

287

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

289

290 --]]--

291 -- implemented in mondelefant_native.c as

292 -- static int mondelefant_class_get_reference(lua_State *L)

293 --//--

294