400 lines
19 KiB
HTML
400 lines
19 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html>
|
|
<head>
|
|
<title>LuaSQL: Conectividade de banco de dados para a linguagem de programação Lua</title>
|
|
<link rel="stylesheet" href="doc.css" type="text/css"/>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
|
|
</head>
|
|
|
|
<body>
|
|
<div id="container">
|
|
|
|
<div id="product">
|
|
<div id="product_logo"><a href="http://www.keplerproject.org">
|
|
<img alt="LuaSQL logo" src="luasql.png"/>
|
|
</a></div>
|
|
<div id="product_name"><big><strong>LuaSQL</strong></big></div>
|
|
<div id="product_description">Conectividade de banco de dados para a linguagem de programação Lua</div>
|
|
</div> <!-- id="product" -->
|
|
|
|
<div id="main">
|
|
|
|
<div id="navigation">
|
|
<h1>LuaSQL</h1>
|
|
<ul>
|
|
<li><a href="index.html">Home</a>
|
|
<ul>
|
|
<li><a href="index.html#overview">Visão Geral</a></li>
|
|
<li><a href="index.html#status">Status</a></li>
|
|
<li><a href="index.html#download">Download</a></li>
|
|
<li><a href="index.html#credits">Créditos</a></li>
|
|
<li><a href="index.html#contact">Contato</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Manual</strong>
|
|
<ul>
|
|
<li><a href="manual.html#introduction">Introdução</a></li>
|
|
<li><a href="manual.html#compiling">Compilando</a></li>
|
|
<li><a href="manual.html#installation">Instalação</a></li>
|
|
<li><a href="manual.html#errors">Tratamento de erros</a></li>
|
|
<li><a href="manual.html#drivers">Drivers</a></li>
|
|
<li><a href="manual.html#environment_object">Ambiente</a></li>
|
|
<li><a href="manual.html#connection_object">Conexão</a></li>
|
|
<li><a href="manual.html#cursor_object">Cursor</a></li>
|
|
<li><a href="manual.html#postgres_extensions">PostgreSQL</a></li>
|
|
<li><a href="manual.html#mysql_extensions">MySQL</a></li>
|
|
<li><a href="manual.html#oracle_extensions">Oracle</a></li>
|
|
<li><a href="manual.html#sqlite3_extensions">SQLite3</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="examples.html">Exemplos</a></li>
|
|
<li><a href="history.html">Histórico</a></li>
|
|
<li><a href="http://github.com/keplerproject/luasql">Projeto</a>
|
|
<ul>
|
|
<li><a href="http://github.com/keplerproject/luasql/issues">Bug Tracker</a></li>
|
|
|
|
</ul>
|
|
</li>
|
|
<li><a href="license.html">Licença</a></li>
|
|
</ul>
|
|
</div> <!-- id="navigation" -->
|
|
|
|
<div id="content">
|
|
|
|
<h2><a name="introduction"></a>Introdução</h2>
|
|
<p>LuaSQL é uma interface simples entre Lua e diversos sistemas gerenciadores de bancos de dados (DBMS) populares
|
|
(atualmente PostgreSQL, ODBC, JDBC, MySQL, SQLite, Oracle e ADO; Interbase e Sybase estão nos nossos planos).
|
|
LuaSQL define uma API orientada a objetos. Todos os drivers devem implementar essa API comum,
|
|
mas cada um é livre para oferecer extensões.</p>
|
|
|
|
<p>LuaSQL define uma única variável global: uma tabela chamada <code>luasql</code>.
|
|
Essa tabela é usada para armazenar os métodos de inicialização dos drivers instalados.
|
|
Esses métodos são usados para criar um
|
|
<a href="#environment_object">ambiente</a>,
|
|
o qual é usado para criar uma
|
|
<a href="#connection_object">conexão</a>.
|
|
A conexão pode executar comandos SQL e, eventualmente, criar um
|
|
<a href="#cursor_object">cursor</a>, utilizado para recuperar dados.</p>
|
|
|
|
<p>LuaSQL é um software livre e usa a mesma <a href="license.html">licença</a> do Lua 5.0.</p>
|
|
|
|
<h2><a name="compiling"></a>Compilando</h2>
|
|
|
|
<p>LuaSQL é distribuído como um conjunto de arquivos fonte C –
|
|
um arquivo fonte e um arquivo cabeçalho comuns a todos os drivers
|
|
(<code>luasql.h</code> e <code>luasql.c</code>) – e um arquivo fonte para cada driver.
|
|
Cada driver deve ser compilado juntamente com o arquivo <code>luasql.c</code>
|
|
para gerar uma biblioteca. Essa biblioteca pode ser linkada à aplicação
|
|
ou carregada dinamicamente. A função de inicialização é
|
|
<code>luaopen_luasql<em>nomedriver</em></code> e é compatível com o formato
|
|
<a href="http://www.lua.org/manual/5.1/manual.html#pdf-require"><code>open-library</code></a> de Lua.</p>
|
|
|
|
<h2><a name="installation"></a>Instalação</h2>
|
|
|
|
<p>Todos os drivers LuaSQL seguem a
|
|
<a href="http://www.keplerproject.org/compat">proposta de pacotes</a>
|
|
para Lua 5.1. Logo, esse pacote deve ser "instalado". Consulte a seção de
|
|
<a href="http://www.keplerproject.org/compat/manual.html#configuration">
|
|
configuração do Compat-5.1</a> para saber como instalar os pacotes binários
|
|
da maneira correta.
|
|
As bibliotecas compiladas devem ser instaladas em um diretório chamado
|
|
<code>luasql</code> no seu LUA_CPATH.</p>
|
|
|
|
<p>Para usar LuaSQL com o JDBC, certifique-se que:</p>
|
|
<ul>
|
|
<li> Lua está rodando com <a href="http://www.keplerproject.org/luajava/">LuaJava</a></li>
|
|
<li> O jar do LuaSQL está na classpath da máquina virtual do Java</li>
|
|
<li> O driver JDBC do banco de dados desejado também está na classpath
|
|
da máquina virtual</li>
|
|
</ul>
|
|
|
|
<p>Para usar LuaSQL com ADO, certifique-se que Lua está rodando com
|
|
<a href="http://www.tecgraf.puc-rio.br/~rcerq/luacom">LuaCOM 1.3</a></p>
|
|
|
|
<h2><a name="errors"></a>Tratamento de erros</h2>
|
|
|
|
<p>LuaSQL é apenas uma camada abstrata de comunicação entre Lua
|
|
e um sistema de banco de dados. Portanto, erros podem ocorrem em ambos os níveis:
|
|
no cliente do banco de dados ou no driver LuaSQL.</p>
|
|
|
|
<p>Erros como comandos SQL mal formados, nomes de tabela desconhecidos etc., chamados
|
|
<em>erros de banco de dados</em>, serão reportados pelo retorno de <code>nil</code>
|
|
pela função/método, seguido de uma mensagem de erro enviada pelo
|
|
sistema de banco de dados. Erros como parâmetros inválidos, ausência
|
|
de conexão, objetos inválidos etc., chamados <em>erros de API</em>,
|
|
são usualmente erros de programação e geram erros Lua.</p>
|
|
|
|
<p>Esse comportamento vale para todas as funções/métodos descritos
|
|
neste documento, a menos que seja especificado de outra forma.</p>
|
|
|
|
<h2><a name="drivers"></a>Drivers</h2>
|
|
|
|
<p>
|
|
Um driver LuaSQL permite o uso da API LuaSQL com um determinado banco de dados. Para usar
|
|
um driver, este deve ser carregado na tabela <code>luasql</code>. O exemplo abaixo
|
|
</p>
|
|
|
|
<pre class="example">
|
|
require "luasql.odbc"
|
|
</pre>
|
|
|
|
<p>
|
|
carrega o driver ODBC na tabela <code>luasql</code>. Note que pode-se ter mais de um driver
|
|
carregado usando-se algo como:
|
|
</p>
|
|
|
|
<pre class="example">
|
|
require "luasql.odbc"
|
|
require "luasql.oci8"
|
|
</pre>
|
|
|
|
<p>
|
|
Este exemplo também mostra que o nome do driver nem sempre corresponde ao
|
|
nome do banco de dados, mas sim ao nome do driver no sistema de arquivos. Dado que
|
|
o driver Oracle se refere à API OCI8, ele recebe o nome de <code>oci8</code>
|
|
ao invés de <code>oracle</code>.
|
|
</p>
|
|
|
|
<p>
|
|
Alguns drivers, tais como o MySQL, tem bibliotecas para versões diferentes
|
|
do banco de dados MySQL mas utilizam o mesmo nome de arquivo (<code>mysql</code>).
|
|
Neste caso não é possível carregar mais de uma versão
|
|
do driver MySQL na tabela <code>luasql</code>.
|
|
</p>
|
|
|
|
<h2><a name="environment_object"></a>Ambiente</h2>
|
|
|
|
<p>Um ambiente é criado chamando a função de inicialização
|
|
do driver que está armazenada na tabela <code>luasql</code> com o mesmo nome do driver
|
|
(odbc, postgres etc). Por exemplo,</p>
|
|
|
|
<pre class="example">
|
|
env = luasql.odbc()
|
|
</pre>
|
|
|
|
<p>tentará criar um ambiente usando o driver ODBC. A única exceção
|
|
é o driver JDBC, que precisa saber que driver interno utilizar.
|
|
Logo, quando se cria um ambiente, deve-se passar o nome da classe do driver como primeiro
|
|
parâmetro para a função <code>luasql.jdbc</code>. Por exemplo:</p>
|
|
|
|
<pre class="example">
|
|
env = luasql.jdbc ("com.mysql.jdbc.Driver")
|
|
</pre>
|
|
|
|
<h4>Métodos</h4>
|
|
|
|
<dl class="reference">
|
|
<dt><a name="env_close"></a><strong><code>env:close()</code></strong></dt>
|
|
<dd>Fecha o ambiente <code>env</code>. Só é bem sucedido se todas as suas
|
|
conexões já tiverem sido fechadas anteriormente.<br/>
|
|
Retorna: <code>true</code>, em caso de sucesso; <code>false</code>, quando o ambiente
|
|
já estiver fechado.
|
|
</dd>
|
|
|
|
<dt><a name="env_connect"></a><strong><code>env:connect(sourcename[,username[,password]])</code></strong></dt>
|
|
<dd>Conecta à fonte de dados especificada em <code>sourcename</code> usando
|
|
<code>username</code> e <code>password</code> se eles são fornecidos.<br/>
|
|
O <code>sourcename</code> pode variar de acordo com cada driver.
|
|
Alguns usam simplesmente o nome do banco de dados, como PostgreSQL, MySQL e SQLite;
|
|
o driver ODBC recebe o nome de DSN; o driver Oracle recebe o nome do serviço; e
|
|
o driver JDBC recebe um comando como
|
|
<code>"jdbc:<database system>://<database name>"</code>, o qual é
|
|
específico para cada driver.<br/>
|
|
Veja também: <a href="#postgres_extensions">PostgreSQL</a> e
|
|
<a href="#mysql_extensions">MySQL</a>.<br/>
|
|
Retorna: uma <a href="#connection_object">conexão</a>.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
<h2><a name="connection_object"></a>Conexão</h2>
|
|
|
|
<p>Uma conexão contém atributos e parâmetros específicos de uma
|
|
única conexão de base de dados. Uma conexão é criada chamando
|
|
o método <code><a href="#env_connect">environment:connect</a></code>.</p>
|
|
|
|
<h4>Métodos</h4>
|
|
|
|
<dl class="reference">
|
|
<dt><a name="conn_close"></a><strong><code>conn:close()</code></strong></dt>
|
|
<dd>Fecha a conexão <code>conn</code>. Só é bem sucedido se todos
|
|
os seus cursores tiverem sido fechados anteriormente e se a conexão ainda estiver aberta.<br/>
|
|
Retorna: <code>true</code>, em caso de sucesso; <code>false</code> em caso de fracasso.
|
|
</dd>
|
|
|
|
<dt><a name="conn_commit"></a><strong><code>conn:commit()</code></strong></dt>
|
|
<dd>Efetua a transação corrente. Esse atributo pode não funcionar
|
|
em sistemas de banco de dados que não implementam transações.<br/>
|
|
Retorna: <code>true</code>, em caso de sucesso; <code>false</code>, quando
|
|
a operação não pode ser realizada ou não está implementada.
|
|
</dd>
|
|
|
|
<dt><a name="conn_execute"></a><strong><code>conn:execute(statement)</code></strong></dt>
|
|
<dd>Executa o <code>statement</code> SQL dado.<br/>
|
|
Retorna: o <a href="#cursor_object">cursor</a>, se houver resultados, ou o número
|
|
de registros alterados pelo comando.
|
|
</dd>
|
|
|
|
<dt><a name="conn_rollback"></a><strong><code>conn:rollback()</code></strong></dt>
|
|
<dd>Desfaz a transação corrente. Esse atributo pode não funcionar
|
|
em sistemas de banco de dados que não implementam transações.<br/>
|
|
Retorna: <code>true</code>, em caso de sucesso; <code>false</code>, quando
|
|
a operação não pode ser realizada ou não está implementada.
|
|
</dd>
|
|
|
|
<dt><a name="conn_setautocommit"></a><strong><code>conn:setautocommit(boolean)</code></strong></dt>
|
|
<dd>Ativa ou desativa o modo "auto commit". Esse atributo pode não funcionar em sistemas
|
|
de banco de dados que não implementam transações. Em sistemas de banco
|
|
de dados que não trabalham com o conceito de "modo auto commit", mas que implementam
|
|
transações, esse mecanismo é implementado pelo driver.<br/>
|
|
Retorna: <code>true</code>, em caso de sucesso; <code>false</code>, quando
|
|
a operação não pode ser realizada ou não está implementada.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
<h2><a name="cursor_object"></a>Cursores</h2>
|
|
|
|
<p>Um cursor contém métodos para recuperar dados resultantes de um comando executado.
|
|
Um cursor é criado por meio de uma função
|
|
<code><a href="#conn_execute">connection:execute</a></code>.
|
|
Veja também: <a href="#postgres_extensions">PostgreSQL</a>
|
|
e <a href="#oracle_extensions">Oracle</a>.</p>
|
|
|
|
<h4>Métodos</h4>
|
|
|
|
<dl class="reference">
|
|
<dt><a name="cur_close"></a><strong><code>cur:close()</code></strong></dt>
|
|
<dd>Fecha esse cursor.<br/>
|
|
Retorna: <code>true</code>, em caso de sucesso; <code>false</code>, quando o cursor
|
|
já está fechado.
|
|
</dd>
|
|
|
|
<dt><a name="cur_fetch"></a><strong><code>cur:fetch([table[,modestring]])</code></strong></dt>
|
|
<dd>Recupera o próximo registro do resultado.<br/>
|
|
Se <code>fetch</code> é chamado sem parâmetros, os resultados
|
|
consistem em uma lista de valores. Se <code>fetch</code> é
|
|
chamado com uma tabela, os resultados são copiados para a tabela e a tabela
|
|
é retornada. Neste caso, pode ser usado um
|
|
parâmetro opcional de modo (<code>modestring</code>): uma seqüência
|
|
de caracteres indicando como deve ser construída a tabela de resultados.
|
|
A seqüência de caracteres do modo pode conter:
|
|
<dl>
|
|
<dt><strong>"n"</strong></dt><dd>a tabela resultante terá índices numéricos (padrão)</dd>
|
|
<dt><strong>"a"</strong></dt><dd>a tabela resultante terá índices alfanuméricos</dd>
|
|
</dl>
|
|
<br/>
|
|
Os <em>índices numéricos</em> representam as posições dos
|
|
campos no comando SELECT; os <em>índices alfanuméricos</em> representam
|
|
os nomes dos campos.<br/>
|
|
A tabela opcional (<code>table</code>) será usada para armazenar o próximo
|
|
registro. Isso permite o uso de uma única tabela para várias chamadas, o que
|
|
pode melhorar o desempenho geral.<br/>
|
|
Não existe garantia sobre os tipos dos resultados: eles podem ou não ser convertidos pelo driver
|
|
para os tipos Lua adequados. Na implementação atual, os drivers PostgreSQL e MySQL
|
|
retornam todos os valores como strings, enquanto os drivers ODBC e Oracle convertem esses valores
|
|
em tipos Lua.<br/>
|
|
Retorna: dados, como descrito acima, ou <code>nil</code> se não existem mais registros.
|
|
Note que esse método pode retornar <code>nil</code> como um resultado válido.
|
|
</dd>
|
|
|
|
<dt><a name="cur_colnames"></a><strong><code>cur:getcolnames()</code></strong></dt>
|
|
<dd>Retorna: uma tabela com os nomes das colunas.
|
|
</dd>
|
|
|
|
<dt><a name="cur_coltypes"></a><strong><code>cur:getcoltypes()</code></strong></dt>
|
|
<dd>Retorna: uma tabela com os tipos das colunas.
|
|
</dd>
|
|
</dl>
|
|
|
|
<p><a name="extensions"></a></p>
|
|
|
|
<h2><a name="postgres_extensions"></a>PostgreSQL</h2>
|
|
|
|
<p>Além das funcionalidades básicas oferecidas por todos os drivers,
|
|
o driver Postgres oferece as seguintes funcionalidades adicionais:</p>
|
|
|
|
<dl class="reference">
|
|
<dt><strong><code>env:connect(sourcename[,username[,password[,hostname[,port]]]])</code></strong></dt>
|
|
<dd>No driver PostgreSQL este método tem mais dois parâmetros opcionais que indicam
|
|
o <code>hostname</code> e a <code>port</code> a serem utilizados na conexão.
|
|
Além disso, o primeiro parâmetro também pode conter todas as informações
|
|
de conexão, como é dito na documentação
|
|
para a função <code>PQconnectdb</code> no manual do PostgreSQL
|
|
(ex. <small><code>environment:connect("dbname=<<em>name</em>> user=<<em>username</em>>")</code></small>)<br/>
|
|
Veja também: <a href="#environment_object">ambiente</a><br/>
|
|
Retorna: uma <a href="#connection_object">conexão</a>
|
|
</dd>
|
|
|
|
<dt><strong><code>cur:numrows()</code></strong></dt>
|
|
<dd>Veja também: <a href="#cursor_object">cursores</a><br/>
|
|
Retorna: o número de registros no resultado da busca.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
<h2><a name="mysql_extensions"></a>MySQL</h2>
|
|
|
|
<p>Além das funcionalidades básicas oferecidas por todos os drivers,
|
|
o driver MySQL ainda oferece as seguintes funcionalidades adicionais:</p>
|
|
|
|
<dl class="reference">
|
|
<dt><strong><code>env:connect(sourcename[,username[,password[,hostname[,port]]]])</code></strong></dt>
|
|
<dd>No driver MySQL, esse método tem mais dois parâmetros opcionais que indicam o
|
|
<code>hostname</code> e a <code>port</code> a serem utilizados na conexão.
|
|
Veja também: <a href="#environment_object">ambiente</a><br/>
|
|
Retorna: uma <a href="#connection_object">conexão</a>
|
|
</dd>
|
|
|
|
<dt><strong><code>cur:numrows()</code></strong></dt>
|
|
<dd>Veja também: <a href="#cursor_object">cursores</a><br/>
|
|
Retorna: o número de registros no resultado da busca.
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>Nota: Este driver é compatível com as versões 4.0, 4.1 e 5.0 da
|
|
API MySQL. Apenas as versões a partir de 4.1 oferecem suporte para transações, através de tabelas
|
|
BDB ou INNODB. Com a versão 4.0 ou sem um desses tipos de tabelas, os métodos
|
|
<code>commit</code>, <code>rollback</code> e <code>setautocommit</code> não funcionam.</p>
|
|
|
|
<h2><a name="oracle_extensions"></a>Oracle</h2>
|
|
|
|
<p>Além das funcionalidades básicas oferecidas por todos os drivers,
|
|
o driver Oracle ainda oferece uma funcionalidade adicional:</p>
|
|
|
|
<dl class="reference">
|
|
<dt><strong><code>cur:numrows()</code></strong></dt>
|
|
<dd>Veja também: <a href="#cursor_object">cursores</a><br/>
|
|
Retorna: o número de registros no resultado da pesquisa.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h2><a name="sqlite3_extensions"></a>SQLite3</h2>
|
|
|
|
<p>Além das funcionalidades básicas oferecidas por todos os drivers,
|
|
o driver para SQLite3 ainda oferece uma funcionalidade adicional:</p>
|
|
|
|
<dt><strong><code>env:connect(sourcename[,locktimeout])</code></strong></dt>
|
|
<dd>No driver para SQLite3, este método tem mais um parâmetro opcional que indica
|
|
a quantidade de milissegundos para esperar por uma trava de escrita no banco de dados, se ela não for obtida de imediato.<br/>
|
|
Veja também: <a href="#environment_object">ambiente</a><br/>
|
|
Retorna: uma <a href="#connection_object">conexão</a></dd>
|
|
|
|
|
|
</div> <!-- id="content" -->
|
|
|
|
</div> <!-- id="main" -->
|
|
|
|
<div id="about">
|
|
<p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
|
|
<p><small>
|
|
$Id: manual.html,v 1.11 2008/06/11 00:26:13 jasonsantos Exp $
|
|
</small></p>
|
|
</div> <!-- id="about" -->
|
|
|
|
</div> <!-- id="container" -->
|
|
|
|
</body>
|
|
</html>
|