Fixture documentation should include non-numeric PK information

[Tim Chase <django.ticket@…>]

The documentation at ​https://docs.djangoproject.com/en/dev/howto/initial-data/#providing-initial-data-with-fixtures only describes the general/default case where the PK/id is numeric. It would be nice to include documentation for the cases where this is non-numeric. E.g

class MyModel(Model):
  id = CharField(primary=True, max_length=3)
  desc = CharField(max_length=50)

The fixture should be

[
{"pk": "BLU",
 "model": "myapp.mymodel",
 "fields": {"description": "Blue"}
}
]

instead of

[
{"pk": 0,
 "model": "myapp.mymodel",
 "fields": {"id"="BLU", "description": "Blue"}
}
]

I had to figure this out through trial & error, and documenting it here may save others the trouble.

[Aymeric Augustin]

Django special-cases the primary key field in the models because it's the identifier of each instance. This implementation detail shows up in the serialization format.

As mentioned at the beginning of the page you link to, the canonical way of creating fixtures is dumpdata. However, a quick explanation of the serialization format couldn't hurt. I think it should go in the serialization docs, not in the initial data howto.

In short, I'd say that each instance is represented by a dictionary with three keys:

• "model" => the name of the model, including the application label,
• "pk" => the value of primary key of the instance,
• "fields" => a dictionary of the values of the other fields of the instance.

[Tim Chase <django.ticket@…>]

Part of the complication is the behind-the-scenes twiddling that Django does between named fields and the automatically-generated "pk" field. Something like your "whatever is declared as the primary key is stored under 'pk' regardless of the field's actual name, and everything else is stored in 'fields'" text makes it pretty clear. While mucking in this section of the docs, it might be nice to explicitly mention that the model-name is lower-cased (something that can be inferred from the examples, but not explicitly stated like it is in the the initial-SQL section).

I don't feel strongly regarding where the documentation resides (whether at my link or your suggestion of the serialization docs) as long as there's commentary/linking between the locations.

[Aymeric Augustin]

In fact, pk is just an alias for the primary key field. The new text could link to ​https://docs.djangoproject.com/en/dev/topics/db/queries/#the-pk-lookup-shortcut.

[Caio Ariede]

I think this could be marked as resolved, as the following commit seems to have indirectly fixed it:

​https://github.com/django/django/commit/5612f54bd56086e2a375e86474ec734c172e7d1f#diff-9dd4e5170c046e9980f7b1bf30910cb6R229-R233

[Carlton Gibson]

Yes, thank you Caio.

Reviewing the ​serialization topic docs it seems clear that the pk is always the primary key, and that that never appears in the fields value. (And then there's the whole lot on each particular format too.)