keplerproject/luasql
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

alteracoes relativas a documentacao do JDBC.

Browse Source
This commit is contained in:
tuler 2004-11-17 16:58:40 +00:00
parent 180bf90ed4
commit aa4253aac7
2 changed files with 672 additions and 665 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

447
index.html
View File

@ -1,222 +1,225 @@
<! See Copyright Notice in license.html>
<html>
<head>
<title>LuaSQL: Database connectivity for the Lua programming language</title>
<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.keplerproject.org/luasql">
<img border=0 alt="LuaSQL logo" src="luasql.png"></a>
<tr><td align=center><big><b>LuaSQL</b></big>
<tr><td align=center valign=top>Database connectivity for the
<a href="http://www.lua.org">Lua</a>
programming language
</table>
</center>
<p>
<center><small>
<a href=#over>overview</a> &middot;
<a href=#version>current version</a> &middot;
<a href=#download>download</a> &middot;
<a href=#new>news</a> &middot;
<a href=#installation>installation</a> &middot;
<a href="manual.html">manual</a> &middot;
<a href="license.html">license</a> &middot;
<a href="#credits">credits</a> &middot;
<a href="#contact">contact us</a>
</small></center>
<p>
<hr>
<h2>Contents</h2>
<p>
<ul>
<li> <a href=#over>Overview</a>
<li> <a href=#version>Current Version</a>
<li> <a href=#download>Download</a>
<li> <a href=#new>What's new</a>
<li> <a href=#installation>Installation</a>
<li> <a href="manual.html">User's manual</a>
<ul>
<li> <a href="manual.html#introduction">Introduction</a>
<li> <a href="manual.html#environment_object">Environment objects</a>
<li> <a href="manual.html#connection_object">Connection objects</a>
<li> <a href="manual.html#cursor_object">Cursor objects</a>
<li> <a href="manual.html#postgres_extensions">PostgreSQL extensions</a>
<li> <a href="manual.html#mysql_extensions">MySQL extensions</a>
<li> <a href="manual.html#oracle_extensions">Oracle extensions</a>
<li> <a href="manual.html#examples">Examples</a>
</ul>
<li> <a href="license.html">Copyright & License</a>
<li> <a href="#credits">Credits</a>
<li> <a href="#contact">Contact us</a>
</ul>
</p>
<a name=over>
<h2>Overview</h2>
<p>
LuaSQL is a simple interface from Lua to a DBMS.
It enables a Lua program to:
<ul>
<li> Connect to ODBC, Oracle, MySQL, SQLite and PostgreSQL databases;
<li> Execute arbitrary SQL statements;
<li> Retrieve results in a row-by-row cursor fashion.
</ul>
LuaSQL is free software and uses the same
<a href="license.html">license</a>
as Lua 5.0.
<a name=version>
<h2>Current version</h2>
<p>
LuaSQL version 2.0 beta 2 (for Lua 5.0) is now available for
<a href="#download">download</a>!
The PostgreSQL driver
has been tested on Linux and MacOS X
and is compatible with PostgreSQL 7.x.
The ODBC driver has been tested on Windows
(SQLServer and Microsoft Access drivers).
The MySQL driver has been tested on Linux
and is compatible with versions 4.0 and 4.1.
The Oracle driver has been tested on Windows
and is compatible with OCI 8 API.
The SQLite driver had been tested on Linux
and are compatible with versions 2.x.
</p>
<a name=download>
<h2>Download</h2>
LuaSQL can be downloaded in source code from the following links: <p>
<blockquote>
<a href="luasql-2.0b2.tar.gz">luasql-2.0b2.tar.gz</a><br>
<a href="luasql-2.0b2.zip">luasql-2.0b2.zip</a>
</blockquote><p>
<a name=new>
<h2>What's new</h2>
<p>
<ul>
<li>[?/?/2004] Version 2.0 beta 2 released
<li>[10/dec/2003] Version 2.0 beta released
</ul>
<p>
Version 2.0 beta 2 has some bug fixes and the new SQLite drivers.
Also, it follows the
<a href="http://www.keplerproject.org/compat">package proposal</a>
for Lua 5.1
(see section <a href="#installation">Installation</a> for more details).
</p>
<p>
Version 2.0 has some design modifications and implementation improvements
<ul>
<li>New <tt>fetch</tt> method: more eficient and more flexible
<li>New <tt>setautocommit</tt> method
<li>Lua 5.0 and 5.1 compatible
<li>Dynamically loadable or statically linked
<li>New drivers for Oracle and MySQL databases
</ul>
</p>
<a name="installation"></a>
<h2>Installation</h2>
<p>
LuaSQL is distributed as a set of C source files:
a common source and header file (<tt>luasql.h</tt> and <tt>luasql.c</tt>);
and one source file for each driver.
Each driver should be compiled together with luasql.c file (it is so small
that we don't make another library of it) to generate a library.
This library could be linked to the application (the initialization
function is <tt>luaopen_luasql<i>drivername</i></tt> and it is a Lua
open-library compatible function)
or dynamically loaded.
<p>
All LuaSQL drivers follow the
<a href="http://www.keplerproject.org/compat">package proposal</a>
for Lua 5.1,
therefore this package should be "installed".
In other words,
if you are using Lua 5.0,
the files <tt>compat-5.1.c</tt> and <tt>compat-5.1.h</tt> must be used
in the compilation and the file <tt>compat-5.1.lua</tt> must be installed
in the <tt>LUA_PATH</tt>.
If you are using Lua 5.1,
nothing should be done.
<a name="credits">
<h2>Credits</h2>
<h4>LuaSQL 2.0</h4>
<p>
Version 2.0 was redesigned by Roberto Ierusalimschy, Andr&eacute; Carregal
and Tom&aacute;s Guisasola as part of the
<a href="http://www.keplerproject.org">Kepler Project</a>.
The implementation is compatible with Lua 5.0 and was coded by
Tom&aacute;s Guisasola, Eduardo Quint&atilde;o and Danilo Tuler,
with many invaluable contributions by Michael Roth, Tiago Dionisio,
and Leonardo Godinho.
<h4>LuaSQL 1.0</h4>
<p>
LuaSQL was designed by Pedro Miller Rabinovitch and Roberto
Ierusalimschy.
The first implementation was compatible with Lua 4.0a.
Many modifications were made but not distributed by Diego Nehab (ODBC),
Carlos Cassino, Tom&aacute;s Guisasola and Eduardo Quint&atilde;o (PostgreSQL).
<p>
LuaSQL development was sponsored by
<a href="http://www.fabricadigital.com.br">Fábrica Digital</a>.
<a name="contact"></a>
<h2>Contact us</h2>
<p>
For more information please
<a href="mailto:info-NO-SPAM-THANKS@keplerproject.org">contact us</a>.
Comments are welcome!
</p>
<p>
<center><small>
<a href=#over>overview</a> &middot;
<a href=#version>current version</a> &middot;
<a href=#download>download</a> &middot;
<a href=#new>what's new</a> &middot;
<a href=#installation>installation</a> &middot;
<a href="manual.html">manual</a> &middot;
<a href="license.html">license</a> &middot;
<a href="#credits">credits</a> &middot;
<a href="#contact">contact us</a>
</small></center>
<p>
<hr>
<small>
$Id: index.html,v 1.27 2004/11/16 18:01:41 tomas Exp $
</small>
</body>
</html>
<! See Copyright Notice in license.html>
<html>
<head>
<title>LuaSQL: Database connectivity for the Lua programming language</title>
<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.keplerproject.org/luasql">
<img border=0 alt="LuaSQL logo" src="luasql.png"></a>
<tr><td align=center><big><b>LuaSQL</b></big>
<tr><td align=center valign=top>Database connectivity for the
<a href="http://www.lua.org">Lua</a>
programming language
</table>
</center>
<p>
<center><small>
<a href=#over>overview</a> &middot;
<a href=#version>current version</a> &middot;
<a href=#download>download</a> &middot;
<a href=#new>news</a> &middot;
<a href=#installation>installation</a> &middot;
<a href="manual.html">manual</a> &middot;
<a href="license.html">license</a> &middot;
<a href="#credits">credits</a> &middot;
<a href="#contact">contact us</a>
</small></center>
<p>
<hr>
<h2>Contents</h2>
<p>
<ul>
<li> <a href=#over>Overview</a>
<li> <a href=#version>Current Version</a>
<li> <a href=#download>Download</a>
<li> <a href=#new>What's new</a>
<li> <a href=#installation>Installation</a>
<li> <a href="manual.html">User's manual</a>
<ul>
<li> <a href="manual.html#introduction">Introduction</a>
<li> <a href="manual.html#environment_object">Environment objects</a>
<li> <a href="manual.html#connection_object">Connection objects</a>
<li> <a href="manual.html#cursor_object">Cursor objects</a>
<li> <a href="manual.html#postgres_extensions">PostgreSQL extensions</a>
<li> <a href="manual.html#mysql_extensions">MySQL extensions</a>
<li> <a href="manual.html#oracle_extensions">Oracle extensions</a>
<li> <a href="manual.html#jdbc_extensions">JDBC extensions</a>
<li> <a href="manual.html#examples">Examples</a>
</ul>
<li> <a href="license.html">Copyright & License</a>
<li> <a href="#credits">Credits</a>
<li> <a href="#contact">Contact us</a>
</ul>
</p>
<a name=over>
<h2>Overview</h2>
<p>
LuaSQL is a simple interface from Lua to a DBMS.
It enables a Lua program to:
<ul>
<li> Connect to ODBC, Oracle, MySQL, SQLite, JDBC and PostgreSQL databases;
<li> Execute arbitrary SQL statements;
<li> Retrieve results in a row-by-row cursor fashion.
</ul>
LuaSQL is free software and uses the same
<a href="license.html">license</a>
as Lua 5.0.
<a name=version>
<h2>Current version</h2>
<p>
LuaSQL version 2.0 beta 2 (for Lua 5.0) is now available for
<a href="#download">download</a>.
The PostgreSQL driver
has been tested on Linux and MacOS X
and is compatible with PostgreSQL 7.x.
The ODBC driver has been tested on Windows
(SQLServer and Microsoft Access drivers).
The MySQL driver has been tested on Linux
and is compatible with versions 4.0 and 4.1.
The Oracle driver has been tested on Windows
and is compatible with OCI 8 API.
The SQLite driver had been tested on Linux
and are compatible with versions 2.x.
The JDBC driver has been tested with LuaJava
Beta 3 and JDK 1.4 (MySQL driver).
</p>
<a name=download>
<h2>Download</h2>
LuaSQL can be downloaded in source code from the following links: <p>
<blockquote>
<a href="luasql-2.0b2.tar.gz">luasql-2.0b2.tar.gz</a><br>
<a href="luasql-2.0b2.zip">luasql-2.0b2.zip</a>
</blockquote><p>
<a name=new>
<h2>What's new</h2>
<p>
<ul>
<li>[19/dec/2004] Version 2.0 beta 2 released
<li>[10/dec/2003] Version 2.0 beta released
</ul>
<p>
Version 2.0 beta 2 has some bug fixes and the new SQLite and JDBC drivers.
Also, it follows the
<a href="http://www.keplerproject.org/compat">package proposal</a>
for Lua 5.1
(see section <a href="#installation">Installation</a> for more details).
</p>
<p>
Version 2.0 has some design modifications and implementation improvements
<ul>
<li>New <tt>fetch</tt> method: more eficient and more flexible
<li>New <tt>setautocommit</tt> method
<li>Lua 5.0 and 5.1 compatible
<li>Dynamically loadable or statically linked
<li>New drivers for Oracle and MySQL databases
</ul>
</p>
<a name="installation"></a>
<h2>Installation</h2>
<p>
LuaSQL is distributed as a set of C source files:
a common source and header file (<tt>luasql.h</tt> and <tt>luasql.c</tt>);
and one source file for each driver.
Each driver should be compiled together with luasql.c file (it is so small
that we don't make another library of it) to generate a library.
This library could be linked to the application (the initialization
function is <tt>luaopen_luasql<i>drivername</i></tt> and it is a Lua
open-library compatible function)
or dynamically loaded.
<p>
All LuaSQL drivers follow the
<a href="http://www.keplerproject.org/compat">package proposal</a>
for Lua 5.1,
therefore this package should be "installed".
In other words,
if you are using Lua 5.0,
the files <tt>compat-5.1.c</tt> and <tt>compat-5.1.h</tt> must be used
in the compilation and the file <tt>compat-5.1.lua</tt> must be installed
in the <tt>LUA_PATH</tt>.
If you are using Lua 5.1,
nothing should be done.
<a name="credits">
<h2>Credits</h2>
<h4>LuaSQL 2.0</h4>
<p>
Version 2.0 was redesigned by Roberto Ierusalimschy, Andr&eacute; Carregal
and Tom&aacute;s Guisasola as part of the
<a href="http://www.keplerproject.org">Kepler Project</a>.
The implementation is compatible with Lua 5.0 and was coded by
Tom&aacute;s Guisasola, Eduardo Quint&atilde;o and Danilo Tuler,
with many invaluable contributions by Michael Roth, Tiago Dionisio,
and Leonardo Godinho.
<h4>LuaSQL 1.0</h4>
<p>
LuaSQL was designed by Pedro Miller Rabinovitch and Roberto
Ierusalimschy.
The first implementation was compatible with Lua 4.0a.
Many modifications were made but not distributed by Diego Nehab (ODBC),
Carlos Cassino, Tom&aacute;s Guisasola and Eduardo Quint&atilde;o (PostgreSQL).
<p>
LuaSQL development was sponsored by
<a href="http://www.fabricadigital.com.br">Fábrica Digital</a>.
<a name="contact"></a>
<h2>Contact us</h2>
<p>
For more information please
<a href="mailto:info-NO-SPAM-THANKS@keplerproject.org">contact us</a>.
Comments are welcome!
</p>
<p>
<center><small>
<a href=#over>overview</a> &middot;
<a href=#version>current version</a> &middot;
<a href=#download>download</a> &middot;
<a href=#new>what's new</a> &middot;
<a href=#installation>installation</a> &middot;
<a href="manual.html">manual</a> &middot;
<a href="license.html">license</a> &middot;
<a href="#credits">credits</a> &middot;
<a href="#contact">contact us</a>
</small></center>
<p>
<hr>
<small>
$Id: index.html,v 1.28 2004/11/17 16:58:40 tuler Exp $
</small>
</body>
</html>

890
manual.html
View File

@ -1,443 +1,447 @@
<! See Copyright Notice in license.html>
<html>
<head>
<title>LuaSQL: Database connectivity for the Lua programming language</title>
<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.keplerproject.org/luasql">
<img border=0 alt="LuaSQL logo" src="luasql.png"></a>
<tr><td align=center><big><b>LuaSQL Reference Manual</b></big>
<tr><td align=center valign=top>Database connectivity for the
<a href="http://www.lua.org">Lua</a>
programming language
</table>
</center>
<p>
<center><small>
<a href="index.html">home</a> &middot;
<a href="#environment_object">environment</a> &middot;
<a href="#connection_object">connection</a> &middot;
<a href="#cursor_object">cursor</a> &middot;
<a href="#extensions">extensions</a> &middot;
<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, SQLite and Oracle;
ADO, Interbase and Sybase are on our plans).
LuaSQL defines a simple object-oriented API.
All drivers should implement this common API,
but each one is free to offer extensions.
</p>
<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.
These methods are 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>
<p>
LuaSQL is free software and uses the same
<a href="license.html">license</a>
as Lua 5.0.
</p>
<a name="errors">
<h2>Errors</h2>
<p>
LuaSQL is just an abstraction layer that communicates between Lua
and a database system.
Therefore errors can occur on both levels, that is,
inside the database client or inside LuaSQL driver.
<p>
Errors like mal-formed SQL statement, unknown table name etc.
are called <em>database errors</em> and
will be reported by the function/method returning <tt>nil</tt> followed
by the error message provided by the database system.
Errors like wrong parameters, absent connection, invalid objects etc.,
called <em>API errors</em>,
are usually program errors hence will raise a Lua error.
</p>
<p>
This behavior will be followed by all functions/methods
described in this document unless otherwise stated.
</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,
<pre>
env = luasql.odbc()
</pre>
will try to create an environment
object using the ODBC driver.
</p>
<h3>JDBC driver</h3>
<p>
LuaSQL offers a way to use LuaSQL interface running over Java's JDBC.
In order to do that, make sure that:
<ul>
<li> Lua is running with
<a href="http://www.keplerproject.org/luajava">LuaJava</a>
<li> LuaSQL driver for JDBC is in the Java's virtual machine classpath
<li> JDBC driver is also in the virtual machine classpath
</ul>
JDBC must know which driver to use,
therefore when creating an environment,
the driver name must be passed as the first parameter of the method.
For example:
<pre>
env = luasql.jdbc ("com.mysql.jdbc.Driver")
</pre>
<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.<br>
Returns: <code>true</code> in case of success; <code>false</code> when
the object is already closed.
<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>
The <tt>sourcename</tt> may vary according to each driver.
Some use a simple database name, like PostgreSQL, MySQL and SQLite;
the ODBC driver expects the name of the DSN;
the oracle driver ...;
the JDBC driver expects a string like <tt>"jdbc:&lt;database system&gt;://&lt;database name&gt;"</tt>, which is specific for each driver.<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.<br>
Returns: <code>true</code> in case of success and <code>false</code> when
the object is already closed.
<a name="conn_commit"></a>
<li> <b><tt>conn:commit()</tt></b> <br>
Commits the current transaction.
This feature might not work on database systems that do not implement
transactions.<br>
Returns: <code>true</code> in case of success and <code>false</code> when
the operation could not be performed or when it is not implemented.
<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.
This feature might not work on database systems that do not implement
transactions.<br>
Returns: <code>true</code> in case of success and <code>false</code> when
the operation could not be performed or when it is not implemented.
<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 do not implement
transactions.
On database systems that do not have the concept of "auto commit mode",
but do implement transactions, this mechanism is implemented by the driver.
<br>
Returns: <code>true</code> in case of success and <code>false</code> when
the operation could not be performed or when it is not implemented.
</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="#oracle_extensions">Oracle</a> extensions.
<h4>Methods</h4>
<ul>
<a name="cur_close"></a>
<li> <b><tt>cur:close()</tt></b> <br>
Closes this cursor.<br>
Returns: <code>true</code> in case of success and <code>false</code> when
the object is already closed.
<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.0b),
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.
<em>Note that this method could return <code>nil</code> as a valid result.</em>
<a name="cur_colnames"></a>
<li> <b><tt>cur:getcolnames()</tt></b> <br>
Returns: a list (table) of column names.
<a name="cur_coltypes"></a>
<li> <b><tt>cur:getcoltypes()</tt></b> <br>
Returns: a list (table) of column types.
</ul>
<a name="extensions"></a>
<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=&lt;<i>name</i>&gt; user=&lt;<i>username</i>&gt;")</tt></small>) <br>
See also: <a href="#environment_object">environment objects</a><br>
Returns: a <a href="#connection_object">connection object</a>
<li> <b><tt>cur:numrows()</tt></b> <br>
See also: <a href="#cursor_object">cursor objects</a><br>
Returns: the number of rows in the query result.
</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><br>
Returns: a <a href="#connection_object">connection object</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.0 and 4.1 (alpha) of MySQL API.
Only version 4.1 provides support for transactions by using BDB or INNODB
tables.
Therefore, with version 4.0 or without one of these types of tables the
methods <code>commit</code>, <code>rollback</code> and
<code>setautocommit</code> would not work.
<a name="oracle_extensions"></a>
<h2>Oracle extensions</h2>
Besides the basic functionality
provided by all drivers (see manual), the Oracle driver also offers
this extra feature:
<ul>
<li> <b><tt>cur:numrows()</tt></b> <br>
See also: <a href="#cursor_object">cursor objects</a><br>
Returns: the number of rows in the query result.
</ul>
<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"luasql.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="#oracle_extensions">Oracle extensions</a>
<li> <a href="#examples">Example</a>
</ul>
</p>
<p>
<center><small>
<a href="index.html">home</a> &middot;
<a href="#environment_object">environment</a> &middot;
<a href="#connection_object">connection</a> &middot;
<a href="#cursor_object">cursor</a> &middot;
<a href="#extensions">extensions</a> &middot;
<a href="#examples">example</a>
</small></center>
<p>
<hr>
<small>
$Id: manual.html,v 1.23 2004/11/16 18:01:41 tomas Exp $
</small>
</body>
</html>
<! See Copyright Notice in license.html>
<html>
<head>
<title>LuaSQL: Database connectivity for the Lua programming language</title>
<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.keplerproject.org/luasql">
<img border=0 alt="LuaSQL logo" src="luasql.png"></a>
<tr><td align=center><big><b>LuaSQL Reference Manual</b></big>
<tr><td align=center valign=top>Database connectivity for the
<a href="http://www.lua.org">Lua</a>
programming language
</table>
</center>
<p>
<center><small>
<a href="index.html">home</a> &middot;
<a href="#environment_object">environment</a> &middot;
<a href="#connection_object">connection</a> &middot;
<a href="#cursor_object">cursor</a> &middot;
<a href="#extensions">extensions</a> &middot;
<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, JDBC, MySQL, SQLite and Oracle;
ADO, Interbase and Sybase are on our plans).
LuaSQL defines a simple object-oriented API.
All drivers should implement this common API,
but each one is free to offer extensions.
</p>
<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.
These methods are 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>
<p>
LuaSQL is free software and uses the same
<a href="license.html">license</a>
as Lua 5.0.
</p>
<a name="errors">
<h2>Errors</h2>
<p>
LuaSQL is just an abstraction layer that communicates between Lua
and a database system.
Therefore errors can occur on both levels, that is,
inside the database client or inside LuaSQL driver.
<p>
Errors like mal-formed SQL statement, unknown table name etc.
are called <em>database errors</em> and
will be reported by the function/method returning <tt>nil</tt> followed
by the error message provided by the database system.
Errors like wrong parameters, absent connection, invalid objects etc.,
called <em>API errors</em>,
are usually program errors hence will raise a Lua error.
</p>
<p>
This behavior will be followed by all functions/methods
described in this document unless otherwise stated.
</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,
<pre>
env = luasql.odbc()
</pre>
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.<br>
Returns: <code>true</code> in case of success; <code>false</code> when
the object is already closed.
<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>
The <tt>sourcename</tt> may vary according to each driver.
Some use a simple database name, like PostgreSQL, MySQL and SQLite;
the ODBC driver expects the name of the DSN;
the oracle driver ...;
the JDBC driver expects a string like <tt>"jdbc:&lt;database system&gt;://&lt;database name&gt;"</tt>, which is specific for each driver.<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.<br>
Returns: <code>true</code> in case of success and <code>false</code> when
the object is already closed.
<a name="conn_commit"></a>
<li> <b><tt>conn:commit()</tt></b> <br>
Commits the current transaction.
This feature might not work on database systems that do not implement
transactions.<br>
Returns: <code>true</code> in case of success and <code>false</code> when
the operation could not be performed or when it is not implemented.
<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.
This feature might not work on database systems that do not implement
transactions.<br>
Returns: <code>true</code> in case of success and <code>false</code> when
the operation could not be performed or when it is not implemented.
<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 do not implement
transactions.
On database systems that do not have the concept of "auto commit mode",
but do implement transactions, this mechanism is implemented by the driver.
<br>
Returns: <code>true</code> in case of success and <code>false</code> when
the operation could not be performed or when it is not implemented.
</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="#oracle_extensions">Oracle</a> extensions.
<h4>Methods</h4>
<ul>
<a name="cur_close"></a>
<li> <b><tt>cur:close()</tt></b> <br>
Closes this cursor.<br>
Returns: <code>true</code> in case of success and <code>false</code> when
the object is already closed.
<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.0b),
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.
<em>Note that this method could return <code>nil</code> as a valid result.</em>
<a name="cur_colnames"></a>
<li> <b><tt>cur:getcolnames()</tt></b> <br>
Returns: a list (table) of column names.
<a name="cur_coltypes"></a>
<li> <b><tt>cur:getcoltypes()</tt></b> <br>
Returns: a list (table) of column types.
</ul>
<a name="extensions"></a>
<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=&lt;<i>name</i>&gt; user=&lt;<i>username</i>&gt;")</tt></small>) <br>
See also: <a href="#environment_object">environment objects</a><br>
Returns: a <a href="#connection_object">connection object</a>
<li> <b><tt>cur:numrows()</tt></b> <br>
See also: <a href="#cursor_object">cursor objects</a><br>
Returns: the number of rows in the query result.
</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><br>
Returns: a <a href="#connection_object">connection object</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.0 and 4.1 (alpha) of MySQL API.
Only version 4.1 provides support for transactions by using BDB or INNODB
tables.
Therefore, with version 4.0 or without one of these types of tables the
methods <code>commit</code>, <code>rollback</code> and
<code>setautocommit</code> would not work.
<a name="oracle_extensions"></a>
<h2>Oracle extensions</h2>
Besides the basic functionality
provided by all drivers (see manual), the Oracle driver also offers
this extra feature:
<ul>
<li> <b><tt>cur:numrows()</tt></b> <br>
See also: <a href="#cursor_object">cursor objects</a><br>
Returns: the number of rows in the query result.
</ul>
<a name="jdbc_extensions"></a>
<h2>JDBC extensions</h2>
<p>
LuaSQL offers a way to use LuaSQL interface running over Java's JDBC.
In order to do that, make sure that:
<ul>
<li> Lua is running with <a href="http://www.keplerproject.org/luajava">LuaJava</a>
<li> LuaSQL driver for JDBC is in the Java's virtual machine classpath
<li> JDBC driver is also in the virtual machine classpath
</ul>
JDBC must know which driver to use, therefore when creating an environment,
the driver class name must be passed as the first parameter of the function
<code>luasql.jdbc</code>.
For example:
<code>
<pre>
env = luasql.jdbc ("com.mysql.jdbc.Driver")
</pre>
</code>
<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"luasql.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="#oracle_extensions">Oracle extensions</a>
<li> <a href="#jdbc_extensions">JDBC extensions</a>
<li> <a href="#examples">Example</a>
</ul>
</p>
<p>
<center><small>
<a href="index.html">home</a> &middot;
<a href="#environment_object">environment</a> &middot;
<a href="#connection_object">connection</a> &middot;
<a href="#cursor_object">cursor</a> &middot;
<a href="#extensions">extensions</a> &middot;
<a href="#examples">example</a>
</small></center>
<p>
<hr>
<small>
$Id: manual.html,v 1.24 2004/11/17 16:58:40 tuler Exp $
</small>
</body>
</html>