adds documentation

README.md

@@ -1,59 +1,26 @@
 # alog
 alog (Append-only Log) is an easy way to start using the Lambda/Kappa architecture in your Elixir/Phoenix Apps while still using PostgreSQL (with Ecto).
 
-This module provides some helper functions to make it easy to insert and retrieve the data you need.
+This module is an Ecto Adapter that extends the default Postgres adapter with functionality to ensure data is only ever appended, never deleted or edited.
 
 ## Usage
 
-  At the top of the schema you wish to use append only functions for, `use` this module:
+ In your Repo module, when defining your Ecto Repo, set the adapter to be this module, Alog
 
-  ``` elixir
-  use Alog
-  ```
-
-  The append only functions will then be available to call as part of your schema.
-
-  ## Example
-
-  ``` elixir
-  defmodule MyApp.User do
-    use Ecto.Schema
-    use Alog
-
-    import Ecto.Changeset
-
-    schema "users" do
-      ...
-    end
-
-    def changeset(user, attrs) do
-      ...
-    end
+ ``` elixir
+  defmodule MyApp.Repo do
+    use Ecto.Repo,
+      otp_app: :my_app,
+      adapter: Alog
   end
-  ```
-
-  ## Repo
-
-  You can set the repo you want Alog to use in a config file:
-
-  ``` elixir
- config :alog, Alog,
-    repo: MyApp.Repo
-  ```
-
-  If you do not explicitly set a Repo, Alog will try to find it using your application name.
-  So if your app is `MyApp` and your schema is `MyApp.User`, or `MyApp.Accounts.User`, your Repo should be `MyApp.Repo`.
-
-  ## Uniqueness
+ ```
 
-  Due to the append only manner in which Alog stores data, it is not compatible with tables that have Unique Indexes applied to any of their columns. If you wish to use alog, you will have to remove these indexes.
+## Considerations
 
-  For example, the following in a migration file would remove a unique index on the `email` column from the `users` table.
+- When inserting or updating an item, the return value of the insert/update function is currently incorrect. The updates and inserts are however done correctly, as you will see if you get all items from the database using `Repo.all`.
 
-  ```
-  drop(unique_index(:users, :email))
-  ```
+- We exclude the `schema_migrations` file from all alog functions, instead forwarding them on to the original Postgres Adapter.
 
-  See https://hexdocs.pm/ecto_sql/Ecto.Migration.html#content for more details.
+- The autogenerated cid is used as the primary key. There is no way currently to define a custom primary key.
 
-  If you want to ensure each entry in your database has a unique field, you can use the [`Ecto.Changeset.unique_constraint/3`](https://hexdocs.pm/ecto/Ecto.Changeset.html#unique_constraint/3) function as normal, and Alog will ensure there are no repeated fields, other than those of the same entry, returning an invalid changeset if there are.
+Hopefully these issues can later be resolved by looking at defining/extending our own version of the the `Ecto.Schema` macro.