Debian packaging for django-tenant-schems
Go to file
Benjamin Dauvergne 8bd62ee84f Merge branch 'wip/schema-aware-introspection' into eo-master
Conflicts:
	tenant_schemas/postgresql_backend/introspection.py
2015-04-24 11:08:21 +02:00
docs Updated docs regarding Django 1.7 changes. 2015-01-05 15:54:11 +01:00
dts_test_project Now using django's new test runner. Fixed test project and examples. 2015-01-05 15:43:40 +01:00
examples/tenant_tutorial Now using django's new test runner. Fixed test project and examples. 2015-01-05 15:43:40 +01:00
tenant_schemas introspection: finish support for schema aware introspection 2015-04-24 11:06:54 +02:00
.gitignore Ignore IntelliJ hidden files 2013-10-20 14:24:03 +02:00
CHANGES.txt pypi should now correctly contain all files 2013-03-03 08:44:03 +01:00
LICENSE pypi should now correctly contain all files 2013-03-03 08:44:03 +01:00
MANIFEST.in Corrected invalid syntax on recursive-include for manifest 2014-12-29 18:37:40 +01:00
README.rst README.rst: Syntax highlighting 2015-01-30 08:54:08 -08:00
__init__.py pypi should now correctly contain all files 2013-03-03 08:44:03 +01:00
setup.py Added missing management.commands.legacy package to setup.py. Fixes #224. 2015-01-12 19:10:41 +01:00
version.py Fix decode error for Python 3 2014-09-01 16:51:24 +02:00

README.rst

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

django-tenant-schemas
=====================

|PyPi version| |PyPi downloads|

This application enables `django`_ powered websites to have multiple
tenants via `PostgreSQL schemas`_. A vital feature for every
Software-as-a-Service website.

Django provides currently no simple way to support multiple tenants
using the same project instance, even when only the data is different.
Because we dont want you running many copies of your project, youll be
able to have:

-  Multiple customers running on the same instance
-  Shared and Tenant-Specific data
-  Tenant View-Routing

What are schemas
----------------

A schema can be seen as a directory in an operating system, each
directory (schema) with its own set of files (tables and objects). This
allows the same table name and objects to be used in different schemas
without conflict. For an accurate description on schemas, see
`PostgreSQLs official documentation on schemas`_.

Why schemas
-----------

There are typically three solutions for solving the multitenancy
problem.

1. Isolated Approach: Separate Databases. Each tenant has its own
   database.

2. Semi Isolated Approach: Shared Database, Separate Schemas. One
   database for all tenants, but one schema per tenant.

3. Shared Approach: Shared Database, Shared Schema. All tenants share
   the same database and schema. There is a main tenant-table, where all
   other tables have a foreign key pointing to.

This application implements the second approach, which in our opinion,
represents the ideal compromise between simplicity and performance.

-  Simplicity: barely make any changes to your current code to support
   multitenancy. Plus, you only manage one database.
-  Performance: make use of shared connections, buffers and memory.

Each solution has its up and down sides, for a more in-depth
discussion, see Microsofts excellent article on `Multi-Tenant Data
Architecture`_.

How it works
------------

Tenants are identified via their host name (i.e tenant.domain.com). This
information is stored on a table on the ``public`` schema. Whenever a
request is made, the host name is used to match a tenant in the
database. If theres a match, the search path is updated to use this
tenants schema. So from now on all queries will take place at the
tenants schema. For example, suppose you have a tenant ``customer`` at
http://customer.example.com. Any request incoming at
``customer.example.com`` will automatically use ``customer``\ s schema
and make the tenant available at the request. If no tenant is found, a
404 error is raised. This also means you should have a tenant for your
main domain, typically using the ``public`` schema. For more information
please read the `setup`_ section.

What can this app do?
---------------------

As many tenants as you want
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Each tenant has its data on a specific schema. Use a single project
instance to serve as many as you want.

Tenant-specific and shared apps
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Tenant-specific apps do not share their data between tenants, but you
can also have shared apps where the information is always available and
shared between all.

