.. cannot use auto-doc here, sqlalchemy dependency!

Database-based stores
*********************


SQLAlchemy
----------

To store data in existing databases, an `SQLAlchemy <http://sqlalchemy.org>`_
based store is available:

::

  from minimalkv.db.sql import SQLAlchemyStore
  from sqlalchemy import create_engine, MetaData

  # use echo=True to see queries
  engine = create_engine('sqlite:///:memory:', echo=True)

  metadata = MetaData(bind=engine)

  # init store
  store = SQLAlchemyStore(engine, metadata, 'kvstore')

  # create the actual table in the database (only do this once!)
  metadata.create_all()
  # also possible: store.table.create()

  # use store normally
  store.put(u'my_key', 'some value')

  print(store.get(u'my_key'))

.. class:: minimalkv.db.sql.SQLAlchemyStore

   Stores data in a table in a database through `SQLAlchemy
   <http://sqlalchemy.org>`_.

   Note that this storage is not well-suited for large binary data, as
   currently it does not support streaming of large blobs. In other words,
   every value must be read into memory, before it can be returned.

   .. method:: __init__(bind, metadata, tablename)

      Generates a new :class:`~sqlalchemy.schema.Table` for use as a
      backend (see :attr:`~minimalkv.db.sql.SQLAlchemyStore.table`) on the
      supplied metadata.

      :param bind: Any queries made by the store run
                   :meth:`~sqlalchemy.sql.expression.Executable.execute`
                   using this bind.
      :param metadata: :class:`sqlalchemy.schema.MetaData` instance on which
                       the table will be created.
      :param tablename: The name for the table.

   .. attribute:: table

      An :class:`sqlalchemy.schema.Table` instance autogenerated by
      :meth:`__init__`.  Calling :meth:`~sqlalchemy.schema.Table.create` can be
      used to create the table in the database.

MongoDB
-------

The :class:`~minimalkv.db.mongo.MongoStore` class requires the ``pymongo``
package to be installed.

.. class:: minimalkv.db.mongo.MongoStore

   .. method:: __init__(db, collection)

       Uses a MongoDB collection as the backend, using pickle as a serializer.

       :param db: A (already authenticated) pymongo database.
       :param collection: A MongoDB collection name.