عرض مصدر Rails/active record migrations

<noinclude>{{DISPLAYTITLE:تهجيرات السجل الفعال في ريلز}}</noinclude>
[[تصنيف:Rails]]
التهجيرات (Migrations) هي ميزة من [[Rails/active record basics|السجل الفعال]] التي تمكّنك من تحديث مخطط قاعدة البيانات على مر الوقت. بدلًا من كتابة تعديلات قاعدة البيانات باستخدام SQL، تمكّنك التهجيرات من كتابة تعليمات DSL باستخدام [[Ruby|روبي]] لتحديث جداولك. بعد قراءة هذا الدليل، ستتعرَّف على:
* المولِّدات التي تستطيع استعمالها لإنشاء التهجيرات.
* التوابع التي يوفرها السجل الفعَّال لتعديل قاعدة البيانات.
* المهام bin/rails التي تعدِّل وتتحكم بالتهجيرات والمخطط (schema) الخاص بك.
* العلاقة بين التهجيرات والملف schema.rb.

== نظرة عامة على التهجيرات ==
إن التهجيرات هي طريقة مناسبة وسلسة من أجل [[wikipedia:Schema_migration|تحديث مخطط قاعدة البيانات على مر الوقت]] بطريقة متناسقة وسهلة. تستخدم التهجيرات تعليمات DSL باستخدام [[Ruby|روبي]]، مما يعني أنه ليس عليك كتابة تعليمات SQL يدويًا، الأمر الذي يؤدي إلى جعل تهجيراتك مستقلة.

يمكنك اعتبار التهجيرات كإصدارات مختلفة من قاعدة البيانات؛ إذ يبدأ المخطط بلا شيء، وكل تهجير يضيف أو يحذف الجداول أو الأعمدة أو السجلات. يعرف [[Rails/active record basics|السجل الفعال]] متى وكيف يتوجب تحديث قاعدة البيانات في هذا المخطط الزمني، مما يمكّن نقل حالة قاعدة البيانات من أي نقطة لآخر إصدار ممكن. يحدِّث السجل الفعال أيضًا الملف db/schema.rb لمطابقة البنية الأخيرة لقاعدة البيانات الخاصة بك.

إليك مثال بسيط عن التهجيرات:<syntaxhighlight lang="rails">
class CreateProducts < ActiveRecord::Migration[5.0]
  def change
    create_table :products do |t|
      t.string :name
      t.text :description
 
      t.timestamps
    end
  end
end
</syntaxhighlight>يضيف هذا التهجير جدولًا يسمى <code>products</code>، يحتوي عمودًا من النوع <code>[[Ruby/String|string]]</code> يسمى <code>name</code>، وعمودًا آخر من نوع النصي (text) يسمى <code>description</code>. يتم أيضًا إضافة مفتاح رئيسي يسمى <code>id</code> بشكل ضمني، لكونه المفتاح الرئيسي الافتراضي لكل نماذج [[Rails/active record basics|السجل الفعال]]. يضيف الماكرو <code>timestamps</code> عمودين هما: <code>created_at</code> و <code>updated_at</code>. يتم إدارة هذين العمودين تلقائيًا من قبل [[Rails/active record basics|السجل الفعال]] في حال وجودهما.

من الجدير بالذكر أننا قمنا بالتعريف عن التغيير الذي نريد وجوده بعد وقت. قبل تنفيذ هذا التهجير، لن يكون هناك جدول. وبعد تنفيذه، سيوجد الجدول. يعرف السجل الفعال كيف تتم إعادة التهجير أيضًا: إذا أعدنا هذا التهجير، سيتم إزالة الجدول.

في قواعد البيانات التي تدعم عمليات النقل (transactions) مع التعليمات التي تحدث تغييرًا في مخطط قاعدة البيانات، يتم تغليف التهجيرات في عملية نقل. في حال كانت قاعدة البيانات لا تدعم عمليات النقل هذه، وعند فشل تنفيذ تهجير ما، لن يتم إعادة الأجزاء التي نجحت منه. إذ من الضروري إعادتها يدويًا.

'''ملاحظة''': هناك بعض الاستعلامات (queries) التي لا يمكن تنفيذها ضمن عملية نقل. في حال كان محول قاعدة البيانات يدعم عمليات نقل DDL، يمكنك استخدام <code>disable_ddl_transaction!‎</code> لإلغاء تفعيلها من أجل تهجير وحيد.

في حال أردت إحداث تغيير في التهجير لا يمكن للسجل الفعال معرفة كيفية إعادته، يمكنك استخدام <code>reversible</code>:<syntaxhighlight lang="rails">
class ChangeProductsPrice < ActiveRecord::Migration[5.0]
  def change
    reversible do |dir|
      change_table :products do |t|
        dir.up   { t.change :price, :string }
        dir.down { t.change :price, :integer }
      end
    end
  end
end
</syntaxhighlight>وبشكل بديل، يمكنك استخدام التوابع <code>up</code> و <code>down</code> بدلًا من <code>change</code>:<syntaxhighlight lang="rails">
class ChangeProductsPrice < ActiveRecord::Migration[5.0]
  def up
    change_table :products do |t|
      t.change :price, :string
    end
  end
 
  def down
    change_table :products do |t|
      t.change :price, :integer
    end
  end
end
</syntaxhighlight>

== إنشاء تهجير ==

=== إنشاء تهجير وحيد (Standalone) ===
تخزن التهجيرات في ملفات ضمن المجلد db/migrate، واحد لكل صنف تهجير. يسمى ملف التهجير وفق النمط <code>YYYYMMDDHHMMSS_create_products.rb</code>، الذي يوافق توقيت غرينتش الذي عُرِّف في أثنائه التجيره يليه اسم التهجير مع الفصل بينهما (وبين الكلمات) بشرطة سفلية. يجب على اسم صنف التهجير (المسمى بطريقة سنام الجمل [CamelCase]) أن يوافق اسم ملف التهجير. مثلًا، الملف ‎20080906120000_create_products.rb يجب أن يعرِّف الصنف <code>CreateProducts</code>، والملف ‎20080906120001_add_details_to_products.rb يجب أن يعرِّف الصنف <code>AddDetailsToProducts</code>. يستخدم ريلز هذه التوقيتات الزمنية لمعرفة التهجيرات التي يجب تنفيذها والترتيب المراد تنفيذها به؛ لذا، في حال نسخ تهجير من تطبيق آخر، أو عند توليد تهجيرات جديدة، يجب الانتباه إلى ترتيب هذه التهجيرات.

