Lua scripting API

This is the reference for the objects available to Lua scripts. The API centres on two classes — sqlitedatabase, which represents a connection to a database, and sqlitequery, which runs SQL and exposes its result set — together with helper functions such as displaydata(). For complete, runnable examples, see Scripting examples.

The sqlitedatabase class

sqlitedatabase:new() 

Creates and returns a new instance of a sqlitedatabase object. 

sqlitedatabase:filename([filename]) 

Sets or retrieves the value of the filename associated with the database object. The filename must point to an existing SQLite3 database, or :memory: for opening an in- memory database. 

sqlitedatabase:connected([value]) 

When called with an argument, connects or disconnects the database to the filename set by sqlitedatabase:filename(). Returns true if connected to the database. 

sqlitedatabase:open() 

Connects to the database. Similar to sqlitedatabase:connected(true) except it does not return a value. 

sqlitedatabase:close() 

Similar to sqlitedatabase:connected(false) except it does not return a value. 

sqlitedatabase:execute(sql) 

Executes an SQL statement in the current database. 

sqlitedatabase:begintransaction() 

Starts a transaction. 

sqlitedatabase:commit() 

Commits the current transaction. 

sqlitedatabase:rollback() 

Rolls back the current transaction. 

sqlitedatabase:intransaction() 

Returns true if a transaction is active, and false otherwise. 

sqlitedatabase:free() 

Destroys the object and frees its associated memory. 

The sqlitequery class

sqlitequery represents a dataset with a result set that is based on an SQL statement.

sqlitequery:new() 

Creates and returns a new instance of a sqlitequery object. 

sqlitequery:database([sqlitedatabase]) 

When called with an argument, it binds the query with the sqlitedatabase object. Returns the associated sqlitedatabase object. 

sqlitequery:active([value]) 

When called with a boolean argument: opens or closes the query depending on whether value is true or false. Returns true if active, false if not. 

sqlitequery:open() 

Opens the query by executing the SQL statement. Similar to sqlitequery:active(true). If the SQL statement returns a cursor the following functions can be used to iterate through the result set: first, last, next, prior, eof, bof. 

sqlitequery:close() 

Closes the query. 

sqlitequery:eof() 

Test eof (end of file) to determine if the dataset is positioned at the last record. 

sqlitequery:bof() 

Test bof (beginning of file) to determine if the dataset is positioned at the first record. 

sqlitequery:``first()

Moves to the first record in the dataset.

sqlitequery:last() 

Moves to the last record in the dataset. 

sqlitequery:next() 

Moves to the next record in the dataset. 

sqlitequery:prior() 

Moves to the previous record in the dataset. 

sqlitequery:edit() 

Enables editing of data in the dataset. 

sqlitequery:post() 

Writes the modified record to the database. 

sqlitequery:insert() 

Inserts a new, empty record in the dataset. 

sqlitequery:``delete()

Deletes the active record and positions the dataset on the next record.

sqlitequery:cancel() 

Cancels modifications to the active record if those changes are not yet posted. 

sqlitequery:recordcount() 

Indicates the total number of records associated with the dataset. Note: the value returned by this function is only valid after reaching the last record in the dataset. 

sqlitequery:recno() 

Indicates the active record in the dataset. 

sqlitequery:fieldcount() 

Indicates the number of field components associated with the dataset. 

sqlitequery:getfield([value]) 

Finds a field based on its name (if value is a string) or its index (if value is an integer number). Returns a sqlitefield object, or null if the field was not found. 

sqlitequery:sql([value]) 

Sets or retrieves the text of the SQL statement to execute for the query. 

sqlitequery:free() 

Destroys the object and frees its associated memory. 

The sqlitefield class

sqlitefield:name() 

Returns the name of the field. 

sqlitefield:value([value]) 

Sets or retrieves the value of the field in the current record, as string. To set the value of the field, the dataset must be in the Edit mode, set by a previous call to Insert or Edit. 

sqlitefield:asstring([value]) 

Same as sqlitefield:value([value]): sets or retrieves the value of the field in the current record, as string. To set the value of the field, the dataset must be in the Edit mode, set by a previous call to Insert or Edit. 

sqlitefield:asfloat([value]) 

Sets or retrieves the value of the field in the current record, as a floating point number. To set the value of the field, the dataset must be in the Edit mode, set by a previous call to Insert or Edit. 

sqlitefield:asboolean([value]) 

Sets or retrieves the value of the field in the current record, as a boolean value. To set the value of the field, the dataset must be in the Edit mode, set by a previous call to Insert or Edit. 

sqlitefield:fullsqltype() 

Returns the full declared type of the field including sqltype, size and precision. 

sqlitefield:sqltype() 

Returns the field declared type. 

sqlitefield:size() 

Returns the field size. 

sqlitefield:precision() 

Returns the field precision.

Output functions

print(...)

Writes its arguments to the Output tab, separated by tabs, followed by a newline. Every argument is converted with tostring, so values of any type can be printed directly:

print("rows:", 42)        --> rows:<tab>42
print(nil, true)          --> nil<tab>true

io.write(...)

Writes its arguments to the Output tab with no separator and no trailing newline. Use it to build a line from several pieces:

io.write("total: ")
io.write(42)
io.write("\n")

Changed in 6.0. print now follows standard Lua: it separates arguments with tabs and terminates the line. Earlier versions did neither, which is why older scripts often end a print with an explicit "\n" argument — for example print(name, "\n"). Those scripts still run, but now produce an extra blank line; drop the "\n" argument, or switch the call to io.write. Earlier versions also rendered non-string values as an internal type and address rather than as nil, true or table: ....