null¶

Field.null¶

IfTrue, Django will store empty values asNULL in the database. DefaultisFalse.

Avoid usingnull on string-based fields such asCharField andTextField. If a string-based field hasnull=True, that means it has two possible values for “no data”:NULL,and the empty string. In most cases, it’s redundant to have two possible valuesfor “no data;” the Django convention is to use the empty string, notNULL. One exception is when aCharField has bothunique=Trueandblank=True set. In this situation,null=True is required to avoidunique constraint violations when saving multiple objects with blank values.

For both string-based and non-string-based fields, you will also need tosetblank=True if you wish to permit empty values in forms, as thenull parameter only affects database storage(seeblank).

blank¶

Field.blank¶

IfTrue, the field is allowed to be blank. Default isFalse.

Note that this is different thannull.null ispurely database-related, whereasblank is validation-related. Ifa field hasblank=True, form validation will allow entry of an empty value.If a field hasblank=False, the field will be required.

choices¶

Field.choices¶

An iterable (e.g., a list or tuple) consisting itself of iterables of exactlytwo items (e.g.[(A,B),(A,B)...]) to use as choices for this field. Ifchoices are given, they’re enforced bymodel validation and the default form widget will be a select box withthese choices instead of the standard text field.

The first element in each tuple is the actual value to be set on the model,and the second element is the human-readable name. For example:

YEAR_IN_SCHOOL_CHOICES=(('FR','Freshman'),('SO','Sophomore'),('JR','Junior'),('SR','Senior'),)

Generally, it’s best to define choices inside a model class, and todefine a suitably-named constant for each value:

fromdjango.dbimportmodelsclassStudent(models.Model):FRESHMAN='FR'SOPHOMORE='SO'JUNIOR='JR'SENIOR='SR'YEAR_IN_SCHOOL_CHOICES=((FRESHMAN,'Freshman'),(SOPHOMORE,'Sophomore'),(JUNIOR,'Junior'),(SENIOR,'Senior'),)year_in_school=models.CharField(max_length=2,choices=YEAR_IN_SCHOOL_CHOICES,default=FRESHMAN,)defis_upperclass(self):returnself.year_in_schoolin(self.JUNIOR,self.SENIOR)

Though you can define a choices list outside of a model class and thenrefer to it, defining the choices and names for each choice inside themodel class keeps all of that information with the class that uses it,and makes the choices easy to reference (e.g,Student.SOPHOMOREwill work anywhere that theStudent model has been imported).

You can also collect your available choices into named groups that canbe used for organizational purposes:

MEDIA_CHOICES=(('Audio',(('vinyl','Vinyl'),('cd','CD'),)),('Video',(('vhs','VHS Tape'),('dvd','DVD'),)),('unknown','Unknown'),)

The first element in each tuple is the name to apply to the group. Thesecond element is an iterable of 2-tuples, with each 2-tuple containinga value and a human-readable name for an option. Grouped options may becombined with ungrouped options within a single list (such as theunknown option in this example).

For each model field that haschoices set, Django will add amethod to retrieve the human-readable name for the field’s current value. Seeget_FOO_display() in the database APIdocumentation.

Note that choices can be any iterable object – not necessarily a list or tuple.This lets you construct choices dynamically. But if you find yourself hackingchoices to be dynamic, you’re probably better off using a properdatabase table with aForeignKey.choices is meant forstatic data that doesn’t change much, if ever.

Unlessblank=False is set on the field along with adefault then a label containing"---------" will be renderedwith the select box. To override this behavior, add a tuple tochoicescontainingNone; e.g.(None,'YourStringForDisplay').Alternatively, you can use an empty string instead ofNone where this makessense - such as on aCharField.

db_column¶

Field.db_column¶

The name of the database column to use for this field. If this isn’t given,Django will use the field’s name.

If your database column name is an SQL reserved word, or containscharacters that aren’t allowed in Python variable names – notably, thehyphen – that’s OK. Django quotes column and table names behind thescenes.

db_index¶

Field.db_index¶

IfTrue, a database index will be created for this field.

db_tablespace¶

