dbConnect

Abre uma conexão com um banco de dados.

Sintaxe

db-connection dbConnect ( string tipo, string destino [, string usuario = "", string senha = "", string opcoes = "" ] )

Parâmetros

Nome	Tipo	Padrão	Descrição
tipo	string	—	"sqlite", "mysql" ou "mariadb".
destino	string	—	O arquivo do banco, no caso do sqlite, ou o endereço do servidor, no caso de mysql/mariadb. Veja abaixo.
usuario	string	""	Usuário do login. Ignorado pelo sqlite.
senha	string	""	Senha do login. Ignorada pelo sqlite.
opcoes	string	""	Ajustes extras, em pares chave=valor.

O que vai em destino

No sqlite é o arquivo do banco, como caminho relativo à pasta databases. Ele é criado se não existir, e subpastas são permitidas e criadas automaticamente — dbConnect("sqlite", "logs/2026.db") funciona. O caminho é recusado se contiver .. ou :, se começar com / ou \, ou se for absoluto. A única exceção é ":memory:", que abre um banco particular que vive na memória e desaparece quando a conexão é fechada.

No mysql e no mariadb é o endereço do servidor, escrito em pares chave=valor:

Chave	Padrão	Descrição
host	localhost	Endereço do servidor de banco.
port	a porta padrão	Porta em que o servidor escuta.
dbname	nenhum	Banco selecionado logo depois de conectar.
unix_socket	nenhum	Socket local, no lugar da conexão pela rede.
charset	utf8mb4	Conjunto de caracteres da conexão, para os acentos não se perderem no caminho.

Opções

opcoes usa o mesmo formato chave=valor. Quais chaves fazem diferença depende do tipo:

Chave	Tipo	Padrão	Descrição
busy_timeout	sqlite	5000	Milissegundos de espera quando o arquivo está travado por outra operação, antes de desistir.
connect_timeout	mysql	5	Segundos de espera pela resposta do servidor durante a conexão.
autoreconnect	mysql	1	1 reabre uma conexão caída na próxima consulta, 0 deixa fechada.
multi_statements	mysql	0	1 libera vários comandos separados por ; em uma chamada só.
ssl	mysql	0	1 exige conexão criptografada e verifica o certificado do servidor.

Os pares podem ser separados por ;, , ou espaço, tanto em destino quanto em opcoes.

-- uma conexão criptografada com um MySQL gerenciado
local db = dbConnect("mysql", "host=db.exemplo.com;port=3306;dbname=servidor",
                     "usuario", "senha", "ssl=1")

ssl=1 é tudo ou nada

Ele liga de uma vez a exigência de criptografia e a checagem do certificado — não dá para separar as duas. Se o servidor apresentar um certificado em que a sua máquina não confia, a conexão falha em vez de cair para texto puro. É esse o objetivo, mas significa que um certificado autoassinado precisa ser instalado antes na loja de confiança do sistema.

Retorno

O elemento de conexão, ou false se o tipo não for nenhum dos três, se destino não for informado, se o caminho do SQLite sair da pasta databases ou não puder ser aberto, ou se o servidor MySQL recusar a conexão. Em caso de falha o motivo aparece no console de debug; nada é lançado, então o seu script continua rodando e a verificação do retorno fica com você.

Nota

A conexão é aberta na hora, antes de o dbConnect retornar. No MySQL isso significa que um host que não responde segura o servidor até o connect_timeout estourar. Conecte uma vez no início do resource e reaproveite o mesmo elemento daí em diante.

Fechando a conexão

destroyElement(conexao) fecha a conexão. Parar o resource que a abriu também: toda conexão aberta por um resource é fechada junto com ele. Depois de fechada, as consultas que ainda estavam em andamento nela são descartadas — os handles param de responder e o dbPoll devolve false com um aviso no console de debug.

O dbFree não tem nada a ver com isso. Ele joga fora o resultado de uma consulta; ele nunca fecha uma conexão.

Veja também

• dbExec — Executa um comando SQL do qual você não precisa das linhas de volta.
• dbQuery — Dispara uma consulta e devolve um handle para você ler o resultado com dbPoll.
• dbPoll — Recolhe o resultado de uma consulta.
• dbFree — Descarta um resultado que você não vai ler.
• dbPrepareString — Monta uma string SQL com os valores já escapados no lugar dos ?.