Documentation update
This commit is contained in:
carregal
parent
f41820b6c1
commit
5083b44b04
BIN
doc/br/luasql.png
Normal file
BIN
doc/br/luasql.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 7.5 KiB |
337
doc/br/manual.html
Normal file
337
doc/br/manual.html
Normal file
@ -0,0 +1,337 @@
|
||||
<!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="http://www.keplerproject.org/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><b>LuaSQL</b></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#history">História</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#installation">Instalação</a></li>
|
||||
<li><a href="manual.html#errors">Tratamento de erros</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>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="examples.html">Exemplos</a></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 um DBMS, que trabalha com uma
|
||||
coleção de drivers de bancos de dados populares: 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="installation"></a>Instalação</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
|
||||
(<tt>luasql.h</tt> e <tt>luasql.c</tt>) – e um arquivo fonte para cada driver.
|
||||
Cada driver deve ser compilado juntamente com o arquivo <code>luasql.c</code>
|
||||
(ele é tão pequeno que não fizemos outra biblioteca para ele)
|
||||
para gerar uma biblioteca. Essa biblioteca pode ser linkada à aplicação
|
||||
ou carregada dinamicamente. A função de inicialização é
|
||||
<tt>luaopen_luasql<i>drivername</i></tt> e é compatível com o formato de
|
||||
abertura de bibliotecas de Lua.</p>
|
||||
|
||||
<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".
|
||||
Em outras palavras, se você está usando Lua 5.0, é preciso usar os arquivos
|
||||
<tt>compat-5.1.c</tt> e <tt>compat-5.1.h</tt> na compilação
|
||||
e instalar o arquivo <tt>compat-5.1.lua</tt> no <tt>LUA_PATH</tt>.
|
||||
Se você está trabalhando com Lua 5.1, nada precisa ser feito.</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 do tipo comandos SQL mal formados, nome de tabela desconhecido etc., chamados
|
||||
<em>erros de banco de dados</em>, serão reportados pelo retorno de <code>nil</code>
|
||||
pela função/método, seguido pela mensagem de erro enviada pelo
|
||||
sistema do 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="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 ser informado sobre o driver interno que vai 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>
|
||||
|
||||
<ul>
|
||||
<li><a name="env_close"></a><b><code>env:close()</code></b><br/>
|
||||
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.
|
||||
</li>
|
||||
|
||||
<li><a name="env_connect"></a><b><code>env:connect(sourcename[,username[,password]])</code></b><br/>
|
||||
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 de 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>.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
<ul>
|
||||
<li><a name="conn_close"></a><b><code>conn:close()</code></b><br/>
|
||||
Fecha a conexão <code>conn</code>. Só é bem sucedido se todos
|
||||
os seus cursores tiverem sido fechados anteriormente.<br/>
|
||||
Retorna: <code>true</code>, em caso de sucesso; <code>false</code>, quando a
|
||||
conexão já estiver fechada.
|
||||
</li>
|
||||
|
||||
<li><a name="conn_commit"></a><b><code>conn:commit()</code></b><br/>
|
||||
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.
|
||||
</li>
|
||||
|
||||
<li><a name="conn_execute"></a><b><code>conn:execute(statement)</code></b><br/>
|
||||
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 afetados de alguma forma pelo comando.
|
||||
</li>
|
||||
|
||||
<li><a name="conn_rollback"></a><b><code>conn:rollback()</code></b><br/>
|
||||
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.
|
||||
</li>
|
||||
|
||||
<li><a name="conn_setautocommit"></a><b><code>conn:setautocommit(boolean)</code></b><br/>
|
||||
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.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<h2><a name="cursor_object"></a>Cursor</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>
|
||||
|
||||
<ul>
|
||||
<li><a name="cur_close"></a><b><code>cur:close()</code></b><br/>
|
||||
Fecha esse cursor.<br/>
|
||||
Retorna: <code>true</code>, em caso de sucesso; <code>false</code>, quando o cursor
|
||||
já está fechado.
|
||||
</li>
|
||||
|
||||
<li><a name="cur_fetch"></a><b><code>cur:fetch([table[,modestring]])</code></b><br/>
|
||||
Recupera o próximo registro de resultados.<br/>
|
||||
Se <code>fetch</code> é chamado sem parâmetros, os resultados
|
||||
retornarão diretamente como uma lista de valores. Se <code>fetch</code> é
|
||||
chamado com uma tabela, os resultados serão copiados para a tabela e a tabela
|
||||
é retornada (por conveniência). Nesse 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:
|
||||
<ul>
|
||||
<li><b>"n"</b>, a tabela resultante terá índices numéricos (padrão)</li>
|
||||
<li><b>"a"</b>, a tabela resultante terá índices alfanuméricos</li>
|
||||
</ul>
|
||||
Os <em>índices numéricos</em> representam as posições dos
|
||||
campos no comando selecionado; 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 resultadao válido.
|
||||
</li>
|
||||
|
||||
<li><a name="cur_colnames"></a><b><code>cur:getcolnames()</code></b><br/>
|
||||
Retorna: uma tabela com os nomes das colunas.
|
||||
</li>
|
||||
|
||||
<li><a name="cur_coltypes"></a><b><code>cur:getcoltypes()</code></b><br/>
|
||||
Retorna: uma tabela com os tipos das colunas.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<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
|
||||
(ver manual), o driver Postgres ainda oferece funcionalidades extras:</p>
|
||||
|
||||
<ul>
|
||||
<li><b><code>env:connect(sourcename[,username[,password[,hostname[,port]]]])</code></b><br/>
|
||||
No driver PostgreSQL, esse método tem dois outros parâmetros que indicam
|
||||
o <code>hostname</code> e a <code>port</code> a serem utilizados na conexão.
|
||||
O primeiro parâmetro também pode conter todas as infornmaçõ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>
|
||||
</li>
|
||||
|
||||
<li><b><code>cur:numrows()</code></b><br/>
|
||||
Veja também: <a href="#cursor_object">cursor</a><br/>
|
||||
Retorna: o número de registros no resultado da busca.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<h2><a name="mysql_extensions"></a>MySQL</h2>
|
||||
|
||||
<p>Além das funcionalidades básicas oferecidas por todos os drivers
|
||||
(ver manual), o driver MySQL ainda oferece uma funcionalidade extra:</p>
|
||||
|
||||
<ul>
|
||||
<li><b><code>env:connect(sourcename[,username[,password[,hostname[,port]]]])</code></b> <br/>
|
||||
No driver MySQL, esse método tem dois outros parâmetros 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>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>Nota: Esse driver é compatível com a versão 4.0 e 4.1 (alpha) do
|
||||
MySQL API. Apenas as versões 4.1 oferecem suporte para transações que usam 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> podem não funcionar.</p>
|
||||
|
||||
<h2><a name="oracle_extensions"></a>Oracle</h2>
|
||||
|
||||
<p>Além das funcionalidades básicas oferecidas por todos os drivers
|
||||
(ver manual), o driver Oracle ainda oferece uma funcionalidade extra:</p>
|
||||
|
||||
<ul>
|
||||
<li><b><code>cur:numrows()</code></b> <br/>
|
||||
Veja também: <a href="#cursor_object">cursor</a><br/>
|
||||
Retorna: o número de registros no resultado da pesquisa.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
</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.1 2005/04/28 16:50:28 carregal Exp $
|
||||
</small></p>
|
||||
</div> <!-- id="about" -->
|
||||
|
||||
</div> <!-- id="container" -->
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Loading…
x
Reference in New Issue
Block a user