MySQL

این صفحه اتصال MySQL را به‌عنوان یک انبار داده (data warehouse) توضیح می‌دهد. برای استفاده از MySQL به‌عنوان پایگاه‌دادهٔ برنامهٔ متابیس (application database)، بخش پیکربندی پایگاه‌دادهٔ برنامهٔ متابیس را ببینید.

برای اضافه کردن یک اتصال پایگاه‌داده، روی آیکون چرخ‌دنده در بالا سمت راست کلیک کنید و به Admin settings > Databases > Add a database بروید.

نسخه‌های پشتیبانی‌شده

متابیس از قدیمی‌ترین نسخهٔ تحت پشتیبانی MySQL تا آخرین نسخهٔ پایدار آن پشتیبانی می‌کند. MySQL end-of-life dates را ببینید.

ویرایش جزئیات اتصال

می‌توانید هر زمان این تنظیمات را ویرایش کنید؛ فقط یادتان باشد تغییرات را ذخیره کنید.

Connection string

می‌توانید یک connection string اینجا paste کنید تا فیلدهای باقی‌مانده به‌طور خودکار پر شوند.

Display name

نام نمایشی پایگاه‌داده در رابط کاربری متابیس.

Host

آدرس IP پایگاه‌داده یا نام دامنهٔ آن (مثلاً esc.mydatabase.com).

Port

پورت پایگاه‌داده؛ مثلاً 3306.

Username

نام کاربری پایگاه‌داده برای اکانتی که می‌خواهید با آن به دیتابیس وصل شوید. می‌توانید چند اتصال مختلف به همان پایگاه‌داده بسازید که هرکدام از یک کاربر متفاوت با مجموعهٔ متفاوتی از سطوح دسترسی (privileges) استفاده می‌کنند.

Password

رمز عبوری که برای نام کاربری اتصال به پایگاه‌داده استفاده می‌کنید.

استفاده از اتصال امن (SSL)

می‌توانید زنجیرهٔ گواهی SSL سرور خود را اینجا paste کنید.

استفاده از SSH tunnel

راهنمای SSH tunneling را ببینید.

Unfold JSON Columns

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

اگر JSON unfolding را روشن گذاشته باشید، می‌توانید رفتار unfold کردن را برای هر ستون، در متادیتای جدول به‌صورت جداگانه تنظیم کنید.

گزینه‌های اضافی JDBC connection string

می‌توانید گزینه‌های اضافی را به connection stringی که متابیس برای اتصال به پایگاه‌داده استفاده می‌کند اضافه کنید.

اجرای دوبارهٔ پرس‌وجو برای اکتشاف ساده

اگر می‌خواهید کاربران قبل از اعمال هر Summarize یا فیلتر، روی Run (دکمهٔ play) کلیک کنند، این گزینه را روی OFF قرار دهید.

به‌طور پیش‌فرض، متابیس به محض انتخاب یک گزینهٔ گروه‌بندی از منوی Summarize یا یک شرط فیلتر از منوی drill-through، پرس‌وجو را اجرا می‌کند. اگر پایگاه‌دادهٔ شما کند است، بهتر است اجرای خودکار را غیرفعال کنید تا با هر کلیک، کوئری جدید اجرا نشود.

انتخاب زمان sync و scan

sync و scan را ببینید.

fingerprint دوره‌ای جدول‌ها

fingerprint دوره‌ای بار روی پایگاه‌دادهٔ شما را افزایش می‌دهد.

این گزینه را روی ON قرار دهید تا هر بار متابیس یک sync اجرا می‌کند، یک نمونه از مقادیر را اسکن کند.

پرس‌وجوی fingerprinting اولین ۱۰٬۰۰۰ ردیف هر ستون را بررسی می‌کند و بر اساس آن، تعداد مقادیر یکتا در هر ستون، و حداقل و حداکثر مقادیر ستون‌های عددی و زمانی و غیره را تخمین می‌زند. اگر این گزینه را روی OFF بگذارید، متابیس فقط یک‌بار و در زمان راه‌اندازی، برای ستون‌ها fingerprint می‌سازد.

اتصال به سرورهای MySQL 8+

