MySQL: Primeiros passos

Como começar com MySQL

👋 Bem-vindo à documentação da Stackhero!

A Stackhero oferece uma solução MySQL cloud pronta a usar que proporciona uma série de benefícios, incluindo:

  • Conexões e transferências ilimitadas.
  • Interface web phpMyAdmin incluída.
  • Atualizações fáceis com apenas um clique.
  • Desempenho ótimo e segurança robusta alimentados por uma VM privada e dedicada.

Poupe tempo e simplifique a sua vida: leva apenas 5 minutos para experimentar a solução de MySQL cloud hosting da Stackhero!

URLs MySQL

Se pretende uma forma rápida de se ligar ao seu serviço MySQL, pode considerar utilizar o formato de URL MySQL, desde que o seu driver o suporte:

mysql://root:<ROOT_PASSWORD>@<XXXXXX>.stackhero-network.com:<PORT>/root?useSSL=true&requireSSL=true

Se estiver a trabalhar com Ruby, o formato da URL é ligeiramente diferente:

mysql2://root:<ROOT_PASSWORD>@<XXXXXX>.stackhero-network.com:<PORT>/root?reconnect=true&useSSL=true&requireSSL=true

Utilizar MySQL com PHP

MySQLi (estilo orientado a objetos)

Aqui está um exemplo de ligação ao MySQL utilizando a extensão MySQLi do PHP em estilo orientado a objetos:

<?php

$hostname = '<XXXXXX>.stackhero-network.com';
$port = '<PORT>';
$user = 'root';
$password = '<ROOT_PASSWORD>';
$database = 'root'; // Embora este exemplo utilize a base de dados "root", é aconselhável criar uma base de dados e um utilizador dedicados para a sua aplicação através do phpMyAdmin.

$mysqli = mysqli_init();
$mysqliConnected = $mysqli->real_connect($hostname, $user, $password, $database, $port, NULL, MYSQLI_CLIENT_SSL);
if (!$mysqliConnected) {
  die("Erro de ligação: " . $mysqli->connect_error);
}

echo 'Ligação bem-sucedida... ' . $mysqli->host_info . "\n";

$mysqli->close();

?>

MySQLi (estilo procedural)

Se preferir código procedural, veja como pode ligar-se utilizando MySQLi em estilo procedural:

<?php

$hostname = '<XXXXXX>.stackhero-network.com';
$port = '<PORT>';
$user = 'root';
$password = '<ROOT_PASSWORD>';
$database = 'root'; // Para maior segurança, crie uma base de dados e um utilizador dedicados no phpMyAdmin em vez de usar "root".

$mysqli = mysqli_init();
$mysqliConnected = mysqli_real_connect($mysqli, $hostname, $user, $password, $database, $port, NULL, MYSQLI_CLIENT_SSL);
if (!$mysqliConnected) {
  die("Erro de ligação: " . mysqli_connect_error($mysqli));
}

echo 'Sucesso: ' . mysqli_get_host_info($mysqli) . "\n";

mysqli_close($mysqli);

?>

PDO

Se preferir utilizar PDO para acesso à base de dados, aqui está um exemplo de configuração de ligação:

<?php

$hostname = '<XXXXXX>.stackhero-network.com';
$port = '<PORT>';
$user = 'root';
$password = '<ROOT_PASSWORD>';
$database = 'root'; // É recomendável criar uma base de dados e um utilizador dedicados para a sua aplicação.

$dsn = "mysql:host=$hostname;port=$port;dbname=$database";

$options = array(
  // Se surgirem erros relacionados com SSL ao ligar, certifique-se de que o seu sistema tem os certificados CA corretos instalados (ver abaixo).
  PDO::MYSQL_ATTR_SSL_CAPATH => '/etc/ssl/certs/',
  // PDO::MYSQL_ATTR_SSL_CA => 'isrgrootx1.pem',
  PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => true,
);

$pdo = new PDO($dsn, $user, $password, $options);

$stm = $pdo->query("SELECT VERSION()");
$version = $stm->fetch();

echo "Está ligado a uma base de dados com a versão " . $version[0] . "\n";

?>

Resolução de problemas: SSL operation failed with code 1

Se vir um erro como este:

Uncaught PDOException: PDO::__construct(): SSL operation failed with code 1. OpenSSL Error messages: error:0A000086:SSL routines::certificate verify failed

Isto provavelmente significa que o seu sistema não tem certificados CA em /etc/ssl/certs/.

Se tiver acesso ao sistema onde o seu código PHP corre, pode adicionar os certificados assim:

  1. Em Ubuntu/Debian, execute: sudo apt-get install ca-certificates
  2. Em Alpine Linux, execute: apk add ca-certificates

Se não tiver acesso direto, pode adicionar o certificado manualmente:

  1. Faça o download do certificado: https://letsencrypt.org/certs/isrgrootx1.pem
  2. Coloque o ficheiro isrgrootx1.pem no seu projeto PHP.
  3. Comente a linha PDO::MYSQL_ATTR_SSL_CAPATH => '/etc/ssl/certs/'
  4. Descomente a linha PDO::MYSQL_ATTR_SSL_CA => 'isrgrootx1.pem'

Resolução: erros de constantes indefinidas com PDO

Se vir erros como:

Fatal error: Uncaught Error: Undefined constant PDO::MYSQL_ATTR_SSL_CAPATH

ou mensagens semelhantes, isto indica que o PDO foi instalado sem suporte para MySQL.

  1. Em Ubuntu/Debian

Pode adicionar a extensão necessária executando:

sudo apt-get install php-mysql
  1. Em Docker

Se estiver a usar Docker, certifique-se de que o suporte MySQL está incluído durante o build. Pode adicionar isto ao seu Dockerfile:

RUN docker-php-ext-install pdo pdo_mysql


### Utilizar MySQL com Symfony e Doctrine

Se estiver a trabalhar com Symfony e Doctrine, pode configurar a sua ligação desta forma:

1. Edite o seu ficheiro `.env` e defina a variável `DATABASE_URL`:

DATABASE_URL="mysql://<USER>:<PASSWORD>@<XXXXXX>.stackhero-network.com:<PORT>/<DATABASE>"


1. Depois, em `config/packages/doctrine.yaml`, defina o driver e as opções:

