MariaDB: 入门指南

如何开始使用 MariaDB

👋 欢迎阅读 Stackhero 文档！

Stackhero 提供即用型 MariaDB 云解决方案，具有众多优势，包括：

无限连接和传输。

包含 phpMyAdmin 网页界面。

轻松更新，只需点击一下。

通过 专用私有 VM 提供最佳性能和强大 安全性。

节省时间，简化生活：只需 5 分钟即可试用 Stackhero 的 MariaDB 云托管解决方案！

MariaDB 连接 URL

连接到您的 MariaDB 服务最简单的方法是使用 MySQL URL 格式，只要您的驱动程序支持即可：

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

如果您使用 Ruby，MySQL URL 会略有不同：

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

在 PHP 中使用 MariaDB

以下是一些示例，展示如何通过不同的 PHP 扩展连接 MariaDB。虽然这些示例使用的是 "root" 数据库，但建议为您的应用程序创建专用的数据库和用户，尤其是在生产环境中。

使用 PHP 和 MySQLi（面向对象风格）连接 MariaDB

<?php

$hostname = '<XXXXXX>.stackhero-network.com';
$port     = '<PORT>';
$user     = 'root';
$password = '<ROOT_PASSWORD>';
$database = 'root'; // 仅用于演示。最佳实践是通过 phpMyAdmin 创建您自己的数据库和用户，并使用这些凭据。

$mysqli = mysqli_init();
$mysqliConnected = $mysqli->real_connect($hostname, $user, $password, $database, $port, NULL, MYSQLI_CLIENT_SSL);
if (!$mysqliConnected) {
  die('连接错误: ' . $mysqli->connect_error);
}

echo '连接成功... ' . $mysqli->host_info . "\n";

$mysqli->close();

?>

使用 PHP 和 MySQLi（过程化风格）连接 MariaDB

<?php

$hostname = '<XXXXXX>.stackhero-network.com';
$port     = '<PORT>';
$user     = 'root';
$password = '<ROOT_PASSWORD>';
$database = 'root'; // 仅用于演示。最佳实践是通过 phpMyAdmin 创建您自己的数据库和用户，并使用这些凭据。

$mysqli = mysqli_init();
$mysqliConnected = mysqli_real_connect($mysqli, $hostname, $user, $password, $database, $port, NULL, MYSQLI_CLIENT_SSL);
if (!$mysqliConnected) {
  die('连接错误: ' . mysqli_connect_error($mysqli));
}

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

mysqli_close($mysqli);

?>

使用 PHP 和 PDO 连接 MariaDB

<?php

$hostname = '<XXXXXX>.stackhero-network.com';
$port     = '<PORT>';
$user     = 'root';
$password = '<ROOT_PASSWORD>';
$database = 'root'; // 仅用于演示。最佳实践是通过 phpMyAdmin 创建您自己的数据库和用户，并使用这些凭据。

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

