docs: migration from 1.0 to 1.1 may need --fake-initial

[ploxiln]

I initially created the sqlite database for graphite-web 1.0.2 according to the documentation recommendation:

https://graphite.readthedocs.io/en/latest/config-database-setup.html#webapp-database-setup

 PYTHONPATH=... django-admin migrate --settings=graphite.settings --run-syncdb

Recently I attempted to upgrade to graphite-web 1.1.5, and followed the documented command in the 1.1.1 release notes:

https://graphite.readthedocs.io/en/latest/releases/1_1_1.html#upgrading

PYTHONPATH=... django-admin migrate --noinput --settings=graphite.settings --run-syncdb

which resulted in failure:

Operations to perform:
  Apply all migrations: account, admin, auth, contenttypes, dashboard, events, sessions, tagging, tags, url_shortener
Running migrations:
  Applying account.0001_initial...Traceback (most recent call last):
  File "/usr/bin/django-admin", line 11, in <module>
    load_entry_point('Django==1.11.18', 'console_scripts', 'django-admin')()
  ...
  File "/usr/lib/python2.7/site-packages/django/core/management/commands/migrate.py", line 204, in handle
    fake_initial=fake_initial,
  File "/usr/lib/python2.7/site-packages/django/db/migrations/executor.py", line 115, in migrate
    state = self._migrate_all_forwards(state, plan, full_plan, fake=fake, fake_initial=fake_initial)
  File "/usr/lib/python2.7/site-packages/django/db/migrations/executor.py", line 145, in _migrate_all_forwards
    state = self.apply_migration(state, migration, fake=fake, fake_initial=fake_initial)
  ...
  File "/usr/lib/python2.7/site-packages/django/db/backends/utils.py", line 62, in execute
    return self.cursor.execute(sql)
  File "/usr/lib/python2.7/site-packages/django/db/backends/sqlite3/base.py", line 326, in execute
    return Database.Cursor.execute(self, query)
django.db.utils.OperationalError: table "account_mygraph" already exists

I found another that hit this too, and didn't seem to solve it directly:
graphite-project/docker-graphite-statsd#32

Anyway, I think I know why this happens. This commit was merged just before 1.1.0 - d1912d4 - and it added migrations for existing django app models. Previously, tables were created for these models due to the option --run-syncdb, which according to django docs:

Allows creating tables for apps without migrations. While this isn’t recommended ...

... but now there are un-applied migrations, which conflict with tables already in the database. I think this would happen to anyone who initialized the db before 1.1 and then followed the upgrade instructions in 1.1.1.

Luckily, django-admin migrate has another relevant option --fake-initial:

Allows Django to skip an app’s initial migration if all database tables with the names of all models created by all CreateModel operations in that migration already exist. This option is intended for use when first running migrations against a database that preexisted the use of migrations. This option does not, however, check for matching database schema beyond matching table names ...

Running migrate with --fake-initial I get:

$ ... django-admin migrate --no-input --settings=graphite.settings --fake-initial
Operations to perform:
  Apply all migrations: account, admin, auth, contenttypes, dashboard, events, sessions, tagging, tags, url_shortener
Running migrations:
  Applying account.0001_initial... FAKED
  Applying auth.0008_alter_user_username_max_length... OK
  Applying dashboard.0001_initial... FAKED
  Applying events.0001_initial... FAKED
  Applying tags.0001_initial... OK
  Applying url_shortener.0001_initial... FAKED

So it seems to me that the release notes should recommend using --fake-initial to migrate from 1.0, and --run-syncdb should no longer be used for migrating from 1.0 nor for new databases.

[deniszh]

Thanks for finally sorting this, @ploxiln !
We'll need to fix docs. Unfortunately, it's not easy for already released versions, but at least, we can do that in master