361 lines
11 KiB
HTML
361 lines
11 KiB
HTML
<html>
|
|
<!$Id: manual.html,v 1.11 2003/07/23 18:26:26 tomas Exp $>
|
|
|
|
<head>
|
|
<style type="text/css">
|
|
ul { list-style-type: disc };
|
|
</style>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
<hr>
|
|
|
|
<center>
|
|
<table border=0 cellspacing=2 cellpadding=2>
|
|
<tr><td align=center><a href="http://www.lua.org">
|
|
<img border=0 alt="The Lua language" src="lua.png"></a>
|
|
<tr><td align=center><big><b>LuaSQL Reference Manual</b></big>
|
|
<tr><td align=center valign=top>Database connectivity for the Lua language
|
|
</table>
|
|
</center>
|
|
<p>
|
|
|
|
<center><small>
|
|
<a href="index.html">home</a> ·
|
|
<a href="#environment_object">environment</a> ·
|
|
<a href="#connection_object">connection</a> ·
|
|
<a href="#cursor_object">cursor</a> ·
|
|
<a href="#postgres_extensions">extensions</a> ·
|
|
<a href="#examples">example</a>
|
|
</small></center>
|
|
<p>
|
|
|
|
<hr>
|
|
|
|
<a name="introduction"></a>
|
|
<h2>Introduction</h2>
|
|
<p>
|
|
LuaSQL is a simple interface from Lua to a DBMS.
|
|
It has a collection of drivers to some popular databases
|
|
(actually PostgreSQL, ODBC, MySQL and Oracle; ADO will be
|
|
ready soon).
|
|
LuaSQL defines a simple object-oriented API.
|
|
All drivers should implement this common API,
|
|
but each one is free to offer extensions.
|
|
<p>
|
|
LuaSQL defines one single global variable,
|
|
a table called <tt>luasql</tt>.
|
|
This table is used to store the initialization methods of the
|
|
loaded drivers.
|
|
This method is used to create an
|
|
<a href="#environment_object">environment object</a>
|
|
which is used to create a
|
|
<a href="#connection_object">connection object</a>.
|
|
A connection object can execute SQL statements and eventually
|
|
create a
|
|
<a href="#cursor_object">cursor object</a>
|
|
which is used to retrieve data.
|
|
<p>
|
|
Each LuaSQL driver is composed by two files:
|
|
a C source file that implements the driver functions;
|
|
and a Lua script used to load the dynamic library.
|
|
The host application can be statically linked with one or more drivers
|
|
or they can be loaded dynamically by the corresponding Lua script (this
|
|
requires the built-in <tt>loadlib</tt> function Lua 5 offers).
|
|
</p>
|
|
|
|
|
|
<a name="environment_object">
|
|
<h2>Environment objects</h2>
|
|
<p>
|
|
An environment object is created by calling the driver's initialization
|
|
function that is stored into the table <tt>luasql</tt> with the same
|
|
name of the driver (odbc, postgres etc.).
|
|
For example, <tt>luasql.odbc()</tt>, will try to create an environment
|
|
object using the ODBC driver.
|
|
</p>
|
|
|
|
<h4>Methods</h4>
|
|
|
|
<ul>
|
|
<a name="env_close"></a>
|
|
<li> <b><tt>env:close()</tt></b> <br>
|
|
Closes the environment <tt>env</tt>.
|
|
Only successful if all connections pertaining to it were closed first.
|
|
|
|
<a name="env_connect"></a>
|
|
<li> <b><tt>env:connect(sourcename[,username[,password]])</tt></b> <br>
|
|
Connects to a data source specified in <tt>sourcename</tt> using
|
|
<tt>username</tt> and <tt>password</tt> if they are supplied.<br>
|
|
See also: <a href="#postgres_extensions">PostgreSQL</a>,
|
|
and <a href="#mysql_extensions">MySQL</a> extensions.<br>
|
|
Returns: a <a href="#connection_object">connection object</a>.
|
|
|
|
</ul>
|
|
|
|
<a name="connection_object">
|
|
<h2>Connection objects</h2>
|
|
|
|
A connection object contains specific attributes and parameters of a single
|
|
data source connection.
|
|
A connection object is created by calling the
|
|
<tt><a href="#env_connect">environment:connect</a></tt>
|
|
method.
|
|
|
|
<h4>Methods</h4>
|
|
|
|
<ul>
|
|
<a name="conn_close"></a>
|
|
<li> <b><tt>conn:close()</tt></b> <br>
|
|
Closes the connection <tt>conn</tt>.
|
|
Only successful if all cursors pertaining to it were closed first.
|
|
|
|
<a name="conn_commit"></a>
|
|
<li> <b><tt>conn:commit()</tt></b> <br>
|
|
Commits the current transaction.
|
|
|
|
<a name="conn_execute"></a>
|
|
<li> <b><tt>conn:execute(statement)</tt></b> <br>
|
|
Executes the given SQL <tt>statement</tt>.<br>
|
|
Returns: a <a href="#cursor_object">cursor object</a>
|
|
if there are results, or the number of rows affected by the command otherwise.
|
|
|
|
<a name="conn_rollback"></a>
|
|
<li> <b><tt>conn:rollback()</tt></b> <br>
|
|
Rolls back the current transaction.
|
|
|
|
<a name="conn_setautocommit"></a>
|
|
<li> <b><tt>conn:setautocommit(boolean)</tt></b> <br>
|
|
Turns on or off the "auto commit" mode.
|
|
This feature might not work on database systems that don't implement
|
|
transactions.
|
|
<!--
|
|
Turning off the "auto commit" mode should begin a new transaction;
|
|
turning the mode on will roll back the current transaction.
|
|
-->
|
|
|
|
<!--
|
|
<li> <tt>TableList()</tt> <br>==> So' no ODBC <==
|
|
Retrieves a list of all the tables in the data source. <br>
|
|
Returns: a list of the table names.
|
|
</p>
|
|
-->
|
|
|
|
</ul>
|
|
|
|
|
|
<a name="cursor_object"></a>
|
|
<h2>Cursor objects</h2>
|
|
|
|
A cursor object contains methods to retrieve
|
|
data resulting from an executed statement.
|
|
A cursor object is created by using the
|
|
<tt><a href="#conn_execute">connection:execute</a></tt>
|
|
function.
|
|
See also <a href="#postgres_extensions">PostgreSQL</a>
|
|
and <a href="#mysql_extensions">MySQL</a> extensions.
|
|
|
|
<h4>Methods</h4>
|
|
|
|
<ul>
|
|
<a name="cur_close"></a>
|
|
<li> <b><tt>cur:close()</tt></b> <br>
|
|
Closes this cursor.
|
|
|
|
<a name="cur_fetch"></a>
|
|
<li> <b><tt>cur:fetch([table[,modestring]])</tt></b> <br>
|
|
Retrieves the next row of results.<br>
|
|
If <tt>fetch</tt> is called without parameters,
|
|
the results will be returned to the caller directly.
|
|
If <tt>fetch</tt> is called with a table, the results will be copied
|
|
into the table and this table will be returned (for convenience).
|
|
In this case, an optional <tt>mode</tt> parameter can be used.
|
|
It is just a string indicating how the result table should be made.
|
|
The mode string can contain:
|
|
<ul>
|
|
<li> <b>"n"</b> the resulting table will have numerical indices (default)
|
|
<li> <b>"a"</b> the resulting table will have alphanumerical indices
|
|
</ul>
|
|
The <i>numerical indices</i> are the positions of the fields in the select
|
|
statement;
|
|
the <i>alphanumerical indices</i> are the names of the fields.<br>
|
|
The optional <tt>table</tt> parameter is a table that should be
|
|
used to store the next row.
|
|
This allows the use of a unique table for many fetches which
|
|
can improve the overall performance.<br>
|
|
There is no guarantee about the types of the results
|
|
-- they can be converted to adequate Lua types by the driver or not.
|
|
<i>In the current implementation (2.0a),
|
|
the PostgreSQL and MySQL drivers returns all values as strings
|
|
while the ODBC and Oracle drivers converts them to Lua types</i>.<br>
|
|
Returns: data, as above, or <tt>nil</tt> if there are no more rows.
|
|
|
|
<a name="cur_colnames"></a>
|
|
<li> <b><tt>cur:getcolnames()</tt></b> <br>
|
|
Returns: a list of column names.
|
|
|
|
<a name="cur_coltypes"></a>
|
|
<li> <b><tt>cur:getcoltypes()</tt></b> <br>
|
|
Returns: a list of column types.
|
|
|
|
</ul>
|
|
|
|
|
|
<a name="postgres_extensions"></a>
|
|
<h2>PostgreSQL extensions</h2>
|
|
|
|
Besides the basic functionality
|
|
provided by all drivers (see manual), the Postgres driver also offers
|
|
these extra features:
|
|
|
|
<ul>
|
|
<li> <b><tt>env:connect(sourcename[,username[,password[,hostname[,port]]]])</tt></b> <br>
|
|
In the PostgreSQL driver, this method has two other optional parameters
|
|
that indicate the hostname and port to connect.
|
|
Also, the first parameter can contain all connection information,
|
|
as stated in the documentation for <tt>PQconnectdb</tt> function
|
|
in the PostgreSQL manual
|
|
(e.g. <small><tt>environment:connect("dbname=<<i>name</i>> user=<<i>username</i>>")</tt></small>) <br>
|
|
See also: <a href="#environment_object">environment objects</a>
|
|
<li> <b><tt>cur:numrows()</tt></b> <br>
|
|
This additional method returns the number of rows in the query result.<br>
|
|
See also: <a href="#cursor_object">cursor objects</a>
|
|
</ul>
|
|
|
|
|
|
<a name="mysql_extensions"></a>
|
|
<h2>MySQL extensions</h2>
|
|
|
|
Besides the basic functionality
|
|
provided by all drivers (see manual),
|
|
the MySQL driver also offers these extra features:
|
|
|
|
<ul>
|
|
<li> <b><tt>env:connect(sourcename[,username[,password[,hostname[,port]]]])</tt></b> <br>
|
|
In the MySQL driver, this method has two other optional parameters
|
|
that indicate the hostname and port to connect.
|
|
See also: <a href="#environment_object">environment objects</a>
|
|
<li> <b><tt>cur:numrows()</tt></b> <br>
|
|
This additional method returns the number of rows in the query result.<br>
|
|
See also: <a href="#cursor_object">cursor objects</a>
|
|
</ul>
|
|
|
|
Note: This driver is compatible to version 4.1 of MySQL API,
|
|
with support to BDB and INNODB tables.
|
|
MySQL has types of tables that don't support transactions,
|
|
so with these types, the methods <tt>setautocommit</tt>, <tt>commit</tt>
|
|
and <tt>rollback</tt> don't work.
|
|
|
|
|
|
<a name="examples"></a>
|
|
<h2>Example</h2>
|
|
|
|
Below is a small sample code displaying the basic use of the library.
|
|
|
|
<blockquote>
|
|
<pre>
|
|
-- load driver
|
|
require"postgres"
|
|
-- create environment object
|
|
env = assert (luasql.postgres())
|
|
-- connect to data source
|
|
con = assert (env:connect("luasql-test"))
|
|
-- reset our table
|
|
res = con:execute"DROP TABLE people"
|
|
res = assert (con:execute[[
|
|
CREATE TABLE people(
|
|
name varchar(50),
|
|
email varchar(50)
|
|
)
|
|
]])
|
|
-- add a few elements
|
|
list = {
|
|
{ name="Jose das Couves", email="jose@couves.com", },
|
|
{ name="Manoel Joaquim", email="manoel.joaquim@cafundo.com", },
|
|
{ name="Maria das Dores", email="maria@dores.com", },
|
|
}
|
|
for i, p in pairs (list) do
|
|
res = assert (con:execute(string.format([[
|
|
INSERT INTO people
|
|
VALUES ('%s', '%s')]], p.name, p.email)
|
|
))
|
|
end
|
|
-- retrieve a cursor
|
|
cur = assert (con:execute"SELECT name, email from people")
|
|
-- print all rows
|
|
row = cur:fetch ({}, "a") -- the rows will be indexed by field names
|
|
while row do
|
|
print(string.format("Name: %s, E-mail: %s", row.name, row.email))
|
|
row = cur:fetch (row, "a") -- reusing the table of results
|
|
end
|
|
-- close everything
|
|
cur:close()
|
|
con:close()
|
|
env:close()
|
|
</pre>
|
|
</blockquote>
|
|
|
|
And the output of this script should be:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
Name: Jose das Couves, E-mail: jose@couves.com
|
|
Name: Manoel Joaquim, E-mail: manoel.joaquim@cafundo.com
|
|
Name: Maria das Dores, E-mail: maria@dores.com
|
|
</pre>
|
|
</blockquote>
|
|
|
|
|
|
<a name="contents"></a>
|
|
<h2>Contents</h2>
|
|
<p>
|
|
<ul>
|
|
<li> <a href="#introduction">Introduction</a>
|
|
<li> <a href="#environment_object">Environment objects</a>
|
|
<ul>
|
|
<li> <a href="#env_close">close</a>
|
|
<li> <a href="#env_connect">connect</a>
|
|
</ul>
|
|
<li> <a href="#connection_object">Connection object</a>
|
|
<ul>
|
|
<li> <a href="#conn_close">close</a>
|
|
<li> <a href="#conn_commit">commit</a>
|
|
<li> <a href="#conn_execute">execute</a>
|
|
<li> <a href="#conn_rollback">rollback</a>
|
|
<li> <a href="#conn_setautocommit">setautocommit</a>
|
|
</ul>
|
|
<li> <a href="#cursor_object">Cursor objects</a>
|
|
<ul>
|
|
<li> <a href="#cur_close">close</a>
|
|
<li> <a href="#cur_fetch">fetch</a>
|
|
<li> <a href="#cur_colnames">getcolnames</a>
|
|
<li> <a href="#cur_coltypes">getcoltypes</a>
|
|
</ul>
|
|
<li> <a href="#postgres_extensions">PostgreSQL extensions</a>
|
|
<li> <a href="#mysql_extensions">MySQL extensions</a>
|
|
<li> <a href="#examples">Example</a>
|
|
</ul>
|
|
</p>
|
|
|
|
|
|
<p>
|
|
<center><small>
|
|
<a href="index.html">home</a> ·
|
|
<a href="#environment_object">environment</a> ·
|
|
<a href="#connection_object">connection</a> ·
|
|
<a href="#cursor_object">cursor</a> ·
|
|
<a href="#postgres_extensions">extensions</a> ·
|
|
<a href="#examples">example</a>
|
|
</small></center>
|
|
<p>
|
|
|
|
<hr>
|
|
<small>
|
|
Last modified on
|
|
Wed Jul 23 17:43:57 BRT 2003
|
|
</small>
|
|
|
|
</body>
|
|
</html>
|