jbe@23: jbe@23: --[[-- jbe@23: db_handle, -- database handle, or nil in case of error jbe@23: errmsg, -- error message jbe@404: db_error = -- error object jbe@23: mondelefant.connect{ jbe@40: conninfo = conninfo, -- string passed directly to PostgreSQL's libpq jbe@23: host = host, -- hostname or directory with leading slash where Unix-domain socket resides jbe@23: hostaddr = hostaddr, -- IPv4, or IPv6 address if supported jbe@23: port = port, -- TCP port or socket file name extension jbe@23: dbname = dbname, -- name of database to connect with jbe@23: user = user, -- login name jbe@23: password = password, -- password jbe@23: connect_timeout = connect_timeout, -- seconds to wait for connection to be established. Zero or nil means infinite jbe@23: ... jbe@23: } jbe@23: jbe@403: 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. jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_connect(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@393: .fd -- file descriptor of underlaying database connection jbe@393: jbe@393: 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. jbe@393: jbe@393: --]]-- jbe@393: -- set/unset in mondelefant_native.c in jbe@393: -- static int mondelefant_connect(lua_State *L) and jbe@393: -- static int mondelefant_close(lua_State *L) jbe@393: --//-- jbe@393: jbe@393: jbe@393: --[[-- jbe@23: :close() jbe@23: jbe@23: Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected. jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_conn_close(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: status = -- true, if database connection has no malfunction jbe@23: :is_ok() jbe@23: jbe@23: Returns false, if the database connection has a malfunction, otherwise true. jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_conn_is_ok(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: status = -- status string jbe@23: :get_transaction_status() jbe@23: jbe@23: Depending on the transaction status of the connection a string is returned: jbe@23: - idle jbe@23: - active jbe@23: - intrans jbe@23: - inerror jbe@23: - unknown jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_conn_get_transaction_status(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@397: db_error, -- error object, or nil in case of success or timeout jbe@397: channel, -- notification channel name, or nil in case of timeout or no pending notify jbe@397: payload, -- notification payload string jbe@397: pid = -- process ID of notifying server process jbe@397: :try_wait( jbe@397: timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely jbe@393: ) jbe@393: jbe@393: Waits for any NOTIFY event that is being LISTENed for. One or more LISTEN commands must have been sent previously with :query("LISTEN channel_name"). jbe@393: jbe@393: --]]-- jbe@393: -- implemented in mondelefant_native.c as jbe@397: -- static int mondelefant_conn_try_wait(lua_State *L) jbe@393: --//-- jbe@393: jbe@393: jbe@393: --[[-- jbe@23: db_list = -- database result being an empty list jbe@23: :create_list() jbe@23: jbe@23: 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: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_conn_create_list(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: db_object = -- database result being an empty object (row) jbe@23: :create_object() jbe@23: jbe@23: 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: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_conn_create_object(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: quoted_encoded_string = -- encoded and quoted string jbe@23: :quote_string( jbe@23: unencoded_string -- string to encode and quote jbe@23: ) jbe@23: jbe@23: 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: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_conn_quote_string(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: quoted_encoded_data = -- encoded and quoted data (as Lua string) jbe@395: :quote_binary( jbe@23: raw_data -- data (as Lua string) to encode and quote jbe@23: ) jbe@23: jbe@23: Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent. jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_conn_quote_binary(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: sql_string = jbe@23: :assemble_command{ jbe@23: template, -- template string jbe@23: arg1, -- value to be inserted jbe@23: arg2, -- another value to be inserted jbe@23: key1 = named_arg3, -- named value jbe@23: key2 = named_arg4, -- another named value jbe@23: ... jbe@23: } jbe@23: jbe@23: 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: jbe@23: TODO: documentation of input-converters jbe@23: jbe@23: 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: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_conn_assemble_command(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: db_error, -- error object, or nil in case of success jbe@23: result1, -- result of first command jbe@23: result2, -- result of second command jbe@23: ... = jbe@23: :try_query( jbe@23: command1, -- first command (to be processed by "assemble_command" method) jbe@23: mode1, -- mode for first command: "list", "object" or "opt_object" jbe@23: command2, -- second command (to be processed by "assemble_command" method) jbe@23: mode2, -- mode for second command: "list", "object" or "opt_object" jbe@23: .. jbe@23: ) jbe@23: jbe@23: 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: jbe@23: The mode of the last command may be ommitted and default to "list". jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_conn_try_query(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: :escalate() jbe@23: jbe@397: Deprecated alias for error(). jbe@397: jbe@397: 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. jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_errorobject_escalate(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: bool = -- true or false jbe@23: :is_kind_of( jbe@23: error_code -- error code as used by this library jbe@23: ) jbe@23: jbe@23: Checks, if a given error is of a given kind. jbe@23: jbe@23: Example: jbe@23: db_error:is_kind_of("IntegrityConstraintViolation") jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_errorobject_is_kind_of(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@397: .code -- hierarchical error code (separated by dots) in camel case jbe@397: jbe@397: An error code in camel case notation with dots to separate hierarchy levels, e.g. "IntegrityConstraintViolation.UniqueViolation". See also :is_kind_of(...). jbe@397: jbe@397: --]]-- jbe@397: -- implemented in mondelefant_native.c as jbe@397: -- static const char *mondelefant_translate_errcode(const char *pgcode) jbe@397: --//-- jbe@397: jbe@397: jbe@397: --[[-- jbe@397: .message -- string which summarizes the error jbe@397: jbe@397: 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 object. Refer to the source code of the mondelefant_translate_errcode C function in mondelefant_native.c. jbe@397: jbe@397: --]]-- jbe@397: -- implemented in mondelefant_native.c jbe@397: --//-- jbe@397: jbe@397: jbe@397: --[[-- jbe@397: channel, -- notification channel name, or nil in case of timeout or no pending notify jbe@397: payload, -- notification payload string jbe@397: pid = -- process ID of notifying server process jbe@397: :wait( jbe@397: timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely jbe@397: ) jbe@397: jbe@397: Same as "try_wait" but raises an error, if a connection error occurred. Timeouts are reported by returning nil as first argument. jbe@397: jbe@397: --]]-- jbe@397: -- implemented in mondelefant_native.c as jbe@397: -- static int mondelefant_conn_wait(lua_State *L) jbe@397: --//-- jbe@397: jbe@397: jbe@397: --[[-- jbe@23: result1, -- result of first command jbe@23: result2, -- result of second command jbe@23: ... = jbe@23: :query( jbe@23: command1, -- first command (to be processed by "assemble_command" method) jbe@23: mode1, -- mode for first command: "list", "object" or "opt_object" jbe@23: command2, -- second command (to be processed by "assemble_command" method) jbe@23: mode2, -- mode for second command: "list", "object" or "opt_object" jbe@23: .. jbe@23: ) jbe@23: jbe@23: Same as "try_query" but raises error, when occurring. jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_conn_query(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: db_list_or_object = -- first argument is returned jbe@23: mondelefant.set_class( jbe@23: db_list_or_object, -- database result list or object jbe@23: db_class -- database class (model) jbe@23: ) jbe@23: jbe@23: 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: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_set_class(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: db_class = -- new database class (model) jbe@23: mondelefant.new_class() jbe@23: jbe@23: This function creates a new class (model) used for database result lists or objects. jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_new_class(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: reference_data = -- table with reference information jbe@23: :get_reference( jbe@23: name -- reference name jbe@23: ) jbe@23: jbe@272: This function performs a lookup for the given name in the "reference" table. Prototypes are used when lookup was unsuccessful. jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_class_get_reference(lua_State *L) jbe@23: --//-- jbe@23: jbe@23: jbe@23: --[[-- jbe@23: reference_name = -- reference name jbe@23: :get_foreign_key_reference_name( jbe@23: foreign_key -- foreign key jbe@23: ) jbe@23: jbe@272: This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used when lookup was unsuccessful. jbe@23: jbe@23: --]]-- jbe@23: -- implemented in mondelefant_native.c as jbe@23: -- static int mondelefant_class_get_reference(lua_State *L) jbe@23: --//-- jbe@23: jbe@416: jbe@416: --[[-- jbe@417: ._col -- proxy table mapping column names to their values jbe@416: jbe@417: This attribute can be used to access column values directly (helpful if :document_column is set). jbe@417: jbe@417: NOTE: Neither pairs(...) nor ipairs(...) are implemented on this proxy table. Use ._column_info instead. jbe@416: jbe@416: --]]-- jbe@416: -- implemented in mondelefant_native.c as jbe@416: -- static const struct luaL_Reg mondelefant_columns_mt_functions[] jbe@416: -- jbe@416: --//-- jbe@416: