SQLITE(3lua)

SQLITE(3lua) | 3lua | SQLITE(3lua)

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

October 28, 2013 | NetBSD 7.0