متابیس برای اتصال به سرورهای MySQL از درایور MariaDB استفاده می‌کند. این درایور از پلاگین احراز هویت پیش‌فرض MySQL 8 پشتیبانی نمی‌کند. برای اتصال، باید پلاگینی را که کاربر Metabase استفاده می‌کند تغییر دهید:

ALTER USER 'metabase'@'%' IDENTIFIED WITH mysql_native_password BY 'thepassword';

ناتوانی در ورود با credentialهای درست

چطور این مشکل را تشخیص بدهیم: متابیس هنگام اتصال به سرور MySQL شما با پیام خطای «Looks like the username or password is incorrect» شکست می‌خورد، اما شما مطمئن هستید نام کاربری و رمز عبور درست‌اند. ممکن است کاربر MySQL را با host مجاز متفاوتی نسبت به میزبان واقعی‌ای که از آن متصل می‌شوید ساخته باشید.

برای مثال، اگر سرور MySQL در یک کانتینر Docker اجرا می‌شود و کاربر metabase را با دستور CREATE USER 'metabase'@'localhost' IDENTIFIED BY 'thepassword'; ساخته باشید، مقدار localhost به کانتینر Docker رِزولوشن می‌شود، نه ماشین میزبان، و در نتیجه دسترسی رد می‌شود.

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

Access denied for user 'metabase'@'172.17.0.1' (using password: YES).

به hostname 172.17.0.1 (در این مثال، یک IP شبکه Docker) و عبارت using password: YES در انتهای پیام توجه کنید.

همین پیام خطا را هنگام تلاش برای اتصال به MySQL با کلاینت خط فرمان هم مشاهده می‌کنید:
mysql -h 127.0.0.1 -u metabase -p

چطور این مشکل را برطرف کنیم: کاربر MySQL را با hostname درست دوباره بسازید:

CREATE USER 'metabase'@'172.17.0.1' IDENTIFIED BY 'thepassword';

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

CREATE USER 'metabase'@'%' IDENTIFIED BY 'thepassword';

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

GRANT SELECT ON targetdb.* TO 'metabase'@'172.17.0.1';
FLUSH PRIVILEGES;

و در نهایت، کاربر قبلی را حذف کنید:

DROP USER 'metabase'@'localhost';

اگر نمی‌توانید به پایگاه‌داده متصل شوید، اما کاربر، host و رمز عبور درست هستند، گزینهٔ trustServerCertificate=true را به گزینه‌های اضافی JDBC اضافه کنید. این گزینه به درایور متابیس می‌گوید به گواهی سرور حتی بدون روت‌سرتیفیکیت اعتماد کند و باید اتصال امن برقرار شود.

Sync رکوردهایی که شامل JSON هستند

متابیس "schema" JSON را بر اساس کلیدهای موجود در اولین ۵۰۰ ردیف جدول استنتاج می‌کند. فیلدهای JSON در MySQL schema صریح ندارند، بنابراین متابیس نمی‌تواند برای فهمیدن این‌که یک فیلد JSON چه کلیدهایی دارد فقط به متادیتای جدول تکیه کند. برای دور زدن نبود schema، متابیس اولین ۵۰۰ رکورد را می‌گیرد و JSON موجود در آن‌ها را parse می‌کند تا "schema" JSON را حدس بزند. دلیل این‌که متابیس خودش را به ۵۰۰ رکورد محدود می‌کند این است که sync کردن متادیتا فشار غیرضروری روی پایگاه‌داده وارد نکند.

مشکل این‌جاست که اگر کلیدهای JSON از رکوردی به رکورد دیگر تغییر کنند، ممکن است ۵۰۰ ردیف اول همهٔ کلیدهایی را که در اشیای JSON استفاده شده‌اند پوشش ندهند. برای این‌که متابیس بتواند همهٔ کلیدهای JSON را تشخیص دهد، لازم است کلیدهای اضافی را به اشیای JSON موجود در ۵۰۰ ردیف اول اضافه کنید.

بالا آوردن یک کانتینر Docker از MySQL 8+

اگر یک کانتینر MySQL جدید بالا می‌آورید و:

• می‌خواهید متابیس بدون ساخت کاربر به‌صورت دستی یا تغییر مکانیزم احراز هویت به آن متصل شود،
• یا با خطای RSA public key is not available client side (option serverRsaPublicKeyFile not set) مواجه هستید،

