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

19

20 --]]--

21 -- implemented in mondelefant_native.c as

22 -- static int mondelefant_connect(lua_State *L)

23 --//--

24

25

26 --[[--

27 <db_handle>:close()

28

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

30

31 --]]--

32 -- implemented in mondelefant_native.c as

33 -- static int mondelefant_conn_close(lua_State *L)

34 --//--

35

36

37 --[[--

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

39 <db_handle>:is_ok()

40

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

42

43 --]]--

44 -- implemented in mondelefant_native.c as

45 -- static int mondelefant_conn_is_ok(lua_State *L)

46 --//--

47

48

49 --[[--

50 status = -- status string

51 <db_handle>:get_transaction_status()

52

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

54 - idle

55 - active

56 - intrans

57 - inerror

58 - unknown

59

60 --]]--

61 -- implemented in mondelefant_native.c as

62 -- static int mondelefant_conn_get_transaction_status(lua_State *L)

63 --//--

64

65

66 --[[--

67 db_list = -- database result being an empty list

68 <db_handle>:create_list()

69

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

71

72 --]]--

73 -- implemented in mondelefant_native.c as

74 -- static int mondelefant_conn_create_list(lua_State *L)

75 --//--

76

77

78 --[[--

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

80 <db_handle>:create_object()

81

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

83

84 --]]--

85 -- implemented in mondelefant_native.c as

86 -- static int mondelefant_conn_create_object(lua_State *L)

87 --//--

88

89

90 --[[--

91 quoted_encoded_string = -- encoded and quoted string

92 <db_handle>:quote_string(

93 unencoded_string -- string to encode and quote

94 )

95

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

97

98 --]]--

99 -- implemented in mondelefant_native.c as

100 -- static int mondelefant_conn_quote_string(lua_State *L)

101 --//--

102

103

104 --[[--

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

106 <db_handle>:quote_string(

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

108 )

109

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

111

112 --]]--

113 -- implemented in mondelefant_native.c as

114 -- static int mondelefant_conn_quote_binary(lua_State *L)

115 --//--

116

117

118 --[[--

119 sql_string =

120 <db_handle>:assemble_command{

121 template, -- template string

122 arg1, -- value to be inserted

123 arg2, -- another value to be inserted

124 key1 = named_arg3, -- named value

125 key2 = named_arg4, -- another named value

126 ...

127 }

128

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

130

131 TODO: documentation of input-converters

132

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

134

135 --]]--

136 -- implemented in mondelefant_native.c as

137 -- static int mondelefant_conn_assemble_command(lua_State *L)

138 --//--

139

140

141 --[[--

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

143 result1, -- result of first command

144 result2, -- result of second command

145 ... =

146 <db_handle>:try_query(

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

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

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

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

151 ..

152 )

153

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

155

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

157

158 --]]--

159 -- implemented in mondelefant_native.c as

160 -- static int mondelefant_conn_try_query(lua_State *L)

161 --//--

162

163

164 --[[--

165 <db_error>:escalate()

166

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

168

169 --]]--

170 -- implemented in mondelefant_native.c as

171 -- static int mondelefant_errorobject_escalate(lua_State *L)

172 --//--

173

174

175 --[[--

176 bool = -- true or false

177 <db_error>:is_kind_of(

178 error_code -- error code as used by this library

179 )

180

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

182

183 Example:

184 db_error:is_kind_of("IntegrityConstraintViolation")

185

186 --]]--

187 -- implemented in mondelefant_native.c as

188 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)

189 --//--

190

191

192 --[[--

193 result1, -- result of first command

194 result2, -- result of second command

195 ... =

196 <db_handle>:query(

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

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

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

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

201 ..

202 )

203

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

205

206 --]]--

207 -- implemented in mondelefant_native.c as

208 -- static int mondelefant_conn_query(lua_State *L)

209 --//--

210

211

212 --[[--

213 db_list_or_object = -- first argument is returned

214 mondelefant.set_class(

215 db_list_or_object, -- database result list or object

216 db_class -- database class (model)

217 )

218

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

220

221 --]]--

222 -- implemented in mondelefant_native.c as

223 -- static int mondelefant_set_class(lua_State *L)

224 --//--

225

226

227 --[[--

228 db_class = -- new database class (model)

229 mondelefant.new_class()

230

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

232

233 --]]--

234 -- implemented in mondelefant_native.c as

235 -- static int mondelefant_new_class(lua_State *L)

236 --//--

237

238

239 --[[--

240 reference_data = -- table with reference information

241 <db_class>:get_reference(

242 name -- reference name

243 )

244

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

246

247 --]]--

248 -- implemented in mondelefant_native.c as

249 -- static int mondelefant_class_get_reference(lua_State *L)

250 --//--

251

252

253 --[[--

254 reference_name = -- reference name

255 <db_class>:get_foreign_key_reference_name(

256 foreign_key -- foreign key

257 )

258

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

260

261 --]]--

262 -- implemented in mondelefant_native.c as

263 -- static int mondelefant_class_get_reference(lua_State *L)

264 --//--

265