Add docs

README.rst

@@ -12,7 +12,7 @@ Shillelagh
 .. image:: https://img.shields.io/pypi/pyversions/shillelagh
    :alt: PyPI - Python Version
 
-Shillelagh (ʃɪˈleɪlɪ) is a Python library and CLI that allows you to query many resources (APIs, files, in memory objects) using SQL. It's both user and developer friendly, making it trivial to access resources and easy to add support for new ones.
+Shillelagh (ʃɪˈleɪlɪ) is a Python library and CLI that allows you to **query many resources (APIs, files, in memory objects) using SQL**. It's both user and developer friendly, making it trivial to access resources and easy to add support for new ones.
 
 Learn more on the `documentation <https://shillelagh.readthedocs.io/en/latest/>`_.
 
@@ -49,6 +49,25 @@ And a command-line utility:
     $ shillelagh
     sql> SELECT * FROM a_table
 
+There is also an [experimental backend](https://shillelagh.readthedocs.io/en/latest/postgres.html) that uses Postgres with the [Multicorn2](http://multicorn2.org/) extension:
+
+.. code-block:: python
+
+    from shillelagh.backends.multicorn.db import connect
+
+    connection = connect(
+        username="username",
+        password="password",
+        host="localhost",
+        port=5432,
+        database="examples",
+    )
+
+.. code-block:: python
+
+    from sqlalchemy import create_engine
+    engine = create_engine("shillelagh+multicorn2://username:password@localhost:5432/examples")
+
 Why SQL?
 ========
 

docs/index.rst

@@ -10,6 +10,7 @@ Contents
    Usage <usage>
    Adapters <adapters>
    Creating a new adapter <development>
+   Postgres backend <postgres>
    License <license>
    Authors <authors>
    Changelog <changelog>

docs/postgres.rst

@@ -0,0 +1,23 @@
+.. _postgres:
+
+================
+Postgres backend
+================
+
+Since version 1.3 Shillelagh ships with an experimental backend that uses Postgres instead of SQLite. The backend implements a custom [pyscopg2](https://pypi.org/project/psycopg2/) cursor that automatically registers a foreign data wrapper (FDW) whenever a supported table is accessed. It's based on the [multicorn2](http://multicorn2.org/) extension and Python package.
+
+To use the backend you need to:
+
+1. Install the [Multicorn2](http://multicorn2.org/) extension.
+2. Install the multicorn2 Python package in the machine running Postgres. Note that this is not the "multicorn" package available on PyPI. You need to download the source and install it manually.
+3. Install Shillelagh in the machine running Postgres.
+
+Note that you need to install Python packages in a way that they are available to the process running Postgres. You can either install them globally, or install them in a virtual environment and have it activated in the process that starts Postgres.
+
+The ``postgres/`` directory has a Docker configuration that can be used to test the backend, or as a basis for installation. To run it, enter the directory and execute:
+
+.. code-block:: bash
+
+   docker-compose up --build -d
+
+You should then be able to run the example script in `examples/postgres.py`_ to test that everything works.

src/shillelagh/backends/multicorn/db.py

@@ -222,6 +222,7 @@ def __call__(self, *args, **kwargs) -> Cursor:
 
 
 def connect(  # pylint: disable=too-many-arguments
+    dsn: Optional[str] = None,
     adapters: Optional[List[str]] = None,
     adapter_kwargs: Optional[Dict[str, Dict[str, Any]]] = None,
     schema: str = DEFAULT_SCHEMA,
@@ -252,6 +253,7 @@ def connect(  # pylint: disable=too-many-arguments
         schema,
     )
     return psycopg2.connect(
+        dsn,
         cursor_factory=cursor_factory,
         **psycopg2_connection_kwargs,
     )

tests/backends/multicorn/db_test.py

@@ -25,6 +25,7 @@ def test_connect(mocker: MockerFixture, registry: AdapterLoader) -> None:
     registry.add("dummy", FakeAdapter)
 
     connect(
+        None,
         ["dummy"],
         username="username",
         password="password",
@@ -33,6 +34,7 @@ def test_connect(mocker: MockerFixture, registry: AdapterLoader) -> None:
         database="database",
     )
     psycopg2.connect.assert_called_with(
+        None,
         cursor_factory=CursorFactory(
             {"dummy": FakeAdapter},
             {},