# dokumentasi Django 2.0.8

# Perpindahan

Migrations are Django's way of propagating changes you make to your models (adding a field, deleting a model, etc.) into your database schema. They're designed to be mostly automatic, but you'll need to know when to make migrations, when to run them, and the common problems you might run into.

## Perintah

There are several commands which you will use to interact with migrations and Django's handling of database schema:

- `migrate`, yang bertanggung jawab untuk memberlakukan dan tidak memberlakukan perpindahan.
- `makemigrations`, which is responsible for creating new migrations based on the changes you have made to your models.
- `sqlmigrate`, yang menampilan pernyataan SQL untuk perpindahan.
- `showmigrations`, yang menampilan perpindahan proyek dan keadaan mereka.

You should think of migrations as a version control system for your database schema. `makemigrations` is responsible for packaging up your model changes into individual migration files - analogous to commits - and `migrate` is responsible for applying those to your database.

The migration files for each app live in a "migrations" directory inside of that app, and are designed to be committed to, and distributed as part of, its codebase. You should be making them once on your development machine and then running the same migrations on your colleagues' machines, your staging machines, and eventually your production machines.

Catatan

It is possible to override the name of the package which contains the migrations on a per-app basis by modifying the `MIGRATION_MODULES` setting.

Migrations will run the same way on the same dataset and produce consistent results, meaning that what you see in development and staging is, under the same circumstances, exactly what will happen in production.

Django will make migrations for any change to your models or fields - even options that don't affect the database - as the only way it can reconstruct a field correctly is to have all the changes in the history, and you might need those options in some data migrations later on (for example, if you've set custom validators).

## Dukungan backend

Migrations are supported on all backends that Django ships with, as well as any third-party backends if they have programmed in support for schema alteration (done via the SchemaEditor class).

However, some databases are more capable than others when it comes to schema migrations; some of the caveats are covered below.

### PostgreSQL

PostgreSQL is the most capable of all the databases here in terms of schema support; the only caveat is that adding columns with default values will cause a full rewrite of the table, for a time proportional to its size.

For this reason, it's recommended you always create new columns with `null=True`, as this way they will be added immediately.

### MySQL

MySQL lacks support for transactions around schema alteration operations, meaning that if a migration fails to apply you will have to manually unpick the changes in order to try again (it's impossible to roll back to an earlier point).

In addition, MySQL will fully rewrite tables for almost every schema operation and generally takes a time proportional to the number of rows in the table to add or remove columns. On slower hardware this can be worse than a minute per million rows - adding a few columns to a table with just a few million rows could lock your site up for over ten minutes.

Finally, MySQL has relatively small limits on name lengths for columns, tables and indexes, as well as a limit on the combined size of all columns an index covers. This means that indexes that are possible on other backends will fail to be created under MySQL.

### SQLite

SQLite has very little built-in schema alteration support, and so Django attempts to emulate it by:

- Creating a new table with the new schema
- Copying the data across
- Dropping the old table
- Renaming the new table to match the original name

This process generally works well, but it can be slow and occasionally buggy. It is not recommended that you run and migrate SQLite in a production environment unless you are very aware of the risks and its limitations; the support Django ships with is designed to allow developers to use SQLite on their local machines to develop less complex Django projects without the need for a full database.

## Alur kerja

Working with migrations is simple. Make changes to your models - say, add a field and remove a model - and then run `makemigrations`:

    $ python manage.py makemigrations
    Migrations for 'books':
      books/migrations/0003_auto.py:
        - Alter field author on book

Your models will be scanned and compared to the versions currently contained in your migration files, and then a new set of migrations will be written out. Make sure to read the output to see what `makemigrations` thinks you have changed - it's not perfect, and for complex changes it might not be detecting what you expect.

Once you have your new migration files, you should apply them to your database to make sure they work as expected:

    $ python manage.py migrate
    Operations to perform:
      Apply all migrations: books
    Running migrations:
      Rendering model states... DONE
      Applying books.0003_auto... OK

Once the migration is applied, commit the migration and the models change to your version control system as a single commit - that way, when other developers (or your production servers) check out the code, they'll get both the changes to your models and the accompanying migration at the same time.

If you want to give the migration(s) a meaningful name instead of a generated one, you can use the `makemigrations --name` option:

    $ python manage.py makemigrations --name changed_my_model your_app_label

### Version control

Because migrations are stored in version control, you'll occasionally come across situations where you and another developer have both committed a migration to the same app at the same time, resulting in two migrations with the same number.

Don't worry - the numbers are just there for developers' reference, Django just cares that each migration has a different name. Migrations specify which other migrations they depend on - including earlier migrations in the same app - in the file, so it's possible to detect when there's two new migrations for the same app that aren't ordered.

When this happens, Django will prompt you and give you some options. If it thinks it's safe enough, it will offer to automatically linearize the two migrations for you. If not, you'll have to go in and modify the migrations yourself - don't worry, this isn't difficult, and is explained more in Migration files below.

## Ketergantungan

While migrations are per-app, the tables and relationships implied by your models are too complex to be created for just one app at a time. When you make a migration that requires something else to run - for example, you add a `ForeignKey` in your `books` app to your `authors` app - the resulting migration will contain a dependency on a migration in `authors`.

This means that when you run the migrations, the `authors` migration runs first and creates the table the `ForeignKey` references, and then the migration that makes the `ForeignKey` column runs afterwards and creates the constraint. If this didn't happen, the migration would try to create the `ForeignKey` column without the table it's referencing existing and your database would throw an error.

This dependency behavior affects most migration operations where you restrict to a single app. Restricting to a single app (either in `makemigrations` or `migrate`) is a best-efforts promise, and not a guarantee; any other apps that need to be used to get dependencies correct will be.

## Migration files

Migrations are stored as an on-disk format, referred to here as "migration files". These files are actually just normal Python files with an agreed-upon object layout, written in a declarative style.

A basic migration file looks like this:

    from django.db import migrations, models

    class Migration(migrations.Migration):

        dependencies = [('migrations', '0001_initial')]

        operations = [
            migrations.DeleteModel('Tribble'),
            migrations.AddField('Author', 'rating', models.IntegerField(default=0)),
        ]

What Django looks for when it loads a migration file (as a Python module) is a subclass of `django.db.migrations.Migration` called `Migration`. It then inspects this object for four attributes, only two of which are used most of the time:

- `dependencies`, a list of migrations this one depends on.
- `operations`, a list of `Operation` classes that define what this migration does.

The operations are the key; they are a set of declarative instructions which tell Django what schema changes need to be made. Django scans them and builds an in-memory representation of all of the schema changes to all apps, and uses this to generate the SQL which makes the schema changes.

That in-memory structure is also used to work out what the differences are between your models and the current state of your migrations; Django runs through all the changes, in order, on an in-memory set of models to come up with the state of your models last time you ran `makemigrations`. It then uses these models to compare against the ones in your `models.py` files to work out what you have changed.

You should rarely, if ever, need to edit migration files by hand, but it's entirely possible to write them manually if you need to. Some of the more complex operations are not autodetectable and are only available via a hand-written migration, so don't be scared about editing them if you have to.

### Bidang penyesuaian

Anda tidak dapat merubah argumen penempatan dalam bidang penyesuaian sudah diminta tanpa memunculkan sebuah `TypeError`. Perpindahan lama akan memanggil metode `__init__ yang telah dirubah dengan tanda tangan lama. Jadi jika anda butuh argumen baru, harap membuat sebuah argumen kata kunci dan menambahkan sesuatu seperti ``assert 'argument_name' in kwargs` dalam pembangun.

### Model managers

You can optionally serialize managers into migrations and have them available in `RunPython` operations. This is done by defining a `use_in_migrations` attribute on the manager class:

    class MyManager(models.Manager):
        use_in_migrations = True

    class MyModel(models.Model):
        objects = MyManager()

If you are using the `from_queryset()` function to dynamically generate a manager class, you need to inherit from the generated class to make it importable:

    class MyManager(MyBaseManager.from_queryset(CustomQuerySet)):
        use_in_migrations = True

    class MyModel(models.Model):
        objects = MyManager()

Please refer to the notes about Historical models in migrations to see the implications that come along.

### Initial migrations

`Migration.``initial`

The "initial migrations" for an app are the migrations that create the first version of that app's tables. Usually an app will have just one initial migration, but in some cases of complex model interdependencies it may have two or more.

Initial migrations are marked with an `initial = True` class attribute on the migration class. If an `initial` class attribute isn't found, a migration will be considered "initial" if it is the first migration in the app (i.e. if it has no dependencies on any other migration in the same app).

Ketika pilihan `migrate --fake-initial` digunakan, perpindahan inisial ini diperlakukan khusus. Untuk sebuah perpindahan inisial yang membuat satu atau lebih tabel (tindakan `CreateModel`), Django memeriksa bahwa semua dari tabel-table tersebut sudah ada dalam basisdata dan pemberlakukan-palsu perpindahan jika demikian. Demikian pula, untuk sebuah perpindahan inisial yang menambahkan satu atau lebih bidang-bidang (tindakan `AddField`), Django memeriksa bahwa semua dari masing-masing kolom sudah ada dalam basisdata dan pemberlakukan-palsu perpindahan jika demikian. Tanpa `--fake-initial`, perpindahan inisial diperlakukan tidak berbeda dari perpindahan lain.

### History consistency

Seperti sebelumnya diobrolkan, anda mungkin butuh melinerarkan perpindahan secara manual ketika dua cabang pengembangan digabungkan. Selagi menyunting ketergantungan perpindahan, anda dapat secara tidak sengaja membuat sebuah keadaan riwayat tidak tetap dimana sebuah perpindahan telah diberlakukan tetapi beberapa ketergantungannya belum. Ini adalah indikasi kuat yang ketergantungan adalah tidak benar, jadi Django akan menolak menjalankan perpindahan atau membuat perpindahan baru sampai itu diperbaiki. Ketika menggunakan banyak basisdata, anda dapat menggunakan metode `allow_migrate()` dari database routers untuk mengendalikan pemeriksaan `makemigrations` basisdata mana untuk riwayat ketetapan.

## Menambahkan perpindahan ke aplikasi

Adding migrations to new apps is straightforward - they come preconfigured to accept migrations, and so just run `makemigrations` once you've made some changes.

If your app already has models and database tables, and doesn't have migrations yet (for example, you created it against a previous Django version), you'll need to convert it to use migrations; this is a simple process:

    $ python manage.py makemigrations your_app_label

This will make a new initial migration for your app. Now, run `python manage.py migrate --fake-initial`, and Django will detect that you have an initial migration and that the tables it wants to create already exist, and will mark the migration as already applied. (Without the `migrate --fake-initial` flag, the command would error out because the tables it wants to create already exist.)

Catat bahwa ini hanya bekerja memberikan dua hal:

- You have not changed your models since you made their tables. For migrations to work, you must make the initial migration first and then make changes, as Django compares changes against migration files, not the database.
- You have not manually edited your database - Django won't be able to detect that your database doesn't match your models, you'll just get errors when migrations try to modify those tables.

## Historical models

Ketika anda menjalankan perpindahan, Django bekerja dari versi riwayat dari model anda disimpan dalam berkas-berkas perpindahan. Jika anda menulis kode Python menggunakan tindakan `RunPython`, atau jika anda mempunyai metode `allow_migrate` pada perute basisdata anda, anda akan terkena ke versi ini dari model anda.

Karena itu tidak mungkin menserialisasikan kode Python berubah-ubah, model-model riwayat ini tidak akan mempunyai penyesuaian metode apapun yang anda telah tentukan. Mereka akan, bagaimanapun, mempunyai bidang-bidang sama, hubungan, pengelola (terbatas ke itu dengan `use_in_migrations = True`) dan pilihan `Meta` (juga berversi, jadi mereka mungkin berbeda dari satu anda saat ini).

Peringatan

Ini berarti bahwa anda TIDAK akan mempunyai metode `save()` penyesuaian dipanggil ketika anda mengakses mereka dalam perpindahan, dan anda TIDAK akan mempunyai pembangun penyesuaian apapun atau metode instance. Rencanakan dengan tepat!

References to functions in field options such as `upload_to` and `limit_choices_to` and model manager declarations with managers having `use_in_migrations = True` are serialized in migrations, so the functions and classes will need to be kept around for as long as there is a migration referencing them. Any custom model fields will also need to be kept, since these are imported directly by migrations.

Sebagai tambahan, kelas-kelas dasar dari model hanya disimpan sebagai petunjuk, jadi anda harus selalu menjaga kelas-kelas dasar disekitar selama ada sebuah perpindahan yang mengandung sebuah acuan ke mereka. Pada sisi tambahan, metode dan pengelola dari kelas-kelas dasar ini mewarisi secara biasa, jadi anda mutlak butuh mengakses ke ini anda dapat memilih memindahkan mereka menjadi sebuah super kelas.

To remove old references, you can squash migrations or, if there aren't many references, copy them into the migration files.

## Considerations when removing model fields

Similar to the "references to historical functions" considerations described in the previous section, removing custom model fields from your project or third-party app will cause a problem if they are referenced in old migrations.

Untuk membantu dengan keadaan ini, Django menyediakan beberapa atribut bidang model untuk memandu dengan pengusangan bidang model menggunakan system checks framework.

Add the `system_check_deprecated_details` attribute to your model field similar to the following:

    class IPAddressField(Field):
        system_check_deprecated_details = {
            'msg': (
                'IPAddressField has been deprecated. Support for it (except '
                'in historical migrations) will be removed in Django 1.9.'
            ),
            'hint': 'Use GenericIPAddressField instead.',  # optional
            'id': 'fields.W900',  # pick a unique ID for your field.
        }

After a deprecation period of your choosing (two or three feature releases for fields in Django itself), change the `system_check_deprecated_details` attribute to `system_check_removed_details` and update the dictionary similar to:

    class IPAddressField(Field):
        system_check_removed_details = {
            'msg': (
                'IPAddressField has been removed except for support in '
                'historical migrations.'
            ),
            'hint': 'Use GenericIPAddressField instead.',
            'id': 'fields.E900',  # pick a unique ID for your field.
        }

You should keep the field's methods that are required for it to operate in database migrations such as `__init__()`, `deconstruct()`, and `get_internal_type()`. Keep this stub field for as long as any migrations which reference the field exist. For example, after squashing migrations and removing the old ones, you should be able to remove the field completely.

## Perpindahan Data

As well as changing the database schema, you can also use migrations to change the data in the database itself, in conjunction with the schema if you want.

Migrations that alter data are usually called "data migrations"; they're best written as separate migrations, sitting alongside your schema migrations.

Django can't automatically generate data migrations for you, as it does with schema migrations, but it's not very hard to write them. Migration files in Django are made up of Operations, and the main operation you use for data migrations is `RunPython`.

To start, make an empty migration file you can work from (Django will put the file in the right place, suggest a name, and add dependencies for you):

    python manage.py makemigrations --empty yourappname

Lalu, buka berkas; dia seharusnya kelihatan sesuatu sepert ini:

    # Generated by Django A.B on YYYY-MM-DD HH:MM
    from django.db import migrations

    class Migration(migrations.Migration):

        dependencies = [
            ('yourappname', '0001_initial'),
        ]

        operations = [
        ]

Sekarang, semua yang perlu anda lakukan adalah membuat sebuah fungsi baru dan memiliki `RunPython` menggunakannya. `RunPython` mengharapkan sebuah callable sebagai argumennya yang mengambil dua argumen - pertama adalah sebuah app registry yang mempunyai versi riwayat dari semua model anda dimuat kedalam itu untuk mencocokkan dimana riwayat perpindahan anda berada, dan kedua adalah SchemaEditor, yang dapat menggunakan secara manual mempengaruhi perubahan skema basisdata (tetapi hati-hati, melakukan ini dapat membingungkan pengenal otomatis perpindahan!)

Let's write a simple migration that populates our new `name` field with the combined values of `first_name` and `last_name` (we've come to our senses and realized that not everyone has first and last names). All we need to do is use the historical model and iterate over the rows:

    from django.db import migrations

    def combine_names(apps, schema_editor):
        # We can't import the Person model directly as it may be a newer
        # version than this migration expects. We use the historical version.
        Person = apps.get_model('yourappname', 'Person')
        for person in Person.objects.all():
            person.name = '%s %s' % (person.first_name, person.last_name)
            person.save()

    class Migration(migrations.Migration):

        dependencies = [
            ('yourappname', '0001_initial'),
        ]

        operations = [
            migrations.RunPython(combine_names),
        ]

