Metadata-Version: 2.1
Name: visaplan.zope.reldb
Version: 1.0.0.dev2
Summary: Configure a Data source name for Zope
Home-page: UNKNOWN
Author: Tobias Herp
Author-email: tobias.herp@visaplan.com
License: GPL version 2
Project-URL: Source, https://github.com/visaplan/zope.reldb
Project-URL: Documentation, https://pypi.org/project/visaplan.zope.reldb
Project-URL: Tracker, https://github.com/visaplan/zope.reldb/issues
Description: .. This README is meant for consumption by humans and pypi. Pypi can render rst files so please do not use Sphinx features.
           If you want to learn more about writing documentation, please check out: http://docs.plone.org/about/documentation_styleguide.html
           This text does not appear on pypi or github. It is a comment.
        
        .. image::
           https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
               :target: https://pycqa.github.io/isort/
        
        ===================
        visaplan.zope.reldb
        ===================
        
        This package simply provides the configuration of a `Data source name`_ (DSN),
        e.g. for use with SQLAlchemy_.
        
        For the heavy lifting of integration of database transactions of your
        relational database (like PostgreSQL_ or whatever) with the ZODB_, you'll
        likely want to use something like zope.sqlalchemy_, which in turn requires
        sqlalchemy_ to talk to the database.  However, zope.sqlalchemy_ doesn't offer a
        configuration method for the DSN.  This packages offers to store this DSN in
        the Zope configuration file (``parts/clientN/etc/zope.conf``).
        
        The idea is: You might have several instances of your Zope (for production,
        testing, development ...), and every now and then you replicate the productive
        data.  With the DSN stored in the ZODB, you'd have this information replicated
        as well, which might not work for you; you might have different databases on
        the same database server, or the production server connects to the database by
        socket which is not possible in your development instance, or whatever.
        
        
        Features
        ========
        
        - Stores a DSN string in the Zope configuration and provides a `get_dsn`
          function.
        - With SQLAlchemy_ installed,
        
          - creates an Engine and a DBSession,
            and
          - provides an optional `.legacy.SQLWrapper` context manager class
            which sports a few simple
            `insert`, `update`, `delete`, `select` and `query` methods
        
        - With zope.sqlalchemy_ installed as well, registers that DBSession
          for the transaction machinery integration.
        
        
        Installation
        ============
        
        Add the package to your product requirements somehow;
        since we'll need to add a product configuration as well,
        you'll most likely add it to your `eggs` value
        in your buildout script (`buildout.cfg`)::
        
        
            [buildout]
        
            ...
        
            eggs =
                your.fancy.product
                visaplan.zope.reldb
        
        Add a product configuration there as well, containing your data source name::
        
            [buildout]
        
            ...
        
            [instance_base]
            ...
            zope-conf-additional =
                <product-config reldb>
                dsn postgresql+psycopg2://localhost/mydb
                </product-config>
        
        (We follow the convention used by the UnifiedInstaller_ here; your section(s)
        might be named differently.)
        
        After running ``bin/buildout`` and restarting your Zope instance,
        the product configuration should have been added to your `zope.conf` file(s),
        and `your.fancy.product` can read the DSN string by calling
        `visaplan.zope.reldb.get_dsn` (*or*, if you have SQLAlchemy_,
        directly use `visaplan.zope.reldb.engine.engine`).
        
        
        Remark
        ------
        
        "But, can't my product simply do all this by itself?!"
        
        Sure. Having this as a package helps / helped us to switch a whole bunch of
        packages from usage of Zope database adapters (stored in the ZODB) to
        sqlalchemy (with a DSN configured in the ``zope.conf`` file(s)).
        
        
        Contribute
        ==========
        
        - Issue Tracker: https://github.com/visaplan/zope.reldb/issues
        - Source Code: https://github.com/visaplan/zope.reldb
        
        
        Support
        =======
        
        If you are having issues, please let us know;
        please use the `issue tracker`_ mentioned above.
        
        
        License
        =======
        
        The project is licensed under the GPLv2.
        
        Futher reading
        ==============
        
        * The `SQLAlchemy documentation`_ about `Database URLs`_
        
        .. _`Database URLs`: https://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls
        .. _`data source name`: https://en.wikipedia.org/wiki/Data_source_name
        .. _`issue tracker`: https://github.com/visaplan/zope.reldb/issues
        .. _PostgreSQL: https://www.postgresql.org
        .. _`SQLAlchemy documentation`: https://docs.sqlalchemy.org
        .. _sqlalchemy: https://pypi.org/project/sqlalchemy
        .. _UnifiedInstaller: https://github.com/plone/Installers-UnifiedInstaller#installation
        .. _ZODB: https://en.wikipedia.org/wiki/Zope_Object_Database
        .. _zope.sqlalchemy: ://pypi.org/project/zope.sqlalchemy
        
        .. vim: tw=79 cc=+1 sw=4 sts=4 si et
        
        
        Contributors
        ============
        
        - Tobias Herp, tobias.herp@visaplan.com
        
        
        Changelog
        =========
        
        
        1.0.0 (unreleased)
        ------------------
        
        - Initial release.
          [tobiasherp]
        
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 4.3
Classifier: Framework :: Plone :: 5.0
Classifier: Framework :: Plone :: 5.1
Classifier: Framework :: Plone :: 5.2
Classifier: Framework :: Zope
Classifier: Framework :: Zope2
Classifier: Framework :: Zope3
Classifier: Framework :: Zope :: 2
Classifier: Framework :: Zope :: 3
Classifier: Framework :: Zope :: 4
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Description-Content-Type: text/x-rst
