Merge pull request #35 from danielberkompas/20-troubleshooting-guide

📝 Document fix for :default values

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

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
+```

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",