skip to content

A Rails 8.1 hospital app already stores national IDs in plain text; how do you switch the column to encrypts without breaking reads or lookups?

level: seniorimportance: should knowfreq 30%

answer

  1. old rows raise Errors::Decryption
  2. support_unencrypted_data, per attribute since 8.1
  3. extend_queries for lookups on mixed data
  4. backfill with record.encrypt in batches
  5. turn both off when done

basics

~10 s

Declare encrypts with support_unencrypted_data: true so plain rows still read, enable extend_queries so deterministic lookups match both forms, re-encrypt existing rows with record.encrypt in batches, then remove both settings.

solid answer

~30 s

Adding `encrypts :national_id, deterministic: true` to a column full of plain text breaks reads: decrypting a non-ciphertext raises `ActiveRecord::Encryption::Errors::Decryption`, because `support_unencrypted_data` defaults to false. For the transition, allow plain values on read, either globally with `config.active_record.encryption.support_unencrypted_data = true` or, since Rails 8.1, on just this attribute with `support_unencrypted_data: true`. Lookups need `config.active_record.encryption.extend_queries = true`, so `find_by(national_id:)` searches for both the plain and the encrypted form. Widen the column first if needed. Then backfill: `Patient.find_each(&:encrypt)` re-saves every encrypted attribute with `update_columns`, which skips validations and callbacks. When every row is ciphertext, remove `support_unencrypted_data` and `extend_queries` so plain values are rejected again.

code

ruby · 10 lines
ruby
# app/models/patient.rb (transition release)
class Patient < ApplicationRecord
  encrypts :national_id, deterministic: true, support_unencrypted_data: true
end

# config/application.rb (transition release)
config.active_record.encryption.extend_queries = true

# Backfill, from a job or task
Patient.find_each(&:encrypt)

go deeper

for a junior

Recall that existing plain values do not encrypt themselves and need a migration plan.

for a middle

Explain support_unencrypted_data, extend_queries, and backfilling with record.encrypt.

for a senior

Run the whole rollout: column sizing, a transition release, a resumable backfill, verification, and closing the transition settings, including uniqueness concerns.

for a principal

Weigh downtime, audit requirements and the risk of plain data creeping back when planning encryption of a large, live dataset.

## The problem A hospital system has `patients.national_id` holding plain text and must now encrypt it while front-desk staff keep looking patients up by it. Simply adding ```ruby encrypts :national_id, deterministic: true ``` causes two failures at once: 1. **Reads break.** Loading an old row tries to decrypt `"AB123456C"`, which is not an encrypted message. With `support_unencrypted_data` false, the default, Rails raises `ActiveRecord::Encryption::Errors::Decryption`. 2. **Lookups miss.** `Patient.find_by(national_id: "AB123456C")` encrypts the argument and compares it with a column that still holds plain text, so old rows are not found. ## The two transition settings | Setting | Default | What it does | |---|---|---| | `support_unencrypted_data` | false | reading a value that is not ciphertext returns it as is instead of raising | | `extend_queries` | false | queries on deterministic attributes also search for the plain value and for ciphertexts from previous schemes | `support_unencrypted_data` can be set globally with `config.active_record.encryption.support_unencrypted_data = true` or per attribute with `encrypts ..., support_unencrypted_data: true`. **Since Rails 8.1, the per-attribute option works even when the global setting is false**, so you can open the door for one column without relaxing every encrypted attribute in the app. `extend_queries` is global only. ## A safe sequence 1. **Make room.** Check the column's limit: the encrypted envelope adds up to about 255 bytes, so a `string(20)` must grow, for example to `string(510)`. Ship that migration on its own. 2. **Declare encryption in transition mode.** ```ruby encrypts :national_id, deterministic: true, support_unencrypted_data: true ``` and in `config/application.rb`, `config.active_record.encryption.extend_queries = true`. Keys must already be in credentials for every environment. 3. **Deploy.** New and updated rows are written encrypted; old rows still read; lookups match both forms. 4. **Backfill.** Re-encrypt existing rows: ```ruby Patient.find_each(&:encrypt) ``` `encrypt` assigns each encrypted attribute its current value and calls `update_columns`, so it writes ciphertext **without running validations or callbacks and without touching `updated_at`**. Run it from a job or task, in batches, so it can resume. 5. **Verify.** Count rows whose value is still plain, for example with `encrypted_attribute?(:national_id)` over a batch, until none remain. 6. **Close the door.** Remove `support_unencrypted_data: true` and set `extend_queries` back to false. From now on a plain value in that column raises, which is what you want: it signals a write that bypassed the model. ## Why not leave the transition settings on - With `support_unencrypted_data`, a row written through raw SQL or a bulk import in plain text reads without complaint, so unencrypted data can creep back in unnoticed. - `extend_queries` is described in the source as experimental; it patches relation queries and widens every lookup on deterministic attributes. - The guide calls the false/false pair the recommended long-term configuration. ## Uniqueness during the transition A uniqueness validation on a deterministic attribute compares ciphertexts. While some rows are plain and some encrypted, the same ID could appear in both forms and the validation would miss it. The guide says to enable `extend_queries` for unique validations on mixed data; a unique **index** cannot see through that difference at all, so add it only after the backfill. ## Other paths that skip encryption - Raw SQL that writes the column bypasses the attribute type, so it stores whatever value it is given. - `ActiveRecord::Encryption.without_encryption { ... }` deliberately writes plain values; keep it out of production code paths. ## What interviewers check - That you know old plain rows raise on read by default. - That you can name `support_unencrypted_data`, `extend_queries` and the 8.1 per-attribute option. - That you backfill with `encrypt`, understand that it skips callbacks, and switch the transition settings off afterwards.

  • Why does Patient.find_each(&:encrypt) not change updated_at or fire after_save callbacks?
    `EncryptableRecord#encrypt` builds a hash of each encrypted attribute's current value and writes it with `update_columns`, which issues a direct UPDATE without validations, callbacks or timestamp changes. That is usually what a backfill wants, but anything that relies on callbacks, such as an audit trail, must be handled separately.
  • After the backfill, a nightly import writes national IDs with raw SQL; what happens once support_unencrypted_data is off?
    The imported rows hold plain text, and reading them raises `ActiveRecord::Encryption::Errors::Decryption`. That failure is useful: it exposes a write path that bypasses the model. Fix the import to go through Active Record, or encrypt the values before inserting.

  • Adding encrypts to an existing column encrypts the old rows automatically.
  • support_unencrypted_data alone makes lookups find the plain rows.
  • record.encrypt runs validations and callbacks like save.
  • Leave support_unencrypted_data on permanently in case old data appears.
  • In Rails 8.1 support_unencrypted_data can only be set globally.

Assumes Rails 8.1; since 8.1 support_unencrypted_data: true on a single encrypts declaration works even when the global support_unencrypted_data setting is false.