Como ligar uma base de dados MySQL a um servidor FiveM com o oxmysql?
Criar a base no painel, instalar o oxmysql, escrever mysql_connection_string no server.cfg, importar o SQL do ESX ou do QBCore e corrigir os erros de
O oxmysql é o recurso que liga um servidor FiveM ou RedM a uma base de dados MySQL ou MariaDB. O ESX Legacy, o QBCore e o Qbox dependem dele: sem ligação à base, o framework não arranca. Na ACLClouds, a base está alojada num servidor MariaDB à parte e incluída no plano: 1 base com Dev, 2 com City, 3 com Empire.
Procedimento passo a passo
-
Criar a base de dados
Em «Bases de dados», clique em «Nova base de dados», dê-lhe um nome curto como esx ou qbcore e deixe «Ligações de» vazio para autorizar o servidor de jogo e o seu PC. O painel acrescenta um prefixo ao nome: a base chama-se, por exemplo, s12345_esx.
-
Anotar os identificadores
Abra a base na lista: o painel mostra o «Ponto de acesso» (anfitrião e porta), o «Nome de utilizador», a «Palavra-passe» e uma cadeia de ligação JDBC. O anfitrião é o endereço do servidor de bases de dados, nunca localhost nem 127.0.0.1.
-
Instalar o oxmysql
Descarregue oxmysql.zip da última versão publicada na página Releases do repositório GitHub overextended/oxmysql, e não o código-fonte: só o arquivo publicado contém os ficheiros compilados. Extraia-o para resources/[standalone]/oxmysql com «Ficheiros». As receitas ESX e QBCore do txAdmin já o instalam.
-
Escrever a ligação no server.cfg
Acrescente set mysql_connection_string com o utilizador, a palavra-passe, o anfitrião, a porta e o nome da base, e depois ensure oxmysql antes do framework e de todos os recursos que usam a base.
-
Importar as tabelas
Os frameworks e muitos scripts incluem um ficheiro .sql. Importe-o a partir do seu PC com o HeidiSQL, o DBeaver ou o cliente mariadb, com as credenciais do painel. Uma receita do txAdmin cria as suas próprias tabelas.
-
Reiniciar e ler a consola
No arranque, o oxmysql indica na consola que está ligado à base, com a versão do MariaDB. Um erro indica quase sempre a sua causa: anfitrião, palavra-passe ou nome da base.
Ligação no server.cfg (formato URL)
set mysql_connection_string "mysql://u12345_AbCdEf:PASSWORD@HOST:3306/s12345_esx?charset=utf8mb4"
ensure oxmysql
ensure es_extended
Outro formato aceite pelo oxmysql
set mysql_connection_string "host=HOST;port=3306;user=u12345_AbCdEf;password=PASSWORD;database=s12345_esx"
Opções úteis do oxmysql
set mysql_slow_query_warning 150
set mysql_ui true
Importar e exportar a partir de um PC
mariadb -h HOST -P 3306 -u u12345_AbCdEf -p s12345_esx < es_extended.sql
mariadb-dump -h HOST -P 3306 -u u12345_AbCdEf -p s12345_esx > backup.sql
Antes de começar
As bases de dados estão incluídas nos planos FiveM pagos, até ao limite indicado no topo de «Bases de dados». Cada base tem o seu próprio utilizador e as suas próprias permissões. Todos os scripts de um mesmo servidor partilham normalmente a mesma base.
- Pare o servidor antes de alterar o server.cfg.
- Com o txAdmin, altere o server.cfg da receita, na pasta txData, e não o da raiz.
- Não execute mysql-async nem ghmattimysql ao mesmo tempo: o oxmysql fornece as funções deles aos scripts antigos.
Caracteres especiais na palavra-passe
No formato URL, os caracteres @, :, /, #, ? e % da palavra-passe partem a cadeia. Codifique-os (@ passa a %40), use o formato key=value ou reutilize a cadeia JDBC do painel, onde a palavra-passe já está codificada, retirando o prefixo jdbc:.
O botão de rotação da palavra-passe gera uma nova: atualize o server.cfg de imediato, senão o oxmysql deixa de se ligar no arranque seguinte.
Fazer cópia da base
As cópias de segurança do painel copiam os ficheiros do servidor, não a base de dados. Exporte-a com regularidade com mariadb-dump ou a exportação do HeidiSQL, sobretudo antes de cada atualização do framework, e guarde uma cópia fora do servidor.
Erros comuns e soluções
O oxmysql escreve a causa da falha na consola, no arranque do servidor.
- ECONNREFUSED ou ETIMEDOUT: anfitrião ou porta errados. Copie de novo o «Ponto de acesso»; localhost não funciona, a base não está no contentor do jogo.
- ER_ACCESS_DENIED_ERROR: utilizador ou palavra-passe errados, muitas vezes por um caráter especial não codificado, ou um valor de «Ligações de» que exclui o servidor de jogo.
- ER_BAD_DB_ERROR: nome da base desconhecido. Indique o nome completo com o prefixo, por exemplo s12345_esx.
- ER_NO_SUCH_TABLE: a base está vazia ou incompleta. Importe o ficheiro .sql do framework ou do script em causa.
- No such export sobre o oxmysql ao carregar um script: o oxmysql arranca demasiado tarde. Coloque ensure oxmysql antes do framework.
Verificação rápida
- A consola mostra a ligação do oxmysql à base, sem erros.
- ensure oxmysql está antes do framework.
- As tabelas do framework aparecem no HeidiSQL ou no DBeaver.
- Uma exportação .sql recente está guardada fora do servidor.
Perguntas frequentes
É preciso instalar o MySQL no servidor FiveM?
Não. A base está alojada num servidor MariaDB separado, incluído no plano: cria-a em «Bases de dados» e o oxmysql liga-se a ela pela rede. O MariaDB é compatível com o MySQL para ESX, QBCore e Qbox.
Como ver e alterar as tabelas?
Ligue-se a partir do seu PC com o HeidiSQL ou o DBeaver, com o anfitrião, a porta, o utilizador e a palavra-passe mostrados no painel. Faça uma exportação antes de qualquer alteração manual.
É possível usar uma base de dados externa?
Sim. O oxmysql liga-se a qualquer servidor MySQL ou MariaDB acessível a partir do servidor de jogo: indique o anfitrião e as credenciais em mysql_connection_string. Uma base próxima do servidor de jogo responde mais depressa, o que conta para os scripts que a consultam muitas vezes.
A consola fala de consultas lentas, o que fazer?
O oxmysql assinala as consultas mais longas do que mysql_slow_query_warning (200 ms por predefinição) e indica o recurso em causa. Acrescente um índice na coluna que ele filtra ou substitua o script: um recurso que consulta a base em ciclo abranda todo o servidor.