ایجاد اولین اتصال

به HarborDB خوش آمدید! این راهنما شما را در مراحل ایجاد اولین اتصال PostgreSQL راهنمایی می‌کند. چه به یک پایگاه داده محلی در Mac خود متصل می‌شوید و چه به یک سرور از راه دور، HarborDB این فرآیند را ساده و امن می‌کند.

پیش‌نیازها

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

1. HarborDB نصب شده است (راهنمای نصب را ببینید)
2. سرور PostgreSQL در حال اجرا و قابل دسترسی است
3. جزئیات اتصال آماده است:
   • نام میزبان (Hostname) یا آدرس IP
   • شماره پورت (پیش‌فرض: 5432)
   • نام پایگاه داده
   • نام کاربری و رمز عبور
   • اختیاری: گواهی SSL در صورت نیاز

مرحله 1: اجرای HarborDB و دسترسی به اتصالات

1. HarborDB را باز کنید از پوشه Applications یا Launchpad
2. نوار کناری Connections را پیدا کنید در سمت چپ پنجره
3. روی دکمه "+" کلیک کنید یا به File → Add Connection بروید

مرحله 2: تکمیل جزئیات اتصال

دیالوگ اتصال چندین فیلد برای تکمیل دارد:

اطلاعات پایه

• Name: نام دوستانه برای این اتصال (مثلاً "Local Development"، "Production Server")
• Host: آدرس سرور PostgreSQL
  • پایگاه داده محلی: localhost یا 127.0.0.1
  • سرور از راه دور: آدرس IP یا نام میزبان (مثلاً db.example.com)
• Port: پورت PostgreSQL (پیش‌فرض: 5432)
• Database: پایگاه داده خاصی که می‌خواهید به آن متصل شوید
• Username: نام کاربری PostgreSQL شما
• Password: رمز عبور PostgreSQL شما

گزینه‌های پیشرفته (اختیاری)

• Schema: اسکیمای ترجیحی (پیش‌فرض: public)
• SSL Mode: بر اساس پیکربندی سرور خود انتخاب کنید:
  • prefer: در صورت امکان از SSL استفاده کنید
  • require: نیاز به اتصال SSL
  • verify-full: نیاز به SSL با اعتبارسنجی گواهی
• Timeout: زمان انقضای اتصال به ثانیه
• Application Name: شناسه سفارشی برای این اتصال

مرحله 3: تست اتصال

قبل از ذخیره، همیشه اتصال خود را تست کنید:

1. روی "Test Connection" در دیالوگ کلیک کنید
2. منتظر تأیید بمانید - باید پیام "Connection successful" را ببینید
3. هشدارها را بررسی کنید درباره SSL یا سایر تنظیمات

نتایج رایج تست

• ✅ موفق: آماده ذخیره و اتصال هستید
• ❌ ناموفق: پیام خطا را برای سرنخ‌ها بررسی کنید:
  • "Connection refused": سرور در حال اجرا نیست یا فایروال مسدود کرده است
  • "Authentication failed": نام کاربری/رمز عبور نادرست
  • "Database does not exist": نام پایگاه داده نادرست است

مرحله 4: ذخیره و ایمن‌سازی اتصال

گزینه‌های ذخیره رمز عبور

HarborDB ذخیره امن رمز عبور را ارائه می‌دهد:

• ذخیره در Keychain (توصیه می‌شود): رمز عبور رمزگذاری شده در macOS Keychain
• ذخیره در اتصال: رمز عبور با تنظیمات اتصال ذخیره می‌شود (کمتر امن)
• هر بار بپرس: در هر اتصال درخواست رمز عبور

انتخاب گزینه مناسب

| روش ذخیره‌سازی | امنیت | راحتی | بهترین برای | | --------------- | ---------- | ----------- | ---------------------------------------- | | macOS Keychain | 🔒 بالا | ⚡ بالا | استفاده روزانه، کامپیوترهای قابل اعتماد | | فایل اتصال | 🔒 متوسط | ⚡ بالا | راه‌اندازی سریع، تست | | هر بار بپرس | 🔒 بالاترین | ⚡ پایین | کامپیوترهای مشترک، امنیت بالا |

ذخیره اتصال

1. روش ذخیره رمز عبور را انتخاب کنید
2. روی "Save" کلیک کنید تا اتصال ذخیره شود
3. اتصال خود را پیدا کنید در نوار کناری Connections
4. دوبار کلیک کنید برای اتصال

مرحله 5: اتصال و کاوش

پس از اتصال، می‌توانید:

ناوبری در پایگاه داده

• اتصال را باز کنید تا پایگاه‌های داده را ببینید
• اسکیماها و جداول را مرور کنید در نوار کناری
• روی جداول کلیک راست کنید برای اقدامات سریع:
  • مشاهده ساختار جدول
  • پیش‌نمایش 100 ردیف اول
  • تولید کوئری SELECT

اقدامات شروع سریع

1. ویرایشگر کوئری را باز کنید: روی آیکون SQL کلیک کنید یا ⌘ + N فشار دهید

2. یک کوئری تست اجرا کنید:

   SELECT version();
   

3. رابط کاربری را کاوش کنید: با تب‌ها، پنل‌ها و ابزارها آشنا شوید

مدیریت اتصال

سازماندهی اتصالات متعدد

با اضافه کردن اتصالات بیشتر، آنها را سازماندهی کنید:

• موارد مورد علاقه: اتصالات پرکاربرد را با ستاره علامت‌گذاری کنید
• گروه‌ها: بر اساس پروژه، محیط یا تیم سازماندهی کنید
• کدگذاری رنگی: از برچسب‌ها یا قراردادهای نام‌گذاری استفاده کنید

ویرایش اتصالات موجود

1. روی اتصال کلیک راست کنید در نوار کناری
2. "Edit Connection" را انتخاب کنید
3. هر فیلدی را که نیاز دارد به‌روزرسانی کنید
4. تست کنید و ذخیره کنید

کپی کردن اتصالات

با کپی کردن اتصالات مشابه، در زمان صرفه‌جویی کنید:

1. روی اتصال مبدأ کلیک راست کنید
2. "Duplicate" را انتخاب کنید
3. فقط فیلدهای تغییر یافته را اصلاح کنید
4. به عنوان اتصال جدید ذخیره کنید

بهترین شیوه‌های امنیتی

امنیت رمز عبور

• هرگز رمزهای عبور Keychain را به اشتراک نگذارید
• از رمزهای عبور قوی برای کاربران PostgreSQL استفاده کنید
• رمزهای عبور را به طور دوره‌ای تغییر دهید
• از استفاده مجدد رمزهای عبور در سرورهای مختلف اجتناب کنید

امنیت اتصال

• از SSL برای اتصالات از راه دور استفاده کنید
• دسترسی‌های پایگاه داده را محدود کنید به عملیات ضروری
• از اتصالات فقط خواندنی برای گزارش‌گیری استفاده کنید
• به طور منظم لاگ‌های اتصال را ممیزی کنید

امنیت شبکه

• پیکربندی فایروال: فقط IPهای قابل اعتماد را مجاز کنید
• دسترسی VPN برای پایگاه‌های داده از راه دور
• تونل‌زنی SSH برای لایه‌های امنیتی اضافی

سناریوهای رایج اتصال

PostgreSQL محلی (نصب شده از طریق Homebrew)

Name: Local PostgreSQL
Host: localhost
Port: 5432
Database: postgres
Username: your_username
Password: [Keychain]

کانتینر Docker PostgreSQL

Name: Docker Dev DB
Host: localhost
Port: 5432  # یا پورت سفارشی اگر متفاوت map شده باشد
Database: app_database
Username: postgres
Password: postgres_password

Amazon RDS PostgreSQL

Name: AWS Production
Host: your-db-instance.region.rds.amazonaws.com
Port: 5432
Database: production_db
Username: app_user
SSL Mode: verify-full

Google Cloud SQL

Name: GCP Cloud SQL
Host: /cloudsql/project:region:instance
Port: 5432
Database: cloud_db
SSL Mode: require

رفع مشکلات اتصال

"Cannot Connect to Server"

1. تأیید کنید که PostgreSQL در حال اجرا است:

   # در Terminal
   pg_isready -h localhost -p 5432
   

2. تنظیمات فایروال را بررسی کنید:

   • فایروال macOS (System Preferences → Security & Privacy)
   • قوانین فایروال شبکه

3. اتصال شبکه را تست کنید:

   # در Terminal
   ping your-server-address
   telnet your-server-address 5432
   

"Password Authentication Failed"

1. روش احراز هویت PostgreSQL را بررسی کنید:

   • فایل pg_hba.conf را مشاهده کنید
   • از احراز هویت md5 یا scram-sha-256 اطمینان حاصل کنید

2. در صورت نیاز رمز عبور را بازنشانی کنید:

   ALTER USER username WITH PASSWORD 'new_password';
   

3. تأیید کنید که کاربر دسترسی به پایگاه داده دارد:

   -- به عنوان superuser متصل شوید
   \du  -- لیست کاربران
   \l   -- لیست پایگاه‌های داده
   

خطاهای اتصال SSL/TLS

1. نیازمندی‌های SSL را بررسی کنید:

   • سرور ممکن است نیاز به حالت SSL خاصی داشته باشد
   • گواهی ممکن است نیاز به import داشته باشد

2. حالت SSL را تنظیم کنید در تنظیمات اتصال

3. گواهی را import کنید اگر از حالت verify-full استفاده می‌کنید

نکات عملکرد

Connection Pooling

• اتصالات را باز نگه دارید برای استفاده مکرر
• اتصالات استفاده نشده را ببندید برای آزادسازی منابع
• از connection pooling استفاده کنید برای برنامه‌ها

بهینه‌سازی شبکه

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

مراحل بعدی

اکنون که متصل شده‌اید:

1. مبانی کوئری را کاوش کنید - نوشتن و اجرای کوئری‌های SQL را یاد بگیرید
2. ناوبری پایگاه داده - اسکیماها، جداول و روابط را کاوش کنید
3. صادرسازی داده‌ها - نتایج را به CSV یا JSON ذخیره کنید

دریافت کمک

اگر هنوز مشکل دارید:

1. راهنمای پشتیبانی ما را برای رفع عیب بیشتر بررسی کنید
2. سؤالات متداول را برای سؤالات رایج ببینید
3. با پشتیبانی تماس بگیرید برای کمک شخصی‌سازی شده