From b74d2d8094cfbdd9467bcd02a87eb5d1096524a5 Mon Sep 17 00:00:00 2001
From: Daniel Berkompas <himself@danielberkompas.com>
Date: Fri, 17 Jun 2022 07:58:33 -0700
Subject: [PATCH] :pencil: Document fix for :default values

Fixes #20. I added a new "Troubleshooting" guide to the hex
documentation, and also added a link to it from the README. I'd prefer
to do this rather than add a lot of edge-case information to the
README itself.
---
 README.md                        |  4 ++++
 guides/how_to/troubleshooting.md | 28 ++++++++++++++++++++++++++++
 mix.exs                          |  1 +
 3 files changed, 33 insertions(+)
 create mode 100644 guides/how_to/troubleshooting.md

diff --git a/README.md b/README.md
index 6520719..e8f467e 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,10 @@ iex> Repo.get(MyApp.EctoSchema, 1)
 
 For complete usage instructions, see the [Hex documentation](https://hexdocs.pm/cloak_ecto).
 
+## Troubleshooting
+
+See our [troubleshooting guide](/guides/how_to/troubleshooting.md) for solutions to common issues.
+
 ## Notable Features
 
 - Transparent, easy to use encryption for database fields
diff --git a/guides/how_to/troubleshooting.md b/guides/how_to/troubleshooting.md
new file mode 100644
index 0000000..7f279b5
--- /dev/null
+++ b/guides/how_to/troubleshooting.md
@@ -0,0 +1,28 @@
+# Troubleshooting
+
+### Error when validating default values
+If you have a field in your schema with a `:default` value, and are running Ecto
+3.6 or later, you may encounter an error like this:
+
+```
+** (ArgumentError) errors were found at the given arguments:
+
+  * 1st argument: the table identifier does not refer to an existing ETS table
+
+    (stdlib 4.0) :ets.lookup(MyApp.Vault.Config, :config)
+    (cloak 1.1.2) lib/cloak/vault.ex:285: Cloak.Vault.read_config/1
+    lib/cloak/vault.ex:224: MyApp.Vault.encrypt/1
+    lib/cloak_ecto/type.ex:37: Cloak.Ecto.Encrypted.Binary.dump/1
+    (ecto 3.8.4) lib/ecto/schema.ex:2198: Ecto.Schema.validate_default!/3
+    (ecto 3.8.4) lib/ecto/schema.ex:1919: Ecto.Schema.__field__/4
+    lib/my_app/post.ex:9: (module)
+```
+
+This error happens because `cloak` relies on an ETS table which is only available
+at runtime, and Ecto 3.6+ tries to validate default values at compile time.
+
+To fix it, add the `:skip_default_validation` option:
+
+```elixir
+field :name, MyApp.Encrypted.Binary, default: "foo", skip_default_validation: true
+```
diff --git a/mix.exs b/mix.exs
index c86199f..943d75f 100644
--- a/mix.exs
+++ b/mix.exs
@@ -72,6 +72,7 @@ defmodule Cloak.Ecto.MixProject do
         "guides/how_to/generate_keys.md": [title: "Generate Encryption Keys"],
         "guides/how_to/encrypt_existing_data.md": [title: "Encrypt Existing Data"],
         "guides/how_to/rotate_keys.md": [title: "Rotate Keys"],
+        "guides/how_to/troubleshooting.md": [title: "Troubleshooting"],
         "guides/upgrading/0.9.x_to_1.0.x.md": [title: "0.9.x to 1.0.x"]
       ],
       extra_section: "GUIDES",