مهاجرت به پایگاهدادهٔ اپلیکیشن مناسب محیط تولید
در این صفحه میبینید چطور متابیسی را که از پایگاهدادهٔ داخلی H2 بهعنوان پایگاهدادهٔ اپلیکیشن استفاده میکند، به یک نمونهٔ PostgreSQL آمادهٔ محیط تولید (Production‑ready) منتقل کنید. برای اینکه بدانید چرا بهتر است برای پایگاهدادهٔ اپلیکیشن از Postgres استفاده کنید، به راهنمای How to run Metabase in production سر بزنید.
اگر ترجیح میدهید به Metabase Cloud مهاجرت کنید، راهنمای Migrate to Metabase Cloud را ببینید.
پایگاهدادهٔ اپلیکیشن متابیس
تفاوت اصلی بین استقرار محلی (local) و استقرار تولیدی (production) متابیس در پایگاهدادهٔ اپلیکیشن آن است. این پایگاهداده، تمام دادههای متابیس شما را نگه میدارد: سؤالها، داشبوردها، کالکشنها و غیره.
متابیس بهصورت پیشفرض همراه با یک پایگاهدادهٔ H2 داخلی برای اپلیکیشن عرضه میشود، اما نباید از این پایگاهداده در محیط تولید استفاده کنید. دلیل وجود H2 این است که بتوانید متابیس را خیلی سریع روی ماشین محلی بالا بیاورید و شروع به پرسیدن سؤال و آزمایش قابلیتها کنید.
اگر میخواهید متابیس را در محیط تولید اجرا کنید، باید از یک پایگاهدادهٔ اپلیکیشن مناسب محیط تولید برای ذخیرهٔ دادههای اپلیکیشن استفاده کنید. میتوانید در هر زمانی از پایگاهدادهٔ H2 پیشفرض به یک پایگاهدادهٔ اپلیکیشن دیگر مهاجرت کنید؛ اما اگر از ابتدا میدانید متابیس را در محیط تولید به کار میگیرید، هرچه زودتر این مهاجرت را انجام دهید، بهتر است. اگر همچنان با پایگاهدادهٔ H2 پیشفرض متابیس را اجرا کنید و مرتباً از آن بکآپ نگیرید، این پایگاهداده ممکن است خراب شود و در نتیجه تمام سؤالها، داشبوردها، کالکشنها و سایر دادههای متابیس را از دست بدهید.
فرآیند مهاجرت یک فرآیند یکباره است. میتوانید اسکریپت مهاجرت را از هر کامپیوتری که به فایل پایگاهدادهٔ H2 دسترسی دارد اجرا کنید.
از مهاجرت و ارتقا همزمان خودداری کنید
نکتهٔ مهم این است که نسخهٔ متابیسی که در طول فرآیند مهاجرت استفاده میکنید باید ثابت باشد. یعنی متابیسی که با آن دستور مهاجرت را اجرا میکنید باید همان نسخهای باشد که آخرین بار فایل H2 را ساخته یا بهروزرسانی کرده، و همان نسخهای باشد که در محیط تولید اجرا خواهید کرد. فقط بعد از اتمام موفق مهاجرت است که میتوانید به ارتقای نسخه فکر کنید.
همچنین میتوانید از پلنهای Metabase Cloud استفاده کنید که تمام این جزئیات را برای شما مدیریت میکنند. اگر همین حالا یک نمونهٔ متابیس دارید، راهنمای migrate to Metabase Cloud توضیح میدهد چطور مهاجرت کنید.
پایگاهدادههای پشتیبانیشده برای ذخیرهٔ دادههای اپلیکیشن متابیس
پیشنهاد ما این است که برای پایگاهدادهٔ اپلیکیشن از PostgreSQL استفاده کنید:
- PostgreSQL – حداقل نسخه:
12. پستگرس انتخاب ترجیحی ما برای پایگاهدادهٔ اپلیکیشن متابیس است. - MySQL – حداقل نسخه:
8.0.17. تنظیمات موردنیاز (که بهطور پیشفرض همینطور هستند): collation برابرutf8mb4_unicode_ci، مجموعه کاراکتریutf8mb4، و گزینهٔinnodb_large_prefix=ON. - MariaDB – حداقل نسخه:
10.4.0. تنظیمات موردنیاز (که بهطور پیشفرض همینطور هستند): collation برابرutf8mb4_unicode_ci، مجموعه کاراکتریutf8mb4، و گزینهٔinnodb_large_prefix=ON.
JAR: مهاجرت از H2 به پایگاهدادهٔ اپلیکیشن مناسب محیط تولید
باید در تمام مراحل مهاجرت از همان نسخهٔ متابیس استفاده کنید.
متابیس یک دستور مهاجرت اختصاصی برای انتقال دادهها به پایگاهدادهٔ اپلیکیشن جدید ارائه میکند. مراحل کار به این صورت است:
- ۱. اطمینان از اینکه میتوانید به پایگاهدادهٔ مقصد متصل شوید
- ۲. خاموشکردن نمونهٔ متابیس
- ۳. بکآپگیری از پایگاهدادهٔ H2
- ۴. اجرای دستور مهاجرت دادههای متابیس
- ۵. راهاندازی متابیس
۱. اطمینان از اینکه میتوانید به پایگاهدادهٔ مقصد متصل شوید
در محیطی که دستور مهاجرت را اجرا میکنید، باید بتوانید به پایگاهدادهٔ مقصد متصل شوید. بنابراین اگر قصد دارید دادهها را به یک پایگاهدادهٔ ابری منتقل کنید، ابتدا مطمئن شوید اتصال به آن پایگاهداده برقرار است.
۲. خاموشکردن نمونهٔ متابیس
در حین مهاجرت نباید کاربران بتوانند آیتم جدیدی در متابیس بسازند. در حالت ایدئال، اگر فایل JAR متابیس را در محیط تولید اجرا میکنید، آن را بهصورت یک سرویس راهاندازی کردهاید.
۳. بکآپگیری از پایگاهدادهٔ H2
اول ایمنی! به راهنمای Backing up Metabase Application Data مراجعه کنید.
۴. اجرای دستور مهاجرت دادههای متابیس
دستور مهاجرت load-from-h2 را با استفاده از متغیرهای محیطی مناسب برای پایگاهدادهٔ مقصدی که میخواهید به آن مهاجرت کنید اجرا کنید.
برای جزئیات بیشتر دربارهٔ مشخصکردن پایگاهدادهها، به راهنمای Configuring the application database مراجعه کنید.
نمونهٔ دستور برای مهاجرت به پایگاهدادهٔ Postgres:
export MB_DB_TYPE=postgres
export MB_DB_CONNECTION_URI="jdbc:postgresql://<host>:5432/metabase?user=<username>&password=<password>"
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar load-from-h2 /path/to/metabase.db # پسوند .mv.db را در مسیر قرار ندهید
نمونهٔ دستور برای مهاجرت به پایگاهدادهٔ MySQL با استفاده از پارامترهای Java (بهجای متغیرهای محیطی):
java -DMB_DB_TYPE=mysql -DMB_DB_CONNECTION_URI="jdbc:mysql://<host>:3306/metabase?user=<username>&password=<password>" -jar metabase.jar load-from-h2 metabase.db
توجه کنید که نام فایل پایگاهداده ممکن است /path/to/metabase.db.mv.db باشد، اما هنگام اجرای دستور load-from-h2 باید مسیر را به شکل /path/to/metabase.db کوتاه کنید.
متابیس انتظار دارد این دستور را روی یک پایگاهدادهٔ کاملاً جدید و خالی اجرا کنید؛ متابیس اسکیما را میسازد و دادهها را برای شما منتقل میکند.
۵. راهاندازی متابیس
پس از مهاجرت، متابیس را فقط با اطلاعات اتصال پایگاهداده (بدون پارامتر load-from-h2 و بدون ارجاع به فایل H2) راهاندازی کنید. برای مثال، اگر از Postgres استفاده میکنید، دستور راهاندازی متابیس شبیه این خواهد بود:
export MB_DB_TYPE=postgres
export MB_DB_CONNECTION_URI="jdbc:postgresql://<host>:5432/metabase?user=<username>&password=<password>"
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar
با این حال، بهتر است فایل H2 قدیمی را برای مدتی نزد خودتان نگه دارید؛ بهعنوان نسخهٔ پشتیبان، یادگار یا بیمهٔ ذهنی.
Docker: مهاجرت از H2 به پایگاهدادهٔ اپلیکیشن مناسب محیط تولید
باید در تمام مراحل مهاجرت از همان نسخهٔ متابیس استفاده کنید.
برای سناریوهای Docker هم متابیس یک دستور مهاجرت اختصاصی برای انتقال دادهها به پایگاهدادهٔ اپلیکیشن جدید ارائه میکند. مراحل کار به این صورت است:
- ۱. اطمینان از اینکه میتوانید به پایگاهدادهٔ مقصد متصل شوید
- ۲. بکآپگیری از پایگاهدادهٔ H2
- ۳. متوقفکردن کانتینر فعلی متابیس
- ۳. دانلود فایل JAR
- ۴. اجرای دستور مهاجرت
- ۵. راهاندازی یک کانتینر Docker جدید که از پایگاهدادهٔ جدید استفاده میکند
- ۷. حذف کانتینر قدیمی که از H2 استفاده میکرد
۱. اطمینان از اینکه میتوانید به پایگاهدادهٔ مقصد متصل شوید
در محیطی که دستور مهاجرت را اجرا میکنید، باید بتوانید به پایگاهدادهٔ مقصد متصل شوید. بنابراین اگر قصد دارید دادهها را به یک پایگاهدادهٔ ابری منتقل کنید، ابتدا مطمئن شوید اتصال به آن پایگاهداده برقرار است.
۲. بکآپگیری از پایگاهدادهٔ H2
اول ایمنی! به راهنمای Backing up Metabase Application Data مراجعه کنید.
اگر از پایگاهدادهٔ H2 بکآپ نگیرید و کانتینر را حذف یا جایگزین کنید، تمام سؤالها، داشبوردها و سایر دادههای متابیس را از دست خواهید داد؛ بنابراین قبل از مهاجرت حتماً بکآپ بگیرید.
۳. متوقفکردن کانتینر فعلی متابیس
در حین مهاجرت، نباید کاربران بتوانند در متابیس محتوای جدید ایجاد کنند.
۳. دانلود فایل JAR
در دایرکتوریای که فایل H2 را (بیرون از کانتینر) ذخیره کردهاید، فایل JAR نسخهٔ فعلی متابیس را از صفحهٔ انتشارها دانلود کنید.
حتماً از همان نسخهای استفاده کنید که تا الان روی آن کار میکردید. اگر قصد ارتقای نسخه را دارید، این کار را بعد از اطمینان از موفقیت مهاجرت انجام دهید.
۴. اجرای دستور مهاجرت
از فایل H2 که در مرحلهٔ بکآپ از کانتینر خارج کردهاید، یک کپی اضافی تهیه کنید.
سپس در مسیری که فایل H2 و فایل JAR متابیس قرار دارند، دستور مهاجرت load-from-h2 را اجرا کنید. برای پایگاهدادهٔ مقصد از رشتهٔ اتصال مناسب یا متغیرهای محیطی استفاده کنید. نمونهٔ دستور:
export MB_DB_TYPE=postgres
export MB_DB_CONNECTION_URI="jdbc:postgresql://<host>:5432/metabase?user=<username>&password=<password>"
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar load-from-h2 /path/to/metabase.db # پسوند .mv.db را در مسیر قرار ندهید
متابیس راهاندازی میشود، عملیات مهاجرت را انجام میدهد (یعنی دادهها را از فایل H2 خوانده و در پایگاهدادهٔ اپلیکیشن جدید — در این مثال Postgres — مینویسد) و سپس خارج میشود.
برای جزئیات بیشتر، به Configuring the application database مراجعه کنید.
۵. راهاندازی یک کانتینر Docker جدید که از پایگاهدادهٔ جدید استفاده میکند
پس از اینکه پایگاهدادهٔ اپلیکیشن جدید با دادههای متابیس شما پر شد، میتوانید یک کانتینر جدید راهاندازی کنید و به متابیس داخل کانتینر بگویید به این پایگاهداده متصل شود. نمونهٔ دستور:
docker run -d -p 3000:3000 \
-e "MB_DB_TYPE=postgres" \
-e "MB_DB_DBNAME=<your-postgres-db-name>" \
-e "MB_DB_PORT=5432" \
-e "MB_DB_USER=<db-username>" \
-e "MB_DB_PASS=<db-password>" \
-e "MB_DB_HOST=<your-database-host>" \
--name metabase metabase/metabase
۷. حذف کانتینر قدیمی که از پایگاهدادهٔ H2 استفاده میکرد
اگر فایل H2 خود را در مکانی امن نگه داشتهاید، میتوانید کانتینر قدیمی را حذف کنید. برای جزئیات، به مستندات Docker دربارهٔ حذف کانتینرها مراجعه کنید.
اجرای دستی مهاجرتهای پایگاهدادهٔ اپلیکیشن متابیس
بهطور معمول، وقتی متابیس راهاندازی میشود، بررسی میکند که آیا لازم است تغییری در پایگاهدادهٔ اپلیکیشن اعمال شود یا نه، و در صورت نیاز این تغییرات را بهصورت خودکار اجرا میکند. اگر به هر دلیل بخواهید این تغییرات را خودتان ببینید و بهصورت دستی روی پایگاهداده اعمال کنید، این امکان را هم دارید.
کافی است قبل از راهاندازی متابیس، متغیر محیطی زیر را تنظیم کنید:
export MB_DB_AUTOMIGRATE=false
وقتی اپلیکیشن راهاندازی میشود، اگر تغییرات لازم در پایگاهداده وجود داشته باشد، پیامی شبیه نمونهٔ زیر دریافت میکنید که نشان میدهد تا زمانی که این بهروزرسانیها را اعمال نکنید، متابیس نمیتواند کامل بالا بیاید:
2015-12-01 12:45:45,805 [INFO ] metabase.db :: Database Upgrade Required
NOTICE: Your database requires updates to work with this version of Metabase. Please execute the following sql commands on your database before proceeding.
-- *********************************************************************
-- Update Database Script
-- *********************************************************************
-- Change Log: migrations/liquibase.yaml
-- Ran at: 12/1/15 12:45 PM
-- Against: @jdbc:h2:file:/Users/agilliland/workspace/metabase/metabase/metabase.db
-- Liquibase version: 3.4.1
-- *********************************************************************
-- Create Database Lock Table
CREATE TABLE PUBLIC.DATABASECHANGELOGLOCK (ID INT NOT NULL, LOCKED BOOLEAN NOT NULL, LOCKGRANTED TIMESTAMP, LOCKEDBY VARCHAR(255), CONSTRAINT PK_DATABASECHANGELOGLOCK PRIMARY KEY (ID));
سپس میتوانید اسکریپت SQL ارائهشده را بهصورت دستی روی پایگاهدادهٔ خود اجرا کنید. بعد از اعمال این تغییرات، متابیس را مجدداً راهاندازی کنید و همهچیز باید بهصورت عادی کار کند.
رفع اشکال در مشکلات مهاجرت
برای نکات تکمیلی و سناریوهای خطا، این راهنمای عیبیابی را ببینید: Troubleshooting H2 migration issues.