Introdução
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.
LuaSQL define uma única variável global: uma tabela chamada luasql.
Essa tabela é usada para armazenar os métodos de inicialização dos drivers instalados.
Esses métodos são usados para criar um
ambiente,
o qual é usado para criar uma
conexão.
A conexão pode executar comandos SQL e, eventualmente, criar um
cursor, utilizado para recuperar dados.
LuaSQL é um software livre e usa a mesma licença do Lua 5.0.
Compilando
LuaSQL é distribuído como um conjunto de arquivos fonte C –
um arquivo fonte e um arquivo cabeçalho comuns a todos os drivers
(luasql.h e luasql.c) – e um arquivo fonte para cada driver.
Cada driver deve ser compilado juntamente com o arquivo luasql.c
para gerar uma biblioteca. Essa biblioteca pode ser linkada à aplicação
ou carregada dinamicamente. A função de inicialização é
luaopen_luasqlnomedriver e é compatível com o formato
open-library de Lua.
Instalação
Todos os drivers LuaSQL seguem a
proposta de pacotes
para Lua 5.1. Logo, esse pacote deve ser "instalado". Consulte a seção de
configuração do Compat-5.1 para saber como instalar os pacotes binários
da maneira correta.
As bibliotecas compiladas devem ser instaladas em um diretório chamado
luasql no seu LUA_CPATH.
Usuários Windows podem utilizar os pacotes compilados do LuaSQL disponíveis na
página do
LuaForge
Para usar LuaSQL com o JDBC, certifique-se que:
- Lua está rodando com LuaJava
- O jar do LuaSQL está na classpath da máquina virtual do Java
- O driver JDBC do banco de dados desejado também está na classpath
da máquina virtual
Para usar LuaSQL com ADO, certifique-se que Lua está rodando com
LuaCOM 1.3
Tratamento de erros
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.
Erros como comandos SQL mal formados, nomes de tabela desconhecidos etc., chamados
erros de banco de dados, serão reportados pelo retorno de nil
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 erros de API,
são usualmente erros de programação e geram erros Lua.
Esse comportamento vale para todas as funções/métodos descritos
neste documento, a menos que seja especificado de outra forma.
Drivers
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 luasql. O exemplo abaixo
require "luasql.odbc"
carrega o driver ODBC na tabela luasql. Note que pode-se ter mais de um driver
carregado usando-se algo como:
require "luasql.odbc"
require "luasql.oci8"
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 oci8
ao invés de oracle.
Alguns drivers, tais como o MySQL, tem bibliotecas para versões diferentes
do banco de dados MySQL mas utilizam o mesmo nome de arquivo (mysql).
Neste caso não é possível carregar mais de uma versão
do driver MySQL na tabela luasql.
Ambiente
Um ambiente é criado chamando a função de inicialização
do driver que está armazenada na tabela luasql com o mesmo nome do driver
(odbc, postgres etc). Por exemplo,
env = luasql.odbc()
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 luasql.jdbc. Por exemplo:
env = luasql.jdbc ("com.mysql.jdbc.Driver")
Métodos
env:close()- Fecha o ambiente
env. Só é bem sucedido se todas as suas
conexões já tiverem sido fechadas anteriormente.
Retorna: true, em caso de sucesso; false, quando o ambiente
já estiver fechado.
env:connect(sourcename[,username[,password]])- Conecta à fonte de dados especificada em
sourcename usando
username e password se eles são fornecidos.
O sourcename 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
"jdbc:<database system>://<database name>", o qual é
específico para cada driver.
Veja também: PostgreSQL e
MySQL.
Retorna: uma conexão.
Conexão
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 environment:connect.
Métodos
conn:close()- Fecha a conexão
conn. Só é bem sucedido se todos
os seus cursores tiverem sido fechados anteriormente e se a conexão ainda estiver aberta.
Retorna: true, em caso de sucesso; false em caso de fracasso.
conn:commit()- Efetua a transação corrente. Esse atributo pode não funcionar
em sistemas de banco de dados que não implementam transações.
Retorna: true, em caso de sucesso; false, quando
a operação não pode ser realizada ou não está implementada.
conn:execute(statement)- Executa o
statement SQL dado.
Retorna: o cursor, se houver resultados, ou o número
de registros alterados pelo comando.
conn:rollback()- Desfaz a transação corrente. Esse atributo pode não funcionar
em sistemas de banco de dados que não implementam transações.
Retorna: true, em caso de sucesso; false, quando
a operação não pode ser realizada ou não está implementada.
conn:setautocommit(boolean)- 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.
Retorna: true, em caso de sucesso; false, quando
a operação não pode ser realizada ou não está implementada.
Cursores
Um cursor contém métodos para recuperar dados resultantes de um comando executado.
Um cursor é criado por meio de uma função
connection:execute.
Veja também: PostgreSQL
e Oracle.
Métodos
cur:close()- Fecha esse cursor.
Retorna: true, em caso de sucesso; false, quando o cursor
já está fechado.
cur:fetch([table[,modestring]])- Recupera o próximo registro do resultado.
Se fetch é chamado sem parâmetros, os resultados
consistem em uma lista de valores. Se fetch é
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 (modestring): uma seqüência
de caracteres indicando como deve ser construída a tabela de resultados.
A seqüência de caracteres do modo pode conter:
- "n"
- a tabela resultante terá índices numéricos (padrão)
- "a"
- a tabela resultante terá índices alfanuméricos
Os índices numéricos representam as posições dos
campos no comando SELECT; os índices alfanuméricos representam
os nomes dos campos.
A tabela opcional (table) 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.
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.
Retorna: dados, como descrito acima, ou nil se não existem mais registros.
Note que esse método pode retornar nil como um resultado válido.
cur:getcolnames()- Retorna: uma tabela com os nomes das colunas.
cur:getcoltypes()- Retorna: uma tabela com os tipos das colunas.
PostgreSQL
Além das funcionalidades básicas oferecidas por todos os drivers,
o driver Postgres oferece as seguintes funcionalidades adicionais:
env:connect(sourcename[,username[,password[,hostname[,port]]]])- No driver PostgreSQL este método tem mais dois parâmetros opcionais que indicam
o
hostname e a port 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 PQconnectdb no manual do PostgreSQL
(ex. environment:connect("dbname=<name> user=<username>"))
Veja também: ambiente
Retorna: uma conexão
cur:numrows()- Veja também: cursores
Retorna: o número de registros no resultado da busca.
MySQL
Além das funcionalidades básicas oferecidas por todos os drivers,
o driver MySQL ainda oferece as seguintes funcionalidades adicionais:
env:connect(sourcename[,username[,password[,hostname[,port]]]])- No driver MySQL, esse método tem mais dois parâmetros opcionais que indicam o
hostname e a port a serem utilizados na conexão.
Veja também: ambiente
Retorna: uma conexão
cur:numrows()- Veja também: cursores
Retorna: o número de registros no resultado da busca.
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
commit, rollback e setautocommit não funcionam.
Oracle
Além das funcionalidades básicas oferecidas por todos os drivers,
o driver Oracle ainda oferece uma funcionalidade adicional:
cur:numrows()- Veja também: cursores
Retorna: o número de registros no resultado da pesquisa.
SQLite3
Além das funcionalidades básicas oferecidas por todos os drivers,
o driver para SQLite3 ainda oferece uma funcionalidade adicional:
env:connect(sourcename[,locktimeout])
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.
Veja também: ambiente
Retorna: uma conexão
