Merge branch 'tc-binary-enc-columns-docs' into 'master'

doc: Recommend binary type for encrypted attribute

See merge request gitlab-org/gitlab!61600

doc/development/database/strings_and_the_text_data_type.md

@@ -34,11 +34,9 @@ but only for updating the declaration of the columns. We can then validate it at
 `VALIDATE CONSTRAINT`, which requires only a `SHARE UPDATE EXCLUSIVE LOCK` (only conflicts with other
 validations and index creation while it allows reads and writes).
 
-### Exceptions
-
-Text columns used by `attr_encrypted` are not required to have a limit, because the length of the
-text after encryption may be longer than the text itself. Instead, you can use an Active Record
-length validation on the attribute.
+NOTE:
+Don't use text columns for `attr_encrypted` attributes. Use a
+[`:binary` column](../migration_style_guide.md#encrypted-attributes) instead.
 
 ## Create a new table with text columns
 

doc/development/migration_style_guide.md

@@ -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.