================================================
How to integrate GingerDJ with a legacy database
================================================

While GingerDJ is best suited for developing new applications, it's quite
possible to integrate it into legacy databases. GingerDJ includes a couple of
utilities to automate as much of this process as possible.

This document assumes you know the GingerDJ basics, as covered in the
:doc:`tutorial </intro/tutorial01>`.

Once you've got GingerDJ set up, you'll follow this general process to integrate
with an existing database.

Give GingerDJ your database parameters
======================================

You'll need to tell GingerDJ what your database connection parameters are, and
what the name of the database is. Do that by editing the :setting:`DATABASES`
setting and assigning values to the following keys for the ``'default'``
connection:

* :setting:`NAME`
* :setting:`ENGINE <DATABASE-ENGINE>`
* :setting:`USER`
* :setting:`PASSWORD`
* :setting:`HOST`
* :setting:`PORT`

Auto-generate the models
========================

GingerDJ comes with a utility called :djadmin:`inspectdb` that can create models
by introspecting an existing database. You can view the output by running this
command:

.. code-block:: shell

    $ python manage.py inspectdb

Save this as a file by using standard Unix output redirection:

.. code-block:: shell

    $ python manage.py inspectdb > models.py

This feature is meant as a shortcut, not as definitive model generation. See the
:djadmin:`documentation of inspectdb <inspectdb>` for more information.

Once you've cleaned up your models, name the file ``models.py`` and put it in
the Python package that holds your app. Then add the app to your
:setting:`INSTALLED_APPS` setting.

By default, :djadmin:`inspectdb` creates unmanaged models. That is,
``managed = False`` in the model's ``Meta`` class tells GingerDJ not to manage
each table's creation, modification, and deletion::

    class Person(models.Model):
        id = models.IntegerField(primary_key=True)
        first_name = models.CharField(max_length=70)

        class Meta:
            managed = False
            db_table = "CENSUS_PERSONS"

If you do want to allow GingerDJ to manage the table's lifecycle, you'll need to
change the :attr:`~gingerdj.db.models.Options.managed` option above to ``True``
(or remove it because ``True`` is its default value).

Install the core GingerDJ tables
================================

Next, run the :djadmin:`migrate` command to install any extra needed database
records such as admin permissions and content types:

.. code-block:: shell

    $ python manage.py migrate

Test and tweak
==============

Those are the basic steps -- from here you'll want to tweak the models GingerDJ
generated until they work the way you'd like. Try accessing your data via the
GingerDJ database API, and try editing objects via GingerDJ's admin site, and edit
the models file accordingly.