آموزش اتصال Laravel به MySQL؛ تنظیم دیتابیس و اجرای Migration

پایگاه داده یکی از اجزای اصلی هر برنامه تحت وب است. در پروژه‌های Laravel، اطلاعاتی مانند کاربران، محصولات، سفارش‌ها، پرداخت‌ها و تنظیمات سیستم معمولاً در یک پایگاه داده ذخیره می‌شوند. به همین دلیل، آشنایی با نحوه اتصال Laravel به دیتابیس یکی از مهارت‌های ضروری برای توسعه‌دهندگان این فریم‌ورک است.

MySQL یکی از محبوب‌ترین سیستم‌های مدیریت پایگاه داده رابطه‌ای است که در بسیاری از وب‌سایت‌ها، فروشگاه‌های اینترنتی و برنامه‌های سازمانی استفاده می‌شود. Laravel نیز امکانات مناسبی برای اتصال به MySQL، مدیریت جداول و انجام عملیات ذخیره‌سازی و بازیابی اطلاعات در اختیار توسعه‌دهندگان قرار می‌دهد.

در این آموزش، از ایجاد پایگاه داده و تنظیم فایل .env شروع می‌کنیم و سپس اتصال را آزمایش می‌کنیم، Migrationها را اجرا می‌کنیم و با خطاهای رایج اتصال MySQL در Laravel آشنا می‌شویم.

MySQL چیست و چرا در Laravel استفاده می‌شود؟

MySQL یک سیستم مدیریت پایگاه داده رابطه‌ای است که اطلاعات را در قالب جدول‌ها، سطرها و ستون‌ها ذخیره می‌کند. این سیستم از زبان SQL برای اجرای Queryها استفاده می‌کند و امکاناتی مانند تعریف کلیدهای اصلی، کلیدهای خارجی، ایندکس‌ها و تراکنش‌ها را ارائه می‌دهد.

استفاده از MySQL در پروژه‌های Laravel مزایای مختلفی دارد:

• ابزارهای متنوع برای مدیریت و بررسی پایگاه داده
• پشتیبانی گسترده در سرویس‌های میزبانی وب
• سازگاری با بسیاری از ابزارهای توسعه PHP
• امکان مدیریت ارتباط میان جدول‌ها
• پشتیبانی از تراکنش‌ها و ایندکس‌گذاری
• مناسب برای بسیاری از فروشگاه‌های اینترنتی، سامانه‌های مدیریتی و برنامه‌های تحت وب

برای مثال، در یک فروشگاه اینترنتی می‌توانید اطلاعات کاربران، محصولات، دسته‌بندی‌ها و سفارش‌ها را در جدول‌های جداگانه ذخیره کنید و با استفاده از روابط میان آن‌ها، اطلاعات موردنیاز را بازیابی کنید.

پیش‌نیازهای اتصال Laravel به MySQL

قبل از شروع، مطمئن شوید موارد زیر آماده هستند:

1. یک پروژه Laravel نصب‌شده
2. یک سرور MySQL فعال
3. یک پایگاه داده و کاربر دارای مجوز دسترسی
4. افزونه PHP مربوط به MySQL
5. دسترسی به ترمینال پروژه

برای بررسی نسخه Laravel، دستور زیر را در پوشه اصلی پروژه اجرا کنید:

php artisan --version

برای مشاهده نسخه PHP نیز از دستور زیر استفاده کنید:

php -v

بررسی افزونه MySQL در PHP

Laravel برای اتصال به MySQL معمولاً از درایور PDO استفاده می‌کند. بنابراین، افزونه pdo_mysql باید در محیط PHP فعال باشد.

برای بررسی افزونه‌های فعال، دستور زیر را اجرا کنید:

php -m

در خروجی، به دنبال موارد زیر بگردید:

PDO

pdo_mysql

اگر pdo_mysql در فهرست وجود ندارد، باید آن را برای نسخه PHP مورد استفاده پروژه نصب یا فعال کنید.

توجه داشته باشید که نسخه PHP مورد استفاده در ترمینال ممکن است با نسخه PHP وب‌سرور متفاوت باشد. اگر اتصال از طریق Artisan موفق است اما سایت با خطای درایور مواجه می‌شود، تنظیمات PHP وب‌سرور را نیز بررسی کنید.

مرحله اول: ایجاد پایگاه داده MySQL

برای اتصال Laravel، ابتدا باید یک پایگاه داده در MySQL ایجاد کنید.

می‌توانید این کار را با ابزارهایی مانند phpMyAdmin، MySQL Workbench یا محیط خط فرمان MySQL انجام دهید.

برای نمونه، دستورات زیر یک پایگاه داده و یک کاربر اختصاصی ایجاد می‌کنند:

CREATE DATABASE laravel_db

    CHARACTER SET utf8mb4

    COLLATE utf8mb4_unicode_ci;



CREATE USER 'laravel_user'@'localhost'

    IDENTIFIED BY 'StrongPasswordHere';



GRANT ALL PRIVILEGES ON laravel_db.*

    TO 'laravel_user'@'localhost';

در این مثال:

• laravel_db نام پایگاه داده است.
• laravel_user نام کاربر دیتابیس است.
• StrongPasswordHere رمز عبور نمونه است.
• localhost مشخص می‌کند این حساب کاربری برای اتصال از میزبان محلی تعریف شده است.

این دستورات باید با کاربری اجرا شوند که مجوز ایجاد پایگاه داده و کاربر را دارد.

اگر Laravel روی سرور دیگری قرار دارد، باید حساب کاربری و مجوزهای دسترسی را متناسب با معماری شبکه تنظیم کنید. برای امنیت بیشتر، از باز کردن دسترسی دیتابیس برای تمام آدرس‌های IP خودداری کنید.

همچنین اگر از قبل پایگاه داده و کاربر مناسب دارید، نیازی به اجرای مجدد این دستورات نیست.

مرحله دوم: تنظیم اتصال MySQL در فایل env

پس از ایجاد پایگاه داده، باید اطلاعات اتصال را در فایل .env پروژه Laravel وارد کنید.

این فایل معمولاً در پوشه اصلی پروژه قرار دارد.

بخش مربوط به دیتابیس را به شکل زیر تنظیم کنید:

DB_CONNECTION=mysql

DB_HOST=127.0.0.1

DB_PORT=3306

DB_DATABASE=laravel_db

DB_USERNAME=laravel_user

DB_PASSWORD=StrongPasswordHere

هر متغیر کاربرد مشخصی دارد:

در این نمونه، مقدار mysql مشخص می‌کند Laravel از اتصال MySQL استفاده کند. پورت پیش‌فرض MySQL معمولاً 3306 است؛ البته ممکن است در سرور شما مقدار دیگری تنظیم شده باشد.

اگر MySQL روی همان سرور Laravel اجرا می‌شود، می‌توانید با توجه به تنظیمات سرویس از 127.0.0.1 استفاده کنید. اگر دیتابیس روی سرور دیگری قرار دارد، باید آدرس قابل دسترسی آن سرور را وارد کنید.

نکته امنیتی: فایل .env را در مخزن عمومی Git قرار ندهید و رمز عبور واقعی دیتابیس را در کدهای برنامه منتشر نکنید.

مرحله سوم: بررسی تنظیمات database.php

Laravel تنظیمات اتصال دیتابیس را در فایل زیر نگهداری می‌کند:

config/database.php

در پروژه‌های استاندارد Laravel، معمولاً اتصال MySQL از قبل تعریف شده است. نمونه‌ای از تنظیمات این اتصال به شکل زیر است:

