Add documentation for running pgcli in ipython.

1 files changed, 86 insertions, 1 deletions

diff --git a/README.rst b/README.rst
index 006f3ff9..93216d58 100644
--- a/README.rst
+++ b/README.rst
@@ -65,7 +65,7 @@ The `pgcli` is written using prompt_toolkit_.
 
 * Primitive support for ``psql`` back-slash commands.
 * Pretty prints tabular data.
-  Note: `pgcli` uses the `tabulate`_ package to pretty-print tables. This library does smart formatting 
+  Note: `pgcli` uses the `tabulate`_ package to pretty-print tables. This library does smart formatting
   of numbers, which can sometimes lead to unexpected output. See `this issue`_ for more details.
 
 .. _prompt_toolkit: https://github.com/jonathanslenders/python-prompt-toolkit
@@ -208,6 +208,91 @@ the docker container:
 
     $ docker run --rm -ti -v /var/run/postgres:/var/run/postgres pgcli pgcli foo
 
+
+IPython
+=======
+
+Pgcli can be run from within IPython console. When working on a query, it may be useful to drop
+into a pgcli session without leaving the IPython console, iterate on a query, then quit pgcli
+to find the query results in your IPython workspace.
+
+Assuming you have IPython installed:
+
+::
+
+    $ pip install ipython-sql
+
+After that, run ipython and load the ``pgcli.magic`` extension:
+
+::
+
+    $ ipython
+    Python 2.7.12 (default, Nov  1 2016, 07:58:43)
+    Type "copyright", "credits" or "license" for more information.
+
+    IPython 5.4.1 -- An enhanced Interactive Python.
+    ?         -> Introduction and overview of IPython's features.
+    %quickref -> Quick reference.
+    help      -> Python's own help system.
+    object?   -> Details about 'object', use 'object??' for extra details.
+
+    In [1]: %load_ext pgcli.magic
+
+
+Connect to a database and construct a query:
+
+::
+
+    In [2]: %pgcli postgres://someone@localhost:5432/world
+    Connected: someone@world
+    Version: 1.7.0
+    Chat: https://gitter.im/dbcli/pgcli
+    Mail: https://groups.google.com/forum/#!forum/pgcli
+    Home: http://pgcli.com
+    someone@localhost:world> select * from city c where countrycode = 'USA' and population > 1000000;
+    +------+--------------+---------------+--------------+--------------+
+    | id   | name         | countrycode   | district     | population   |
+    |------+--------------+---------------+--------------+--------------|
+    | 3793 | New York     | USA           | New York     | 8008278      |
+    | 3794 | Los Angeles  | USA           | California   | 3694820      |
+    | 3795 | Chicago      | USA           | Illinois     | 2896016      |
+    | 3796 | Houston      | USA           | Texas        | 1953631      |
+    | 3797 | Philadelphia | USA           | Pennsylvania | 1517550      |
+    | 3798 | Phoenix      | USA           | Arizona      | 1321045      |
+    | 3799 | San Diego    | USA           | California   | 1223400      |
+    | 3800 | Dallas       | USA           | Texas        | 1188580      |
+    | 3801 | San Antonio  | USA           | Texas        | 1144646      |
+    +------+--------------+---------------+--------------+--------------+
+    SELECT 9
+    Time: 0.003s
+
+
+Exit out of pgcli session with ``Ctrl + D`` and find the query results:
+
+::
+
+    someone@localhost:world>
+    Goodbye!
+    9 rows affected.
+    Out[2]:
+    [(3793, u'New York', u'USA', u'New York', 8008278),
+     (3794, u'Los Angeles', u'USA', u'California', 3694820),
+     (3795, u'Chicago', u'USA', u'Illinois', 2896016),
+     (3796, u'Houston', u'USA', u'Texas', 1953631),
+     (3797, u'Philadelphia', u'USA', u'Pennsylvania', 1517550),
+     (3798, u'Phoenix', u'USA', u'Arizona', 1321045),
+     (3799, u'San Diego', u'USA', u'California', 1223400),
+     (3800, u'Dallas', u'USA', u'Texas', 1188580),
+     (3801, u'San Antonio', u'USA', u'Texas', 1144646)]
+
+The results are available in special local variable ``_``, and can be assigned to a variable of your
+choice:
+
+::
+
+    In [3]: my_result = _
+
+
 Thanks:
 -------