Field.db_tablespace¶

The name of thedatabase tablespace to use forthis field’s index, if this field is indexed. The default is the project’sDEFAULT_INDEX_TABLESPACE setting, if set, or thedb_tablespace of the model, if any. If the backend doesn’tsupport tablespaces for indexes, this option is ignored.

default¶

Field.default¶

The default value for the field. This can be a value or a callable object. Ifcallable it will be called every time a new object is created.

The default can’t be a mutable object (model instance,list,set, etc.),as a reference to the same instance of that object would be used as the defaultvalue in all new model instances. Instead, wrap the desired default in acallable. For example, if you want to specify a defaultdict forJSONField, use a function:

defcontact_default():return{"email":"to1@example.com"}contact_info=JSONField("ContactInfo",default=contact_default)

lambdas can’t be used for field options likedefault because theycan’t beserialized by migrations. See thatdocumentation for other caveats.

For fields likeForeignKey that map to model instances, defaultsshould be the value of the field they reference (pk unlessto_field is set) instead of model instances.

The default value is used when new model instances are created and a valueisn’t provided for the field. When the field is a primary key, the default isalso used when the field is set toNone.

editable¶

Field.editable¶

IfFalse, the field will not be displayed in the admin or any otherModelForm. They are also skipped duringmodelvalidation. Default isTrue.

error_messages¶

Field.error_messages¶

Theerror_messages argument lets you override the default messages that thefield will raise. Pass in a dictionary with keys matching the error messages youwant to override.

Error message keys includenull,blank,invalid,invalid_choice,unique, andunique_for_date. Additional error message keys arespecified for each field in theField types section below.

These error messages often don’t propagate to forms. SeeConsiderations regarding model’s error_messages.

help_text¶

Field.help_text¶

Extra “help” text to be displayed with the form widget. It’s useful fordocumentation even if your field isn’t used on a form.

Note that this value isnot HTML-escaped in automatically-generatedforms. This lets you include HTML inhelp_text if you sodesire. For example:

help_text="Please use the following format: <em>YYYY-MM-DD</em>."

Alternatively you can use plain text anddjango.utils.html.escape() to escape any HTML special characters. Ensurethat you escape any help text that may come from untrusted users to avoid across-site scripting attack.

primary_key¶

Field.primary_key¶

IfTrue, this field is the primary key for the model.

If you don’t specifyprimary_key=True for any field in your model, Djangowill automatically add anAutoField to hold the primary key, so youdon’t need to setprimary_key=True on any of your fields unless you want tooverride the default primary-key behavior. For more, seeAutomatic primary key fields.

primary_key=True impliesnull=False andunique=True. Only one primary key is allowed on anobject.

The primary key field is read-only. If you change the value of the primarykey on an existing object and then save it, a new object will be createdalongside the old one.

unique¶

Field.unique¶

IfTrue, this field must be unique throughout the table.

This is enforced at the database level and by model validation. Ifyou try to save a model with a duplicate value in auniquefield, adjango.db.IntegrityError will be raised by the model’ssave() method.

This option is valid on all field types exceptManyToManyField andOneToOneField.

Note that whenunique isTrue, you don’t need to specifydb_index, becauseunique implies the creation of an index.

unique_for_date¶

Field.unique_for_date¶

Set this to the name of aDateField orDateTimeField torequire that this field be unique for the value of the date field.

For example, if you have a fieldtitle that hasunique_for_date="pub_date", then Django wouldn’t allow the entry of tworecords with the sametitle andpub_date.

Note that if you set this to point to aDateTimeField, only the dateportion of the field will be considered. Besides, whenUSE_TZ isTrue, the check will be performed in thecurrent time zone at the time the object gets saved.

This is enforced byModel.validate_unique() during model validationbut not at the database level. If anyunique_for_date constraintinvolves fields that are not part of aModelForm (forexample, if one of the fields is listed inexclude or haseditable=False),Model.validate_unique() willskip validation for that particular constraint.

unique_for_month¶

Field.unique_for_month¶

Likeunique_for_date, but requires the field to be unique withrespect to the month.

unique_for_year¶

Field.unique_for_year¶

Likeunique_for_date andunique_for_month.

verbose_name¶

Field.verbose_name¶

A human-readable name for the field. If the verbose name isn’t given, Djangowill automatically create it using the field’s attribute name, convertingunderscores to spaces. SeeVerbose field names.

validators¶

Field.validators¶

A list of validators to run for this field. See thevalidatorsdocumentation for more information.

AutoField¶

classAutoField(**options)[source]¶

AnIntegerField that automatically incrementsaccording to available IDs. You usually won’t need to use this directly; aprimary key field will automatically be added to your model if you don’t specifyotherwise. SeeAutomatic primary key fields.

BigAutoField¶

classBigAutoField(**options)[source]¶

A 64-bit integer, much like anAutoField except that it isguaranteed to fit numbers from1 to9223372036854775807.

BigIntegerField¶

classBigIntegerField(**options)[source]¶

A 64-bit integer, much like anIntegerField except that it isguaranteed to fit numbers from-9223372036854775808 to9223372036854775807. The default form widget for this field is aTextInput.

BinaryField¶

classBinaryField(max_length=None,**options)[source]¶

A field to store raw binary data. It can be assignedbytes,bytearray, ormemoryview.

By default,BinaryField setseditable toFalse, in whichcase it can’t be included in aModelForm.

BinaryField has one extra optional argument:

BinaryField.max_length¶

The maximum length (in characters) of the field. The maximum length isenforced in Django’s validation usingMaxLengthValidator.

BooleanField¶

classBooleanField(**options)[source]¶

A true/false field.

The default form widget for this field isCheckboxInput,orNullBooleanSelect ifnull=True.

The default value ofBooleanField isNone whenField.defaultisn’t defined.

CharField¶

classCharField(max_length=None,**options)[source]¶

A string field, for small- to large-sized strings.

For large amounts of text, useTextField.

The default form widget for this field is aTextInput.

CharField has one extra required argument:

CharField.max_length¶

The maximum length (in characters) of the field. The max_length is enforcedat the database level and in Django’s validation usingMaxLengthValidator.

DateField¶

classDateField(auto_now=False,auto_now_add=False,**options)[source]¶

A date, represented in Python by adatetime.date instance. Has a few extra,optional arguments:

DateField.auto_now¶

Automatically set the field to now every time the object is saved. Usefulfor “last-modified” timestamps. Note that the current date isalwaysused; it’s not just a default value that you can override.

The field is only automatically updated when callingModel.save(). The field isn’t updated when making updatesto other fields in other ways such asQuerySet.update(), though you can specify a customvalue for the field in an update like that.

DateField.auto_now_add¶

Automatically set the field to now when the object is first created. Usefulfor creation of timestamps. Note that the current date isalways used;it’s not just a default value that you can override. So even if youset a value for this field when creating the object, it will be ignored.If you want to be able to modify this field, set the following instead ofauto_now_add=True:

• ForDateField:default=date.today - fromdatetime.date.today()
• ForDateTimeField:default=timezone.now - fromdjango.utils.timezone.now()

The default form widget for this field is aTextInput. The admin adds a JavaScript calendar,and a shortcut for “Today”. Includes an additionalinvalid_date errormessage key.

The optionsauto_now_add,auto_now, anddefault are mutually exclusive.Any combination of these options will result in an error.

DateTimeField¶

classDateTimeField(auto_now=False,auto_now_add=False,**options)[source]¶

A date and time, represented in Python by adatetime.datetime instance.Takes the same extra arguments asDateField.

The default form widget for this field is a singleTextInput. The admin uses two separateTextInput widgets with JavaScript shortcuts.

DecimalField¶

classDecimalField(max_digits=None,decimal_places=None,**options)[source]¶

A fixed-precision decimal number, represented in Python by aDecimal instance. It validates the input usingDecimalValidator.

Has tworequired arguments:

DecimalField.max_digits¶

The maximum number of digits allowed in the number. Note that this numbermust be greater than or equal todecimal_places.

DecimalField.decimal_places¶

The number of decimal places to store with the number.

For example, to store numbers up to999 with a resolution of 2 decimalplaces, you’d use:

models.DecimalField(...,max_digits=5,decimal_places=2)

And to store numbers up to approximately one billion with a resolution of 10decimal places:

models.DecimalField(...,max_digits=19,decimal_places=10)

The default form widget for this field is aNumberInputwhenlocalize isFalse orTextInput otherwise.

DurationField¶

classDurationField(**options)[source]¶

A field for storing periods of time - modeled in Python bytimedelta. When used on PostgreSQL, the data typeused is aninterval and on Oracle the data type isINTERVALDAY(9)TOSECOND(6). Otherwise abigint of microseconds is used.

EmailField¶

classEmailField(max_length=254,**options)[source]¶

ACharField that checks that the value is a valid email address usingEmailValidator.

FileField¶

classFileField(upload_to=None,max_length=100,**options)[source]¶

A file-upload field.

Has two optional arguments:

FileField.upload_to¶

This attribute provides a way of setting the upload directory and file name,and can be set in two ways. In both cases, the value is passed to theStorage.save() method.

If you specify a string value, it may containstrftime()formatting, which will be replaced by the date/time of the file upload (sothat uploaded files don’t fill up the given directory). For example:

classMyModel(models.Model):# file will be uploaded to MEDIA_ROOT/uploadsupload=models.FileField(upload_to='uploads/')# or...# file will be saved to MEDIA_ROOT/uploads/2015/01/30upload=models.FileField(upload_to='uploads/%Y/%m/%d/')

If you are using the defaultFileSystemStorage, the string valuewill be appended to yourMEDIA_ROOT path to form the location onthe local filesystem where uploaded files will be stored. If you are usinga different storage, check that storage’s documentation to see how ithandlesupload_to.

upload_to may also be a callable, such as a function. This will becalled to obtain the upload path, including the filename. This callable mustaccept two arguments and return a Unix-style path (with forward slashes)to be passed along to the storage system. The two arguments are:

Argument	Description
instance	An instance of the model where theFileField is defined. More specifically,this is the particular instance where thecurrent file is being attached. In most cases, this object will not have beensaved to the database yet, so if it uses thedefaultAutoField,it might not yet have avalue for its primary key field.
filename	The filename that was originally given to thefile. This may or may not be taken into accountwhen determining the final destination path.

For example:

defuser_directory_path(instance,filename):# file will be uploaded to MEDIA_ROOT/user_<id>/<filename>return'user_{0}/{1}'.format(instance.user.id,filename)classMyModel(models.Model):upload=models.FileField(upload_to=user_directory_path)

FileField.storage¶

A storage object, which handles the storage and retrieval of yourfiles. SeeManaging files for details on how to provide this object.

The default form widget for this field is aClearableFileInput.

Using aFileField or anImageField (see below) in a modeltakes a few steps:

1. In your settings file, you’ll need to defineMEDIA_ROOT as thefull path to a directory where you’d like Django to store uploaded files.(For performance, these files are not stored in the database.) DefineMEDIA_URL as the base public URL of that directory. Make surethat this directory is writable by the Web server’s user account.
2. Add theFileField orImageField to your model, definingtheupload_to option to specify a subdirectory ofMEDIA_ROOT to use for uploaded files.
3. All that will be stored in your database is a path to the file(relative toMEDIA_ROOT). You’ll most likely want to use theconvenienceurl attributeprovided by Django. For example, if yourImageField is calledmug_shot, you can get the absolute path to your image in a template with{{object.mug_shot.url}}.

For example, say yourMEDIA_ROOT is set to'/home/media', andupload_to is set to'photos/%Y/%m/%d'. The'%Y/%m/%d'part ofupload_to isstrftime() formatting;'%Y' is the four-digit year,'%m' is the two-digit month and'%d' isthe two-digit day. If you upload a file on Jan. 15, 2007, it will be saved inthe directory/home/media/photos/2007/01/15.

If you wanted to retrieve the uploaded file’s on-disk filename, or the file’ssize, you could use thename andsize attributes respectively; for moreinformation on the available attributes and methods, see theFile class reference and theManaging filestopic guide.

The uploaded file’s relative URL can be obtained using theurl attribute. Internally,this calls theurl() method of theunderlyingStorage class.

Note that whenever you deal with uploaded files, you should pay close attentionto where you’re uploading them and what type of files they are, to avoidsecurity holes.Validate all uploaded files so that you’re sure the files arewhat you think they are. For example, if you blindly let somebody upload files,without validation, to a directory that’s within your Web server’s documentroot, then somebody could upload a CGI or PHP script and execute that script byvisiting its URL on your site. Don’t allow that.

Also note that even an uploaded HTML file, since it can be executed by thebrowser (though not by the server), can pose security threats that areequivalent to XSS or CSRF attacks.

FileField instances are created in your database asvarcharcolumns with a default max length of 100 characters. As with other fields, youcan change the maximum length using themax_length argument.

fromdjango.core.filesimportFile# Open an existing file using Python's built-in open()f=open('/path/to/hello.world')myfile=File(f)

fromdjango.core.files.baseimportContentFilemyfile=ContentFile("hello world")

FilePathField¶

classFilePathField(path=None,match=None,recursive=False,max_length=100,**options)[source]¶

ACharField whose choices are limited to the filenames in a certaindirectory on the filesystem. Has three special arguments, of which the first isrequired:

FilePathField.path¶

Required. The absolute filesystem path to a directory from which thisFilePathField should get its choices. Example:"/home/images".

FilePathField.match¶

Optional. A regular expression, as a string, thatFilePathFieldwill use to filter filenames. Note that the regex will be applied to thebase filename, not the full path. Example:"foo.*\.txt$", which willmatch a file calledfoo23.txt but notbar.txt orfoo23.png.

FilePathField.recursive¶

Optional. EitherTrue orFalse. Default isFalse. Specifieswhether all subdirectories ofpath should be included

FilePathField.allow_files¶

Optional. EitherTrue orFalse. Default isTrue. Specifieswhether files in the specified location should be included. Either this orallow_folders must beTrue.

FilePathField.allow_folders¶

Optional. EitherTrue orFalse. Default isFalse. Specifieswhether folders in the specified location should be included. Either thisorallow_files must beTrue.

Of course, these arguments can be used together.

The one potential gotcha is thatmatch applies to thebase filename, not the full path. So, this example:

FilePathField(path="/home/images",match="foo.*",recursive=True)

…will match/home/images/foo.png but not/home/images/foo/bar.pngbecause thematch applies to the base filename(foo.png andbar.png).

FilePathField instances are created in your database asvarcharcolumns with a default max length of 100 characters. As with other fields, youcan change the maximum length using themax_length argument.

FloatField¶

classFloatField(**options)[source]¶

A floating-point number represented in Python by afloat instance.

The default form widget for this field is aNumberInputwhenlocalize isFalse orTextInput otherwise.

ImageField¶

classImageField(upload_to=None,height_field=None,width_field=None,max_length=100,**options)[source]¶

Inherits all attributes and methods fromFileField, but alsovalidates that the uploaded object is a valid image.

In addition to the special attributes that are available forFileField,anImageField also hasheight andwidth attributes.

To facilitate querying on those attributes,ImageField has two extraoptional arguments:

ImageField.height_field¶

Name of a model field which will be auto-populated with the height of theimage each time the model instance is saved.

ImageField.width_field¶

Name of a model field which will be auto-populated with the width of theimage each time the model instance is saved.

Requires thePillow library.

ImageField instances are created in your database asvarcharcolumns with a default max length of 100 characters. As with other fields, youcan change the maximum length using themax_length argument.

The default form widget for this field is aClearableFileInput.

IntegerField¶

classIntegerField(**options)[source]¶

An integer. Values from-2147483648 to2147483647 are safe in alldatabases supported by Django.

It usesMinValueValidator andMaxValueValidator to validate the input basedon the values that the default database supports.

The default form widget for this field is aNumberInputwhenlocalize isFalse orTextInput otherwise.

GenericIPAddressField¶

classGenericIPAddressField(protocol='both',unpack_ipv4=False,**options)[source]¶

An IPv4 or IPv6 address, in string format (e.g.192.0.2.30 or2a02:42fe::4). The default form widget for this field is aTextInput.

The IPv6 address normalization followsRFC 4291#section-2.2 section 2.2,including using the IPv4 format suggested in paragraph 3 of that section, like::ffff:192.0.2.0. For example,2001:0::0:01 would be normalized to2001::1, and::ffff:0a0a:0a0a to::ffff:10.10.10.10. All charactersare converted to lowercase.

GenericIPAddressField.protocol¶

Limits valid inputs to the specified protocol.Accepted values are'both' (default),'IPv4'or'IPv6'. Matching is case insensitive.

GenericIPAddressField.unpack_ipv4¶

Unpacks IPv4 mapped addresses like::ffff:192.0.2.1.If this option is enabled that address would be unpacked to192.0.2.1. Default is disabled. Can only be usedwhenprotocol is set to'both'.

If you allow for blank values, you have to allow for null values since blankvalues are stored as null.

NullBooleanField¶

classNullBooleanField(**options)[source]¶

LikeBooleanField withnull=True. Use that instead of this fieldas it’s likely to be deprecated in a future version of Django.

PositiveIntegerField¶

classPositiveIntegerField(**options)[source]¶

Like anIntegerField, but must be either positive or zero (0).Values from0 to2147483647 are safe in all databases supported byDjango. The value0 is accepted for backward compatibility reasons.

PositiveSmallIntegerField¶

classPositiveSmallIntegerField(**options)[source]¶

Like aPositiveIntegerField, but only allows values under a certain(database-dependent) point. Values from0 to32767 are safe in alldatabases supported by Django.

SlugField¶

classSlugField(max_length=50,**options)[source]¶

Slug is a newspaper term. A slug is a short label for something,containing only letters, numbers, underscores or hyphens. They’re generally usedin URLs.

Like a CharField, you can specifymax_length (read the noteabout database portability andmax_length in that section,too). Ifmax_length is not specified, Django will use adefault length of 50.

Implies settingField.db_index toTrue.

It is often useful to automatically prepopulate a SlugField based on the valueof some other value. You can do this automatically in the admin usingprepopulated_fields.

It usesvalidate_slug orvalidate_unicode_slug for validation.

SlugField.allow_unicode¶

IfTrue, the field accepts Unicode letters in addition to ASCIIletters. Defaults toFalse.

SmallIntegerField¶

classSmallIntegerField(**options)[source]¶

Like anIntegerField, but only allows values under a certain(database-dependent) point. Values from-32768 to32767 are safe in alldatabases supported by Django.

TextField¶

classTextField(**options)[source]¶

A large text field. The default form widget for this field is aTextarea.

If you specify amax_length attribute, it will be reflected in theTextarea widget of the auto-generated form field.However it is not enforced at the model or database level. Use aCharField for that.

TimeField¶

classTimeField(auto_now=False,auto_now_add=False,**options)[source]¶

A time, represented in Python by adatetime.time instance. Accepts the sameauto-population options asDateField.

The default form widget for this field is aTextInput.The admin adds some JavaScript shortcuts.

URLField¶

classURLField(max_length=200,**options)[source]¶

ACharField for a URL, validated byURLValidator.

The default form widget for this field is aTextInput.

Like allCharField subclasses,URLField takes the optionalmax_length argument. If you don’t specifymax_length, a default of 200 is used.

UUIDField¶

classUUIDField(**options)[source]¶

A field for storing universally unique identifiers. Uses Python’sUUID class. When used on PostgreSQL, this stores in auuid datatype, otherwise in achar(32).

Universally unique identifiers are a good alternative toAutoField forprimary_key. The database will not generate the UUID for you, soit is recommended to usedefault:

importuuidfromdjango.dbimportmodelsclassMyUUIDModel(models.Model):id=models.UUIDField(primary_key=True,default=uuid.uuid4,editable=False)# other fields

