Update README.md

README.md

@@ -3,11 +3,11 @@ MySQL/OTP
 
 This is a MySQL driver for Erlang following the OTP principles.
 
-Status: Pre-alpha. Connecting and queries using the text protocol work. The API and the value representation are subjects to change.
+Status: Work in progress. Connecting and executing queries using the text protocol (plain queries) and binary protocols (prepared statements) work. The API and the value representation are subjects to change.
 
 Background: We are starting this project with the aim at overcoming the problems with Emysql (the currently most popular driver) and erlang-mysql-driver (the even older driver).
 
-Design choices (ideas):
+Design choices:
 
 * A connection is a gen_server.
 * No connection pool. Poolboy or your own supervisor can be used for this.
@@ -19,6 +19,60 @@ Contributing
 
 We welcome contributors and new members of the project. We are open for suggestions about the API, the internal design and almost anything else. Let's use the project's wiki for discussions and TODOs.
 
+Synopsis
+--------
+
+```Erlang
+Opts = [{host, "localhost"}, {user, "foo"}, {password, "hello"},
+        {database, "test"}],
+
+%% This will probably be renamed to start_link/1
+{ok, Pid} = mysql:connect(Opts),
+
+%% A query returning results
+{ok, ColumnNames, Rows} = mysql:query(Pid, <<"SELECT * FROM mytable">>),
+
+%% An "anonymous prepared statement" with parameters, prepared and executed
+%% on the fly. NOT IMPLEMENTED YET.
+{ok, ColumnNames, Rows} =
+    mysql:query(Pid, <<"SELECT * FROM mytable WHERE id=?">>, [42]),
+
+%% A query not returning any rows just returns ok.
+ok = mysql:query(Pid, "INSERT INTO mytable (foo, bar) VALUES (?, ?)",
+                 [1, 42]),
+
+%% Separate calls to fetch more info about the last query
+LastInsertId = mysql:insert_id(Pid),
+AffectedRows = mysql:affected_rows(Pid),
+WarningCount = mysql:warning_count(Pid),
+
+%% Named prepared statements
+{ok, foo} = mysql:prepare(Pid, "SELECT * FROM mytable WHERE id=?", foo),
+{ok, Columns, Rows} = mysql:execute(Pid, foo, [42]),
+
+%% Unnamed prepared statements
+{ok, StmtId} = mysql:prepare(Pid, "SELECT * FROM mytable WHERE id=?"),
+{ok, Columns, Rows} = mysql:execute(Pid, StmtId, [42]).
+
+%% Transactions: If an exception (throw/error/exit) occurs, the transaction
+%% is rollbacked without catching the exception. This means transactions are
+%% transparent to error handling. NOT IMPLEMENTED YET.
+try
+    mysql:transaction(
+        Pid,
+        fun () ->
+            ok = mysql:query(Pid, "INSERT INTO mytable (foo) VALUES (1)"),
+            throw(foo),
+            ok = mysql:query(Pid, "INSERT INTO mytable (foo) VALUES (1)")
+        end
+    )
+catch
+    throw:foo ->
+        %% Foo occurred. Fortunately nothing was stored.
+        foo_occured
+end.
+```
+
 Problems with Emysql
 --------------------
 
@@ -34,7 +88,7 @@ From the Emysql README:
 >
 >However, this is probably the best MySQL driver out there for Erlang. The erlang-mysql-driver uses a problematic connection pool design for many use cases and is not suitable for general purpose use. This driver is.
 
-Licence
+License
 -------
 
-GNU General Public License (GPL) version 3 or any later version. See the LICENCE file.
+GNU General Public License (GPL) version 3 or any later version. See the LICENSE file.