NAME
sqlite —
access SQLite3 files from
Lua
SYNOPSIS
local sqlite = require 'sqlite'
err =
sqlite.initialize()
-
sqlite.shutdown()
-
db, err =
sqlite.open(file [, flags])
-
version =
sqlite.libversion()
-
version =
sqlite.libversion_number()
-
id =
sqlite.sourceid()
-
err =
sqlite.close(db)
-
stmt, err =
sqlite.prepare(db, sql)
-
err =
sqlite.exec(db, sql)
-
err =
sqlite.errcode(db)
-
msg =
sqlite.errmsg(db)
-
res =
sqlite.get_autocommit(db)
-
res =
sqlite.changes(db)
-
err =
sqlite.bind(stmt, pidx, value)
-
count =
sqlite.bind_parameter_count(stmt)
-
pidx =
sqlite.bind_parameter_index(stmt, name)
-
name =
sqlite.bind_parameter_name(stmt, pidx)
-
err =
sqlite.step(stmt)
-
value =
sqlite.column(stmt, cidx)
-
sqlite.reset(stmt)
-
sqlite.clear_bindings(stmt)
-
sqlite.finalize(stmt)
-
name =
sqlite.column_name(stmt, cidx)
-
count =
sqlite.column_count(stmt)
-
DESCRIPTION
The
sqlite Lua binding provides access to SQLite3 files.
GENERAL FUNCTIONS
err =
sqlite.initialize()
- Initialize the SQLite3 library. Workstation applications
using SQLite normally do not need to invoke this function.
sqlite.shutdown()
- Deallocate any resources that were allocated by
sqlite.initialize(). Workstation applications using
SQLite normally do not need to invoke this function.
db, err =
sqlite.open(file [, flags])
- Open a database, optionally passing flags. When called
without flags, the database will be opened for reading and writing and it
will be created if it does not yet exist. The following flags are defined:
sqlite.OPEN_READONLY
- The database is opened in read-only mode. If the
database does not already exist, an error is returned.
sqlite.OPEN_READWRITE
- The database is opened for reading and writing if
possible, or reading only if the file is write protected by the
operating system. In either case the database must already exist,
otherwise an error is returned.
sqlite.OPEN_CREATE
- The database is opened for reading and writing, and is
created if it does not already exist.
version =
sqlite.libversion()
- Return the SQLite3 library version number as a string.
version =
sqlite.libversion_number()
- Return the SQLite3 library version number as a number.
id =
sqlite.sourceid()
- Return the SQLite3 library source id as a string.
DATABASE FUNCTIONS
Database functions operate on database objects returned by
sqlite.open().
err =
sqlite.close(db)
- Close an open database. Like with all remaining database
functions, this function can also be called using the Lua
"colon" syntactic sugar as db:close().
stmt, err =
sqlite.prepare(db, sql)
- Return a prepared statement.
err =
sqlite.exec(db, sql)
- Directly execute an SQL statement. Be careful when creating
SQL on the fly (SQL injection attacks).
err =
sqlite.errcode(db)
- Return the numeric error code.
msg =
sqlite.errmsg(db)
- Return the error message as a string.
res =
sqlite.get_autocommit(db)
- Return the autocommit flag.
res =
sqlite.changes(db)
- This function returns the number of database rows that were
changed or inserted or deleted by the most recently completed SQL
statement on the database.
STATEMENT FUNCTIONS
err =
sqlite.bind(stmt, pidx, value)
- Bind value to the parameter
pidx in the prepared statement
stmt.
count =
sqlite.bind_parameter_count(stmt)
- Return the number of parameters in the prepared statement
stmt.
pidx =
sqlite.bind_parameter_index(stmt, name)
- Return the parameter index for name
in the prepared statement stmt.
name =
sqlite.bind_parameter_name(stmt, pidx)
- Return the parameter name for the parameter index
pidx in the prepared statement
stmt.
err =
sqlite.step(stmt)
- Execute prepared statement stmt.
value =
sqlite.column(stmt, cidx)
- Return the value at column cidx in
the prepared statement stmt.
sqlite.reset(stmt)
- The sqlite.reset() function is called to
reset a prepared statement object back to its initial state, ready to be
re-executed.
sqlite.clear_bindings(stmt)
- Contrary to the intuition of many,
sqlite.reset() does not reset the bindings on a prepared
statement. Use this routine to reset all host parameters to
NULL
.
sqlite.finalize(stmt)
- The sqlite.finalize() function is called
to delete a prepared statement.
name =
sqlite.column_name(stmt, cidx)
- Return the name assigned to a particular column in the
result set of a SELECT statement.
count =
sqlite.column_count(stmt)
- Return the number of columns in the result set returned by
the prepared statement stmt. This routine returns 0
if stmt is an SQL statement that does not return
data (for example an UPDATE).
ERROR CODES
Most functions return an error code, the following error codes are defined:
sqlite.OK
- Successful result.
sqlite.ERROR
- SQL error or missing database.
sqlite.INTERNAL
- Internal logic error in SQLite.
sqlite.PERM
- Access permission denied.
sqlite.ABORT
- Callback routine requested an abort.
sqlite.BUSY
- The database file is locked.
sqlite.LOCKED
- A table in the database is locked.
sqlite.NOMEM
- Out of memory.
sqlite.READONLY
- Attempt to write a readonly database.
sqlite.INTERRUPT
- Operation terminated by
sqlite3_interrupt().
sqlite.IOERR
- Some kind of disk I/O error occurred.
sqlite.CORRUPT
- The database disk image is malformed.
sqlite.NOTFOUND
- Unknown opcode in sqlite3_file_control().
sqlite.FULL
- Insertion failed because database is full.
sqlite.CANTOPEN
- Unable to open the database file.
sqlite.PROTOCOL
- Database lock protocol error.
sqlite.EMPTY
- Database is empty.
sqlite.SCHEMA
- The database schema changed.
sqlite.TOOBIG
- String or BLOB exceeds size limit.
sqlite.CONSTRAINT
- Abort due to constraint violation.
sqlite.MISMATCH
- Data type mismatch.
sqlite.MISUSE
- Library used incorrectly.
sqlite.NOLFS
- Uses OS features not supported on host.
sqlite.AUTH
- Authorization denied.
sqlite.FORMAT
- Auxiliary database format error.
sqlite.RANGE
- 2nd parameter to sqlite.bind() out of
range.
sqlite.NOTADB
- File opened that is not a database file.
sqlite.ROW
- sqlite.step() has another row ready.
sqlite.DONE
- sqlite.step() has finished
executing.
SEE ALSO
lua(1),
luac(1),
sqlite3(1),
intro(3lua)
HISTORY
An
sqlite manual appeared in
NetBSD
7.0.
AUTHORS
The
sqlite Lua binding was written by
Marc
Balmer
<
mbalmer@NetBSD.org>.