Metadata-Version: 1.1
Name: datafreeze
Version: 0.1.0
Summary: Export data from a SQL database to a set of file formats.
Home-page: http://github.com/pudo/datafreeze
Author: Friedrich Lindenberg, Gregor Aisch, Stefan Wehrmeyer
Author-email: friedrich@pudo.org
License: MIT
Description: datafreeze
        ==========
        
        .. figure:: https://api.travis-ci.org/datafreeze/aleph.png
           :target: https://travis-ci.org/pudo/datafreeze/
           :alt: Build Status
        
        ``datafreeze`` creates static extracts of SQL databases for use in interactive
        web applications. SQL databases are a great way to manage relational data, but
        exposing them on the web to drive data apps can be cumbersome. Often, the
        capacities of a proper database are not actually required, a few static JSON
        files and a bit of JavaScript can have the same effect. Still, exporting JSON
        by hand (or with a custom script) can also become a messy process.
        
        With ``datafreeze``, exports are scripted in a Makefile-like description,
        making them simple to repeat and replicate.
        
        
        Installation
        ------------
        
        The easiest way to install ``datafreeze`` is to retrieve it from the Python
        package index using ``pip``:
        
        .. code-block:: bash
        
            pip install datafreeze
        
        
        Basic Usage
        -----------
        
        Calling DataFreeze is simple, the application is called with a
        freeze file as its argument:
        
        .. code-block:: bash
        
            datafreeze Freezefile.yaml
        
        Freeze files can be either written in JSON or in YAML. The database URI
        indicated in the Freezefile can also be overridden via the command line:
        
        .. code-block:: bash
        
            datafreeze --db sqlite:///foo.db Freezefile.yaml
        
        
        Example Freezefile.yaml
        -----------------------
        
        A freeze file is composed of a set of scripted queries and
        specifications on how their output is to be handled. An example could look
        like this:
        
        .. code-block:: yaml
        
            common:
        
              database: "postgresql://user:password@localhost/operational_database"
              prefix: my_project/dumps/
              format: json
        
            exports:
        
              - query: "SELECT id, title, date FROM events"
                filename: "index.json"
        
              - query: "SELECT id, title, date, country FROM events"
                filename: "countries/{{country}}.csv"
                format: csv
        
              - query: "SELECT * FROM events"
                filename: "events/{{id}}.json"
                mode: item
        
              - query: "SELECT * FROM events"
                filename: "all.json"
                format: tabson
        
        An identical JSON configuration can be found in this repository.
        
        
        Options in detail
        -----------------
        
        The freeze file has two main sections, ``common`` and ``exports``. Both
        accept many of the same arguments, with ``exports`` specifying a list of
        exports while ``common`` defines some shared properties, such as the
        database connection string.
        
        The following options are recognized:
        
        * ``database`` is a database URI, including the database type, username
          and password, hostname and database name. Valid database types include
          ``sqlite``, ``mysql`` and ``postgresql`` (requires psycopg2).
        * ``prefix`` specifies a common root directory for all extracted files.
        * ``format`` identifies the format to be generated, ``csv``, ``json`` and
          ``tabson`` are supported. ``tabson`` is a condensed JSON
          representation in which rows are not represented by objects but by
          lists of values.
        * ``query`` needs to be a valid SQL statement. All selected fields will
          become keys or columns in the output, so it may make sense to define
          proper aliases if any overlap is to be expected.
        * ``mode`` specifies whether the query output is to be combined into a
          single file (``list``) or whether a file should be generated for each
          result row (``item``).
        * ``filename`` is the output file name, appended to ``prefix``. All
          occurences of ``{{field}}`` are expanded to a fields value to allow the
          generation of file names e.g. by primary key. In list mode, templating
          can be used to group records into several buckets, e.g. by country or
          category.
        * ``wrap`` can be used to specify whether the output should be wrapped
          in a ``results`` hash in JSON output. This defaults to ``true`` for
          ``list``-mode output and ``false`` for ``item``-mode.
        
        
        Contributors
        ------------
        
        ``dataset`` is written and maintained by `Friedrich Lindenberg
        <https://github.com/pudo>`_, `Gregor Aisch <https://github.com/gka>`_ and
        `Stefan Wehrmeyer <https://github.com/stefanw>`_. We're standing on the
        `shoulders of giants <http://www.sqlalchemy.org/>`_.
        
Keywords: sql sqlalchemy etl loading utility
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