Once that's done, we can just run `python manage.py migrate` as normal and the data migration will run in place alongside other migrations.

You can pass a second callable to `RunPython` to run whatever logic you want executed when migrating backwards. If this callable is omitted, migrating backwards will raise an exception.

### Mengakses model dari aplikasi lain

When writing a `RunPython` function that uses models from apps other than the one in which the migration is located, the migration's `dependencies` attribute should include the latest migration of each app that is involved, otherwise you may get an error similar to: `LookupError: No installed app with label 'myappname'` when you try to retrieve the model in the `RunPython` function using `apps.get_model()`.

In the following example, we have a migration in `app1` which needs to use models in `app2`. We aren't concerned with the details of `move_m1` other than the fact it will need to access models from both apps. Therefore we've added a dependency that specifies the last migration of `app2`:

    class Migration(migrations.Migration):

        dependencies = [
            ('app1', '0001_initial'),
            # added dependency to enable using models from app2 in move_m1
            ('app2', '0004_foobar'),
        ]

        operations = [
            migrations.RunPython(move_m1),
        ]

### Perpindahan lebih lanjut

If you're interested in the more advanced migration operations, or want to be able to write your own, see the migration operations reference and the "how-to" on writing migrations.

## Squashing migrations

You are encouraged to make migrations freely and not worry about how many you have; the migration code is optimized to deal with hundreds at a time without much slowdown. However, eventually you will want to move back from having several hundred migrations to just a few, and that's where squashing comes in.

