Online Help
SQLite is an action plugin that makes use of the SQLite Embeddable SQL Database Engine to add high-performance database functionality to your application.
Note: The SQLite database engine is not a client used to connect to a big database server. It is the server. The SQLite database engine reads and writes directly to and from database files on disk.
Highlights of the SQLite Database Engine:
For more information on the SQLite database engine, see the SQLite website at www.sqlite.org.
Working with a SQLite database consists of three basic steps: opening a database, querying the database, and then closing the database once you're done with it.
The first step to working with a SQLite database is to open an existing database file (or create a new database file) using SQLite.Open():
db = SQLite.Open("sesame.db");
Note that SQLite.Open returns a database handle, which is needed for most other SQLite actions. Each handle uniquely identifies one open database, so you can use multiple handles to interact with several databases at the same time.
There are three basic methods you can use to perform a SQLite query on the database:
Use the SQLite.Query() action. This is the best method to use when executing query statements that don't return any results. For example:
SQLite.Query(db, "create table Users(userid integer primary key, LastName text, FirstName text, Age integer)");
If you need to process the query results, you can provide an optional callback function and it will be called once for every row in the result set. For example:
function myfunc(db, nRow, nColumns, tbRowDataAssoc, tbRowDataArray, tbColumnNamesArray, tbColumnTypesArray, tbColumnTypesAssoc) -- do something here end sql = "select * from users"; SQLite.Query(db, sql, myfunc);
Use the SQLite.QueryToTable() action, which returns the results of the query in a table. For example:
sql = "select * from users"; tbResults = SQLite.QueryToTable(db, sql); -- get the value in FirstName in row 1 of the result set first_name = tbResults.Data[1]["FirstName"];
Use the SQLite.Compile() action to compile the query into a "virtual machine" so you can step through query one row at a time. For example, your would first compile a query like this:
SQLite.Compile(db, "select * from users");
Once you have the query compiled, you can repeatedly call SQLite.Step() to process it:
repeat SQLite.Step(db); err = Application.GetLastError(); until err ~= SQLite.ROW
At each step, you can retrieve the current row of data by using one of the "GetRow..." actions:
tbRow = SQLite.GetRowDataAssoc(db); first_name = tbRow["FirstName"];
Once you're done with a compiled query, you must call SQLite.Finalize() to finalize it:
SQLite.Finalize(db);
When you're done with a database, you should call SQLite.Close() to close it.
SQLite.Close(db);
SQLite.Close
SQLite.Compile
SQLite.Finalize
SQLite.GetChanges
SQLite.GetEncoding
SQLite.GetErrorString
SQLite.GetLastErrorString
SQLite.GetLastInsertRowID
SQLite.GetNullString
SQLite.GetRowColumnNamesArray
SQLite.GetRowColumnTypesArray
SQLite.GetRowColumnTypesAssoc
SQLite.GetRowDataArray
SQLite.GetRowDataAssoc
SQLite.GetVersion
SQLite.Interrupt
SQLite.Open
SQLite.Query
SQLite.QueryToTable
SQLite.SetBusyTimeout
SQLite.SetNullString
SQLite.Step
Closes a SQLite database.
Note: This releases the database handle and reclaims any memory that the database was using.
(database) The handle to the database that you want to close.
Nothing.
-- Close the database SQLite.Close(db);
Compiles a query so it can be stepped through one row at a time using SQLite.Step.
(database) The handle to the database that you want to operate on.
(string) The SQLite query string that you want to perform. See the SQLite Query Language for more information.
(number) The length of the query string that was processed.
-- Compile a query in the database sql = "SELECT * FROM Users"; nLen = SQLite.Compile(db, sql); if nLen ~= len(sql) then Debug.Print("Posible error: length of compiled query doesn't match original query length"); end
Completes a compiled query and frees the associated memory.
(database) The handle to the database that you want to finalize.
Nothing.
-- Done with the compiled query SQLite.Finalize(db);
Returns the number of rows modified by the last query.
(database) The handle to the database that you want to operate on.
(number) The number of rows that were modified by the last query performed on the specified database.
-- how many changes were made? nChanges = SQLite.GetChanges(db);
Returns the character encoding that the SQLite database engine is using.
(string) The character encoding that the SQLite database engine is using (e.g. "iso8859").
-- get a string describing the current encoding method strEncoding = SQLite.GetEncoding();
Returns the error string that corresponds to a specific SQLite error code.
(number) A SQLite error code that you want to get the error message for.
Tip: Use nil or pass nothing to get the error message for the last internal error (exactly the same as calling SQLite.GetLastErrorString).
(string) The error string that corresponds to the specified error code.
-- what error message is associated with SQLite.CANTOPEN? strErrMsg = SQLite.GetErrorString(SQLite.CANTOPEN);
Returns the error string for the last internal error that occurred.
Tip: Use this to get the internal error message returned by sqlite on SQLite.ERROR.
(string) The error string for the last internal error.
err = Application.GetLastError(); if err == SQLite.ERROR then strErrMsg = SQLite.GetLastErrorString(); Debug.Print("Error: " .. strErrMsg); end
Returns the row ID of the most recent insert in the database.
Note: This action is similar to the mysql_insert_id() function in MySQL.
(database) The handle to the database that you want to operate on.
(number) The ID of the row that was modified by the last "insert" operation.
Note: Each entry in an SQLite table has a unique integer key. The key is the value of the INTEGER PRIMARY KEY column if there is such a column, otherwise the key is generated at random.
SQLite.Query(db,"insert into Users values('Sellers','Ted','Mr.')"); -- which row was modified? nRID = SQLite.GetLastInsertRowID(db);
Returns the string that will be used to represent NULL values in query results.
(string) The string that will be used to represent NULL values in query results.
-- get the current null string strNullValue = SQLite.GetNullString();
Returns the column names for the current row of data from a compiled query as a numerically indexed table.
(database) The handle to the database that you want to operate on.
(table) A numerically indexed table containing the column names for the current row of data.
-- get the column names tbColumnNames = SQLite.GetRowColumnNamesArray(db); -- display them in a debug window Debug.ShowWindow(true); for i = 1, Table.Count(tbColumnNames) do Debug.Print("Name of column "..i.." is: " .. tbColumnNames[i] .."\r\n"); end
Returns the column types for the current row of data from a compiled query as a numerically indexed table.
Note: The database must have a compiled query in it or a syntax error will be generated.
(database) The handle to the database that you want to operate on.
(table) A numerically indexed table containing the column types for the current row of data.
Note: This returns the types that were declared for the columns when they were created. Since SQLite is typeless, the actual values in the columns can be of any type. (The column type is not enforced.)
-- get the column types tbColumnNames = SQLite.GetRowColumnTypesArray(db); -- display them in a debug window Debug.ShowWindow(true); for i = 1, Table.Count(tbColumnTypes) do Debug.Print("Type of column "..i.." is: " .. tbColumnTypes[i] .."\r\n"); end
Returns the column types for the current row of data from a compiled query as an associative table indexed by column name.
Note: The database must have a compiled query in it or a syntax error will be generated.
(database) The handle to the database that you want to operate on.
(table) A table containing the column types for the current row of data, indexed by column name.
Note: This returns the types that were declared for the columns when they were created. Since SQLite is typeless, the actual values in the columns can be of any type. (The column type is not enforced.)
-- get the column types tbColumnNames = SQLite.GetRowColumnTypesAssoc(db); -- display them in a debug window Debug.ShowWindow(true); for strColumnName, strColumnType in pairs(tbColumnTypes) do Debug.Print("Type of column '"..strColumName.."' is: " .. strColumnType .."\r\n"); end
Returns the current row of data from a compiled query as a numerically indexed table.
Note: The database must have a compiled query in it or a syntax error will be generated.
(database) The handle to the database that you want to operate on.
(table) A numerically indexed table containing the current row of data in the compiled query.
-- get the data indexed by column # tbRow = SQLite.GetRowDataArray(db); -- display the values in a debug window Debug.ShowWindow(true); for i = 1, Table.Count(tbRow) do Debug.Print("Data in column "..i.." is: " .. tbRow[i] .."\r\n"); end
Returns the current row of data from a compiled query as an associative table indexed by column name.
Note: The database must have a compiled query in it or a syntax error will be generated.
(database) The handle to the database that you want to operate on.
(table) A table containing the current row of data in the compiled query, indexed by column name.
-- get the data indexed by column name tbRow = SQLite.GetRowDataAssoc(db); -- display the values in a debug window Debug.ShowWindow(true); for strColumn, strData in pairs(tbRow) do Debug.Print(strColumn .. " = " .. strData .. "\r\n"); end
Returns the version of the plugin's SQLite database engine.
(string) The version number of the SQLite database engine.
-- what version of the SQLite database does the plugin use? strVer = SQLite.GetVersion();
Aborts the query presently running in the database.
(database) The handle to the database that you want to operate on.
Nothing.
-- Aroooga! Aroooga! SQLite.Interrupt(db);
Opens a SQLite database. If the database does not exist, it is created.
(string) The full path and filename of the database file that you want to open. Use ":memory:" to open a temporary database that only exists in the computer's memory.
Note: The special ":memory:" filename is primarily useful for temporary processing, as the in-memory database will be destroyed when the database is closed.
(database) A handle to the database that you can use in other SQLite actions.
Note that you can open multiple databases at the same time. Each database connection is identified by a unique database handle.
-- open a database file in the user's temp folder handle = SQLite.Open(_TempFolder .. "\\MyDatabase.db");
-- open a database file in memory and create a 3-column table in it db = SQLite.Open(":memory:"); SQLite.Query(db,"CREATE TABLE Users(userid INTEGER PRIMARY KEY, LastName TEXT, FirstName TEXT, Age INTEGER)");
Performs a query on an SQLite database.
(database) The handle to the database that you want to operate on.
(string) The SQLite query string that you want to perform. See the SQLite Query Language for more information.
(function) The name of a function that will be called for every row returned from the query. (You can use this callback function to collect the results returned from the query.)
Note: The CallbackFunction is optional...if you don't need to process the results, you may set this parameter to nil (or omit it completely).
The callback function must be able to receive the following parameters:
(database) A handle to the database that is being operated on.
(number) The current row in the query result. (This number gets incremented each time the callback is called.)
(number) The number of columns in the query result.
(table) A table containing the row data indexed by column name.
If the EMPTY_RESULT_CALLBACKS pragma is on, and the query didn't return any results, tbRowDataAssoc will be nil.
(table) A table containing the row data indexed numerically.
If the EMPTY_RESULT_CALLBACKS pragma is on, and the query didn't return any results, tbRowDataArray will be nil.
(table) A table containing the column names indexed numerically.
(table) A table containing the column types indexed numerically.
If the SHOW_DATATYPES pragma is off, tbColumnTypesArray will be nil.
(table) A table containing the column types indexed by column name.
If the SHOW_DATATYPES pragma is off, tbColumnTypesAssoc will be nil.
Note: The SHOW_DATATYPES pragma is off by default.
The callback function should return a boolean value (true or false) indicating whether the query should continue:
true - Continue performing the query.
false - Abort the query.
Nothing.
-- open a temporary database in memory db = SQLite.Open(":memory:"); -- create a table with 3 columns SQLite.Query(db,"create table foo(a integer primary key, b text, c integer)");");
--[[ cbPrintRow function. Use this to print a row of data to the debug window (assumes the debug window is already open). ]] function cbPrintRow(db, nRow, nColumns, tbRowDataAssoc, tbRowDataArray, tbColumnNamesArray, tbColumnTypesArray, tbColumnTypesAssoc) Debug.Print("** ROW " .. nRow .. " IN RESULT SET HAS " .. nColumns .. " COLUMNS **\r\n"); --[[ note: always make sure tbRowDataAssoc, tbRowDataArray, tbColumnTypesArray, and tbColumnTypesAssoc are NOT nil before working with them. An easy way to do this is to test those variables to see if they contain something that is considered "true." Only the values nil and false are considered "false"...anything else (including a table) is considered true. ]] if tbRowDataAssoc then Debug.Print("\r\nRow ".. nRow .." data (associative style):\r\n"); for strColumnName, strData in pairs(tbRowDataAssoc) do nCol = 1; Debug.Print(strColumnName .. " = " .. strData); if nCol ~= nColumns then Debug.Print(", "); end end Debug.Print("\r\n"); end if tbRowDataArray then Debug.Print("\r\nRow ".. nRow .." data (array style):\r\n"); for nCol = 1,nColumns do Debug.Print(tbColumnNamesArray[nCol] .. " = " .. tbRowDataArray[nCol] ); if nCol ~= nColumns then Debug.Print(", "); end end Debug.Print("\r\n"); end if tbColumnTypesAssoc then Debug.Print("\r\nColumn types (associative style):\r\n\r\n"); for strColumnName, strColumnType in pairs(tbColumnTypesAssoc) do Debug.Print(strColumnName .. " type: " .. strColumnType .. "\r\n"); end end if tbColumnTypesArray then Debug.Print("\r\nColumn types (array style):\r\n\r\n"); for i, strColumnType in pairs(tbColumnTypesArray) do Debug.Print ("Column " .. i .. " type: " .. strColumnType .. "\r\n"); end end Debug.Print("\r\n"); -- continue with the query return true; end -- create a database in memory db = SQLite.Open(":memory:"); err = Application.GetLastError(); if err == SQLite.OK then -- create a table and fill it with data SQLite.Query(db,"create table Users(userid integer primary key, LastName text, FirstName text, Age integer)"); SQLite.Query(db,"insert into Users values(1,'Sellers','Ted',48)"); SQLite.Query(db,"insert into Users values(2,'Blow','Joe',64)"); SQLite.Query(db,"insert into Users values(NULL,'Dandy','Jim',31)"); SQLite.Query(db,"insert into Users values(NULL,'Osborne','Super Dave',47)"); SQLite.Query(db,"insert into Users values(NULL,'Hakimoto','Fuji',52)"); --[[ note: to keep this example from getting too complicated, we'll assume that the table can be created and filled with no errors. In practice, you should check for errors after each call to SQLite.Query. ]] -- open the debug window Debug.ShowWindow(true); -- turn on the SHOW_DATATYPES option in this database -- so the callback function will display the column types SQLite.Query(db,"PRAGMA SHOW_DATATYPES=ON;") -- Perform a query and use our callback function to print the results to the debug window SQLite.Query(db,"SELECT * FROM Users",cbPrintRow); err = Application.GetLastError(); if err ~= SQLite.OK then Debug.Print( "Error: " .. SQLite.GetErrorString(err) ); end -- close the database SQLite.Close(db); else -- error trying to open the database Debug.Print( "Error: " .. SQLite.GetErrorString(err) ); end
Performs a query on an SQLite database and returns a table containing the results.
(database) The handle to the database that you want to operate on.
(string) The SQLite query string that you want to perform. See the SQLite Query Language for more information.
(table) A table containing the query results. If an error occurs, this action returns nil.
If successful, the following information will be stored in the table:
Rows:
(number) The number of rows in the query result.
Columns:
(number) The number of columns in the query result.
ColumnNames:
(table) A numerically indexed table containing the names of the columns in the query result.
Use .ColumnNames[<column_number>] to get the name of a column:
column_three = tbResult.ColumnNames[3];
Data:
(table) A
table containing the data returned by the query. The data is organized
into sub-tables, one for each row in the query result. Each sub-table
contains the data from one row, indexed by column name.
Use .Data[<row_number>] to access a row of data:
tbRow2 = tbResult.Data[2];
Then use [<column_name>] to access a cell value:
strLastName = tbRow2["LastName"];
Or, use .Data[<row_number>][<column_name>] to access a cell value directly:
strLastName = tbResult.Data[2]["LastName"];
tbResult = SQLite.QueryToTable(mydb, "select * from players,teams where teamid=7;"); -- get the name of player 7: tbRow2 = tbResult.Data[2]; player_name = tbRow2["FirstName"] .. " " .. tbRow2["LastName"];
tbResult = SQLite.QueryToTable(mydb, "select * from players,teams where teamid=7;"); -- get the name of player 7: player_name = tbResult.Data[2]["FirstName"] .. " " .. tbResult.Data[2]["LastName"];
-- open the debug window Debug.ShowWindow(true); -- create a database in memory dbname = ":memory:"; db = SQLite.Open(dbname); err = Application.GetLastError(); if err == SQLite.OK then Debug.Print("Opening database: \"" .. dbname .. "\"\r\n\r\n"); -- create a table and fill it with data SQLite.Query(db,"create table Users(userid integer primary key, LastName text, FirstName text, Age integer)"); SQLite.Query(db,"insert into Users values(1,'Sellers','Ted',48)"); SQLite.Query(db,"insert into Users values(2,'Blow','Joe',64)"); SQLite.Query(db,"insert into Users values(NULL,'Dandy','Jim',31)"); SQLite.Query(db,"insert into Users values(NULL,'Osborne','Super Dave',47)"); SQLite.Query(db,"insert into Users values(NULL,'Hakimoto','Fuji',52)"); --[[ note: to keep this example from getting too complicated, we'll assume that the table can be created and filled with no errors. In practice, you should check for errors after each call to SQLite.Query. ]] -- perform a query and store all of the results in a table called tbUsers tbUsers = SQLite.QueryToTable(db,"SELECT * FROM Users"); err = Application.GetLastError(); if err ~= SQLite.OK then Debug.Print( "Error: " .. SQLite.GetErrorString(err) ); end -- display the contents of the table Debug.Print("Results returned from QueryToTable:\r\n\r\n"); Debug.Print(tbUsers.Columns .." Columns\r\n"); Debug.Print(tbUsers.Rows .." Rows\r\n\r\n"); for n = 1,tbUsers.Columns do Debug.Print("Name of column "..n.." is: "..tbUsers.ColumnNames[n].."\r\n"); end Debug.Print("\r\n\r\n"); for nRow = 1,tbUsers.Rows do Debug.Print("Row "..nRow..":\r\n\r\n"); Debug.Print(" User ID: "..tbUsers.Data[nRow]["userid"].."\r\n"); Debug.Print(" First name: "..tbUsers.Data[nRow]["FirstName"].."\r\n"); Debug.Print(" Last name: "..tbUsers.Data[nRow]["LastName"].."\r\n"); Debug.Print(" Age: "..tbUsers.Data[nRow]["Age"].."\r\n\r\n"); end for nRow = 1,tbUsers.Rows do Debug.Print("Row "..nRow..": "); for nCol = 1, tbUsers.Columns do strColumnName = tbUsers.ColumnNames[nCol]; Debug.Print(strColumnName .."="..tbUsers.Data[nRow][strColumnName]); if nCol ~= tbUsers.Columns then Debug.Print(", "); end end Debug.Print("\r\n"); end -- close the database Debug.Print("\r\nClosing database: \"" .. dbname .. "\"\r\n\r\n"); SQLite.Close(db) else -- error trying to open the database Debug.Print( "Error: " .. SQLite.GetErrorString(err) ); end
Sets the busy timeout for the database.
(database) The handle to the database that you want to operate on.
(number) The value you want to set the busy timeout to, in milliseconds.
Nothing.
-- Set busy timeout to 10 seconds SQLite.SetBusyTimeout(db, 10000);
Sets the string that will be used to represent NULL values in query results.
Note: The null string is set to "NULL" by default.
(number) The string that you want to use to represent NULL values in query results.
Nothing.
-- Set the null string to "Oh yeah, it's null!" SQLite.SetNullString("Oh yeah, it's null!");
Advances a compiled query to the next row.
After a query has been compiled using SQLite.Compile, it is actually performed by one or more calls to SQLite.Step. Each invocation of SQLite.Step, except the last one, returns a single row of the result. To access these results, use one of the following actions:
GetRowDataArray
GetRowDataAssoc
GetRowColumnNamesArray
GetRowColumnTypesArray
GetRowColumnTypesAssoc
You can use Application.GetLastError() immediately after calling SQLite.Step to determine what happened during that step. The resulting error code may be SQLite.BUSY, SQLite.ROW, SQLite.DONE, SQLite.ERROR, or SQLite.MISUSE.
Whenever another row of result data is available, the error code will be SQLite.ROW.
When all processing is complete, the error code will either be SQLite.DONE or SQLite.ERROR. SQLite.DONE indicates that the statement completed successfully and SQLite.ERROR indicates that there was a run-time error. It is incorrect to attempt calling SQLite.Step again after it has generated SQLite.DONE or SQLite.ERROR.
(database) The handle to the database that you want to operate on.
Note: The database must have a compiled query in it or a syntax error will be generated.
Nothing.
sql="select * from Users"; SQLite.Compile(db,sql); err = Application.GetLastError(); if (err ~= SQLite.OK ) then Debug.Print("Error (".. err .."): ".. SQLite.GetErrorString(err) .. "\r\n"); else Debug.ShowWindow(true); repeat SQLite.Step(db); err = Application.GetLastError(); if (err == SQLite.ROW) then tbRow=SQLite.GetRowDataAssoc(db) for strColumnName,strValue in pairs(tbRow) do Debug.Print(strColumnName.." = "..strValue.."\r\n"); end Debug.Print("----\r\n"); end until (err ~= SQLite.ROW) SQLite.Finalize(db) err = Application.GetLastError(); if (err ~= SQLite.OK ) then Debug.Print("Error (".. err .."): ".. SQLite.GetErrorString(err) .. "\r\n"); end end
0 | (SQLite.OK) | - | Successful result |
---|---|---|---|
30001 | (SQLite.ERROR) | - | SQL error or missing database |
30002 | (SQLite.INTERNAL) | - | An internal logic error in SQLite |
30003 | (SQLite.PERM) | - | Access permission denied |
30004 | (SQLite.ABORT) | - | Callback routine requested an abort |
30005 | (SQLite.BUSY) | - | The database file is locked |
30006 | (SQLite.LOCKED) | - | A table in the database is locked |
30007 | (SQLite.NOMEM) | - | A memory allocation failed |
30008 | (SQLite.READONLY) | - | Attempt to write a readonly database |
30009 | (SQLite.INTERRUPT) | - | Operation terminated by SQLite.Interrupt() |
30010 | (SQLite.IOERR) | - | Some kind of disk I/O error occurred |
30011 | (SQLite.CORRUPT) | - | The database disk image is malformed |
30012 | (SQLite.NOTFOUND) | - | (Internal Only) Table or record not found |
30013 | (SQLite.FULL) | - | Insertion failed because database is full |
30014 | (SQLite.CANTOPEN) | - | Unable to open the database file |
30015 | (SQLite.PROTOCOL) | - | Database lock protocol error |
30016 | (SQLite.EMPTY) | - | (Internal Only) Database table is empty |
30017 | (SQLite.SCHEMA) | - | The database schema changed |
30018 | (SQLite.TOOBIG) | - | Too much data for one row of a table |
30019 | (SQLite.CONSTRAINT) | - | Abort due to constraint violation |
30020 | (SQLite.MISMATCH) | - | Data type mismatch |
30021 | (SQLite.MISUSE) | - | Library used incorrectly |
30022 | (SQLite.NOLFS) | - | Uses OS features not supported on host |
30023 | (SQLite.AUTH) | - | Authorization denied |
30024 | (SQLite.FORMAT) | - | Auxiliary database format error |
30100 | (SQLite.ROW) | - | SQLite.Step() has another row ready |
30101 | (SQLite.DONE) | - | SQLite.Step() has finished executing |
30200 | (SQLite.UNCOMPILED) | - | Database does not have a compiled query in it |
Indigo Rose Corporation
support.indigorose.com
The SQLite Actions Plugin is copyright © 2003-2010 Indigo Rose Software Design Corporation.
Copyright © 2003-2010 Indigo Rose Software Design Corporation.
All Rights Reserved.