![\"\"](\"https:\/\/www.pascalscada.com\/wp-content\/uploads\/2026\/09\/THMIDBConnection.png\")
O THMIDBConnection<\/code> \u00e9 o componente de acesso a banco de dados do PascalSCADA: conecta a um SGBD e executa comandos SQL de forma ass\u00edncrona<\/strong>, sem travar a interface enquanto a consulta roda. Fica no pacote pascalscada_db<\/code> (que n\u00e3o depende da LCL, ent\u00e3o tamb\u00e9m funciona em aplica\u00e7\u00f5es de console) e \u00e9 a base de componentes como o THMIEventLogger<\/code> e o THMIAlarmLogger<\/code><\/a>, al\u00e9m de servir para telas pr\u00f3prias \u2014 cadastro de usu\u00e1rios, receitas, hist\u00f3rico.<\/p>\nPor baixo, ele usa o SQLdb<\/strong> do Free Pascal (n\u00e3o mais o ZeosLib, removido como depend\u00eancia a partir da vers\u00e3o 0.7.7 \u2014 veja Como instalar<\/a>). Isso significa que o THMIDBConnection<\/code> j\u00e1 sai pronto para os bancos com conector SQLdb; n\u00e3o \u00e9 um ORM nem esconde SQL de voc\u00ea \u2014 voc\u00ea escreve o comando e ele cuida da fila, da thread e do retorno do resultado.<\/p>\nBancos de dados suportados<\/h5>\n
A propriedade Protocol<\/code><\/strong> escolhe o banco. No Object Inspector ela vem com uma lista suspensa fixa:<\/p>\n\n\n\nProtocol<\/th>\n Conector SQLdb usado<\/th>\n Observa\u00e7\u00e3o<\/th>\n<\/tr>\n<\/thead>\n \n\npostgresql<\/td>\n PostgreSQL<\/td>\n <\/td>\n<\/tr>\n \nsqlite<\/td>\n SQLite3<\/td>\n Database<\/code> \u00e9 o caminho do arquivo .db<\/code>\/.sqlite<\/code>.<\/td>\n<\/tr>\n\nmysql<\/td>\n MySQL 5.7<\/td>\n S\u00f3 o driver de fio do MySQL 5.7 \u00e9 suportado no momento \u2014 mesmo em servidores mais novos, funciona pelo protocolo de compatibilidade.<\/td>\n<\/tr>\n \nfirebird<\/td>\n Firebird<\/td>\n <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nValores herdados de instala\u00e7\u00f5es antigas com sufixo de vers\u00e3o (por exemplo mysql-5.7<\/code>, formato que o ZeosLib usava) continuam funcionando: s\u00f3 a parte antes do tra\u00e7o \u00e9 considerada para escolher o conector.<\/p>\nPropriedades de conex\u00e3o<\/h5>\n
\n\n\nPropriedade<\/th>\n Descri\u00e7\u00e3o<\/th>\n<\/tr>\n<\/thead>\n \n\nProtocol<\/td>\n Um dos quatro protocolos da tabela acima.<\/td>\n<\/tr>\n \nHostName<\/td>\n Endere\u00e7o ou nome da m\u00e1quina do banco. Em SQLite n\u00e3o \u00e9 usado.<\/td>\n<\/tr>\n \nPort<\/td>\n Porta de conex\u00e3o. 0<\/code> deixa a porta padr\u00e3o do conector.<\/td>\n<\/tr>\n\nDatabase<\/td>\n Nome do banco (Postgres\/MySQL\/Firebird) ou caminho do arquivo (SQLite).<\/td>\n<\/tr>\n \nUser, Password<\/td>\n Credenciais de acesso.<\/td>\n<\/tr>\n \nCatalog<\/td>\n S\u00f3 tem efeito em bancos cujo conector SQLdb tem o conceito de cat\u00e1logo; na maioria \u00e9 ignorado.<\/td>\n<\/tr>\n \nProperties<\/td>\n Lista de chave=valor<\/code> repassada direto para os par\u00e2metros de conex\u00e3o do SQLdb (por exemplo, op\u00e7\u00f5es de charset ou de SSL espec\u00edficas do conector).<\/td>\n<\/tr>\n\nLibraryLocation<\/td>\n Caminho de uma biblioteca cliente nativa (libpq.so<\/code>, libmysqlclient.so<\/code>\u2026) quando ela n\u00e3o est\u00e1 no caminho padr\u00e3o do sistema.<\/td>\n<\/tr>\n\nConnected<\/td>\n Abre ou fecha a conex\u00e3o.<\/td>\n<\/tr>\n \nReadOnly<\/td>\n Ver se\u00e7\u00e3o pr\u00f3pria abaixo.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nComo os comandos s\u00e3o executados<\/h5>\n
O THMIDBConnection<\/code> n\u00e3o exp\u00f5e um TDataset<\/code> conectado ao vivo: ele enfileira comandos SQL numa thread pr\u00f3pria (TProcessSQLCommandThread<\/code>) que os executa em ordem<\/strong>, um de cada vez, sobre a mesma conex\u00e3o. Isso evita duas telas concorrendo pela mesma conex\u00e3o SQLdb (que n\u00e3o \u00e9 thread-safe) e mant\u00e9m a interface responsiva mesmo com uma consulta lenta.<\/p>\nOs dois m\u00e9todos que colocam trabalho na fila:<\/p>\n
procedure ExecSQL(sql: UTF8String; ReturnDatasetCallback: TReturnDataSetProc;\n ReturnSync: Boolean = true; NewConnection: Boolean = false);\n\nprocedure ExecTransaction(statements: THMIDBConnectionStatementList;\n ReturnTransactionResult: TReturnTransactionStatementsProc;\n FreeStatemensAfterExecute: Boolean;\n ReturnSync: Boolean = true; NewConnection: Boolean = false);<\/pre>\n
\nExecSQL<\/code><\/strong> executa um \u00fanico comando. Se ele come\u00e7ar com SELECT<\/code>, o resultado chega pronto \u2014 um TFPSBufDataSet<\/code> (um dataset em mem\u00f3ria, veja abaixo) \u2014 em ReturnDatasetCallback<\/code>; para INSERT<\/code>\/UPDATE<\/code>\/DELETE<\/code>\/DDL, passe nil<\/code> no callback ou ignore o par\u00e2metro do dataset. Cada ExecSQL<\/code> roda dentro da sua pr\u00f3pria transa\u00e7\u00e3o, com commit autom\u00e1tico ao final se n\u00e3o houver erro.<\/li>\nExecTransaction<\/code><\/strong> executa uma lista<\/strong> de comandos como uma \u00fanica transa\u00e7\u00e3o: se qualquer um falhar, todos s\u00e3o desfeitos. FreeStatemensAfterExecute<\/code> decide se a lista de strings \u00e9 liberada pelo componente ao terminar. O callback informa sucesso\/falha, em qual linha da lista parou (LineOfError<\/code>) e a exce\u00e7\u00e3o, se houve uma.<\/li>\nReturnSync<\/code><\/strong> decide em qual thread<\/strong> o seu callback roda: True<\/code> (padr\u00e3o) o traz de volta para a thread principal via Synchronize<\/code> \u2014 seguro para tocar em controles visuais; False<\/code> chama o callback na pr\u00f3pria thread de banco<\/strong>, mais r\u00e1pido mas s\u00f3 seguro para c\u00f3digo que n\u00e3o mexe na interface.<\/li>\nNewConnection<\/code><\/strong>: quando True<\/code>, for\u00e7a fechar e reabrir a conex\u00e3o antes de rodar o comando. \u00datil para isolar um comando de um estado de conex\u00e3o suspeito, ao custo do tempo de reconectar.<\/li>\nGetPendingSQLCommands<\/code><\/strong> informa quantos comandos ainda est\u00e3o na fila \u2014 d\u00e1 para usar como indicador visual de fila cheia numa tela que dispara muitas escritas.<\/li>\n<\/ul>\nO dataset que chega em ReturnDatasetCallback<\/code> (assinatura procedure(Sender: TObject; DS: TFPSBufDataSet; error: Exception)<\/code>) \u00e9 criado exclusivamente para aquela chamada \u2014 voc\u00ea \u00e9 dono dele a partir da\u00ed: ligue-o a um TDataSource<\/code>\/TDBGrid<\/code> e libere-o (DS.Free<\/code>) quando n\u00e3o precisar mais. Em caso de erro, DS<\/code> vem nil<\/code> e error<\/code> traz a exce\u00e7\u00e3o original do SQLdb.<\/p>\nAcesso somente leitura<\/h5>\n
Com ReadOnly = True<\/code><\/strong>, todo comando que n\u00e3o seja um SELECT<\/code> \u00e9 recusado antes de chegar ao banco \u2014 o callback recebe erro, nada \u00e9 executado. Use numa tela de consulta ou numa segunda inst\u00e2ncia de conex\u00e3o que s\u00f3 deve exibir dados, nunca alter\u00e1-los.<\/p>\nAcesso s\u00edncrono direto<\/h5>\n
Para os casos em que voc\u00ea quer usar componentes de dados do SQLdb (TSQLQuery<\/code>, TDataSource<\/code>) ligados diretamente \u00e0 conex\u00e3o \u2014 um DBGrid<\/code> edit\u00e1vel, por exemplo \u2014 em vez de passar pela fila ass\u00edncrona, o THMIDBConnection<\/code> exp\u00f5e a conex\u00e3o interna:<\/p>\nfunction GetSyncConnection: TSQLConnector;\nprocedure LockSyncConnection;\nprocedure UnlockSyncConnection;<\/pre>\nGetSyncConnection<\/code> devolve o TSQLConnector<\/code> usado internamente. Como ele \u00e9 compartilhado com a thread ass\u00edncrona, cerque qualquer uso direto com LockSyncConnection<\/code>\/UnlockSyncConnection<\/code> (a mesma se\u00e7\u00e3o cr\u00edtica que a fila usa) para n\u00e3o colidir com um ExecSQL<\/code> em andamento.<\/p>\nFormatando literais SQL<\/h5>\n
Montar comandos SQL por concatena\u00e7\u00e3o de string \u00e9 a porta de entrada cl\u00e1ssica para inje\u00e7\u00e3o de SQL e para bugs de localidade (um FloatToStr<\/code> que vira v\u00edrgula decimal no Brasil e quebra o INSERT<\/code>). Para isso o THMIDBConnection<\/code> tem quatro fun\u00e7\u00f5es de classe \u2014 chamadas sem precisar de uma inst\u00e2ncia:<\/p>\n