Squashing is the act of reducing an existing set of many migrations down to one (or sometimes a few) migrations which still represent the same changes.

Django does this by taking all of your existing migrations, extracting their `Operation`s and putting them all in sequence, and then running an optimizer over them to try and reduce the length of the list - for example, it knows that `CreateModel` and `DeleteModel` cancel each other out, and it knows that `AddField` can be rolled into `CreateModel`.

Once the operation sequence has been reduced as much as possible - the amount possible depends on how closely intertwined your models are and if you have any `RunSQL` or `RunPython` operations (which can't be optimized through unless they are marked as `elidable`) - Django will then write it back out into a new set of migration files.

These files are marked to say they replace the previously-squashed migrations, so they can coexist with the old migration files, and Django will intelligently switch between them depending where you are in the history. If you're still part-way through the set of migrations that you squashed, it will keep using them until it hits the end and then switch to the squashed history, while new installs will just use the new squashed migration and skip all the old ones.

This enables you to squash and not mess up systems currently in production that aren't fully up-to-date yet. The recommended process is to squash, keeping the old files, commit and release, wait until all systems are upgraded with the new release (or if you're a third-party project, just ensure your users upgrade releases in order without skipping any), and then remove the old files, commit and do a second release.

The command that backs all this is `squashmigrations` - just pass it the app label and migration name you want to squash up to, and it'll get to work:

    $ ./manage.py squashmigrations myapp 0004
    Will squash the following migrations:
     - 0001_initial
     - 0002_some_change
     - 0003_another_change
     - 0004_undo_something
    Do you wish to proceed? [yN] y
    Optimizing...
      Optimized from 12 operations to 7 operations.
    Created new squashed migration /home/andrew/Programs/DjangoTest/test/migrations/0001_squashed_0004_undo_somthing.py
      You should commit this migration but leave the old ones in place;
      the new migration will be used for new installs. Once you are sure
      all instances of the codebase have applied the migrations you squashed,
      you can delete them.

