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

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

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

در این مقاله یاد می‌گیریم چگونه یک پایگاه داده PostgreSQL ایجاد کنیم، اتصال آن را در Laravel تنظیم کنیم، Migrationها را اجرا کنیم و در صورت بروز خطا، مشکل اتصال را مرحله‌به‌مرحله برطرف کنیم.

PostgreSQL چیست و چرا از آن در Laravel استفاده کنیم؟

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

برخی از قابلیت‌های مهم PostgreSQL عبارت‌اند از:

• پشتیبانی از تراکنش‌ها و کنترل یکپارچگی داده‌ها
• پشتیبانی از کلیدهای اصلی و خارجی
• قابلیت تعریف ایندکس‌های متنوع
• پشتیبانی از انواع داده پیشرفته، از جمله JSONB
• امکانات مناسب برای اجرای Queryهای پیچیده
• پشتیبانی از چندین اتصال هم‌زمان و کنترل دسترسی کاربران

در Laravel می‌توانید از PostgreSQL برای پروژه‌هایی مانند فروشگاه اینترنتی، سیستم مدیریت کاربران، پنل‌های مدیریتی، سامانه‌های SaaS و API استفاده کنید.

انتخاب PostgreSQL یا MySQL به نیازهای پروژه، ساختار داده‌ها، مهارت تیم و زیرساخت مورد استفاده بستگی دارد. هیچ‌کدام برای تمام پروژه‌ها الزاماً بهترین انتخاب نیستند.

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

پیش از شروع، باید موارد زیر را آماده کنید:

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

برای بررسی نسخه Laravel می‌توانید دستور زیر را اجرا کنید:

php artisan --version

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

php -v

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

Laravel برای ارتباط با PostgreSQL از درایور PDO استفاده می‌کند. در محیط PHP باید افزونه‌های pdo_pgsql و معمولاً pgsql فعال باشند.

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

php -m

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

PDO

pdo_pgsql

pgsql

وجود pdo_pgsql برای اتصال PDO به PostgreSQL اهمیت دارد. اگر این افزونه فعال نباشد، ممکن است هنگام اجرای دستورات دیتابیس با خطایی درباره نبودن درایور مواجه شوید.

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

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

برای اتصال Laravel، ابتدا باید یک پایگاه داده در PostgreSQL داشته باشید.

اگر PostgreSQL روی سیستم شما نصب شده باشد، می‌توانید از ابزارهایی مانند psql یا یک نرم‌افزار مدیریت دیتابیس برای ایجاد پایگاه داده استفاده کنید.

برای نمونه، با اتصال به PostgreSQL از طریق کاربر دارای مجوز مناسب، می‌توانید دستورات زیر را اجرا کنید:

CREATE USER laravel_user WITH PASSWORD 'StrongPasswordHere';



CREATE DATABASE laravel_db

    OWNER laravel_user;

در این مثال:

• laravel_user نام کاربر دیتابیس است.
• laravel_db نام پایگاه داده است.
• StrongPasswordHere رمز عبور نمونه است که باید با یک رمز قوی و اختصاصی جایگزین شود.

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

در محیط production، رمز عبور واقعی را در کد برنامه یا مخزن Git قرار ندهید. همچنین برای اتصال از راه دور، دسترسی شبکه و مجوزهای PostgreSQL را فقط به منابع موردنیاز محدود کنید.

مرحله دوم: تنظیم اتصال PostgreSQL در Laravel

Laravel اطلاعات اتصال پایگاه داده را معمولاً از متغیرهای محیطی فایل .env دریافت می‌کند.

فایل .env را در پوشه اصلی پروژه باز کنید و تنظیمات دیتابیس را به شکل زیر قرار دهید:

DB_CONNECTION=pgsql

DB_HOST=127.0.0.1

DB_PORT=5432

DB_DATABASE=laravel_db

DB_USERNAME=laravel_user

DB_PASSWORD=StrongPasswordHere

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

در این نمونه، مقدار pgsql به Laravel می‌گوید از اتصال PostgreSQL استفاده کند.

پورت پیش‌فرض PostgreSQL معمولاً 5432 است؛ اما اگر سرویس شما روی پورت دیگری تنظیم شده باشد، باید مقدار واقعی را وارد کنید.

اگر دیتابیس روی سرور دیگری قرار دارد، مقدار DB_HOST باید آدرس همان سرور یا نام میزبان قابل دسترسی از محیط اجرای Laravel باشد.

تنظیم اتصال در فایل database.php

فایل config/database.php تنظیمات اتصال‌های پایگاه داده را نگهداری می‌کند.

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

'pgsql' => [

    'driver' => 'pgsql',

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

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

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

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

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

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

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

    'prefix' => '',

    'prefix_indexes' => true,

    'search_path' => 'public',

    'sslmode' => 'prefer',

],

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

اگر اتصال pgsql از قبل وجود دارد، معمولاً نیازی به اضافه کردن مجدد آن نیست. کافی است متغیرهای محیطی را تنظیم کنید.

همچنین اگر از DB_URL برای تعریف اتصال کامل استفاده می‌کنید، مقدار آن را بررسی کنید؛ زیرا ممکن است تنظیمات URL در پیکربندی اتصال مورد استفاده قرار بگیرد.

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

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

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

php artisan config:clear

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

php artisan config:cache

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

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

مرحله چهارم: آزمایش اتصال Laravel به PostgreSQL

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

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

ابتدا اجرا کنید:

php artisan tinker

سپس در محیط Tinker بنویسید:

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

اگر اتصال برقرار شود، Laravel یک شیء PDO برمی‌گرداند. در صورت بروز خطا، پیام نمایش‌داده‌شده می‌تواند سرنخی برای شناسایی مشکل باشد.

برای خروج از Tinker می‌توانید از دستور زیر استفاده کنید:

exit

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

مرحله پنجم: اجرای Migration در PostgreSQL

یکی از مزیت‌های Laravel این است که می‌توانید ساختار جداول را با Migration مدیریت کنید.

برای مثال، اگر بخواهید جدول کاربران را در PostgreSQL ایجاد کنید، ابتدا Migration موجود در پروژه را بررسی کنید.

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

php artisan migrate:status

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

php artisan migrate

Laravel ساختار جداول را بر اساس Migrationهای پروژه ایجاد می‌کند.

اگر Migration جدیدی بسازید، می‌توانید از دستور زیر استفاده کنید:

php artisan make:migration create_products_table

برای نمونه، بدنه متد up() در Migration جدول محصولات می‌تواند به شکل زیر باشد:

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 یک جدول محصولات با ستون‌های شناسه، نام، قیمت، وضعیت فعال بودن و زمان ایجاد و به‌روزرسانی می‌سازد.

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

php artisan migrate

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

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

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

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

برای مثال، مدل Product را در نظر بگیرید:

namespace App\Models;



use Illuminate\Database\Eloquent\Model;



class Product extends Model

{

    protected $fillable = [

        'name',

        'price',

        'is_active',

    ];

}

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

use App\Models\Product;



$product = Product::create([

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

    'price' => 250000,

    'is_active' => true,

]);

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

$products = Product::query()

    ->where('is_active', true)

    ->orderBy('id', 'desc')

    ->get();

نکته مهم این است که Eloquent همچنان از تنظیم اتصال دیتابیس پروژه استفاده می‌کند. بنابراین اگر DB_CONNECTION=pgsql تنظیم شده باشد و اتصال دیگری برای مدل تعریف نکرده باشید، این Queryها از اتصال پیش‌فرض PostgreSQL استفاده خواهند کرد.

استفاده از چند اتصال دیتابیس در Laravel

گاهی ممکن است یک پروژه نیاز داشته باشد هم‌زمان به چند پایگاه داده متصل شود؛ برای مثال، اطلاعات اصلی در PostgreSQL ذخیره شوند و یک دیتابیس دیگر برای یکپارچه‌سازی با سامانه‌ای قدیمی مورد استفاده قرار بگیرد.

در چنین شرایطی، می‌توانید چند اتصال را در config/database.php تعریف کنید و اتصال موردنیاز را برای مدل یا Query مشخص کنید.

برای نمونه، اگر اتصال PostgreSQL با نام pgsql تعریف شده باشد، می‌توانید از Query Builder استفاده کنید:

use Illuminate\Support\Facades\DB;



$products = DB::connection('pgsql')

    ->table('products')

    ->get();

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

protected $connection = 'pgsql';

این ویژگی را داخل کلاس مدل قرار دهید تا مدل از اتصال مشخص‌شده استفاده کند.

پیکربندی چند اتصال نیازمند مدیریت دقیق‌تر تراکنش‌ها و ساختار داده‌ها است. به‌ویژه اگر چند دیتابیس در یک عملیات تجاری دخیل باشند، نباید فرض کنید یک تراکنش معمولی Laravel به‌صورت خودکار تمام دیتابیس‌ها را با هم هماهنگ می‌کند.

خطاهای رایج اتصال Laravel به PostgreSQL

در ادامه چند خطای رایج را بررسی می‌کنیم که ممکن است هنگام راه‌اندازی پروژه با PostgreSQL مشاهده کنید.

خطای could not find driver

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

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

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

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

خطای Connection refused

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

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

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

در محیط Docker، مقدار 127.0.0.1 داخل کانتینر Laravel به خود همان کانتینر اشاره می‌کند، نه لزوماً به کانتینر PostgreSQL. در چنین شرایطی معمولاً باید از نام سرویس دیتابیس در شبکه Docker استفاده کنید.

خطای password authentication failed

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

نام کاربری، رمز عبور، نام دیتابیس و روش احراز هویت سرور را بررسی کنید.

اگر رمز عبور را در فایل .env تغییر داده‌اید، کش تنظیمات Laravel را نیز پاک کنید:

php artisan config:clear

همچنین مطمئن شوید رمز عبور واردشده با رمز واقعی کاربر در PostgreSQL یکسان است.

خطای database does not exist

این خطا معمولاً به این معناست که پایگاه داده با نام تعیین‌شده وجود ندارد یا Laravel به سرور دیگری متصل شده است.

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

خطای permission denied

اگر اتصال برقرار می‌شود اما اجرای Migration یا عملیات نوشتن با خطای مجوز مواجه می‌شود، باید مجوزهای کاربر PostgreSQL را بررسی کنید.

کاربر دیتابیس باید برای عملیات موردنیاز پروژه، مانند ایجاد جدول، خواندن اطلاعات یا درج و به‌روزرسانی رکوردها، مجوز مناسب داشته باشد.

در محیط production از اعطای دسترسی‌های مدیریتی غیرضروری به کاربر برنامه خودداری کنید.

نکات مهم هنگام استفاده از PostgreSQL در محیط production

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

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

همچنین اگر پروژه شما قبلاً با MySQL توسعه داده شده است، تغییر مقدار DB_CONNECTION به pgsql به‌تنهایی برای مهاجرت کامل کافی نیست. باید داده‌ها، Migrationها، Queryهای اختصاصی، نوع ستون‌ها و وابستگی‌های پروژه را نیز بررسی کنید.

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

آیا Laravel از PostgreSQL پشتیبانی می‌کند؟

بله. Laravel از طریق درایور pgsql و لایه ارتباطی PDO می‌تواند به PostgreSQL متصل شود. برای این کار باید افزونه PHP موردنیاز فعال و اطلاعات اتصال صحیح تنظیم شده باشند.

آیا برای استفاده از PostgreSQL باید کدهای Eloquent را تغییر دهیم؟

در بسیاری از موارد، کدهای معمول Eloquent بدون تغییر قابل استفاده هستند. بااین‌حال، Queryهای اختصاصی SQL، برخی انواع داده و ویژگی‌های وابسته به موتور دیتابیس ممکن است به تغییر نیاز داشته باشند.

آیا می‌توان از PostgreSQL در Laravel با Docker استفاده کرد؟

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

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

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

چگونه بفهمیم Laravel واقعاً به PostgreSQL متصل شده است؟

می‌توانید در محیط Tinker دستور DB::connection()->getPdo() را اجرا کنید. اگر اتصال برقرار باشد، شیء PDO برگردانده می‌شود؛ در غیر این صورت، خطای اتصال می‌تواند برای عیب‌یابی استفاده شود.

جمع‌بندی

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

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