diff --git a/postgres/README.org b/postgres/README.org
new file mode 100644
index 0000000..a556706
--- /dev/null
+++ b/postgres/README.org
@@ -0,0 +1,23 @@
+# -*- ispell-local-dictionary: "english" -*-
+
+* Usage
+
+By default, =postgres= charm won't need any options in general.
+
+However, services using =postgres= through relations will typically
+want to set some options (if the default behavior is not enough).
+
+#+begin_src yaml
+myservice:
+  relations:
+    postgres-database:
+      postgres:
+        dbname: foo     ## default uses the name of querying service (here: 'myservice')
+        user: mydbuser  ## default uses the name of querying service (here: 'myservice')
+        password: bar   ## if not set, a random password will be generated
+        extensions:     ## default is empty list
+          - unaccent
+          - pg_trgm
+        init-sql: !bash-stdout | ## default is empty
+          zcat "$BASE_CHARM_PATH/src/init.sql.gz"
+#+end_src