Use the `squashmigrations --squashed-name` option if you want to set the name of the squashed migration rather than use an autogenerated one.

Note that model interdependencies in Django can get very complex, and squashing may result in migrations that do not run; either mis-optimized (in which case you can try again with `--no-optimize`, though you should also report an issue), or with a `CircularDependencyError`, in which case you can manually resolve it.

To manually resolve a `CircularDependencyError`, break out one of the ForeignKeys in the circular dependency loop into a separate migration, and move the dependency on the other app with it. If you're unsure, see how makemigrations deals with the problem when asked to create brand new migrations from your models. In a future release of Django, squashmigrations will be updated to attempt to resolve these errors itself.

Once you've squashed your migration, you should then commit it alongside the migrations it replaces and distribute this change to all running instances of your application, making sure that they run `migrate` to store the change in their database.

You must then transition the squashed migration to a normal migration by:

- Deleting all the migration files it replaces.
- Updating all migrations that depend on the deleted migrations to depend on the squashed migration instead.
- Removing the `replaces` attribute in the `Migration` class of the squashed migration (this is how Django tells that it is a squashed migration).

Catatan

Once you've squashed a migration, you should not then re-squash that squashed migration until you have fully transitioned it to a normal migration.

## Serializing values

Migrations are just Python files containing the old definitions of your models - thus, to write them, Django must take the current state of your models and serialize them out into a file.

