Zero to an encrypted attribute, ending with you looking at the ciphertext in your own database.

By the end you will have: a key provider running, a vault, a resource with an encrypted :email, a row you can read back as plaintext through Ash, and a psql query proving the column holds an AshVault envelope and no trace of the email address.

Assumed: an existing Phoenix or Elixir app with Ash and ash_postgres already working.

1. Add the dependency

# mix.exs
def deps do
  [
    {:ash, "~> 3.0"},
    {:ash_postgres, "~> 2.0"},
    {:ash_vault, "~> 0.2.0"}
  ]
end
mix deps.get

Add AshVault to your formatter so the DSL formats correctly:

# .formatter.exs
[
  import_deps: [:ash, :ash_postgres, :ash_vault],
  ...
]

2. Pick a key provider

This is the one decision that matters, and the whole guarantee rests on it: the key store must be a different system from the database, so that restoring a database backup cannot restore the keys.

ProviderUse it for
AshVault.KeyProviders.Memorytests only — keys die with the process
AshVault.KeyProviders.Localsingle-node deployments, homelab, dev with persistence
AshVault.KeyProviders.OpenBaoproduction, multi-node

We will use Local: it persists across restarts (so your data survives an iex restart, which Memory would not), it needs no extra infrastructure, and it makes the "keys live somewhere else" requirement concrete — it is a directory you can point at.

Create the key root. This is an explicit, one-time operator step:

mix ash_vault.local.init priv/ash_vault_keys
Initialised AshVault key root: /home/you/my_app/priv/ash_vault_keys
  mode:     0700
  sentinel: .ash_vault_root

Back this directory up separately from the database, and exclude it from the
database backup job. See the AshVault.KeyProviders.Local moduledoc.

priv/ is fine for development and wrong for production

In production the key root belongs on its own volume, excluded from the database backup job — /var/lib/my_app/ash_vault_keys, say. If the keys and the database ever land in the same tarball, crypto-erasure is defeated. Add priv/ash_vault_keys/ to your .gitignore now, before you forget.

Configure it and start it:

# config/runtime.exs — under your own OTP application, not AshVault's
config :my_app, AshVault.KeyProviders.Local,
  root: System.get_env("ASH_VAULT_KEY_ROOT", "priv/ash_vault_keys")
# lib/my_app/application.ex
def start(_type, _args) do
  children =
    [MyApp.Repo] ++ MyApp.Vault.child_specs() ++ [MyAppWeb.Endpoint]

  Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
end

MyApp.Vault.child_specs/0 answers for whichever provider the vault was built with, so this line does not change when you move from Local to OpenBao — Local is a GenServer and contributes itself, OpenBao is stateless HTTP and contributes nothing.

The provider also needs a one-time operator step, which is deliberately not something a supervisor does on every boot. One line again, for any provider:

# a deploy step, a release command, or a `mix my_app.setup` task
:ok = MyApp.Vault.setup()

For AshVault.KeyProviders.Local that creates the key root and its .ash_vault_root sentinel; for AshVault.KeyProviders.OpenBao it mounts the KV-v2 engine that holds tombstones; for AshVault.KeyProviders.Memory it does nothing and returns :ok.

AshVault.KeyProviders.Local never creates its own key root as a side effect of starting; if the directory or its .ash_vault_root sentinel is missing it refuses to start, which is what stops an unmounted key volume from looking like a pristine, empty key store.

3. Define a vault

A vault bundles the key provider with a cipher, an envelope format, a scope and a rotation policy. Only the provider is required:

# lib/my_app/vault.ex
defmodule MyApp.Vault do
  use AshVault.Vault, key_provider: AshVault.KeyProviders.Local
end

The defaults are AshVault.Ciphers.AES.GCM, AshVault.Envelope.V1, AshVault.Scopes.AshTenant and AshVault.RotationPolicies.Manual — AES-256-GCM, per-tenant keys, rotate only when asked. That is the right starting point.

4. Add ash_vault to a resource

# lib/my_app/accounts/user.ex
defmodule MyApp.Accounts.User do
  use Ash.Resource,
    domain: MyApp.Accounts,
    data_layer: AshPostgres.DataLayer,
    extensions: [AshVault]

  ash_vault do
    vault MyApp.Vault

    encrypt :email

    decrypt_by_default [:email]
  end

  postgres do
    table "users"
    repo MyApp.Repo
  end

  multitenancy do
    strategy :attribute
    attribute :org_id
  end

  attributes do
    uuid_primary_key :id
    attribute :org_id, :uuid, allow_nil?: false, public?: true
    attribute :name, :string, public?: true
    attribute :email, :string, public?: true
  end

  actions do
    default_accept :*
    defaults [:read, :destroy, create: :*]

    update :update do
      primary? true
      require_atomic? false
    end
  end
end

Four things to notice:

  • encrypt :email replaces the attribute. At compile time the :email attribute is removed and replaced by a private encrypted_email :binary attribute plus an :email calculation that decrypts. There is no plaintext column, so no data layer can write one. You still declare attribute :email, :string — that declaration is what tells AshVault the type, the constraints and the nullability to preserve.
  • decrypt_by_default [:email] loads the decrypt calculation automatically. Without it you load :email explicitly, like any other calculation.
  • The default scope is the Ash tenant, so this resource needs multitenancy — here, attribute multitenancy on org_id. Every read and write must pass a tenant. (If you are not multitenant, see the note at the end.)
  • require_atomic? false is not required — AshVault.Changes.Encrypt implements atomic/3 and both paths scrub the plaintext from the changeset. It is here because most resources have other non-atomic changes; drop it if yours does not.

5. Generate and run the migration

mix ash.codegen add_encrypted_users
mix ash.migrate

The generated migration creates encrypted_email bytea and no email column — the attribute is gone by the time codegen sees the resource. Schema migrations like this need no keys at all.

6. Write and read

iex -S mix
org_id = Ecto.UUID.generate()

user =
  MyApp.Accounts.User
  |> Ash.Changeset.for_create(:create, %{org_id: org_id, name: "Ada", email: "ada@example.com"},
    tenant: org_id
  )
  |> Ash.create!()

user.email
#=> "ada@example.com"

The key was minted on that first write — version 1, created by current_key/1, with no explicit setup step.

Read it back:

[found] = Ash.read!(MyApp.Accounts.User, tenant: org_id)

found.email
#=> "ada@example.com"

decrypt_by_default loaded the calculation. Without it:

MyApp.Accounts.User
|> Ash.Query.load([:email])
|> Ash.read!(tenant: org_id)

7. Verify the column holds ciphertext

This is the step that matters. Look at the raw bytes:

%{rows: [[blob]]} = MyApp.Repo.query!("SELECT encrypted_email FROM users LIMIT 1")

# An AshVault envelope: "AV" magic, then the envelope version byte.
<<"AV", 1::8, _rest::binary>> = blob

# And no trace of the plaintext anywhere in it.
String.contains?(blob, "ada@example.com")
#=> false

String.contains?(blob, "example.com")
#=> false

There is no plaintext column at all:

MyApp.Repo.query!("""
SELECT column_name FROM information_schema.columns
WHERE table_name = 'users' AND column_name = 'email'
""").rows
#=> []

Decode the envelope to see what it actually carries — everything needed to decrypt except the key itself:

AshVault.Envelope.decode(blob)
#=> {:ok,
#=>  %{
#=>    version: 1,
#=>    cipher: "aes_256_gcm_v1",
#=>    key_version: 1,
#=>    nonce: <<...12 bytes...>>,
#=>    tag: <<...16 bytes...>>,
#=>    ciphertext: <<...>>
#=>  }}

That key_version: 1 is what makes rotation cheap: rotate the tenant's key and this row keeps decrypting with version 1 while new writes use version 2.

And the key material is where you put it, not in the database:

$ ls priv/ash_vault_keys/
.ash_vault_root  <base64-of-the-tenant-id>

$ ls priv/ash_vault_keys/<base64-of-the-tenant-id>/
meta.json  v1.key
AshVault.KeyProviders.Local.scope_dir(org_id)
#=> the directory name for that tenant

8. See what erasure does

The reason for all of this. Destroy the tenant's keys:

:ok = AshVault.destroy_keys!(MyApp.Vault, org_id)

Now read:

Ash.read(MyApp.Accounts.User, tenant: org_id)
#=> {:error, %Ash.Error.Invalid{errors: [%AshVault.Errors.KeyDestroyed{...}]}}
Encryption key for scope "<org_id>" (version 1) has been destroyed.

This data was cryptographically erased and cannot be recovered.

The row is still there. Its bytes are unchanged. Every backup you have taken still contains it — and none of them can be read. That is the whole library.

Note what the error is not: it is not CiphertextIntegrityFailed (which would mean tampering) and not ProviderUnavailable (which would mean retry). Destruction is checked before any decryption is attempted, and the provider records a tombstone so the tenant can never be silently re-minted — even if someone restores an old key directory over the top, the tombstone sits beside the scope directory rather than inside it.

In production this is a mix task with real guardrails — it makes you type the scope back, and --yes does not skip that:

mix ash_vault.destroy_keys MyApp.Accounts.Organization --tenant <org_id>

Where to go next

  • Architecture — what the five layers do and why the envelope carries a key version
  • Tenant-scoped encryption — how the tenant becomes a key, and the scope-agreement rule the verifier enforces
  • Crypto-erasure — the guarantee in detail, plus the operational checklist to run through before you rely on it
  • Threat model — read the non-goals before you promise anyone anything
  • Operations — provider setup, backups, and every error
  • Migrating from plaintext — if the column already has data in it

Notes and gotchas

If you are not multitenant, use the global scope. Both the vault and the resource must say so — the verifier requires the resource to restate a non-default scope:

defmodule MyApp.Vault do
  use AshVault.Vault,
    key_provider: AshVault.KeyProviders.Local,
    scope: AshVault.Scopes.Global
end

ash_vault do
  vault MyApp.Vault
  scope :global
  encrypt :email
end

One key lineage for the whole application, so rotation and erasure are application-wide.

You cannot filter or sort on an encrypted field. The decrypt calculation is filterable?: false, sortable?: false, because randomized AEAD ciphertext supports neither. See Searchable fields.

Every read and write needs a tenant, including background jobs and mix tasks. Without one you get AshVault.Errors.MissingScope:

Cannot encrypt MyApp.Accounts.User.email because no Ash tenant was present.

This resource uses tenant-scoped encryption.
Pass a tenant when executing the Ash action or configure another AshVault scope.

Do not lose the key directory. In this tutorial it is under priv/, which means a git clean -xfd destroys every encrypted value you have written. That is the correct behaviour — it is just cheaper to learn here than in production.