==================================
Integrating with a legacy database
==================================

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

This document assumes you know the Django basics, as covered in the
`official tutorial`_.

.. _official tutorial: http://www.djangoproject.com/documentation/tutorial1/

Give Django your database parameters
====================================

You'll need to tell Django what your database connection parameters are, and
what the name of the database is. Do that by editing these settings in your
`settings file`_:

    * `DATABASE_NAME`
    * `DATABASE_ENGINE`_
    * `DATABASE_USER`_
    * `DATABASE_PASSWORD`_
    * `DATABASE_HOST`_
    * `DATABASE_PORT`_

.. _settings file: http://www.djangoproject.com/documentation/settings/
.. _DATABASE_NAME: http://www.djangoproject.com/documentation/settings/#database-name
.. _DATABASE_ENGINE: http://www.djangoproject.com/documentation/settings/#database-engine
.. _DATABASE_USER: http://www.djangoproject.com/documentation/settings/#database-user
.. _DATABASE_PASSWORD: http://www.djangoproject.com/documentation/settings/#database-password
.. _DATABASE_HOST: http://www.djangoproject.com/documentation/settings/#database-host
.. _DATABASE_PORT: http://www.djangoproject.com/documentation/settings/#database-port

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

Django comes with a utility that can create models by introspecting an existing
database. You can view the output by running this command::

    django-admin.py inspectdb --settings=path.to.settings

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

    django-admin.py inspectdb --settings=path.to.settings > models.py

This feature is meant as a shortcut, not as definitive model generation. See
the `django-admin.py documentation`_ 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
``INSTALLED_APPS`` setting.

.. _django-admin.py documentation: http://www.djangoproject.com/documentation/django_admin/

Install the core Django tables
==============================

Next, run the ``manage.py syncdb`` command to install any extra needed database
records such as admin permissions and content types::

    django-admin.py init --settings=path.to.settings

See whether it worked
=====================

That's it. Try accessing your data via the Django database API, and try editing
objects via Django's admin site.