بالطبع، ليس من السهل توليد وحساب التوقيتات الزمنية، لذلك يزودنا [[Rails/active record basics|السجل الفعال]] بمولد ينشئها لنا بسهولة:<syntaxhighlight lang="shell">
$ bin/rails generate migration AddPartNumberToProducts
</syntaxhighlight>سينشئ هذا تهجيرًا فارغًا:<syntaxhighlight lang="rails">
class AddPartNumberToProducts < ActiveRecord::Migration[5.0]
  def change
  end
end
</syntaxhighlight>في حال كان اسم التهجير بالشكل "AddXXXToYYY" أو "RemoveXXXFromYYY" واتبِع بقائمة بالأعمدة وأنواعها، فسيتم إنشاء تهجير يحتوي على التعابير <code>add_column</code> و <code>remove_column</code> بطريقة مناسبة. أي:<syntaxhighlight lang="shell">
$ bin/rails generate migration AddPartNumberToProducts part_number:string
</syntaxhighlight>سيولّد:<syntaxhighlight lang="rails">
class AddPartNumberToProducts < ActiveRecord::Migration[5.0]
  def change
    add_column :products, :part_number, :string
  end
end
</syntaxhighlight>وفي حال أردت إضافة فهرس للعمود الجديد، يمكنك ذلك من خلال:<syntaxhighlight lang="shell">
$ bin/rails generate migration AddPartNumberToProducts part_number:string:index
</syntaxhighlight>سيولّد:<syntaxhighlight lang="rails">
class AddPartNumberToProducts < ActiveRecord::Migration[5.0]
  def change
    add_column :products, :part_number, :string
    add_index :products, :part_number
  end
end
</syntaxhighlight>وبطريقة مماثلة، يمكنك توليد تهجير يؤدي إلى حذف عمود وذلك كالتالي:<syntaxhighlight lang="shell">
$ bin/rails generate migration RemovePartNumberFromProducts part_number:string
</syntaxhighlight>يولّد:<syntaxhighlight lang="rails">
class RemovePartNumberFromProducts < ActiveRecord::Migration[5.0]
  def change
    remove_column :products, :part_number, :string
  end
end
</syntaxhighlight>لست مجبرًا على عمود وحيد فقط. إليك مثلًا:<syntaxhighlight lang="shell">
$ bin/rails generate migration AddDetailsToProducts part_number:string price:decimal
</syntaxhighlight>يولّد:<syntaxhighlight lang="rails">
class AddDetailsToProducts < ActiveRecord::Migration[5.0]
  def change
    add_column :products, :part_number, :string
    add_column :products, :price, :decimal
  end
end
</syntaxhighlight>في حال كان اسم التهجير بالشكل "CreateXXX"، وتبعه قائمةٌ بالأعمدة وأنواعها، فسيتم إنشاء تهجير ينشئ جدولًا يسمى XXX يحتوي على الأعمدة المحددة. مثلًا:<syntaxhighlight lang="shell">
$ bin/rails generate migration CreateProducts name:string part_number:string
</syntaxhighlight>يولّد:<syntaxhighlight lang="rails">
class CreateProducts < ActiveRecord::Migration[5.0]
  def change
    create_table :products do |t|
      t.string :name
      t.string :part_number
    end
  end
end
</syntaxhighlight>وكما جرت العادة، ما تم توليده هو نقطة البداية فقط. يمكنك الإضافة أو الحذف من الملف المولد كما تريد عن طريق تعديل الملف db/migrate/YYYYMMDDHHMMSS_add_details_to_products.rb.

أيضاً، يقبل المولّد أنواع الأعمدة كموارد مثل <code>references</code> (أو <code>belongs_to</code> متاح أيضًا). مثلًا:<syntaxhighlight lang="shell">
$ bin/rails generate migration AddUserRefToProducts user:references
</syntaxhighlight>يولّد:<syntaxhighlight lang="rails">
class AddUserRefToProducts < ActiveRecord::Migration[5.0]
  def change
    add_reference :products, :user, foreign_key: true
  end
end
</syntaxhighlight>ينشئ هذا التهجير العمود <code>user_id</code> وفهرس مناسب. للاطلاع على قائمة خيارات add_reference الكاملة، انتقل إلى توثيق [http://api.rubyonrails.org/v5.2.2/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_reference الواجهة البرمجية].

يوجد أيضًا مولّد لإنشاء [[SQL/join|جداول ربط]] (join tables) في حال كانت الكلمة <code>JoinTable</code> جزءًا من اسم التهجير:<syntaxhighlight lang="shell">
$ bin/rails g migration CreateJoinTableCustomerProduct customer product
</syntaxhighlight>يولّد:<syntaxhighlight lang="rails">
class CreateJoinTableCustomerProduct < ActiveRecord::Migration[5.0]
  def change
    create_join_table :customers, :products do |t|
      # t.index [:customer_id, :product_id]
      # t.index [:product_id, :customer_id]
    end
  end
end
</syntaxhighlight>

=== مولّدات النماذج ===
تمكّنك مولّدات النماذج (Model Generators) من إنشاء التهجيرات المناسبة للنماذج الجديدة، إذ تحوي التهجيرات على التعليمات المناسبة لإنشاء الجدول المطابق. في حال أخبرت ريلز بالأعمدة التي تريدها، سيتم كتابة تعليمات إنشاء هذه الأعمدة تلقائيًا. إليك مثلًا:<syntaxhighlight lang="shell">
$ bin/rails generate model Product name:string description:text
</syntaxhighlight>سيؤدي إلى إنشاء التهجير التالي:<syntaxhighlight lang="rails">
class CreateProducts < ActiveRecord::Migration[5.0]
  def change
    create_table :products do |t|
      t.string :name
      t.text :description
 
      t.timestamps
    end
  end
end
</syntaxhighlight>يمكنك أيضًا إضافة المزيد من الأعمدة وأنواعها في حال أردت ذلك.

=== تمرير معدلات الأنواع ===
يمكن تمرير بعض معدلات الأنواع المستخدمة بشكل دوري مباشرةً في سطر الأوامر. توضع معدلات الأنواع ضمن أقواس معقوصة وتلي نوع الحقل. مثلًا، يؤدي تنفيذ الأمر التالي:<syntaxhighlight lang="shell">
$ bin/rails generate migration AddDetailsToProducts 'price:decimal{5,2}' supplier:references{polymorphic}

</syntaxhighlight>إلى إنشاء التهجير التالي:<syntaxhighlight lang="rails">
class AddDetailsToProducts < ActiveRecord::Migration[5.0]
  def change
    add_column :products, :price, :decimal, precision: 5, scale: 2
    add_reference :products, :supplier, polymorphic: true
  end
end
</syntaxhighlight>

== كتابة التهجيرات ==
بعد إنشاء تهجيراتك باستخدام أحد المولّدات، فقد حان الوقت للبدء بالعمل به واستخدامه!

=== إنشاء جدول ===
إن التابع <code>create_table</code> هي أحد أهم التوابع لكن في معظم الأوقات، سيتم توليد الجدول تلقائيًا باستخدام أحد المولدات. الاستخدام التقليدي سيكون كالتالي:<syntaxhighlight lang="rails">
create_table :products do |t|
  t.string :name
end
</syntaxhighlight>الذي ينشئ الجدول <code>products</code> الذي يحوي عمودًا باسم <code>name</code> (وكما تم مناقشته أدناه، العمود <code>id</code> منشأ بشكل ضمني).

افتراضيًا، سينشئ التابع <code>create_table</code> مفتاحًا رئيسيًا يدعى <code>id</code>. يمكنك تغيير اسم المفتاح الرئيسي باستخدام الخيار ‎<code>:primary_key</code> (لا تنسَ تعديل النموذج الموافق)، أو في حال لم ترد إنشاء مفتاح رئيسي إطلاقًا، يمكنك تمرير الخيار <code>id: false</code>. في حال أردت تمرير خيارات خاصة بقاعدة البيانات، يمكنك وضع قطع [[SQL]] في الخيار ‎<code>:option</code>. مثلًا:<syntaxhighlight lang="rails">
create_table :products, options: "ENGINE=BLACKHOLE" do |t|
  t.string :name, null: false
end
</syntaxhighlight>سيؤدي إلى إضافة <code>ENGINE=BLACKHOLE</code> إلى تعليمة [[SQL]] المستخدمة لإنشاء الجدول.

أيضًا، يمكنك تمرير الخيار ‎<code>:comment</code> مع أي شرح أو تعليق حول الجدول الذي سيتم تخزينه في قاعدة البيانات والذي يمكن عرضه في أدوات إدارة قواعد البيانات، مثل MySQL Workbench و PgAdmin III. من المستحسن تعريف التعليقات في التهجيرات للتطبيقات التي تملك قواعد بيانات كبيرة، الأمر الذي يساعد المطوّرين من فهم تحليل النظام وتوليد توثيقات. في الوقت الحالي، فقط محوّلات قواعد البيانات MySQL و PostgreSQL تدعم التعليقات.

=== إنشاء جدول رابط ===
التابع التهجيري <code>create_join_table</code> ينشئ الجدول HABTM (اختصار للعبارة has and belongs to many]) الرابط. يكون استخدامه كالتالي:<syntaxhighlight lang="rails">
create_join_table :products, :categories
</syntaxhighlight>ينشئ هذا جدولًا يدعى <code>categories_products</code> بحقلين <code>category_id</code> و <code>product_id</code>. في هذه الحقول، يضبط الخيار ‎<code>:null</code> إلى القيمة <code>false</code> افتراضيًّا. يمكن تجاوز هذا عن طريق تحديد الخيار ‎<code>:column_options</code>.<syntaxhighlight lang="rails">
create_join_table :products, :categories, column_options: { null: true }
</syntaxhighlight>بشكل افتراضي، يأتي اسم الجدول الرابط من أول وسيطين ممررين للتابع <code>create_join_table</code> وذلك بترتيب أبجدي. لتعديل اسم الجدول، قم بتعديل الخيار ‎<code>:table_name</code>:<syntaxhighlight lang="rails">
create_join_table :products, :categories, table_name: :categorization
</syntaxhighlight>يقبل التابع <code>create_join_table</code> أيضًا كتلةً، والتي يمكنك استخدامها لإضافة الفهارس (التي لا يتم إنشاؤها بشكل افتراضي)، أو الحقول الإضافية:<syntaxhighlight lang="rails">
create_join_table :products, :categories do |t|
  t.index :product_id
  t.index :category_id
end
</syntaxhighlight>

=== تغيير الجداول ===
بشكل مقارب للتابع <code>create_table</code>، يمكن استخدام <code>change_table</code> من أجل تغيير الجداول الموجودة مسبقًا. يمكن استخدامه بشكل مشابه للتابع <code>create_table</code>، لكن الكائن المزود للكتلة يملك بعض المزايا الإضافية. مثلاً:<syntaxhighlight lang="rails">
change_table :products do |t|
  t.remove :description, :name
  t.string :part_number
  t.index :part_number
  t.rename :upccode, :upc_code
end
</syntaxhighlight>يزيل هذا التابع الحقول <code>name</code> و <code>description</code>، وينشئ حقلاً يدعى <code>part_number</code> ويضيف فهرسًا عليه. نهايةً، يعيد تسمية الحقل <code>upccode</code>.

=== تغيير الحقول ===
بشكل مشابه للتابع <code>remove_column</code> و <code>add_column</code>، يمكنك استخدام التابع <code>change_column</code> الذي توفره ريلز لتغيير حقل محدَّد:<syntaxhighlight lang="rails">
change_column :products, :part_number, :text
</syntaxhighlight>يغيّر هذا التابع الحقل <code>part_number</code> من الجدول <code>products</code> ليصبح حقلًا من النوع النصي (text). لاحظ أن التغييرات التي تجرى عبر التابع <code>change_column</code> لا رجعة فيها (irreversible).

إلى جانب <code>change_column</code>، يمكن استخدام التابعين <code>change_column_null</code> و <code>change_column_default</code> لتغيير القيد "not null" أو القيم الافتراضية من الحقول وذلك بشكل واضح.<syntaxhighlight lang="rails">
change_column_null :products, :name, false
change_column_default :products, :approved, from: true, to: false
</syntaxhighlight>يغيّر هذا الحقل <code>name</code> من الجدول <code>products</code> ليصبح <code>NOT NULL</code>، والقيمة الافتراضية له تصبح <code>false</code>.

'''ملاحظة''': يمكنك أيضًا كتابة التغيير نفسه بالشكل:<syntaxhighlight lang="rails">
change _column_default :products, :approved, false
</syntaxhighlight>لكن على عكس المثال السابق، سيجعل هذا التغيير من تهجيرك غير قابل للاستعادة.

=== معدّلات الحقول ===
يمكن تطبيق معدلات الحقول (Column modifiers) عند إنشاء أو تغيير حقل ما:
* <code>limit</code>: يحدد الحجم الأعظمي للحقول التي من الأنواع string، أو text، أو binary، أو integer.
* <code>precision</code>: يحدد دقة حقول الأعداد العشرية، إذ يمثل عدد الخانات الرقمية الكلية في العدد.
* <code>scale</code>: يحدد دقة المنازل العشرية، إذ يمثل عدد الخانات العشرية بعد الفاصلة العشرية.
* <code>polymorphic</code>: يضيف الحقل <code>type</code> إلى العلاقات من النوع <code>belongs_to</code>.
* <code>null</code>: يسمح/لا يسمح بإضافة القيم <code>NULL</code> في الحقل.
* <code>default</code>: يسمح بضبط القيمة الافتراضية في الحقل. تجب الملاحظة أنه عند استخدام قيمة ديناميكية (مثل قيمة تاريخ)، سيتم حساب القيمة الافتراضية في المرة الأولى فقط (عند تطبيق التهجير).
* <code>index</code>: يضيف فهرسًا للحقل.
* <code>comment</code>: يضيف تعليقًا للحقل.
قد تدعم بعض المحولات (adapters) المزيد من الخيارات؛ اطّلع على توثيق الواجهة البرمجية الخاص بالمحول من أجل المزيد من المعلومات.

'''ملاحظة''': لا يمكن تحديد المعدلات <code>null</code> و <code>default</code> من سطر الأوامر.

=== المفاتيح الأجنبية ===
رغم أنَّ المفاتيح الأجنبية غير مطلوبة، يمكنك إضافتها لضمان السلامة المرجعية (referential integrity).<syntaxhighlight lang="rails">
add_foreign_key :articles, :authors
</syntaxhighlight>يضيف هذا الأمر مفتاحًا أجنبيًا جديدًا للحقل <code>author_id</code> من الجدول <code>articles</code>؛ إذ يكون الحقل مرجعًا للحقل <code>id</code> من الجدول <code>authors</code>. في حال عدم قابلية اشتقاق أسماء الحقول من أسماء الجداول، يمكنك استخدام الخيارين ‎<code>:column</code> و ‎<code>:primary_key</code>.

يقوم ريلز بتوليد اسم من أجل كل مفتاح أجنبي يبدأ بالسابقة <code>_fk_rails</code>، ويليها 10 محارف يتم توليدها من اسم الجدول <code>from_table</code> والحقل <code>column</code>. يمكن تحديد اسم المفتاح الأجنبي من الخيار ‎<code>:name</code>.

'''ملاحظة''': يدعم السجل الفعال المفاتيح الأجنبية الوحيدة فقط. لاستخدام المفاتيح الأجنبية المركبة، يجب استخدام <code>execute</code> و structure.sql. اقرأ قسم تعديل المخططات في الأسفل.

يمكن أيضًا إزالة مفتاح أجنبي بسهولة:<syntaxhighlight lang="rails">
# دع السجل الفعال يكتشف اسم الحقل
remove_foreign_key :accounts, :branches

# إزالة المفتاح الأجنبي لحقل معين
remove_foreign_key :accounts, column: :owner_id

# إزالة المفتاح الأجنبي باسم معين
remove_foreign_key :accounts, name: :special_fk_name


</syntaxhighlight>

=== عند عدم كفاية التوابع المساعدة ===
في حال كانت التوابع المساعدة التي يزودها السجل الفعال غير كافية، يمكنك استخدام التابع <code>execute</code> لتنفيذ تعليمات SQL:<syntaxhighlight lang="rails">
Product.connection.execute("UPDATE products SET price = 'free' WHERE 1=1")
</syntaxhighlight>للمزيد من المعلومات والأمثلة حول التوابع المفردة، يمكنك الاطلاع على توثيق الواجهة البرمجية. بالتحديد، توثيق [http://api.rubyonrails.org/v5.2.2/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html ActiveRecord::ConnectionAdapters::SchemaStatements] (الذي يزود التوابع المتاحة في التوابع <code>change</code> و <code>up</code> و <code>down</code>)، وتوثيق [http://api.rubyonrails.org/v5.2.2/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html ActiveRecord::ConnectionAdapters::TableDefinition] (الذي يزود التوابع المتاحة في الكائن المعاد بواسطة <code>create_table</code>)، وتوثيق [http://api.rubyonrails.org/v5.2.2/classes/ActiveRecord/ConnectionAdapters/Table.html ActiveRecord::ConnectionAdapters::Table] (الذي يزود التوابع المتاحة في الكائن المعاد بواسطة <code>change_table</code>).

=== استخدام التابع <code>change</code> ===
إن التابع <code>change</code> هو الطريقة الأساسية لكتابة التهجيرات؛ إذ يعمل في معظم الحالات، التي يعلم فيها السجل الفعال كيف يستعيد التهجيرات بشكل تلقائي. في الوقت الحالي، يدعم التابع <code>change</code> فقط تعريفات التهجيرات التالية:
* <code>add_column</code>
* <code>add_foreign_key</code>
* <code>add_index</code>
* <code>add_reference</code>
* <code>add_timestamps</code>
* <code>change_column_default</code> (يجب أن يُزوَّد بالخيارين ‎<code>:from</code> و ‎<code>:to</code>)
* <code>change_column_null</code>
* <code>create_join_table</code>
* <code>create_table</code>
* <code>disable_extension</code>
* <code>drop_join_table</code>
* <code>drop_table</code> (يجب أن يُزوَّد بكتلة)
* <code>enable_extension</code>
* <code>remove_column</code> (يجب أن يُزوَّد بنوع)
* <code>remove_foreign_key</code> يجب أن يُزوَّد بجدولٍ ثانٍ)
* <code>remove_index</code>
* <code>remove_reference</code>
* <code>remove_timestamps</code>
* <code>rename_column</code>
* <code>rename_index</code>
* <code>rename_table</code>
إن التابع <code>change_table</code> أيضًا قابل للاستعادة (reversible)، طالما لا يستدعي الهيكل أي من التوابع <code>change</code> و <code>change_default</code> و <code>remove</code>.

التابع <code>remove_column</code> قابل للاستعادة في حال زوّدته بنوع الحقل كوسيط ثالث. زوّده بخيارات الحقل الأساسي أيضًا، وإلّا لن يتمكّن ريلز من إعادة إنشاء الحقل عند استعادة التهجير:<syntaxhighlight lang="rails">
remove_column :posts, :slug, :string, null: false, default: '', index: true
</syntaxhighlight>في حال أردت استعمال أي من التوابع الأخرى، يجب عليه استخدام <code>reversible</code> لكتابة التوابع <code>up</code> و <code>down</code>، بدلًا من استخدام التابع <code>change</code>.

=== استخدام <code>reversible</code> ===
قد تحتاج التهجيرات المعقدة إلى بعض أنواع المعالجة التي لا يعلم السجل الفعال كيفية استعادتها. يمكنك استخدام <code>reversible</code> لتحديد ما يجب فعله عند تشغيل التهجير وما يجب فعله عند استعادته. مثلًا:<syntaxhighlight lang="rails">

class ExampleMigration < ActiveRecord::Migration[5.0]
  def change
    create_table :distributors do |t|
      t.string :zipcode
    end
 
    reversible do |dir|
      dir.up do
        # add a CHECK constraint
        execute <<-SQL
          ALTER TABLE distributors
            ADD CONSTRAINT zipchk
              CHECK (char_length(zipcode) = 5) NO INHERIT;
        SQL
      end
      dir.down do
        execute <<-SQL
          ALTER TABLE distributors
            DROP CONSTRAINT zipchk
        SQL
      end
    end
 
    add_column :users, :home_page_url, :string
    rename_column :users, :email, :email_address
  end
end
</syntaxhighlight>باستخدام <code>reversible</code>، يمكنك ضمان تشغيل التعليمات بالترتيب الصحيح أيضًا. في حال تمّت استعادة التهجير في المثال السابق، يتم تنفيذ الكتلة <code>down</code> بعد إزالة الحقل <code>home_page_url</code> وقبل حذف الجدول <code>distributors</code>.

في بعض الأوقات، تفعل التهجيرات أمورًا لا يمكن استعادتها؛ مثلًا، قد تحذف بعض البيانات. في هذه الحالات، يمكنك اطلاق الاستثناء <code>ActiveRecord::IrreversibleMigration</code> في الكتلة <code>down</code>. في حال أراد شخص ما استعادة تهجيرك، ستظهر رسالة خطأ تبلغه بعدم إمكانية ذلك.

=== استخدام التابعان <code>up</code> و <code>down</code> ===
يمكنك أيضًا العودة للشكل القديم من التهجيرات واستخدام التابعان <code>up</code> و <code>down</code> بدلًا من التابع <code>change</code>. يحوي التابع <code>up</code> التحويلات التي تُجرَى على المخطط، بينما يقوم التابع <code>down</code> باستعادة التحويلات التي جرت في التابع <code>up</code>. أي يجب على مخطط قاعدة البيانات ألّا يتغيّر بعد القيام بتنفيذ التابع <code>up</code> ثمّ التابع <code>down</code>. مثلًا، إذا قمت بإنشاء جدول في التابع <code>up</code>، يجب عليك حذفه في التابع <code>down</code>. من الحكمة أيضًا تنفيذ التحويلات بشكل عكسي تمامًا لما تمّت كتابته في التابع <code>up</code>. المثال السابق في القسم "استخدام <code>reversible</code>" مماثل للمثال التالي:<syntaxhighlight lang="rails">
class ExampleMigration < ActiveRecord::Migration[5.0]
  def up
    create_table :distributors do |t|
      t.string :zipcode
    end
 
    # add a CHECK constraint
    execute <<-SQL
      ALTER TABLE distributors
        ADD CONSTRAINT zipchk
        CHECK (char_length(zipcode) = 5);
    SQL
 
    add_column :users, :home_page_url, :string
    rename_column :users, :email, :email_address
  end
 
  def down
    rename_column :users, :email_address, :email
    remove_column :users, :home_page_url
 
    execute <<-SQL
      ALTER TABLE distributors
        DROP CONSTRAINT zipchk
    SQL
 
    drop_table :distributors
  end
end
</syntaxhighlight>في حال كان تهجيرك غير قابل للاستعادة، يجب عليك اطلاق الاستثناء <code>ActiveRecord::IrreversibleMigration</code> في التابع <code>down</code>؛ إذ في حال أراد شخص ما استعادة تهجيرك، ستظهر رسالة خطأ تبلغه بعدم إمكانية ذلك.

=== استعادة التهجيرات القديمة ===
يمكنك استخدام قدرات السجل الفعال لاستعادة التهجيرات باستخدام التابع <code>revert</code>:<syntaxhighlight lang="rails">
require_relative '20121212123456_example_migration'
 
class FixupExampleMigration < ActiveRecord::Migration[5.0]
  def change
    revert ExampleMigration
 
    create_table(:apples) do |t|
      t.string :variety
    end
  end
end
</syntaxhighlight>يقبل التابع <code>revert</code> أيضًا هيكلًا من التعليمات لاستعادتها. يفيد ذلك في حال أردت استعادة أجزاء من تهجيرات سابقة. مثلًا، لنفترض أنّه تم تنفيذ التهجير <code>ExampleMigration</code> لكن اكتشف لاحقًا أنّه من المفضّل استخدام [[Rails/active record validations|عمليات التحقق من السجل الفعال]] بدلًا من القيد <code>CHECK</code> لتأكيد الرمز البريدي (zipcode):<syntaxhighlight lang="rails">
class DontUseConstraintForZipcodeValidationMigration < ActiveRecord::Migration[5.0]
  def change
    revert do
      # copy-pasted code from ExampleMigration
      reversible do |dir|
        dir.up do
          # add a CHECK constraint
          execute <<-SQL
            ALTER TABLE distributors
              ADD CONSTRAINT zipchk
                CHECK (char_length(zipcode) = 5);
          SQL
        end
        dir.down do
          execute <<-SQL
            ALTER TABLE distributors
              DROP CONSTRAINT zipchk
          SQL
        end
      end
 
      # بقية التجهير لا غبار عليه
    end
  end
end
</syntaxhighlight>كان من الممكن كتابة التهجير نفسه دون استخدام التابع <code>revert</code>، لكن كان ليتضمّن ذلك بعض الخطوات الإضافية: عكس ترتيب استدعاء <code>create_table</code> و <code>reversible</code>، وتبديل <code>create_table</code> بـ <code>drop_table</code>، وأخيرًا تبديل <code>up</code> بـ <code>down</code> والعكس صحيح. هذا الأمر مُعالج بأكمله في التابع <code>revert</code>.

'''ملاحظة''': في حال أردت إضافة القيد <code>CHECK</code> كما في المثال السابق، يجب عليك استخدام الملف structure.sql مثل التابع <code>dump</code>. اقرأ قسم تعديل المخططات في الأسفل.

== تنفيذ التهجيرات ==
يزوّد ريلز بمجموعة من مهام <code>bin/rails</code> لتنفيذ مجموعة محددة من التهجيرات.

من المرجَّح أن تكون المهمة الأولى المتعلقة بالتهجيرات والتي ستستخدمها هي <code>rails db:migrate</code>. في شكلها الأكثر بساطة، تشغّل هذه المهمة التوابع <code>change</code> أو <code>up</code> للتهجيرات التي لم يتم تشغيلها بعد. في حال لم يكن هناك تهجيرات لم تُشغّل بعد، تقوم هذه المهمة بالإنهاء. تنفّذ هذه المهمة التهجيرات بالترتيب حسب تاريخ التهجير.

من الجدير بالذكر أن تنفيذ المهمة <code>db:migrate</code> ينفّذ بدوره المهمة <code>db:schema:dump</code>، التي تحدّث الملف db/schema.rb ليناسب المخطط الحالي لقاعدة البيانات.

في حال حدّدت إصدارًا معيّنًا، يقوم السجل الفعال بتنفيذ التهجيرات المطلوبة (<code>change</code> و <code>up</code> و <code>down</code>) حتّى يصل للإصدار المعطى. يُحدد الإصدار بالسابقة الرقمية في اسم ملف التهجير. مثلًا، للتهجير حتّى الإصدار 20080906120000، نفذ الأمر التالي:<syntaxhighlight lang="shell">
$ bin/rails db:migrate VERSION=20080906120000
</syntaxhighlight>في حال كان الإصدار 20080906120000 أكبر من الإصدار الحالي (أي يتم التهجير للأعلى)، تُنفّذ التوابع <code>change</code> (أو <code>up</code>) على كل التهجيرات وصولًا إلى وبما فيها التهجير 20080906120000 ولن تنفذ بعد ذلك أية تهجيرات لاحقة. في حال كان التهجير للأسفل، يتم تنفيذ التوابع <code>down</code> على كل التهجيرات تنازليًّا حتى الوصول إلى ودون تضمين التهجير 20080906120000.

=== الاستعادة ===
مهمّة استعادة التهجير الأخير هي مهمّة متكرّرة أيضًا. مثلًا، في حال ارتكبت خطأ معيّنًا وأردت إصلاحه، بدلًا من البحث عن رقم الإصدار المرافق للتهجير الأخير، يمكنك تشغيل:<syntaxhighlight lang="shell">
$ bin/rails db:rollback
</syntaxhighlight>يستعيد هذا الأمر آخر تهجير تمّ تنفيذه، إمّا بعكس التابع <code>change</code>، أو بتنفيذ التابع <code>down</code>. في حال أردت استعادة مجموعة من التهجيرات، يمكنك تمرير المعامل <code>STEP</code>:<syntaxhighlight lang="rails">
$ bin/rails db:rollback STEP=3
</syntaxhighlight>يستعيد ذلك آخر ثلاثة تهجيرات.

المهمة <code>db:migrate:redo</code> هو اختصار للقيام باستعادة التهجيرات وتنفيذها مجددًا. وكما هو الحال في المهمة <code>db:rollback</code>، يمكنك استخدام المعامل <code>STEP</code> لتنفيذه على أكثر من تهجير، مثلًا:<syntaxhighlight lang="shell">
$ bin/rails db:migrate:redo STEP=3
</syntaxhighlight>لا تقوم أي من المهمّات <code>bin/rails</code> هذه بأي شيء لا يمكنك فعله مع المهمة <code>db:migrate</code>. ببساطة، هي أكثر أريحية، بما أنّك لست بحاجة لتحديد إصدار التهجير الذي تريد العودة له.

=== تهيئة قاعدة البيانات ===
تقوم المهمة <code>rails db:setup</code> بإنشاء قاعدة البيانات، وتحميل المخطط وتهيئته بالبيانات اللازمة.

=== إعادة تهيئة قاعدة البيانات ===
تقوم المهمة <code>rails db:reset</code> بحذف قاعدة البيانات وتهيئتها من جديد. تكافئ هذه المهمّة الأمر <code>rails db:drop db:setup</code>.

'''ملاحظة''': لا يكافئ ذلك تنفيذ كل التهجيرات؛ إذ يستخدم فقط الملف db/schema.rb أو الملف db/structure.sql. في حال عدم إمكانية استعادة تهجير ما، قد لا تساعدك المهمة <code>db:reset</code>. لقراءة المزيد حول حذف المخطط، اقرأ قسم تحديث المخططات في الأسفل.

=== تنفيذ تهجيرات محددة ===
في حال أردت تنفيذ تهجير محدد للأعلى (up) أو للأسفل (down)، يمكنك استخدام المهمات <code>db:migrate:up</code> أو <code>db:migrate:down</code>. زوّدها بالإصدار المناسب، وسيتم تنفيذ التوابع <code>change</code> أو <code>up</code> أو <code>down</code> للتهجير الموافق للإصدار المعطى. مثلًا:<syntaxhighlight lang="shell">
$ bin/rails db:migrate:up VERSION=20080906120000
</syntaxhighlight>يُنفّذ التهجير 20080906120000 عن طريق تنفيذ التابع <code>change</code> (أو التابع <code>up</code>). تقوم هذه المهمة أولًا بفحص فيما إذا كان التهجير هذا مطبّق مسبقًا على قاعدة البيانات، ولن تقوم بأي شيء في حال معرفة السجل الفعال أنّ التهجير قد تم تطبيقه مسبقًا.

=== تنفيذ التهجيرات في بيئات مختلفة ===
افتراضيًا، تنفّذ المهمة <code>bin/rails db:migrate</code> بالبيئة <code>development</code>. لتنفيذ التهجيرات على بيئة مختلفة، يمكنك تحديدها في متغير البيئة <code>RAILS_ENV</code> عند تشغيل الأمر. مثلًا، لتنفيذ تهجير ما على بيئة الاختبار (test)، يمكنك تشغيل:<syntaxhighlight lang="shell">
$ bin/rails db:migrate RAILS_ENV=test
</syntaxhighlight>

=== تغيير خرج تنفيذ التهجيرات ===
افتراضيًا، تخبرك التهجيرات بما تفعله حاليًا، وكم من الوقت استغرق تنفيذها؛ ففي حال كان لدينا تهجير ينشئ جدولًا ويضيف فهرسًا عليه، يبدو خرج تنفيذه كالتالي:<syntaxhighlight lang="text">
==  CreateProducts: migrating =================================================

-- create_table(:products)

  -> 0.0028s

==  CreateProducts: migrated (0.0028s) ========================================


</syntaxhighlight>تم تزويد مجموعة من التوابع في التهجيرات للتحكم بخرج تنفيذ التهجيرات:
{| class="wikitable"
!التابع
!الغرض
|-
|<code>suppress_messages</code>
|يأخذ كتلةً كوسيط له، ويزيل أي خرج يتم توليده من الكتلة.
|-
|<code>say</code>
|يأخذ رسالة كوسيط له، ويظهرها كما هي. يمكن تمرير وسيط منطقيٍّ (boolean) ثانٍ لتحديد ضرورة وضع الفراغات قبل الكلام.
|-
|<code>say_with_time</code>
|يظهر نصًا، وكم من الوقت استغرق تنفيذ الكتلة. في حال أعادت الكتلة عددًا صحيحًا، يفترض التابع أنّه يمثّل عدد الأسطر المتأثرة.
|}
مثلًا، ألقِ نظرة فاحصة على هذا التهجير:<syntaxhighlight lang="rails">
class CreateProducts < ActiveRecord::Migration[5.0]
  def change
    suppress_messages do
      create_table :products do |t|
        t.string :name
        t.text :description
        t.timestamps
      end
    end
 
    say "Created a table"
 
    suppress_messages {add_index :products, :name}
    say "and an index!", true
 
    say_with_time 'Waiting for a while' do
      sleep 10
      250
    end
  end
end
</syntaxhighlight>يولّد الخرج التالي:<syntaxhighlight lang="text">
==  CreateProducts: migrating =================================================
-- Created a table
   -> and an index!
-- Waiting for a while
   -> 10.0013s
   -> 250 rows
==  CreateProducts: migrated (10.0054s) =======================================
</syntaxhighlight>في حال أردت من السجل الفعال ألّا يطبع شيئًا، يمكنك استخدام <code>rails db:migrate VERBOSE=false</code> لإزالة أي مخرجات.

== تغيير التهجيرات الموجودة ==
قد ترتكب بعض الأخطاء عند كتابتك لتهجير ما. في حال نفّذت هذا التهجير، لن تتمكّن من تعديل التهجير وتنفيذه مجددًا، إذ يفترض ريلز أنّ التهجير تمّ تنفيذه مسبقًا، ولن يقوم بأي شيء عند تشغيلك للأمر <code>rails db:migrate</code>. يجب عليك استعادة التهجير، ثم تعديله وتشغيل الأمر <code>rails db:migrate</code> لتنفيذ التهجير المصحّح.

بشكل عام، ليس من المحبّذ تعديل التهجيرات الموجودة؛ إذ ستبني المزيد من العمل لنفسك ولأفراد فريق عملك وتتسبب بصداع في حال كان الإصدار الحالي من التهجير منفّذ على الخوادم المنتجة. بدلًا من ذلك، يجب عليك كتابة تهجير جديد يقوم بالتغيير الذي تريده. تعديل تهجير جديد لم يتم بعد تسليمه لمنصة التحكم بالمصدر (أو بشكل أعم، لم يتم تنفيذه على الخوادم المنتجة) هو مناسب أيضًا بشكل مماثل.

يمكن للتابع <code>revert</code> أن يفيدك في هذه الحالة، عند كتابة تهجير جديد يلغي تهجيرًا قديمًا ككل أو كجزء.

== تعديل المخططات ==

=== لمَ نستخدم ملفات المخططات؟ ===
لا يمكن اعتبار التهجيرات - رغم متانتها - مصدرًا موثوقًا لمخطط (schema) قاعدة البيانات، إذ يقع هذا الدور على الملف db/schema.rb أو ملف [[SQL]] الذي يولده السجل الفعال عن طريق تحليل قاعدة البيانات. لم تصمّم هذه الملفات ليتم تعديلها، إذ تمثّل حالة قاعدة البيانات الحالية.

لا يوجد حاجة لرفع إصدار جديد من تطبيق ما عن طريق إعادة تنفيذ سجل التهجيرات ككل. من البسيط جدًا والسريع تنفيذ ملف مخطط وحيد لقاعدة البيانات.

مثلًأ، هكذا يتم إنشاء قاعدة بيانات الاختبار: يتم تنزيل قاعدة بيانات التطوير (إمّا إلى db/schema.rb أو db/strucutre.sql)، ومن ثم تحميلها على قاعدة بيانات الاختبار.

تفيدك ملفات المخططات أيضًا عندما تريد الاطلاع على الحقول التي يمتلكها كائن السجل الفعال. هذه المعلومات غير موجودة في مصدر النموذج، وغالبًا ما تكون موزّعة في مجموعة من التهجيرات، لكنّها مجمّعة بشكل جيّد في ملف المخطط. تضيف وتحدّث الجوهرة <code>annotate_models</code> التعليقات على كل نموذج لشرح مخطّطه إن أردت هذا الحل.

=== أنواع عمليات تنزيل المخططات ===
هناك طريقتين لتنزيل المخطط. يحدّد ذلك في الملف config/application.rb عن طريق الإعداد <code>config.active_record_schema_format</code>، إذ يكون إمّا <code>sql:</code> أو <code>ruby:</code>.