هنگام اجرای کانتینر از پارامتر ['--default-authentication-plugin=mysql_native_password'] استفاده کنید؛ مثلاً:

• اجرای ساده با docker run:
  docker run -p 3306:3306 -e MYSQL_ROOT_PASSWORD=xxxxxx mysql:8.xx.xx --default-authentication-plugin=mysql_native_password

• یا در docker-compose:

mysql:
  image: mysql:8.xx.xx
  container_name: mysql
  hostname: mysql
  ports:
    - 3306:3306
  environment:
    - "MYSQL_ROOT_PASSWORD=xxxxxx"
    - "MYSQL_USER=metabase"
    - "MYSQL_PASSWORD=xxxxxx"
    - "MYSQL_DATABASE=metabase"
  volumes:
    - $PWD/mysql:/var/lib/mysql
  command: ["--default-authentication-plugin=mysql_native_password"]

محدودیت‌ها در پایگاه‌داده‌های مبتنی بر Vitess

• هنگام اجرای پرس‌وجو روی پایگاه‌داده‌های مبتنی بر Vitess (مثل Planetscale)، باید داخل هر زیربرس‌وجو (subquery) یک عبارت LIMIT اضافه کنید.

  دلیلش این است که معمولاً متابیس limit (مثلاً ۲۰۰۰ یا ۱۰٬۰۰۰ ردیف) را روی نتیجهٔ نهایی پرس‌وجو اعمال می‌کند؛ اما به‌دلیل یک باگ شناخته‌شده در Vitess، این سیستم ممکن است همین limit را روی زیربرس‌وجوها اعمال کند، که می‌تواند به نتایج غیرمنتظره (مثلاً نمایش‌ندادن همهٔ ردیف‌ها در متابیس) منجر شود. راه‌حل این است که روی هر زیربرس‌وجو یک limit جداگانه قرار دهید.

• همچنین بهتر است با سرویس‌دهنده‌ای که این پلتفرم را میزبانی می‌کند در تماس باشید، چون Vitess گاهی در بازگرداندن متادیتا از information schema مشکل دارد. متابیس برای پر کردن پایگاه‌دادهٔ برنامهٔ خود به این متادیتا نیاز دارد؛ اگر متابیس نتواند این متادیتا را دریافت کند، ممکن است فیلدها ظاهر نشوند (یا خالی نمایش داده شوند).

رمزهای عبور با کاراکترهای خاص

اگر رمز عبور شما شامل کاراکترهایی است که UTF-8 نیستند، ممکن است لازم باشد یک متغیر اضافی به connection string اضافه کنید:
passwordCharacterEncoding=<your_encoding_here>. این کار مطمئن می‌شود MySQL هنگام احراز هویت، کاراکترهای خاص موجود در رمز عبور را به‌درستی تفسیر کند.

امکانات مدل (Model features)

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

Model actions

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

Model persistence

متابیس جداولی با داده‌های مدل ایجاد می‌کند و آن‌ها را بر اساس زمان‌بندی‌ای که تعریف می‌کنید تازه‌سازی می‌کند. برای فعال کردن model persistence، باید به اعتبارنامه‌های این اتصال، مجوز خواندن و نوشتن روی schemaای که متابیس فراهم می‌کند بدهید.

ویرایش دادهٔ جدول (Editable table data)

این تنظیم را روی ON بگذارید تا امکان ویرایش داده جدول‌ها مستقیماً در متابیس فعال شود. وقتی این ویژگی فعال باشد، ادمین‌ها می‌توانند رکوردها را در جدول‌های شما از طریق رابط متابیس ایجاد، به‌روزرسانی و حذف کنند.

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

مسیریابی پایگاه‌داده (Database routing)

با Database routing، ادمین می‌تواند یک‌بار با استفاده از یک پایگاه‌داده سؤال بسازد و آن سؤال، بسته به اینکه چه کسی آن را می‌بیند، روی پایگاه‌داده دیگری با همان schema اجرا شود.

Database routing را ببینید.

بخش خطر (Danger zone)

Danger zone را ببینید.

مطالعهٔ بیشتر

• MariaDB
• مدیریت پایگاه‌داده‌ها
• ویرایش متادیتا
• مدل‌ها
• تنظیم مجوزهای دسترسی به داده