Added raw_query support, documentation and tests

1 files changed, 10 insertions, 2 deletions

diff --git a/README.markdown b/README.markdown
index c85139a..2b90921 100644
--- a/README.markdown
+++ b/README.markdown
@@ -21,9 +21,7 @@ Features
 TODO
 ----
 
-* Implement raw queries.
 * Improve documentation.
-* Proper testing.
 * More features.
 
 Philosophy
@@ -112,6 +110,16 @@ Two methods are provided to add `ORDER BY` clauses to your query. These are `ord
 
     ORM::for_table('person')->order_by_asc('gender')->order_by_desc('name')->find_many();
 
+#### Raw queries ####
+
+If you need to perform more complex queries, you can completely specify the query to execute by using the `raw_query` method. This method takes a string and an array of parameters. The string should contain placeholders, either in question mark or named placeholder syntax, which will be used to bind the parameters to the query.
+
+    ORM::for_table('person')->raw_query('SELECT p.* FROM person p JOIN role r ON p.role_id = r.id WHERE r.name = :role', array('role' => 'janitor')->find_many();
+
+The ORM class instance(s) returned will contain data for all the columns returned by the query. Note that you still must call `for_table` to bind the instances to a particular table, even though there is nothing to stop you from specifying a completely different table in the query. This is because if you wish to later called `save`, the ORM will need to know which table to update.
+
+Note that using `raw_query` is advanced and possibly dangerous, and Idiorm does not make any attempt to protect you from making errors when using this method. If you find yourself calling `raw_query` often, you may have misunderstood the purpose of using an ORM, or your application may be too complex for Idiorm. Consider using a more full-featured database abstraction system.
+
 ### Getting data from objects ###
 
 Once you've got a set of records (objects) back from a query, you can access properties on those objects (the values stored in the columns in its corresponding table) in two ways: by using the `get` method, or simply by accessing the property on the object directly: