Opened 12 years ago

Closed 4 years ago

#17007 closed New feature (fixed)

Fixture documentation should include non-numeric PK information

Reported by: Tim Chase <django.ticket@…> Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords: fixture, initial data
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Change History (5)

comment:1 by Aymeric Augustin, 12 years ago

Easy pickings: unset
Triage Stage: UnreviewedAccepted

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.

comment:2 by Tim Chase <django.ticket@…>, 12 years ago

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.

comment:3 by Aymeric Augustin, 12 years ago

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.

comment:4 by Caio Ariede, 4 years ago

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

comment:5 by Carlton Gibson, 4 years ago

Resolution: fixed
Status: newclosed

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.)

Note: See TracTickets for help on using tickets.
Back to Top