1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
|
<!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="https://github.com/lunarmodules/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 e em caso de falha retorna <code>false</code> com uma <code>mensagem de string</code> indicando o motivo da falha.
</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 e em caso de falha retorna <code>false</code> com uma <code>mensagem de string</code> indicando o motivo da falha.
</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 e em caso de falha retorna <code>false</code> com uma <code>mensagem de string</code> indicando o motivo da falha.
</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[,socket[,client_flag]]]]]])</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.
Ela também aceita dois outros parâmetros que indicam um Unix socket de onde abrir a conexão e um flag do cliente.<br/>
Veja também: <a href="#environment_object">ambiente</a><br/>
Retorna: uma <a href="#connection_object">conexão</a>
</dd>
<dt><strong><code>conn:ping()</code></strong></dt>
<dd>Verifica se uma conexão está fechada (retorna false) ou aberta (retorna true).
Irá retornar nil seguido de uma mensagem no caso de erro.<br/>
Retorna: true, se a conexão estiver aberta, ou false, se estiver fechada.
</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,readOnlyMode])</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.
O parâmetro <code>readOnlyMode</code> (booleano) pode ser usado para abrir uma conexão apenas de leitura.<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">Valid XHTML 1.0!</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>
|
