==================
About Python dumps
==================

This document describes the :manage:`dump2py` command.

A *database dump* is an image of the data in a database which you can use e.g.
to backup and restore your data.  While Django's :manage:`dumpdata` command lets
you make database dumps in *json* and *xml* format, Lino extends this by letting
you make a database dump in *Python* format. This is what we call a **Python
dump**.

To make a Python dump of your database, you simply use the :manage:`dump2py`
command.  This :term:`django-admin command` creates a directory of Python modules with
one main module :xfile:`restore.py`.

Another important thing is that you can use such a backup for :doc:`data
migrations <datamig>`.

See also :doc:`/specs/dumps`.


The :manage:`dump2py` command
=============================

Write a Python dump of your database to a set of Python modules.  This dump is
useful for creating a daily backup or before an upgrade with data migration.

Usage: cd to your project directory and say::

  $ python manage.py dump2py TARGET

This will create a python dump of your database to the directory `TARGET`.

The directory will contain a file :xfile:`restore.py` and a series of
`.py` files (one for every model) which are being :func:`execfile`\ d
from that :xfile:`restore.py`.

Options:

.. option:: --noinput

    Do not prompt for user input of any kind.

.. option:: --tolerate

    Tolerate database errors. This can help making a partial snapshot
    of a database which is not (fully) synced with the application
    code.

.. option:: --overwrite

    Don't complain if the TARGET directory already exists. This will
    potentially overwrite existing files.

.. option:: --max-row-count <NUM>

    Change the maximum number of rows per source file from its default
    value (50000) to NUM.

    When a table contains many rows, the resulting :file:`.py` file can become
    so large that it doesn't fit into memory, causing the Python process to get
    killed when it tries to restore the data.  To avoid this limitation,
    :xfile:`dump2py` distributes the content over several files if a table
    contains are more than NUM rows.

    The default value has been "clinically tested" and should be small enough
    for most machines.

    Hint: When your process gets killed, before using this option, consider
    restarting the web services on your server and trying again. The web
    services can occupy considerable amounts of memory on a long-running
    :term:`production site`. A simple :xfile:`reload_services.sh`  can fix your
    issue.

.. You might theoretically use Django's :manage:`dumpdata` command for
   writing a Python fixture, but this possibility is currently
   deactivated because a huge database would create a huge Python module
   which might not fit into memory.


Files
=====

.. xfile:: restore.py

    The main script of a Python dump generated by the :manage:`dump2py`
    command.

    To restore a dump created using :manage:`dump2py` to your database,
    simply run the `restore.py` script using the :manage:`run` management
    command::

      $ python manage.py run mydump/restore.py