diff options
Diffstat (limited to 'doc/development/migration_style_guide.md')
| -rw-r--r-- | doc/development/migration_style_guide.md | 42 |
1 files changed, 38 insertions, 4 deletions
diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index e1444f1a726..009ead8ba16 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -45,16 +45,16 @@ columns manually for existing tables as this causes confusion to other people using `db/structure.sql` generated by Rails. When your local database in your GDK is diverging from the schema from -`master` it might be hard to cleanly commit the schema changes to +`main` it might be hard to cleanly commit the schema changes to Git. In that case you can use the `scripts/regenerate-schema` script to regenerate a clean `db/structure.sql` for the migrations you're adding. This script applies all migrations found in `db/migrate` or `db/post_migrate`, so if there are any migrations you don't want to commit to the schema, rename or remove them. If your branch is not -targeting `master` you can set the `TARGET` environment variable. +targeting `main` you can set the `TARGET` environment variable. ```shell -# Regenerate schema against `master` +# Regenerate schema against `main` scripts/regenerate-schema # Regenerate schema against `12-9-stable-ee` @@ -844,7 +844,7 @@ You have to use a serializer to provide a translation layer: ```ruby class BuildMetadata - serialize :config_options, Serializers::JSON # rubocop:disable Cop/ActiveRecordSerialize + serialize :config_options, Serializers::Json # rubocop:disable Cop/ActiveRecordSerialize end ``` @@ -856,6 +856,37 @@ class BuildMetadata end ``` +## Encrypted attributes + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227779) in GitLab 14.0. + +Do not store `attr_encrypted` attributes as `:text` in the database; use +`:binary` instead. This uses the `bytea` type in PostgreSQL and makes storage more +efficient: + +```ruby +class AddSecretToSomething < ActiveRecord::Migration[5.0] + def change + add_column :something, :encrypted_secret, :binary + add_column :something, :encrypted_secret_iv, :binary + end +end +``` + +When storing encrypted attributes in a binary column, we need to provide the +`encode: false` and `encode_iv: false` options to `attr_encrypted`: + +```ruby +class Something < ApplicationRecord + attr_encrypted :secret, + mode: :per_attribute_iv, + key: Settings.attr_encrypted_db_key_base_32, + algorithm: 'aes-256-gcm', + encode: false, + encode_iv: false +end +``` + ## Testing See the [Testing Rails migrations](testing_guide/testing_migrations_guide.md) style guide. @@ -945,6 +976,9 @@ If using a model in the migrations, you should first [clear the column cache](https://api.rubyonrails.org/classes/ActiveRecord/ModelSchema/ClassMethods.html#method-i-reset_column_information) using `reset_column_information`. +If using a model that leverages single table inheritance (STI), there are [special +considerations](single_table_inheritance.md#in-migrations). + This avoids problems where a column that you are using was altered and cached in a previous migration. |