$options = array(
  // 如果遇到 "Uncaught PDOException: PDO::__construct(): SSL operation failed with code 1. OpenSSL Error messages: error:0A000086:SSL routines::certificate verify failed" 错误，请确保 /etc/ssl/certs/ 目录下包含 CA 证书。
  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 '您已连接到数据库，版本为 ' . $version[0] . "\n";

?>

如何解决 "SSL operation failed with code 1" 错误

如果您看到如下错误：

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

很可能是因为 /etc/ssl/certs/ 目录缺少必要的 CA 证书。如果您有系统访问权限，可以参考以下方法安装：

在 Ubuntu 上，您可以运行：
```
apt-get install ca-certificates
```
在 Alpine Linux 上，您可以尝试：
```
apk add ca-certificates
```

如果您没有系统级访问权限，可以手动添加证书：

下载证书：https://letsencrypt.org/certs/isrgrootx1.pem
将 isrgrootx1.pem 文件放到您的 PHP 项目中。
注释掉 PDO::MYSQL_ATTR_SSL_CAPATH => '/etc/ssl/certs/' 这一行。
取消注释 PDO::MYSQL_ATTR_SSL_CA => 'isrgrootx1.pem' 这一行。

如何解决 "Fatal error: Uncaught Error: Undefined constant PDO::MYSQL_ATTR_SSL_CAPATH"

如果您看到如下错误：

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

或类似提示 PDO MySQL 属性常量未定义的信息，说明您的 PDO 安装可能没有包含 MySQL 支持。

在 Ubuntu/Debian 上

您可以通过以下命令安装所需的 PHP MySQL 扩展：

sudo apt-get install php-mysql

如果您使用 Docker

为确保 MySQL 支持可用，可以在 Dockerfile 中添加如下内容：

RUN docker-php-ext-install pdo pdo_mysql


### 在 Symfony 和 Doctrine 中使用 MariaDB

首先，编辑您的 `.env` 文件，设置 `DATABASE_URL` 变量如下：

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


接着，更新 `config/packages/doctrine.yaml` 文件，设置驱动和选项：

```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

如何修复 "SSL operation failed with code 1" 错误

如果遇到如下错误：

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

很可能是您的系统没有安装 CA 证书。您可以通过以下方式安装：

在 Ubuntu/Debian 上，运行：
```
sudo apt-get install ca-certificates
```
在 Alpine Linux 上，尝试：
```
apk add ca-certificates
```

如果无法在系统范围内安装 CA 证书，可以手动添加：

下载证书：https://letsencrypt.org/certs/isrgrootx1.pem
将 isrgrootx1.pem 文件放到您的 Symfony 项目中。

更新 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

在 Laravel 中使用 MariaDB

要在 Laravel 中配置 MariaDB，请打开 config/database.php 并按如下方式更新 mysql 配置：

'mysql' => [
  'driver'   => 'mysql',
  'host'     => env('STACKHERO_MARIADB_HOST'),
  'port'     => env('STACKHERO_MARIADB_PORT'),
  'username' => env('STACKHERO_MARIADB_USER'),
  'password' => env('STACKHERO_MARIADB_PASSWORD'),
  'database' => env('STACKHERO_MARIADB_USER'),
  'charset'  => 'utf8mb4',
  'collation'=> 'utf8mb4_unicode_ci',
  'prefix'   => '',
  'prefix_indexes' => true,
  'strict'   => true,
  'engine'   => null,
  'sslmode'  => 'require',
  'options'  => extension_loaded('pdo_mysql')
    ? array_filter([
      // 如果遇到 SSL 错误，如 "Uncaught PDOException: PDO::__construct(): SSL operation failed with code 1. OpenSSL Error messages: error:0A000086:SSL routines::certificate verify failed"，请参考上方的故障排查步骤。
      PDO::MYSQL_ATTR_SSL_CAPATH => '/etc/ssl/certs/',
      // PDO::MYSQL_ATTR_SSL_CA => 'isrgrootx1.pem',
      PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => true,
    ])
    : [],
],

在 PHP CodeIgniter 中使用 MariaDB

在您的 database.php 文件中，可以进行如下配置：

$db['default'] = array(
  'hostname' => getenv('STACKHERO_MARIADB_HOST'),
  'port'     => getenv('STACKHERO_MARIADB_PORT'),
  'username' => getenv('STACKHERO_MARIADB_USER'),
  'password' => getenv('STACKHERO_MARIADB_PASSWORD'),
  'database' => getenv('STACKHERO_MARIADB_USER'), // 按惯例，数据库名与用户名一致。
  'dbdriver' => 'mysqli',
  'dbprefix' => '',
  'pconnect' => TRUE,
  'char_set' => 'utf8',
  'dbcollat' => 'utf8_general_ci',
  'encrypt'  => array() // 重要：启用 TLS 加密
);

通过环境变量在 PHP 中连接 MariaDB

推荐的做法是将凭据存储在环境变量中，而不是硬编码在代码里。您可以这样获取：

$hostname = getenv('STACKHERO_MARIADB_HOST');
$port     = getenv('STACKHERO_MARIADB_PORT');
$user     = getenv('STACKHERO_MARIADB_USER');
$password = getenv('STACKHERO_MARIADB_PASSWORD');
$database = getenv('STACKHERO_MARIADB_USER'); // 按惯例，数据库名与用户名一致。

在 WordPress 中使用 MariaDB

将 WordPress 连接到 Stackhero for MariaDB 非常简单。在您的 wp-config.php 文件中，设置以下数据库参数：

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

// 启用 TLS 加密（也称为 SSL）
define('MYSQL_CLIENT_FLAGS', MYSQLI_CLIENT_SSL);

关键步骤是启用 TLS 加密（有时称为 SSL）。如果未启用，连接将无法正常工作。

在 Node.js 中使用 MariaDB

如果您使用 Node.js，可以尝试带有 Promise 支持的 mysql2 包。安装方法如下：

npm install mysql2

以下是一个可供参考的示例：

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

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

  // 如果数据库不存在则创建
  await db.query('CREATE DATABASE IF NOT EXISTS stackherotest');

  // 如果 users 表不存在则创建
  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;'
  );

  // 插入一个示例用户
  await db.query(
    'INSERT INTO `stackherotest`.`users` (`userId`, `name`, `address`, `email`) VALUES ?',
    [
      [
        Math.round(Math.random() * 100000), // 生成 userId
        'User name',                         // name
        'User address',                      // address
        '[email protected]'                     // email
      ]
    ]
  );

  // 统计表中的用户数量
  const [usersCount] = await db.query('SELECT COUNT(*) AS `cpt` FROM `stackherotest`.`users`');
  console.log(`当前 "users" 表中有 ${usersCount[0].cpt} 条记录`);

  // 关闭连接
  await db.end();

})().catch(error => {
  console.error('');
  console.error('发生错误！');
  console.error(error);
  process.exit(1);
});

在 Node.js/NestJS/TypeORM 中使用 MariaDB

对于 Node.js、NestJS 或 TypeORM，您可以通过添加 ssl 选项来启用 SSL：

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

在 Prisma 中使用 MariaDB

要通过 Prisma 连接 MariaDB，只需在连接 URL 中添加 sslaccept=strict。例如，若以 "root" 用户连接 "root" 数据库：

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

在 Django 中使用 MariaDB

如果尚未安装，可以通过以下命令安装 mysqlclient 模块以连接 Django 到 MariaDB：

pip install mysqlclient

如果安装时遇到 Exception: Can not find valid pkg-config name 错误，您可能需要先安装 libmysqlclient 包。对于 Ubuntu/Debian：
apt-get update && apt-get install --no-install-recommends -y libmysqlclient-dev

测试连接时，您可以直接在 settings.py 中填写凭据。仅用于测试，生产环境请勿硬编码凭据。

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>'
  }
}

请注意：此示例仅用于测试。生产环境请勿使用硬编码凭据。

确认连接无误后，建议将凭据存储在环境变量中。如果您使用 django-environ，可通过以下方式安装：

pip install django-environ

然后更新 settings.py：

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

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

然后，在与 settings.py 同一目录下创建或更新 .env 文件：

STACKHERO_MARIADB_HOST=<XXXXXX>.stackhero-network.com
STACKHERO_MARIADB_PORT=<PORT>
STACKHERO_MARIADB_ROOT_PASSWORD=<ROOT_PASSWORD>

最后，为了保证凭据安全，将 .env 添加到 .gitignore：

echo ".env" >> .gitignore

在 Java/Spring 中连接 MariaDB

要将 Spring 应用连接到 MariaDB，可以通过设置 SPRING_DATASOURCE_URL 环境变量，使用 jdbc: 前缀。例如：

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

在 Groovy/Grails 中连接 MariaDB

以下是 Grails 应用连接 MariaDB 的配置示例：

dataSource {
  pooled = true
  driverClassName = "com.mysql.cj.jdbc.Driver"
  dialect = org.hibernate.dialect.MySQL8Dialect
  // 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" // 请将 '/root' 替换为实际数据库名。
      username = "root" // 建议为您的应用创建专用用户。
      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"
      }
    }
  }
}

通过 phpMyAdmin 创建 MariaDB 用户

为提升安全性，建议为您的应用创建专用用户，而不是使用 "root" 用户。您可以通过 phpMyAdmin 轻松完成：

在 phpMyAdmin 顶部点击 User accounts。
点击 Add user account。
填写表单：
- 选择一个用户名（通常为您的应用名称）。
- 点击 Generate password 生成强密码，并复制。
- 勾选 Create database with same name and grant all privileges。

提交后，系统会为您创建新用户及同名数据库。

MariaDB 与 MySQL 的区别

MariaDB 是 MySQL 的一个独立分支（fork），由开源社区在 2010 年 Oracle 收购 MySQL 后创建。对于大多数使用场景，MariaDB 和 MySQL 在功能和兼容性方面非常接近。