Note that a callable (with the parentheses omitted) is passed todefault,not an instance ofUUID.

ForeignKey¶

classForeignKey(to,on_delete,**options)[source]¶

A many-to-one relationship. Requires two positional arguments: the class towhich the model is related and theon_delete option.

To create a recursive relationship – an object that has a many-to-onerelationship with itself – usemodels.ForeignKey('self',on_delete=models.CASCADE).

If you need to create a relationship on a model that has not yet been defined,you can use the name of the model, rather than the model object itself:

fromdjango.dbimportmodelsclassCar(models.Model):manufacturer=models.ForeignKey('Manufacturer',on_delete=models.CASCADE,)# ...classManufacturer(models.Model):# ...pass

Relationships defined this way onabstract models are resolved when the model is subclassed as aconcrete model and are not relative to the abstract model’sapp_label:

fromdjango.dbimportmodelsclassAbstractCar(models.Model):manufacturer=models.ForeignKey('Manufacturer',on_delete=models.CASCADE)classMeta:abstract=True

fromdjango.dbimportmodelsfromproducts.modelsimportAbstractCarclassManufacturer(models.Model):passclassCar(AbstractCar):pass# Car.manufacturer will point to `production.Manufacturer` here.

To refer to models defined in another application, you can explicitly specifya model with the full application label. For example, if theManufacturermodel above is defined in another application calledproduction, you’dneed to use:

classCar(models.Model):manufacturer=models.ForeignKey('production.Manufacturer',on_delete=models.CASCADE,)

This sort of reference, called a lazy relationship, can be useful whenresolving circular import dependencies between two applications.

A database index is automatically created on theForeignKey. You candisable this by settingdb_index toFalse. You may want toavoid the overhead of an index if you are creating a foreign key forconsistency rather than joins, or if you will be creating an alternative indexlike a partial or multiple column index.

ManyToManyField¶

classManyToManyField(to,**options)[source]¶

A many-to-many relationship. Requires a positional argument: the class towhich the model is related, which works exactly the same as it does forForeignKey, includingrecursive andlazy relationships.

Related objects can be added, removed, or created with the field’sRelatedManager.

OneToOneField¶

classOneToOneField(to,on_delete,parent_link=False,**options)[source]¶

A one-to-one relationship. Conceptually, this is similar to aForeignKey withunique=True, but the“reverse” side of the relation will directly return a single object.

This is most useful as the primary key of a model which “extends”another model in some way;Multi-table inheritance isimplemented by adding an implicit one-to-one relation from the childmodel to the parent model, for example.

One positional argument is required: the class to which the model will berelated. This works exactly the same as it does forForeignKey,including all the options regardingrecursiveandlazy relationships.

If you do not specify therelated_name argument fortheOneToOneField, Django will use the lower-case name of the current modelas default value.

With the following example:

fromdjango.confimportsettingsfromdjango.dbimportmodelsclassMySpecialUser(models.Model):user=models.OneToOneField(settings.AUTH_USER_MODEL,on_delete=models.CASCADE,)supervisor=models.OneToOneField(settings.AUTH_USER_MODEL,on_delete=models.CASCADE,related_name='supervisor_of',)

your resultingUser model will have the following attributes:

>>>user=User.objects.get(pk=1)>>>hasattr(user,'myspecialuser')True>>>hasattr(user,'supervisor_of')True

ADoesNotExist exception is raised when accessing the reverse relationshipif an entry in the related table doesn’t exist. For example, if a user doesn’thave a supervisor designated byMySpecialUser:

>>>user.supervisor_ofTraceback (most recent call last):...DoesNotExist:User matching query does not exist.

Additionally,OneToOneField accepts all of the extra argumentsaccepted byForeignKey, plus one extra argument:

OneToOneField.parent_link¶

WhenTrue and used in a model which inherits from anotherconcrete model, indicates that this field should be used as thelink back to the parent class, rather than the extraOneToOneField which would normally be implicitly created bysubclassing.

SeeOne-to-one relationships for usageexamples ofOneToOneField.