رفع خطای SQLSTATE[HY000] [2002] Connection refused | راهنمای کامل ۱۴۰۵

اگر با پیام خطای SQLSTATE[HY000] [2002] Connection refused روبه‌رو شده‌اید، بدانید که این یکی از رایج‌ترین مشکلات فنی در پروژه‌های PHP، وردپرس و لاراول است. این خطا دقیقاً به این معناست که اپلیکیشن شما نمی‌تواند به سرور MySQL متصل شود و اگر سریع رفع نشود، می‌تواند کل سایت یا اپلیکیشن شما را از دسترس خارج کند.

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

خطای SQLSTATE[HY000] [2002] دقیقاً چیست؟

این خطا یک خطای اتصال به دیتابیس MySQL است که از لایه PDO یعنی PHP Data Objects برمی‌خیزد. کد HY000 یک کد خطای عمومی در PDO است و عدد 2002 به معنای Connection refused یعنی اتصال رد شد می‌باشد.

به زبان ساده: PHP یا فریمورکی مثل لاراول سعی کرده به MySQL وصل شود، اما MySQL یا در دسترس نیست یا مشخصات اتصال اشتباه است.

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

دلایل اصلی بروز خطای Connection refused در MySQL

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

روش‌های رفع خطای SQLSTATE[HY000] [2002]

۱. بررسی وضعیت سرویس MySQL

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

برای بررسی وضعیت سرویس در سیستم‌عامل اوبونتو یا دبیان، از ترمینال دستور بررسی وضعیت systemctl برای سرویس mysql استفاده کنید. در CentOS یا RHEL نام سرویس mysqld است.

اگر سرویس متوقف بود، آن را با دستور start در systemctl راه‌اندازی کنید. برای اینکه MySQL بعد از هر ریبوت سرور هم خودکار اجرا شود، دستور enable را برای آن اعمال کنید.

اگر MySQL به‌درستی راه‌اندازی نشد، لاگ‌های خطا را در مسیر var/log/mysql/error.log بررسی کنید تا دلیل دقیق مشکل مشخص شود.

۲. بررسی و تصحیح آدرس هاست

یکی از رایج‌ترین دلایل این خطا، سردرگمی بین localhost و آدرس IP محلی یعنی 127.0.0.1 است. این دو ظاهراً یکی به نظر می‌رسند اما از نظر فنی متفاوت عمل می‌کنند:

• localhost از Unix Socket برای اتصال استفاده می‌کند
• 127.0.0.1 از پروتکل TCP/IP استفاده می‌کند

اگر MySQL روی socket پیکربندی نشده باشد، localhost کار نمی‌کند و باید از آدرس IP محلی استفاده کنید.

در PHP ساده: در رشته DSN مقدار host را برابر با 127.0.0.1 و port را برابر با 3306 قرار دهید.

در لاراول در فایل env. مقدار DB_HOST را از localhost به 127.0.0.1 تغییر دهید و DB_PORT را روی 3306 بگذارید.

در وردپرس در فایل wp-config.php مقدار ثابت DB_HOST را به 127.0.0.1 تغییر دهید.

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

۳. بررسی پورت MySQL

پورت پیش‌فرض MySQL عدد 3306 است. اما در برخی سرورها یا محیط‌های Docker ممکن است این پورت تغییر کرده باشد.

برای بررسی پورت فعلی، از دستور netstat یا ss با فیلتر روی mysql استفاده کنید. اگر پورت متفاوت بود، آن را در فایل env. لاراول در بخش DB_PORT یا در رشته اتصال PHP اصلاح کنید.

۴. رفع خطای اتصال دیتابیس در وردپرس

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

مرحله اول: فایل wp-config.php را در root سایت باز کنید. چهار مقدار اصلی را بررسی کنید: نام دیتابیس در DB_NAME، نام کاربری در DB_USER، رمز عبور در DB_PASSWORD و آدرس سرور در DB_HOST.

مرحله دوم: از طریق phpMyAdmin یا SSH با همین اطلاعات سعی کنید وارد دیتابیس شوید تا مطمئن شوید اطلاعات درست است.

مرحله سوم: اگر از هاست اشتراکی استفاده می‌کنید، توجه داشته باشید که در بسیاری از هاست‌های ایرانی آدرس MySQL نه localhost است و نه 127.0.0.1 بلکه یک آدرس اختصاصی مثل mysql.yourhost.com است. این آدرس را از پنل cPanel یا پشتیبانی هاست دریافت کنید.

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

همچنین اگر اخیراً مقاله آموزش رفع خطای Error 524 Cloudflare در وردپرس را خوانده‌اید، می‌دانید که بسیاری از خطاهای سرور از همین مشکلات زیرساختی ریشه می‌گیرند.

۵. رفع ارور SQLSTATE در لاراول

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

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

دستور اول config:clear کش تنظیمات را پاک می‌کند. دستور دوم cache:clear کش کلی را پاک می‌کند. دستور سوم config:cache تنظیمات را دوباره ذخیره می‌کند.

قدم دوم: اتصال به دیتابیس را مستقیم تست کنید. دستور artisan db:show وضعیت اتصال را نشان می‌دهد. همچنین می‌توانید از Tinker برای تست مستقیم PDO استفاده کنید.

قدم سوم: فایل env. را با دقت بررسی کنید. یک اشتباه رایج وجود فاصله ناخواسته در ابتدا یا انتهای مقادیر است. مثلاً اگر بعد از علامت مساوی در DB_HOST یک فاصله وجود داشته باشد، لاراول نمی‌تواند به دیتابیس وصل شود.

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

۶. رفع خطا در محیط Docker

اگر MySQL و اپلیکیشن شما در Container های جداگانه Docker هستند، نباید از localhost یا 127.0.0.1 استفاده کنید. در Docker هر Container آدرس IP مجزا دارد و Container های مختلف از طریق نام سرویس با هم ارتباط برقرار می‌کنند.

در فایل docker-compose.yml مقدار DB_HOST را برابر با نام سرویس MySQL قرار دهید؛ مثلاً اگر سرویس دیتابیس شما نام db دارد، در فایل env. باید بنویسید DB_HOST=db.

این یکی از رایج‌ترین اشتباهاتی است که توسعه‌دهندگان تازه‌کار در Docker مرتکب می‌شوند و حل آن بسیار ساده است.

۷. بررسی مجوزهای کاربر دیتابیس

گاهی کاربر MySQL وجود دارد اما مجوز اتصال از آدرس مشخصی را ندارد. برای بررسی وارد محیط MySQL شوید و دستور SHOW GRANTS را برای کاربر مورد نظر اجرا کنید.

اگر کاربر مجوز کافی نداشت، با دستور GRANT و مشخص کردن نام دیتابیس، نام کاربر و آدرس مجاز، دسترسی لازم را بدهید. سپس دستور FLUSH PRIVILEGES را اجرا کنید تا تغییرات اعمال شوند.

۸. بررسی فایروال و دسترسی به پورت ۳۳۰۶

در سرورهای VPS یا ددیکیتد، فایروال ممکن است پورت MySQL را مسدود کرده باشد. وضعیت UFW را در اوبونتو با دستور ufw status بررسی کنید و در صورت نیاز اجازه دسترسی داخلی به پورت 3306 را بدهید.

اگر از سرور ابری ایرانی مثل آروان‌کلاد یا لیارا استفاده می‌کنید، Security Group یا Firewall پنل مدیریت را هم بررسی کنید.

۹. بررسی و تنظیم bind-address در MySQL

تنظیم bind-address در فایل پیکربندی MySQL مشخص می‌کند که MySQL روی کدام IP گوش می‌دهد. این فایل معمولاً در مسیر etc/mysql/mysql.conf.d/mysqld.cnf قرار دارد.

اگر مقدار bind-address روی 127.0.0.1 باشد، MySQL فقط اتصال‌های محلی را می‌پذیرد که برای اکثر موارد درست است. اگر می‌خواهید از IP خارجی هم وصل شوید، مقدار را به 0.0.0.0 تغییر دهید؛ اما این کار را فقط با فایروال مناسب انجام دهید.

بعد از هر تغییر در فایل پیکربندی، سرویس MySQL را ری‌استارت کنید.

۱۰. رفع خطا در هاست اشتراکی با cPanel

در هاست‌های اشتراکی با cPanel معمولاً دیتابیس باید از طریق بخش MySQL Databases در cPanel ساخته شود و کاربر باید به دیتابیس Assign شده باشد.

مراحل بررسی در cPanel به این شکل است:

• وارد cPanel شوید و به بخش MySQL Databases بروید
• مطمئن شوید دیتابیس با نام درست وجود دارد
• مطمئن شوید کاربر به دیتابیس اضافه شده است
• آدرس MySQL Host را از همین بخش یا از پشتیبانی هاست دریافت کنید

جدول عیب‌یابی سریع

تأثیر این خطا روی سئو سایت

اگر در حوزه سئو تکنیکال فعالیت می‌کنید، می‌دانید که خطاهای دیتابیس مستقیماً روی دسترس‌پذیری سایت و Crawl Budget تأثیر می‌گذارند. هر چه سایت بیشتر Down باشد، رتبه گوگل آسیب بیشتری می‌بیند.

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

سوالات متداول

۱. چرا خطای SQLSTATE[HY000] [2002] بعد از ری‌استارت سرور ظاهر می‌شود؟
چون MySQL به‌صورت خودکار بالا نیامده. دستور enable در systemctl برای سرویس mysql را اجرا کنید تا MySQL بعد از هر ری‌استارت خودکار اجرا شود.

