Better documentation for multiple databases

[jlauu]

Problem Statement
I'm having trouble integrating with my particular use case:

DATABASES = {
  'default': {...}, // this is the Django auto-generated DB where I want historical records stored
  'external_app': {...} // my model instances live in this external DB
} 

My users are also maintained in the default DB.

Describe the solution you'd like
I want historical records to be written to the default app_data Django DB (where admin models are also stored).

Describe alternatives you've considered
Having setup my settings.py accordingly, let MyModel be the model instance of the external db, I've tried:

1. Simple integration

// This tries to write to `external_app` DB
class MyModel(models.Model):
     history = HistoricalRecords()

2. Use different app param

// This does not migrate/auto-generate in `default` DB
class MyModel(models.Model):
     history = HistoricalRecords(app="MyApp") // which routes to the `default` DB

3. Try bases

// This throws a conflict on `id` field of `MyModel` and `MyHistoricalRecord`
class MyHistoricalRecord:
  class Meta:
     app_label = 'default'
     managed = True

class MyModel(models.Model):
     history = HistoricalRecords(app="MyApp", bases=[MyHistoricalRecord]) // which routes to the `default` DB

Seems like 2) is the closest to my desired solution -- however the tables don't exist and when I try to run makemigrations no changes are made.

[rossmechanic]

What's the error that you get with option 2? Assuming it's a foreign key error on history user?

[jlauu]

@rossmechanic
Option 2 throws Programmingerror: (1146, "Table '<default_db_name>.<table>' doesn't exist")

Option 3 throws the conflict

django.core.exceptions.FieldError: Local field 'id' in class 'MyClass' clashes with field of the same name from base class 'MyHistoricalRecords'.

[erikvw]

@jlauu, probably better to work with UUID primary keys. Try using models.UUIDField for your primary key field (id) on models.

class MyModel(models.Model):
     """Model uses a UUID as a primary key"""
    id = models.UUIDField(default=uuid.uuid4))
    history = HistoricalRecords()

Watch out for use_base_model_db which defaults to False. See the docs.

You may also want the history_id on the historical model to be a UUIDField as well. Do this by setting SIMPLE_HISTORY_HISTORY_ID_USE_UUID = True