```yaml
doctrine:
    dbal:
        url: '%env(resolve:DATABASE_URL)%'
        driver: 'pdo_mysql'
        options:
            # PDO::MYSQL_ATTR_SSL_CAPATH
            1010: '/etc/ssl/certs'
            # PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT
            1014: true

Resolução de problemas: SSL operation failed with code 1

Se encontrar um erro como:

Uncaught PDOException: PDO::__construct(): SSL operation failed with code 1. OpenSSL Error messages: error:0A000086:SSL routines::certificate verify failed

Isto provavelmente significa que o diretório /etc/ssl/certs/ não tem os certificados CA.

Se tiver acesso ao sistema, pode instalá-los assim:

  1. Em Ubuntu/Debian: sudo apt-get install ca-certificates
  2. Em Alpine Linux: apk add ca-certificates

Se não tiver acesso direto, pode adicionar o certificado manualmente:

  1. Faça o download: https://letsencrypt.org/certs/isrgrootx1.pem
  2. Coloque isrgrootx1.pem no seu projeto Symfony.
  3. Atualize config/packages/doctrine.yaml:
doctrine:
    dbal:
        url: '%env(resolve:DATABASE_URL)%'
        driver: 'pdo_mysql'
        options:
            # PDO::MYSQL_ATTR_SSL_CA
            1009: 'isrgrootx1.pem'
            # PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT
            1014: true

Utilizar MySQL com Laravel

Para configurar o MySQL no Laravel, abra o ficheiro config/database.php e atualize a secção MySQL:

'mysql' => [
  'driver' => 'mysql',
  'host' => env('STACKHERO_MYSQL_HOST'),
  'port' => env('STACKHERO_MYSQL_PORT'),
  'username' => env('STACKHERO_MYSQL_USER'),
  'password' => env('STACKHERO_MYSQL_PASSWORD'),
  'database' => env('STACKHERO_MYSQL_USER'),
  'charset' => 'utf8mb4',
  'collation' => 'utf8mb4_unicode_ci',
  'prefix' => '',
  'prefix_indexes' => true,
  'strict' => true,
  'engine' => null,
  'sslmode' => 'require',
  'options' => extension_loaded('pdo_mysql')
    ? array_filter([
      // Para erros SSL, consulte a resolução de problemas acima.
      PDO::MYSQL_ATTR_SSL_CAPATH => '/etc/ssl/certs/',
      // PDO::MYSQL_ATTR_SSL_CA => 'isrgrootx1.pem',
      PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => true,
    ])
    : [],
],

Utilizar MySQL com PHP CodeIgniter

No ficheiro de configuração database.php, pode adicionar:

$db['default'] = array(
  'hostname' => getenv('STACKHERO_MYSQL_HOST'),
  'port'     => getenv('STACKHERO_MYSQL_PORT'),
  'username' => getenv('STACKHERO_MYSQL_USER'),
  'password' => getenv('STACKHERO_MYSQL_PASSWORD'),
  'database' => getenv('STACKHERO_MYSQL_USER'), // Por convenção, o nome da base de dados corresponde ao utilizador.
  'dbdriver' => 'mysqli',
  'dbprefix' => '',
  'pconnect' => true,
  'char_set' => 'utf8',
  'dbcollat' => 'utf8_general_ci',
  'encrypt'  => array() // Importante: ative a encriptação TLS
);

Ligar com variáveis de ambiente em PHP

É geralmente mais seguro evitar guardar as credenciais da base de dados no código. Em vez disso, pode utilizar variáveis de ambiente. Veja como as pode obter:

$hostname = getenv('STACKHERO_MYSQL_HOST');
$port = getenv('STACKHERO_MYSQL_PORT');
$user = getenv('STACKHERO_MYSQL_USER');
$password = getenv('STACKHERO_MYSQL_PASSWORD');
$database = getenv('STACKHERO_MYSQL_USER'); // Por convenção, o nome da base de dados corresponde ao utilizador.

Utilizar MySQL com WordPress

Ligar o WordPress ao Stackhero para MySQL é simples. Só precisa de editar o ficheiro wp-config.php desta forma:

define('DB_HOST', '<XXXXXX>.stackhero-network.com');
define('DB_PORT', '<PORT>');
define('DB_NAME', 'root');
define('DB_USER', 'root');
define('DB_PASSWORD', '<yourPassword>');

// Ativar encriptação TLS (também conhecido como SSL)
define('MYSQL_CLIENT_FLAGS', MYSQLI_CLIENT_SSL);

O passo fundamental aqui é ativar a encriptação TLS (SSL). Sem isto, a ligação não funcionará como esperado.

Utilizar MySQL com Node.js

Protocolo MySQL X (pacote xdevapi)

Para utilizar o protocolo MySQL X, pode instalar o pacote oficial xdevapi:

npm install @mysql/xdevapi

Aqui está um exemplo de script:

const mysqlx = require('@mysql/xdevapi');

(async () => {
  // Ligar ao MySQL usando o protocolo MySQL X
  const session = await mysqlx.getSession({
    host: '<XXXXXX>.stackhero-network.com',
    port: '<PORT>',
    user: 'root',
    password: '<ROOT_PASSWORD>'
  });

  // Criar o schema (base de dados) se não existir
  const schemaExists = await session.getSchema('stackherotest').existsInDatabase();
  if (!schemaExists) {
    await session.createSchema('stackherotest');
  }

  // Criar a tabela 'users' se não existir
  const tableExists = await session
    .getSchema('stackherotest')
    .getTable('users')
    .existsInDatabase();
  if (!tableExists) {
    await session
      .sql('CREATE TABLE `stackherotest`.`users` '
        + '('
        + '`userId` INT UNSIGNED NOT NULL,'
        + '`name` VARCHAR(128) NOT NULL,'
        + '`address` TEXT NOT NULL,'
        + '`email` VARCHAR(265) NOT NULL'
        + ') '
        + 'ENGINE = InnoDB;')
      .execute();
  }

  // Inserir um utilizador de exemplo
  await session
    .getSchema('stackherotest')
    .getTable('users')
    .insert('userId', 'name', 'address', 'email')
    .values(
      Math.round(Math.random() * 100000),
      'User name',
      'User address',
      '[email protected]'
    )
    .execute();

  // Contar o número de utilizadores
  const usersCount = await session
    .getSchema('stackherotest')
    .getTable('users')
    .count();

  console.log(`Existem agora ${usersCount} registos na tabela "users"`);

  // Fechar a ligação
  await session.close();

})().catch(error => {
  console.error('');
  console.error('Ocorreu um erro!');
  console.error(error);
  process.exit(1);
});

Protocolo MySQL clássico (pacote mysql2)

Se preferir o protocolo clássico, pode utilizar o pacote mysql2 com suporte a promessas. Instale-o com:

npm install mysql2

Exemplo de utilização:

const mysql = require('mysql2/promise');

(async () => {
  const db = await mysql.createConnection({
    host: '<XXXXXX>.stackhero-network.com',
    port: '<PORT>',
    user: 'root',
    password: '<ROOT_PASSWORD>'
  });

  // Criar a base de dados se necessário
  await db.query('CREATE DATABASE IF NOT EXISTS stackherotest');

  // Criar a tabela se necessário
  await db.query('CREATE TABLE IF NOT EXISTS `stackherotest`.`users` '
    + '('
    + '`userId` INT UNSIGNED NOT NULL,'
    + '`name` VARCHAR(128) NOT NULL,'
    + '`address` TEXT NOT NULL,'
    + '`email` VARCHAR(265) NOT NULL'
    + ') '
    + 'ENGINE = InnoDB;');

  // Inserir um utilizador de exemplo
  await db.query(
    'INSERT INTO `stackherotest`.`users` (`userId`, `name`, `address`, `email`) VALUES ?',
    [
      [
        Math.round(Math.random() * 100000),
        'User name',
        'User address',
        '[email protected]'
      ]
    ]
  );

  // Contar utilizadores
  const [ usersCount ] = await db.query('SELECT COUNT(*) AS `cpt` FROM `stackherotest`.`users`');
  console.log(`Existem agora ${usersCount[0].cpt} registos na tabela "users"`);

  // Fechar a ligação
  await db.end();

})().catch(error => {
  console.error('');
  console.error('Ocorreu um erro!');
  console.error(error);
  process.exit(1);
});

Utilizar MySQL com Node.js, NestJS ou TypeORM

Para se ligar a partir de Node.js, NestJS ou TypeORM, pode adicionar a opção ssl conforme o exemplo abaixo:

TypeOrmModule.forRoot({
  type: 'mysql',
  host: '<XXXXXX>.stackhero-network.com',
  port: <PORT>,
  username: 'root',
  password: '<ROOT_PASSWORD>',
  database: 'root',
  entities: [],
  synchronize: true,
  ssl: {}
});

Utilizar MySQL com Prisma

Se estiver a utilizar Prisma, adicionar a opção sslaccept=strict ajuda a garantir ligações encriptadas. Eis um exemplo de configuração:

datasource db {
  provider = "mysql"
  url = "mysql://root:<ROOT_PASSWORD>@<XXXXXX>.stackhero-network.com:<PORT>/root?sslaccept=strict"
}

Utilizar MySQL com Django

Se ainda não instalou o módulo mysqlclient, pode fazê-lo com:

pip install mysqlclient

Se surgir o erro Exception: Can not find valid pkg-config name durante a instalação, poderá ser necessário instalar o pacote libmysqlclient. Em Ubuntu/Debian, pode fazê-lo com: apt-get update && apt-get install --no-install-recommends -y libmysqlclient-dev

Inicialmente, pode testar a ligação guardando a palavra-passe diretamente no ficheiro settings.py. Para maior segurança a longo prazo, é preferível utilizar variáveis de ambiente (ver abaixo).

Edite o seu settings.py desta forma:

DATABASES = {
  'default': {
    'ENGINE': 'django.db.backends.mysql',
    'HOST': '<XXXXXX>.stackhero-network.com',
    'PORT': '<PORT>',
    'OPTIONS': {
      'ssl_mode': 'REQUIRED',
    },
    'NAME': 'root',
    'USER': 'root',
    'PASSWORD': '<ROOT_PASSWORD>'
  }
}

Atenção: este exemplo destina-se apenas a testes e não é recomendado para ambientes de produção!

Depois de confirmar que a ligação funciona, pode passar para uma abordagem mais segura utilizando o django-environ para gerir variáveis de ambiente.

Primeiro, instale o pacote:

pip install django-environ

Depois, atualize o seu settings.py:

import environ
env = environ.Env()
environ.Env.read_env()

DATABASES = {
  'default': {
    'ENGINE': 'django.db.backends.mysql',
    'HOST': env('STACKHERO_MYSQL_HOST'),
    'PORT': env('STACKHERO_MYSQL_PORT'),
    'OPTIONS': {
      'ssl_mode': 'REQUIRED',
    },
    'NAME': 'root',
    'USER': 'root',
    'PASSWORD': env('STACKHERO_MYSQL_ROOT_PASSWORD')
  }
}

Crie ou edite o ficheiro .env no mesmo diretório que o settings.py e adicione:

STACKHERO_MYSQL_HOST=<XXXXXX>.stackhero-network.com
STACKHERO_MYSQL_PORT=<PORT>
STACKHERO_MYSQL_ROOT_PASSWORD=<ROOT_PASSWORD>

Por fim, para manter as suas credenciais seguras, pode adicionar .env ao seu ficheiro .gitignore:

echo ".env" >> .gitignore

Ligar MySQL com Java/Spring

Para ligar a sua aplicação Spring, pode definir a variável de ambiente SPRING_DATASOURCE_URL com o URL da sua base de dados, certificando-se de que começa com jdbc::

SPRING_DATASOURCE_URL=jdbc:mysql://root:<ROOT_PASSWORD>@<XXXXXX>.stackhero-network.com:<PORT>/root?useSSL=true&requireSSL=true

Ligar MySQL com Groovy/Grails

Aqui está um exemplo de configuração da sua aplicação Grails para se ligar ao MySQL:

dataSource {
  pooled = true
  driverClassName = "com.mysql.cj.jdbc.Driver"
  dialect = org.hibernate.dialect.MySQL8Dialect
  // Propriedades específicas de SSL
  properties {
    useSSL = true
    requireSSL = true
    verifyServerCertificate = true
    sslMode = "REQUIRED"
  }
}

environments {
  production {
    dataSource {
      dbCreate = "none"
      url = "jdbc:mysql://" + System.env.STACKHERO_MYSQL_HOST + ":" + System.env.STACKHERO_MYSQL_PORT + "/root?useSSL=true&requireSSL=true&verifyServerCertificate=true&sslMode=required" // Pode substituir "/root" pela base de dados que preferir.
      username = "root" // É aconselhável criar um utilizador dedicado para a sua aplicação.
      password = System.env.STACKHERO_MYSQL_ROOT_PASSWORD
      properties {
        maxActive = 50
        minEvictableIdleTimeMillis = 1800000
        timeBetweenEvictionRunsMillis = 1800000
        numTestsPerEvictionRun = 3
        testOnBorrow = true
        testWhileIdle = true
        testOnReturn = false
        validationQuery = "SELECT 1"
      }
    }
  }
}

Criar um utilizador no MySQL usando phpMyAdmin

Para maior segurança, é uma boa prática criar um utilizador dedicado para a sua aplicação em vez de utilizar o utilizador "root". Pode fazê-lo facilmente com o phpMyAdmin:

  1. No phpMyAdmin, selecione User accounts no menu superior.

  2. Clique em Add user account.

  3. Preencha o formulário de criação de utilizador:

    • Indique um nome de conta (normalmente o nome da sua aplicação)
    • Clique em Generate password para obter uma palavra-passe segura e copie-a
    • Selecione Create database with same name and grant all privileges

Depois de submeter o formulário, terá um novo utilizador e uma base de dados dedicada com o mesmo nome do seu nome de utilizador.

Outros artigos para MySQL

  1. Introdução
    Introdução ao MySQL
  2. Utilização avançada
    Como configurar, otimizar, exportar ou importar dados MySQL
  3. Configurar GUIs
    Como ligar interfaces gráficas ao MySQL
  4. Resolução de Problemas
    Problemas comuns e soluções para MySQL
  5. Workbench
    Como configurar o MySQL Workbench