Skip to main content

Django: How and why to use migrations. Django-South.

Hi there guys and we're here to talk about migrations today. My app grown to complex app with profiles, social registration permits and so on. First time I've decided to make myself a simple app. Now it became complex enough and contains enough code to need code comments :). Anyway Migrations is a process anybody someday will need. I thought it's hard to learn or understand, but it's not.

Main point is that you:
- save your current database tables structure
- change your model tables
- scan for differences and create script
- then write changes to your database with automatically generated python script.

Sound's simple? I't not all so simple in fact. App that you need to learn is Django-south. Its main objectives are to provide a simple, stable and database-independent migration layer to prevent all the hassle schema changes over time bring to your Django applications. It has quite understandable tutorial here.

So if you're tired of ALTER'ing your tables and writing code to python Sqlite console or editing raw SQL, go get yourself a copy of south. It's an app that IMHO everybody should use/hear/understand.

It is meant to change old one and quite simple command 'manage.py syncdb' someday. For now go get yourself this tool and learn to use it. It took me about half an hour to understand basics.. So it's not hard (at first) :).

Brief look at usage:

1. Install app in some way. Use pip/easy_install script or simply put 'south' dir to your project root dir.
Add 'south', to your INSTALLED_APPS dictionary.
!IMPORTANT! you need to make syncdb after that. Another way wo will get an error with future commands.

2. Connect existing app's to migrations. Use command python manage.py convert_to_south myapp to convert your app from syncdb ready to south migratable. Or you can run python manage.py schemamigration newappname --initial to add south migrations ability to your new app. In general it will create directory 'migrations' inside your app directory.

3. Change your model. I dont think you need separate stop here. But... Just in case add some field to your django model like bollean or text and/or edit your existing field rather by adding 'null=True' for e.g.

4. Create your migration. It can be done by command python manage.py schemamigration newappname --auto to create your migration script. you can check it in your app's 'migrations' dir. It has numbers in the beginning with migration number.

5. Run your migration. It is done by command python manage.py migrate appname or even without an app name: python manage.py migrate to migrate all apps. Thats it.

Hope you'll never use 'syncdb' again for complex tasks like this. I'm adding it to my base developer tools. And you?

Comments

  1. How is that different from the manual?

    ReplyDelete
  2. It's a bit why do you need it and shorten a bit...

    ReplyDelete
  3. Hi
    I am using South but I am getting an error while running syncdb. 'no module named southregistration'. I have installed south using pip for python 2.7. and I have included south in INSTALLED_APP as well but still I am getting this error

    ReplyDelete
    Replies
    1. If Django doesn’t seem to pick this up, check that you’re not overriding INSTALLED_APPS elsewhere, and that you can run import south from inside ./manage.py shell with no errors.

      Please run the console from where you manage.py lives (environment if you're using virtualenv) and try to do:

      (virtualenv_name):projectdir username$ python
      Python 2.7.2 (v2.7.2:8527427914a2, Jun 11 2011, 15:22:34)
      [GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
      Type "help", "copyright", "credits" or "license" for more information.
      >>> import south
      >>>

      IF you see any errors there then you've probably have not installed south... try to do:

      easy_install South

      Delete
  4. It tells you what to do. Database has the table named like so. Try renaming your model (resulting to different name of that table to migrate to) and either delete your destination table in the database. Other way you can not use south in case this has happened without really creating of that table before and entirely by south-migrations. It means you may have to have other database backend in order south to support migrations. E.g. more new MySQL or whatever you are using there as a database backend.

    ReplyDelete
  5. @Yordis - you can also use "--fake" for the initial migration if you are adding this to a legacy database that already has the initial sync'd tables in it. This means you don't have to drop everything.

    ReplyDelete
  6. Hello i install south with : $pip install south
    all was correct. I put 'south', in INSTALLED_APPS .
    But when i'm running $python manage.py syncdb
    I got this error :
    There is no South database module 'south.db.sqlite3' for your database. Please either choose a supported database, check for SOUTH_DATABASE_ADAPTER[S] settings, or remove South from INSTALLED_APPS.

    ReplyDelete
    Replies
    1. You need to check your settings.py especially for DATABASES section. Checking for typical novice mistakes like forgotten comma or something similar may also be a case here. Note you need to syncdb before installing south to your apps section. This will create an actual database first...

      Delete

Post a Comment

Popular posts from this blog

Pretty git Log

SO you dislike git log output in console like me and do not use it... Because it looks like so: How about this one? It's quite easy... Just type: git log - - graph - - pretty = format : '%Cred%h%Creset -%C ( yellow ) %d%Creset %s %Cgreen ( %cr) %C ( bold blue ) <%an>%Creset' - - abbrev - commit - - It may be hard to enter such an easy command every time. Let's make an alias instead... Copypaste this to your terminal: git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --" And use simple command to see this pretty log instead: git lg Now in case you want to see lines that changed use: git lg - p In order for this command to work remove  the -- from the end of the alias. May the code be with you! NOTE: this article is a rewritten copy of  http://coderwall.com/p/euwpig?i=3&p=1&t=git   and have b

Django: Resetting Passwords (with internal tools)

I have had a task recently. It was about adding a forms/mechanism for resetting a password in our Django based project. We have had our own registration system ongoing... It's a corporate sector project. So you can not go and register yourself. Admins (probably via LDAP sync) will register your email/login in system. So you have to go there and only set yourself a password. For security reasons you can not register. One word. First I've tried to find standart decision. From reviewed by me were: django-registration and django password-reset . These are nice tools to install and give it a go. But I've needed a more complex decision. And the idea was that own bicycle is always better. So I've thought of django admin and that it has all the things you need to do this yourself in no time. (Actually it's django.contrib.auth part of django, but used out of the box in Admin UI) You can find views you need for this in there. they are: password_reset password_reset_

Time Capsule for $25

The real article name might be something like:  Configuring Raspbery Pi to serve like a Time Capsule with Netatalk 3.0 for Mountain Lion.  But it's too long ;) Here I will describe the process of using Raspberry Pi like a Time Machine in my network. To be able to backup your MAC's remotely (Like it would be NAS of some kind). It assumes you have a Raspberry Pi and have installed a Raspbian there and have a ssh connection, or somehow having access to it's console. Refer to my previous article for details . Now that we have a Pi that is ready for action let's animate it. So to make it suit you as a Time Capsule (NAS) for your MAC's you need to do those basic steps: - connect and configure USB hard drive(s) - install support of HFS+ filesystem to be able to use MAC's native filesystem - make mount (auto-mount on boot) of your hard drive - install Avahi and Netatalk demons - configure Netatalk daemon to make it all serve as a Time Machine - configure