۲. تفاوت خطای Connection refused و Connection timed out چیست؟
Connection refused یعنی سرور فعالانه اتصال را رد کرد که نشانه خاموش بودن MySQL یا بسته بودن پورت است. Connection timed out یعنی پاسخی دریافت نشد که معمولاً مشکل شبکه یا فایروال است.

۳. آیا این خطا باعث از دست رفتن اطلاعات دیتابیس می‌شود؟
خیر. این خطا فقط مشکل اتصال است نه خرابی دیتابیس. داده‌های شما سالم هستند.

۴. در لاراول بعد از تغییر فایل env. همچنان خطا می‌دهد، چرا؟
چون لاراول تنظیمات را cache کرده. دستورات config:clear و config:cache را در artisan اجرا کنید.

۵. آیا این خطا در نسخه‌های مختلف MySQL فرق می‌کند؟
خیر. این خطا مربوط به لایه اتصال است و در هر نسخه MySQL ممکن است رخ دهد.

۶. این خطا در سایت‌های وردپرسی چه نشانه‌ای دارد؟
معمولاً صفحه سفید یا پیام «خطا در ایجاد اتصال به پایگاه داده» نمایش داده می‌شود.

۷. آیا می‌توان بدون دسترسی SSH این خطا را رفع کرد؟
بله. از طریق phpMyAdmin در cPanel، فایل‌منیجر برای ویرایش فایل‌های پیکربندی و پشتیبانی هاست می‌توان اقدام کرد.

۸. اگر در Docker این خطا بدهد، آیا باید Container را حذف کنم؟
خیر. فقط نام هاست را در فایل env. به نام سرویس MySQL در docker-compose تغییر دهید و Container را ری‌استارت کنید.

۹. آیا این خطا روی سئو سایت تأثیر می‌گذارد؟
بله، مستقیماً. اگر سایت Down باشد گوگل‌بات نمی‌تواند صفحات را Crawl کند و رتبه سایت کاهش می‌یابد.

۱۰. چطور از تکرار این خطا در آینده جلوگیری کنم؟
از یک سرویس مانیتورینگ مثل UptimeRobot استفاده کنید، MySQL را روی autostart تنظیم کنید و از هاست یا سرور با Uptime بالا استفاده کنید.

۱۱. آیا این خطا فقط برای MySQL است؟
کد خطای مشابه در MariaDB هم وجود دارد چون MariaDB یک fork از MySQL است. در PostgreSQL پیام متفاوتی نمایش داده می‌شود.

۱۲. در محیط لوکال XAMPP چطور رفع کنم؟
کنترل پنل XAMPP را باز کنید و وضعیت MySQL را بررسی کنید. اگر Start نمی‌شود، احتمالاً پورت 3306 توسط برنامه دیگری اشغال شده مثل اسکایپ. در این حالت پورت MySQL را در تنظیمات XAMPP تغییر دهید.

۱۳. آیا پیکربندی اشتباه دیتابیس باعث هک شدن سایت می‌شود؟
نه مستقیماً، اما تنظیم bind-address روی 0.0.0.0 بدون فایروال مناسب می‌تواند MySQL را در معرض اینترنت قرار دهد که بسیار خطرناک است. همیشه MySQL را پشت فایروال نگه دارید.

۱۴. خطای No such file or directory با Connection refused فرق دارد؟
بله. No such file or directory معمولاً مشکل Unix Socket است. راه‌حل تغییر localhost به 127.0.0.1 در تنظیمات است.

۱۵. اگر پس از همه این مراحل خطا ادامه داشت چه کنم؟
مشکل احتمالاً در سطح زیرساخت سرور است و نیاز به بررسی تخصصی دارد. در این حالت با تیم پشتیبانی فنی تماس بگیرید. تیم وب پایا آماده ارائه مشاوره رایگان در این زمینه است.

جمع‌بندی

خطای SQLSTATE[HY000] [2002] Connection refused در اکثر موارد با یکی از این اقدامات ساده رفع می‌شود:

• ری‌استارت سرویس MySQL و تنظیم autostart
• تغییر localhost به 127.0.0.1 در فایل تنظیمات
• بررسی و اصلاح اطلاعات دیتابیس در فایل پیکربندی
• پاک‌سازی کش در لاراول
• بررسی فایروال و پورت 3306

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

آیا به کمک فنی متخصص نیاز دارید؟

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

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

📞 همین حالا با کارشناسان وب پایا تماس بگیرید: 09197743400

برای مشاهده نمونه کارها، پروژه‌های طراحی سایت، نمونه کارهای سئو و نمونه کارهای اپلیکیشن را ببینید. همچنین برای پاسخ به سوالات رایج‌تر، صفحه FAQ وب پایا را بررسی کنید.