Cơ sở dữ liệu - Hướng dẫn sử dụng

iSPA CMS hỗ trợ đồng thời MySQL/MariaDB và PostgreSQL, phân chia theo domain.

Kiến trúc

Domain	Database	Biến cấu hình
CMS legacy (bài viết, sản phẩm, đơn hàng...)	MySQL / MariaDB	`DB_CONNECTION=mysql`
Game system (wallet, inventory, leaderboard...)	PostgreSQL 16	`GAME_DB_CONNECTION=pgsql`

Mặc định

Cài đặt mặc định sử dụng MySQL. PostgreSQL chỉ cần khi triển khai các module Game.

Cấu hình MySQL

Cấu hình mặc định trong .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ispa_cms
DB_USERNAME=root
DB_PASSWORD=

Docker Compose sử dụng MariaDB 10:

services:
  mysql:
    image: 'mariadb:10'
    ports:
      - '${FORWARD_DB_PORT:-3306}:3306'
    environment:
      MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}'
      MYSQL_DATABASE: '${DB_DATABASE}'

Cấu hình PostgreSQL

Biến môi trường cho PostgreSQL sử dụng prefix PTG_:

# Kích hoạt PostgreSQL cho game
GAME_DB_CONNECTION=pgsql

# PostgreSQL connection
PTG_HOST=127.0.0.1
PTG_PORT=5432
PTG_DATABASE=ispa_dev
PTG_USERNAME=ispa_dev_user
PTG_PASSWORD=
PTG_SEARCH_PATH=public
PTG_SSLMODE=prefer

Docker Compose với profile pgsql:

services:
  pgsql:
    image: 'postgres:16'
    profiles:
      - pgsql
    ports:
      - '${FORWARD_PGSQL_PORT:-5432}:5432'
    environment:
      POSTGRES_DB: '${DB_DATABASE}'
      POSTGRES_USER: '${DB_USERNAME}'
      POSTGRES_PASSWORD: '${DB_PASSWORD}'

Kích hoạt:

COMPOSE_PROFILES=pgsql docker-compose up

PHP Extension

Để kết nối PostgreSQL từ Docker, cần bật biến INSTALL_PGSQL=1 trong .env để cài extension PHP.

Driver-aware code

Migrations và commands trong iSPA CMS tự động phát hiện database driver để sử dụng cú pháp phù hợp:

Foreign key constraints: MySQL dùng SET FOREIGN_KEY_CHECKS=0, PostgreSQL dùng SET session_replication_role = replica.
UPDATE IGNORE: MySQL hỗ trợ native, PostgreSQL dùng ON CONFLICT DO NOTHING.
System info queries: MySQL dùng SHOW VARIABLES, PostgreSQL dùng SHOW hoặc pg_catalog.

// Ví dụ: driver-aware foreign key handling
if (config('database.default') === 'pgsql') {
    DB::statement('SET session_replication_role = replica');
} else {
    DB::statement('SET FOREIGN_KEY_CHECKS=0');
}

Config Laravel

Cấu hình kết nối trong config/database.php:

'pgsql' => [
    'driver'         => 'pgsql',
    'host'           => env('PTG_HOST', '127.0.0.1'),
    'port'           => env('PTG_PORT', '5432'),
    'database'       => env('PTG_DATABASE', 'forge'),
    'username'       => env('PTG_USERNAME', 'forge'),
    'password'       => env('PTG_PASSWORD', ''),
    'charset'        => 'utf8',
    'prefix'         => '',
    'search_path'    => env('PTG_SEARCH_PATH', 'public'),
    'sslmode'        => env('PTG_SSLMODE', 'prefer'),
],

PhpMyAdmin

Development environment cung cấp PhpMyAdmin trên port 8080:

services:
  phpmyadmin:
    image: phpmyadmin
    ports:
      - '8080:80'
    environment:
      PMA_HOST: mysql