diff --git a/README.md b/README.md
new file mode 100644
index 0000000..09efa3d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,32 @@
+# ezpg
+
+this is predominantly a stripped-down and opinionated version of [miniorm](https://crates.io/miniorm) by [meuter](https://github.com/meuter/miniorm-rs).
+
+while some verbiage is changed to reflect the fact this is postgres-only and has some flexibility removed, the actual value comes from miniorm with a splash of [some changes i've proposed](https://github.com/Arcayr/miniorm-rs/tree/uuid-handler-trait).
+
+do not use this unless you specifically want postgres-only, uuid-only entity records.
+
+## usage
+
+```rust
+use sqlx::FromRow;
+use ezpg::Record;
+
+#[derive(FromRow, Record)]
+struct Item {
+    title: String,
+    description: String,
+}
+
+// ...
+
+// Item derives `Record`, providing query functions.
+fn do_thing(db_pool: &PgPool) -> sqlx::Result<Item> {
+    let item = Item { title: String::from("hi"), description: String::from("no") };
+    item.create(db_pool); // example uuid: 01940cf1-0249-73dc-ac19-79fb07a51ba1
+
+    let mut new_item = Item::read(Uuid::from("01940cf1-0249-73dc-ac19-79fb07a51ba1"))?;
+    new_item.title = String::from("whoa!");
+    new_item.update(db_pool)?;
+}
+```