Tenant View-Routing
~~~~~~~~~~~~~~~~~~~

You can have different views for ``http://customer.example.com/`` and
``http://example.com/``, even though Django only uses the string after
the host name to identify which view to serve.

Magic
~~~~~

Everyone loves magic! Youll be able to have all this barely having to
change your code!

Setup & Documentation
---------------------

**This is just a short setup guide**, it is **strongly** recommended
that you read the complete version at
`django-tenant-schemas.readthedocs.org`_.

Your ``DATABASE_ENGINE`` setting needs to be changed to

.. code-block:: python

    DATABASES = {
        'default': {
            'ENGINE': 'tenant_schemas.postgresql_backend',
            # ..
        }
    }    

Add the middleware ``tenant_schemas.middleware.TenantMiddleware`` to the
top of ``MIDDLEWARE_CLASSES``, so that each request can be set to use
the correct schema.

.. code-block:: python

    MIDDLEWARE_CLASSES = (
        'tenant_schemas.middleware.TenantMiddleware',
        #...
    )
    
Add ``tenant_schemas.routers.TenantSyncRouter`` to your `DATABASE_ROUTERS` 
setting, so that the correct apps can be synced, depending on what's 
being synced (shared or tenant).

.. code-block:: python

    DATABASE_ROUTERS = (
        'tenant_schemas.routers.TenantSyncRouter',
    )

Add ``tenant_schemas`` to your ``INSTALLED_APPS``.

Create your tenant model
~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from django.db import models
    from tenant_schemas.models import TenantMixin

    class Client(TenantMixin):
        name = models.CharField(max_length=100)
        paid_until =  models.DateField()
        on_trial = models.BooleanField()
        created_on = models.DateField(auto_now_add=True)

Define on ``settings.py`` which model is your tenant model. Assuming you
created ``Client`` inside an app named ``customers``, your
``TENANT_MODEL`` should look like this:

.. code-block:: python

    TENANT_MODEL = "customers.Client" # app.Model

Now run ``sync_schemas``, this will sync your apps to the ``public``
schema.

::

    python manage.py sync_schemas --shared

Create your tenants just like a normal django model. Calling ``save``
will automatically create and sync the schema.

.. code-block:: python

    from customers.models import Client

    # create your public tenant
    tenant = Client(domain_url='tenant.my-domain.com',
                    schema_name='tenant1',
                    name='My First Tenant',
                    paid_until='2014-12-05',
                    on_trial=True)
    tenant.save()

Any request made to ``tenant.my-domain.com`` will now automatically set
your PostgreSQLs ``search_path`` to ``tenant1`` and ``public``, making
shared apps available too. This means that any call to the methods
``filter``, ``get``, ``save``, ``delete`` or any other function
involving a database connection will now be done at the tenants schema,
so you shouldnt need to change anything at your views.

Youre all set, but we have left key details outside of this short
tutorial, such as creating the public tenant and configuring shared and
tenant specific apps. Complete instructions can be found at
`django-tenant-schemas.readthedocs.org`_.



.. _django: https://www.djangoproject.com/
.. _PostgreSQL schemas: http://www.postgresql.org/docs/9.1/static/ddl-schemas.html
.. _PostgreSQLs official documentation on schemas: http://www.postgresql.org/docs/9.1/static/ddl-schemas.html
.. _Multi-Tenant Data Architecture: http://msdn.microsoft.com/en-us/library/aa479086.aspx

.. |PyPi version| image:: https://pypip.in/v/django-tenant-schemas/badge.png
   :target: https://crate.io/packages/django-tenant-schemas/
.. |PyPi downloads| image:: https://pypip.in/d/django-tenant-schemas/badge.png
   :target: https://crate.io/packages/django-tenant-schemas/
.. _setup: https://django-tenant-schemas.readthedocs.org/en/latest/install.html
.. _django-tenant-schemas.readthedocs.org: https://django-tenant-schemas.readthedocs.org/en/latest/