في حال تمّ اختيار <code>ruby:</code>، ستجد المخطط في db/schema.rb. إذا اطلعت على الملف، ستجده مماثلًا لتهجير كبير جدًا:<syntaxhighlight lang="rails">
ActiveRecord::Schema.define(version: 20080906171750) do
  create_table "authors", force: true do |t|
    t.string   "name"
    t.datetime "created_at"
    t.datetime "updated_at"
  end
 
  create_table "products", force: true do |t|
    t.string   "name"
    t.text     "description"
    t.datetime "created_at"
    t.datetime "updated_at"
    t.string   "part_number"
  end
end
</syntaxhighlight>يتم إنشاء هذا الملف عن طريق تحليل قاعدة البيانات والتعبير عن بنيتها باستخدام <code>create_table</code> و <code>add_index</code> والمزيد. باعتبار هذا الملف مستقل عن قاعدة البيانات، يمكن تنفيذه على أي قاعدة بيانات يدعمها السجل الفعال. من الضروري القيام بذلك عند العمل مع تطبيق يقوم بتشغيل مجموعة من قواعد البيانات.

'''ملاحظة''': لا يمكن للملف db/schema.rb التعبير عن الأمور المتعلقة بقاعدة البيانات مثل القوادح (triggers)، والسلاسل (sequences)، والإجراءات المخزنة (stored procedures) أو القيود (check)، ...إلخ. تجدر الملاحظة أنّه في حين يمكن تنفيذ تعليمات [[SQL]] في التهجيرات، إلّا أنّه لا يمكن إعادة كتابة ذلك عند تنزيل المخطط. في حال استخدمت إحدى هذه الميّزات، يجب عليك تعيين نمط المخطط الحالي إلى <code>sql:</code>.

بدلًا من استخدام تنزيل المخططات الخاص بالسجل الفعال، يمكنك تنزيل مخطط قاعدة البيانات باستخدام أداة مناسبة لقاعدة البيانات الحالية (عن طريق المهمة <code>db:structure:dump</code>) إلى الملف db/structure.sql. مثلًا، من أجل قاعدة بيانات من النوع PostgreSQL، يمكنك استخدام الأداة <code>pg_dump</code>. ومن أجل MySQL و MariaDB، سيحتوي هذا الملف على خرج <code>SHOW CREATE TABLE</code> من أجل مجموعة من الجداول.

إن تحميل هذه المخططات يعني ببساطة تنفيذ تعليمات [[SQL]] التي تحويها. باستخدام النمط <code>sql:</code>، لن تتمكّن من تحميل المخطط على قاعدة بيانات من نوع مختلف عن النوع المستخدم لتنزيل ملف المخطط.

=== ملفات المخططات والتحكم بالمصدر ===
بما أنّ ملفات المخططات هي المصدر الأساسي لمخطط قاعدة البيانات، من المستحسن جدًا تسليمها لنظام التحكم بالمصدر الخاص بك.

يحوي الملف db/schema.rb على الإصدار الحالي من قاعدة بياناتك. هذا يضمن أنه سيحصل تضارب عند تعديل ملف المخطط من قبل طرفين. عند حدوث هذا التضارب، قم بحلّه يدويًا، واضعًا رقم الإصدار الأكبر من بين الاثنين.

== السجل الفعال والسلامة المرجعية ==
يدّعي السجل الفعال أنّ العمليّات المعقّدة والمنطقية يجب أن تكون جزءًا من طبقة النماذج، وليس من قاعدة البيانات. لذلك، فإنّ الميزات مثل القوادح (triggers) والقيود (constraints) والتي تضفي المنطقية إلى قاعدة بياناتك ليست مستخدمة بكثرة.

التحققات من الصحة مثل <code>validates :foreign_key, uniqueness: true</code> هي طريقة من الطرق المستخدمة لتضمن نماذجك تكامل البيانات (data integrity). يسمح الخيار <code>dependent:</code> للارتباطات من حذف الكائنات الأبناء لنموذج ما عند حذف الكائن الأب لها. كما هو الحال مع أي شيء يُشغّل على مستوى التطبيق، لا يمكن لهذه الأوامر أن تضمن السلامة المرجعية (referential integrity)، لذلك يقوم بعض المبرمجون بإضافة قيود المفاتيح الأجنبية لقاعدة البيانات.

رغم أن السجل الفعال لا يوفر هذه الإمكانية، إلّا أن التابع <code>execute</code> يمكن استخدامه لتنفيذ تعليمات SQL وتحقيق المطلوب.

== التهجيرات وبيانات البذور ==
إن الهدف الأساسي من تهجيرات ريلز هو تنفيذ الأوامر التي تعدّل المخطط باستخدام عملية متناسقة. يمكن استخدام التهجيرات أيضًا لإضافة أو تعديل البيانات. يفيدك ذلك عند العمل مع قاعدة بيانات موجودة مسبقًا، ولا يمكن حذفها وإعادة إنشاؤها، مثل قاعدة البيانات المنتجة.<syntaxhighlight lang="rails">
class AddInitialProducts < ActiveRecord::Migration[5.0]
  def up
    5.times do |i|
      Product.create(name: "Product ##{i}", description: "A product.")
    end
  end
 
  def down
    Product.delete_all
  end
end
</syntaxhighlight>لإضافة بيانات ابتدائية بعد إنشاء قاعدة البيانات، يملك ريلز ميزة "البذور" (seeds) التي تجعل الأمر سهلًا وسريعًا. يفيدك ذلك بشكل خاص عند إعادة تحميل قاعدة البيانات بشكل متكرر في بيئات التطوير والاختبار. من السهل البدء بهذه الميزة: فقط املأ الملف db/seeds.rb بشيفرة [[Ruby|روبي]]، ثم شغّل <code>rails db:seed</code>.<syntaxhighlight lang="rails">
5.times do |i|
  Product.create(name: "Product ##{i}", description: "A product.")
end
</syntaxhighlight>هذه الطريقة أفضل بكثير لتهيئة قاعدة بيانات تطبيق جديد.

== مصادر ==
* [https://guides.rubyonrails.org/active_record_migrations.html صفحة Active Record Migrations في توثيق Ruby on Rails الرسمي.]