'mysql' => [

    'driver' => 'mysql',

    'url' => env('DB_URL'),

    'host' => env('DB_HOST', '127.0.0.1'),

    'port' => env('DB_PORT', '3306'),

    'database' => env('DB_DATABASE', 'laravel'),

    'username' => env('DB_USERNAME', 'root'),

    'password' => env('DB_PASSWORD', ''),

    'unix_socket' => env('DB_SOCKET', ''),

    'charset' => env('DB_CHARSET', 'utf8mb4'),

    'collation' => env('DB_COLLATION', 'utf8mb4_unicode_ci'),

    'prefix' => '',

    'prefix_indexes' => true,

    'strict' => true,

    'engine' => null,

],

این نمونه برای آشنایی با ساختار تنظیمات است. جزئیات پیکربندی ممکن است بر اساس نسخه Laravel یا تنظیمات پروژه متفاوت باشند.

اگر اتصال mysql از قبل در فایل وجود دارد، معمولاً نیازی به تعریف مجدد آن نیست. ابتدا ساختار موجود را بررسی کنید و سپس در صورت نیاز تغییر دهید.

همچنین اگر از متغیر DB_URL برای تعریف کامل اتصال استفاده می‌کنید، مقدار آن را بررسی کنید؛ زیرا ممکن است بر نحوه دریافت اطلاعات اتصال اثر بگذارد.

مرحله چهارم: پاک کردن کش تنظیمات Laravel

Laravel می‌تواند تنظیمات برنامه را برای افزایش سرعت در حافظه کش ذخیره کند. به همین دلیل، تغییر فایل .env همیشه به این معنا نیست که تنظیمات جدید بلافاصله استفاده می‌شوند.

برای پاک کردن کش تنظیمات، دستور زیر را اجرا کنید:

php artisan config:clear

پس از آن، می‌توانید اتصال را آزمایش کنید.

در محیط production، پس از بررسی صحت تنظیمات، امکان ایجاد مجدد کش تنظیمات وجود دارد:

php artisan config:cache

بهتر است این دستور در فرایند انتشار برنامه اجرا شود.

همچنین در کدهای برنامه برای دریافت تنظیمات از config() استفاده کنید؛ زیرا پس از کش شدن تنظیمات، نباید به فراخوانی مستقیم env() در بخش‌های مختلف برنامه وابسته باشید.

مرحله پنجم: آزمایش اتصال Laravel به MySQL

پس از تنظیم فایل .env، بهتر است پیش از اجرای Migrationها، اتصال دیتابیس را آزمایش کنید.

یکی از ساده‌ترین روش‌ها استفاده از Laravel Tinker است.

در ترمینال اجرا کنید:

php artisan tinker

سپس دستور زیر را وارد کنید:

DB::connection()->getPdo();

اگر اتصال برقرار باشد، یک شیء PDO دریافت می‌کنید. اگر اتصال برقرار نشود، خطایی نمایش داده می‌شود که می‌تواند برای عیب‌یابی مفید باشد.

برای خروج از Tinker نیز بنویسید:

exit

اگر Tinker در پروژه شما نصب نیست، می‌توانید از یک تست موقت یا دستور Artisan سفارشی برای بررسی اتصال استفاده کنید.

مرحله ششم: اجرای Migration در MySQL

Migration یکی از امکانات مهم Laravel برای مدیریت ساختار پایگاه داده است. با استفاده از Migration می‌توانید ایجاد، تغییر و حذف جدول‌ها را در قالب فایل‌های قابل نسخه‌بندی مدیریت کنید.

برای مشاهده وضعیت Migrationها، دستور زیر را اجرا کنید:

php artisan migrate:status

سپس برای اجرای Migrationهای اجرا‌نشده از دستور زیر استفاده کنید:

php artisan migrate

اگر تنظیمات اتصال صحیح باشد و کاربر دیتابیس مجوزهای لازم را داشته باشد، Laravel جدول‌های تعریف‌شده در Migrationها را ایجاد می‌کند.

ساخت Migration جدید

برای ایجاد یک Migration جهت ساخت جدول محصولات، دستور زیر را اجرا کنید:

php artisan make:migration create_products_table