While Django can serialize most things, there are some things that we just can't serialize out into a valid Python representation - there's no Python standard for how a value can be turned back into code (`repr()` only works for basic values, and doesn't specify import paths).

Django can serialize the following:

- `int`, `float`, `bool`, `str`, `bytes`, `None`
- `list`, `set`, `tuple`, `dict`
- `datetime.date`, `datetime.time`, and `datetime.datetime` instances (include those that are timezone-aware)
- `decimal.Decimal` instances
- `enum.Enum` instances
- `uuid.UUID` instances
- `functools.partial` instances which have serializable `func`, `args`, and `keywords` values.
- `LazyObject` instances which wrap a serializable value.
- Bidang Django Apapun
- Any function or method reference (e.g. `datetime.datetime.today`) (must be in module's top-level scope)
- Unbound methods used from within the class body
- Any class reference (must be in module's top-level scope)
- Anything with a custom `deconstruct()` method (see below)

Changed in Django 1.11:

Serialization support for `uuid.UUID` was added.

Django tidak dapat diserialkan:

- Kelas bersarang
- Arbitrary class instances (e.g. `MyClass(4.3, 5.7)`)
- Lambdas

### Menambahkan cara `deconstruct()`

You can let Django serialize your own custom class instances by giving the class a `deconstruct()` method. It takes no arguments, and should return a tuple of three things `(path, args, kwargs)`:

- `path` should be the Python path to the class, with the class name included as the last part (for example, `myapp.custom_things.MyClass`). If your class is not available at the top level of a module it is not serializable.
- `args` should be a list of positional arguments to pass to your class' `__init__` method. Everything in this list should itself be serializable.
- `kwargs` should be a dict of keyword arguments to pass to your class' `__init__` method. Every value should itself be serializable.

Catatan

This return value is different from the `deconstruct()` method for custom fields which returns a tuple of four items.

Django will write out the value as an instantiation of your class with the given arguments, similar to the way it writes out references to Django fields.

To prevent a new migration from being created each time `makemigrations` is run, you should also add a `__eq__()` method to the decorated class. This function will be called by Django's migration framework to detect changes between states.

As long as all of the arguments to your class' constructor are themselves serializable, you can use the `@deconstructible` class decorator from `django.utils.deconstruct` to add the `deconstruct()` method:

    from django.utils.deconstruct import deconstructible

    @deconstructible
    class MyCustomClass:

        def __init__(self, foo=1):
            self.foo = foo
            ...

        def __eq__(self, other):
            return self.foo == other.foo

The decorator adds logic to capture and preserve the arguments on their way into your constructor, and then returns those arguments exactly when deconstruct() is called.

## Mendukung banyak versi Django

If you are the maintainer of a third-party app with models, you may need to ship migrations that support multiple Django versions. In this case, you should always run `makemigrations` with the lowest Django version you wish to support.

The migrations system will maintain backwards-compatibility according to the same policy as the rest of Django, so migration files generated on Django X.Y should run unchanged on Django X.Y+1. The migrations system does not promise forwards-compatibility, however. New features may be added, and migration files generated with newer versions of Django may not work on older versions.

lihat juga

The Migrations Operations Reference 1
  Menutupi skema API tindakan, tindakan khusus, dan menulis tindakan anda sendiri.
Menulis Perpindahan "how-to"
  Explains how to structure and write database migrations for different scenarios you might encounter.