سپس فایل ایجادشده در پوشه database/migrations را باز کنید و کد زیر را در آن قرار دهید:

<?php



use Illuminate\Database\Migrations\Migration;

use Illuminate\Database\Schema\Blueprint;

use Illuminate\Support\Facades\Schema;



return new class extends Migration

{

    public function up(): void

    {

        Schema::create('products', function (Blueprint $table) {

            $table->id();

            $table->string('name');

            $table->decimal('price', 12, 2);

            $table->boolean('is_active')->default(true);

            $table->timestamps();

        });

    }



    public function down(): void

    {

        Schema::dropIfExists('products');

    }

};

این Migration جدول products را با ستون‌های زیر ایجاد می‌کند:

• id: شناسه هر محصول
• name: نام محصول
• price: قیمت محصول
• is_active: وضعیت فعال بودن محصول
• created_at و updated_at: زمان ایجاد و آخرین به‌روزرسانی رکورد

پس از ذخیره فایل، دستور زیر را اجرا کنید:

php artisan migrate

اکنون Laravel می‌تواند جدول محصولات را در پایگاه داده ایجاد کند.

در محیط production، پیش از اجرای Migrationهای تغییردهنده ساختار دیتابیس، از اطلاعات نسخه پشتیبان تهیه کنید و اثر تغییرات بر برنامه فعال را بررسی کنید.

مرحله هفتم: ذخیره و بازیابی اطلاعات با Eloquent

پس از ایجاد جدول، می‌توانید با استفاده از Eloquent ORM اطلاعات را ذخیره و بازیابی کنید.

برای نمونه، یک مدل به نام Product ایجاد کنید:

php artisan make:model Product

سپس مدل را به شکل زیر تنظیم کنید:

<?php



namespace App\Models;



use Illuminate\Database\Eloquent\Model;



class Product extends Model

{

    protected $fillable = [

        'name',

        'price',

        'is_active',

    ];

}

ویژگی fillable مشخص می‌کند کدام فیلدها می‌توانند از طریق عملیات انتساب گروهی مانند create() مقداردهی شوند.

اکنون می‌توانید یک محصول جدید ایجاد کنید:

use App\Models\Product;



$product = Product::create([

    'name' => 'محصول آزمایشی',

    'price' => 250000,

    'is_active' => true,

]);

برای دریافت محصولات فعال نیز می‌توانید از کد زیر استفاده کنید:

$products = Product::query()

    ->where('is_active', true)

    ->orderByDesc('id')

    ->get();

مزیت استفاده از Eloquent این است که در بسیاری از عملیات روزمره، نیازی به نوشتن مستقیم SQL ندارید. Laravel Query مناسب را تولید و اجرا می‌کند.

البته برای پروژه‌های واقعی باید اعتبارسنجی ورودی‌ها، مجوزهای دسترسی و قواعد تجاری را نیز پیاده‌سازی کنید؛ صرفاً تعریف مدل برای امن و کامل شدن عملیات کافی نیست.

تفاوت MySQL و PostgreSQL در پروژه‌های Laravel

Laravel از هر دو دیتابیس MySQL و PostgreSQL پشتیبانی می‌کند؛ اما این موضوع به معنای یکسان بودن تمام رفتارهای آن‌ها نیست.

انتخاب بین این دو دیتابیس به نوع پروژه و نیازهای آن بستگی دارد. برای مثال، ممکن است یک پروژه به قابلیت‌های خاص PostgreSQL نیاز داشته باشد، درحالی‌که پروژه‌ای دیگر به‌دلیل زیرساخت میزبانی یا تجربه تیم، با MySQL راحت‌تر توسعه داده شود.

آیا برای تغییر PostgreSQL به MySQL فقط باید env را تغییر دهیم؟

خیر. تغییر مقدار DB_CONNECTION به‌تنهایی برای مهاجرت کامل یک پروژه از PostgreSQL به MySQL کافی نیست.

در چنین شرایطی باید موارد زیر را بررسی کنید:

• ساختار و نوع ستون‌های جدول‌ها
• Queryهای نوشته‌شده به‌صورت SQL خام
• Migrationهای وابسته به ویژگی‌های اختصاصی دیتابیس
• توابع و عملگرهای مورد استفاده در Queryها
• ایندکس‌ها و محدودیت‌های دیتابیس
• داده‌های موجود و روش انتقال آن‌ها

برای مهاجرت بین دو دیتابیس، ابتدا برنامه را در یک محیط آزمایشی بررسی کنید و پس از اطمینان از صحت داده‌ها و عملکرد، تغییرات را به محیط اصلی منتقل کنید.

خطاهای رایج اتصال Laravel به MySQL و روش رفع آن‌ها

هنگام تنظیم اتصال ممکن است با خطاهای مختلفی مواجه شوید. در ادامه مهم‌ترین موارد را بررسی می‌کنیم.

خطای could not find driver

این خطا معمولاً زمانی نمایش داده می‌شود که درایور PDO موردنیاز برای MySQL در محیط PHP فعال نباشد.

برای رفع مشکل:

1. نسخه PHP مورد استفاده پروژه را بررسی کنید.
2. افزونه pdo_mysql را برای همان نسخه نصب یا فعال کنید.
3. در صورت نیاز، سرویس PHP-FPM یا وب‌سرور را مجدداً راه‌اندازی کنید.
4. با دستور php -m فعال بودن افزونه را بررسی کنید.

اگر خطا فقط در محیط وب مشاهده می‌شود، تنظیمات PHP وب‌سرور را نیز بررسی کنید.

خطای SQLSTATE[HY000] [2002] Connection refused

این خطا معمولاً به برقراری نشدن ارتباط با سرور MySQL مربوط است.

موارد زیر را بررسی کنید:

• آیا سرویس MySQL فعال است؟
• آیا DB_HOST صحیح است؟
• آیا پورت تنظیم‌شده در DB_PORT درست است؟
• آیا فایروال یا تنظیمات شبکه اتصال را مسدود کرده‌اند؟
• اگر از Docker استفاده می‌کنید، آیا Laravel و MySQL در شبکه مناسب قرار دارند؟

در Docker، مقدار 127.0.0.1 درون کانتینر Laravel به همان کانتینر اشاره می‌کند؛ نه لزوماً به کانتینر MySQL. معمولاً باید از نام سرویس دیتابیس در شبکه Docker استفاده کنید.

خطای Access denied for user

این خطا معمولاً به اطلاعات احراز هویت یا مجوزهای کاربر مربوط می‌شود.

موارد زیر را بررسی کنید:

• نام کاربری و رمز عبور صحیح باشند.
• کاربر به پایگاه داده موردنظر دسترسی داشته باشد.
• میزبان تعریف‌شده برای حساب MySQL با نوع اتصال سازگار باشد.
• پس از تغییر فایل .env، کش تنظیمات پاک شده باشد.

برای پاک کردن کش تنظیمات می‌توانید از دستور زیر استفاده کنید:

php artisan config:clear

توجه کنید که در MySQL، حساب‌هایی مانند 'user'@'localhost' و 'user'@'%' لزوماً رفتار و سطح دسترسی یکسانی ندارند. بنابراین فقط تغییر رمز عبور همیشه مشکل را حل نمی‌کند.

خطای Unknown database

این خطا نشان می‌دهد پایگاه داده‌ای با نام تنظیم‌شده پیدا نشده است یا برنامه به سرور دیگری متصل شده است.

مقدار DB_DATABASE و DB_HOST را بررسی کنید و مطمئن شوید پایگاه داده روی همان سروری ایجاد شده که Laravel به آن متصل می‌شود.

تغییرات فایل env اعمال نمی‌شوند

اگر پس از تغییر اطلاعات دیتابیس همچنان از مقادیر قبلی استفاده می‌شود، احتمال دارد تنظیمات کش شده باشند.

دستور زیر را اجرا کنید:

php artisan config:clear

سپس اتصال را مجدداً آزمایش کنید. در محیط production نیز فرایند کش تنظیمات را مطابق روش انتشار پروژه انجام دهید.

نکات مهم برای استفاده از MySQL در محیط production

برای راه‌اندازی مطمئن پروژه Laravel در محیط عملیاتی، فقط برقراری اتصال کافی نیست. بهتر است موارد زیر را نیز رعایت کنید:

• برای برنامه یک کاربر اختصاصی با مجوزهای محدود تعریف کنید.
• رمز عبور دیتابیس را در کد منبع یا مخزن عمومی قرار ندهید.
• دسترسی شبکه به دیتابیس را فقط به میزبان‌های موردنیاز محدود کنید.
• پیش از تغییرات مهم ساختار، نسخه پشتیبان تهیه کنید.
• اجرای Migrationها را در فرایند انتشار برنامه مدیریت کنید.
• برای Queryهای پرتکرار، عملکرد و ایندکس‌ها را بررسی کنید.
• در پروژه‌های Docker، تنظیمات شبکه و آدرس سرویس‌ها را به‌درستی تعریف کنید.
• در برنامه‌های حساس، تراکنش‌ها را برای عملیات چندمرحله‌ای به‌درستی به کار ببرید.

همچنین اگر از چند اتصال دیتابیس استفاده می‌کنید، باید مشخص کنید هر مدل یا Query از کدام اتصال استفاده می‌کند و عملیات تراکنشی را متناسب با معماری برنامه طراحی کنید.

سؤالات متداول درباره اتصال Laravel به MySQL

آیا Laravel به‌صورت پیش‌فرض از MySQL پشتیبانی می‌کند؟

بله. Laravel به‌صورت استاندارد اتصال MySQL را پشتیبانی می‌کند. با این حال، باید سرور دیتابیس در دسترس باشد و افزونه pdo_mysql در محیط PHP فعال باشد.

چگونه اتصال Laravel به MySQL را تست کنیم؟

می‌توانید دستور php artisan tinker را اجرا کنید و سپس DB::connection()->getPdo() را وارد کنید. اگر اتصال برقرار باشد، شیء PDO برگردانده می‌شود.

آیا برای استفاده از MySQL باید جدول‌ها را دستی ایجاد کنیم؟

خیر. می‌توانید ساختار جدول‌ها را با Migration تعریف کنید و با اجرای php artisan migrate آن‌ها را در دیتابیس بسازید.

آیا می‌توان Laravel را به MySQL روی سرور دیگر متصل کرد؟

بله. باید آدرس سرور، پورت، مجوزهای کاربر و دسترسی شبکه را به‌درستی تنظیم کنید. همچنین بهتر است ارتباط میان برنامه و دیتابیس با رعایت الزامات امنیتی برقرار شود.

آیا MySQL برای فروشگاه اینترنتی مناسب است؟

بله. MySQL برای بسیاری از فروشگاه‌های اینترنتی و سامانه‌های مدیریت سفارش مناسب است. طراحی صحیح ساختار داده‌ها، ایندکس‌گذاری و مدیریت تراکنش‌ها در عملکرد و پایداری سیستم نقش مهمی دارند.

جمع‌بندی

اتصال Laravel به MySQL یکی از مراحل پایه‌ای توسعه برنامه‌های مبتنی بر لاراول است. برای انجام این کار باید پایگاه داده و کاربر مناسب ایجاد کنید، اطلاعات اتصال را در فایل .env قرار دهید، درایور PHP را بررسی کنید و سپس با اجرای Migrationها ساختار جدول‌ها را بسازید.

پس از برقراری اتصال، می‌توانید با استفاده از Eloquent اطلاعات را ذخیره، بازیابی و مدیریت کنید. رعایت اصول امنیتی، تهیه نسخه پشتیبان و بررسی Queryها نیز برای استفاده از دیتابیس در محیط production اهمیت زیادی دارد.