{"id":1629,"date":"2024-03-16T02:55:19","date_gmt":"2024-03-15T23:25:19","guid":{"rendered":"https:\/\/mshaeri.com\/blog\/?p=1629"},"modified":"2026-07-06T11:15:00","modified_gmt":"2026-07-06T21:15:00","slug":"django-best-practices-part-1","status":"publish","type":"post","link":"https:\/\/mshaeri.com\/blog\/django-best-practices-part-1\/","title":{"rendered":"Django Best Practices – Part 1, Django Models"},"content":{"rendered":"\n

Django is famous for its simplicity, flexibility, and robust features that made it a “batteries-included” framework offering comprehensive tools for web development, database operations, URL routing, HTML templating, and security. In this post and later posts (should time allow), I try to cover best practices for developing Django applications, with an emphasis on building performant, maintainable APIs, by gathering insights from authoritative sources and hands-on experience across multiple projects.<\/p>\n\n\n\n

Let’s start with Django’s ORM, which serves as cornerstone of any application. As a developer, often, we hastily code the models without considering the long-term consequences. Our rushed decisions usually lead to future complications or even data corruption. So, it’s crucial to carefully plan and design Django models to ensure a robust foundation for your application.<\/p>\n\n\n\n

This post covers some best practice advices in these topics :<\/p>\n\n\n\n

    \n
  1. Optimal number of models in Django apps<\/a><\/li>\n\n\n\n
  2. Django model inheritance<\/a><\/li>\n\n\n\n
  3. Denormalization in django model<\/a><\/li>\n\n\n\n
  4. Django Custom managers<\/a><\/li>\n\n\n\n
  5. Empty values in Django char based fields<\/a><\/li>\n\n\n\n
  6. Django model migrations consolidation<\/a><\/li>\n\n\n\n
  7. Unique uuid identifier in Django model<\/a><\/li>\n\n\n\n
  8. Django ORM advanced query tools<\/a><\/li>\n\n\n\n
  9. Django model pk property for primary key fields<\/a><\/li>\n\n\n\n
  10. Django model naming<\/a><\/li>\n\n\n\n
  11. Update existing record in DB using Model.save()<\/a><\/li>\n\n\n\n
  12. Avoid count() when it isn’t necessary <\/a><\/li>\n\n\n\n
  13. Avoid unique foreign Key relation<\/a><\/li>\n\n\n\n
  14. Order querysets in model level<\/a><\/li>\n\n\n\n
  15. Use select_for_update wisely<\/a><\/li>\n\n\n\n
  16. Keep Business Logic Inside the Model<\/a><\/li>\n\n\n\n
  17. Enforce Data Consistency at the Database Level<\/a><\/li>\n<\/ol>\n\n\n\n

    1. Keep Number Of Models In Apps No MoreThan 10<\/h2>\n\n\n\n

    If you’ve got 20 models in a single app , it’s time to slice and dice the app into smaller ones. To keep things manageable and avoid overloading, keep number of models no more than ten models per app. Using bounded context principles in Domain-Driven Design (DDD) can help in organizing separate apps and grouping related models.<\/p>\n\n\n

    \n
    \"Break<\/a>
    Break down the app to keep models number no more than 10<\/figcaption><\/figure><\/div>\n\n\n

    <\/p>\n\n\n\n

    2. Don’t Use Multi Table Inheritance<\/h2>\n\n\n\n

    It’s a good practice to have base model. Typically, fields such as ‘created_at’ and ‘updated_at’ are ideal for go into the BaseModel. But, you should avoid using multi-table inheritance<\/strong>, because it leads to confusion and significant overhead. For each query on child it equires to join on parent model. Instead, opt for OneToOneFields<\/strong> and ForeignKeys<\/strong>. Multi-table inheritance does nothing but making troubles. In other word, in Django, subclassing creates new tables and involves numerous left joins, which can hamper performance, especially in high-demand environments like game backends. To avoid this, handle inheritance manually using techniques like null<\/strong>, OneToOne<\/strong>, or Foreign key<\/strong>.<\/p>\n\n\n

    \n
    \"OneToOneFields\u00a0and\u00a0ForeignKeys<\/a>
    OneToOneFields and ForeignKeys in most cases are better option than multi table inheritance<\/figcaption><\/figure><\/div>\n\n\n

    Bad practice:<\/p>\n\n\n\n

    from django.db import models         \n\n                    \nclass Employee(models.Model):                          \n    name= models.CharField(max_length=100)         \n                            \n\nclass RegularEmployee(Employee):              \n    salary= models.IntegerField()       \n    bonus= models.IntegerField()       \n\n<\/code><\/pre>\n\n\n\n
    However, abstract models<\/strong> are still very useful. They allow you to eliminate redundant fields across multiple tables (e.g., created<\/code>, updated<\/code>, soft_delete<\/code>). An abstract model doesn\u2019t exist as a table in the database and cannot be instantiated. It simply serves as a reusable template for defining shared structure and behavior across your models:<\/p>\n\n\n\n
    class BaseModel(models.Model):\n     created = models.DateTimeField(auto_now_add=True)\n     updated = models.DateTimeField(auto_now=True)\n     soft_delete = models.BooleanField(default=False)\n     class Meta:\n         abstract = True\n\n class Product(BaseModel):\n     name= models.CharField(max_length=25)\n     company= models.CharField(max_length=25)\n     serial_number= models.CharField(max_length=25)<\/code><\/pre>\n\n\n\n
    3. Denormalization Should be The Last Solution<\/h2>\n\n\n\n
    We often see the denormalization as a first solution for challenges in our projects, unaware that it can cause complexity and increase the risk of data loss. It’s strongly recommended to consider other techniques such as caching before denormalization. Consider denormalization only when other techniques didn’t meet your needs.<\/p>\n\n\n
    \n
    \"Denormalization<\/a>
    Denormalization Should be The Last Solution<\/figcaption><\/figure><\/div>\n\n\n
    4. Use Managers For Custom DB Queries<\/h2>\n\n\n\n
    Django model manager provides a convenient mechanism for encapsulating complex query logic related to a model. Try to place frequently used operations associated with a particular model in the custom manager to have reusable code as well as improved code organization and readability. In the following example the get_published_posts()<\/code> method filters blog posts with a status of \u201cpublished\u201d. We can use this method wherever we need to retrieve published posts, keeping our code DRY.<\/p>\n\n\n\n
    from django.db import models\nclass PostManager(models.Manager):\n     def get_published_posts(self):\n         \"\"\"Retrieve all published blog posts.\"\"\"\n         return self.filter(status='published')\n\nclass BlogPost(models.Model):\n     title = models.CharField(max_length=200)\n     content = models.TextField()\n     status = models.CharField(max_length=10, choices=[('draft', 'Draft'), ('published', 'Published')])\n\n     objects = PostManager()\n\n # Usage:\n published_posts = BlogPost.objects.get_published_posts()<\/code><\/pre>\n\n\n\n
    The Manager method should be dedicated to database-related tasks. Take, for example, the Manager method below, which filters product records based on their numeric serial number using their display serial number that starts with ‘SN’:<\/p>\n\n\n\n
    class DeviceManager(models.Manager):\n    def get_by_display_serial_number(display_serial_number:str):\n        numeric_serial_number = int(display_serial_number[2:])\n        products = Products.objects.filter(serial_number= numeric_serial_number)\n        return products<\/code><\/pre>\n\n\n\n
    This approach falls short in terms of code clarity and single responsibility principle. It’s not a specialized database query or a complex operation; rather, it merely involves manipulating the input parameter, which is none of Manager method’s business. A more effective and cleaner approach would be creating a simple helper method to convert the display serial number to the numeric serial number, followed by querying it using Django’s model filter:<\/p>\n\n\n\n
    def get_numeric_serial_number(display_serial_number:str) -> int:\n    return int(display_serial_number[2:])\n\ndef some_service_or_view():\n   ...\n   numeric_serial_number = get_numeric_serial_number(display_serial_number)\n   products = Product.objects.filter(serial_number=numeric_serial_number)<\/code><\/pre>\n\n\n\n
    By segregating the conversion logic into a separate function, the code becomes more modular and comprehensible. This way, the purpose of each function is distinct, adhering to the single responsibility principle, that improves maintainability and readability. <\/p>\n\n\n\n
    5. Avoid null=True For Char Fields<\/h2>\n\n\n\n
    Allowing both NULL<\/code> <\/strong>and empty values <\/strong>in string-based fields is generally discouraged because it’s against data consistency. Allowing null <\/strong>values in such fields results in two possible representations for absence of data: NULL or an empty string<\/strong>. To maintain clarity and consistency, Django conventionally favors the use of an empty string<\/strong> to represent absence of data.<\/p>\n\n\n\n
    Bad practice:<\/p>\n\n\n\n
    from django.db import models\n\n\nclass Person(models.Model):\n    name = models.CharField(max_length=150, null=True, blank=True)\n<\/code><\/pre>\n\n\n\n
    Best Practice:<\/p>\n\n\n\n
    from django.db import models\n\n\nclass Person(models.Model):\n    name = models.CharField(max_length=150, blank=True)\n<\/code><\/pre>\n\n\n\n
    However, there is an exception to this guideline when the field is declared with unique=True<\/strong>. In such cases, two empty strings<\/strong> is considered as duplication, so you should change it to null=True<\/strong> instead of blank=True<\/strong>.<\/p>\n\n\n\n
    String-based fields includes:<\/p>\n\n\n\n
      \n
    • CharField<\/li>\n\n\n\n
    • TextField<\/li>\n\n\n\n
    • EmailField<\/li>\n\n\n\n
    • URLField<\/li>\n\n\n\n
    • SlugField<\/li>\n\n\n\n
    • FilePathField<\/li>\n\n\n\n
    • URLField (Repeated mention)<\/li>\n<\/ul>\n\n\n\n
      6. Consolidate Migrations for Cleaner Release<\/h2>\n\n\n\n
      We may have more than on changes in models in a release. Consolidating all migrations into a single file for each app in each release simplifies the management and deployment of database schema changes. This approach bring a cleaner release process and reduces the risk of migration related issues. You can use Django squashmigrations <\/strong>to bring specific generated migrations to heel:<\/p>\n\n\n\n
      python manage.py squashmigrations <appname> <squashfrom> <squashto><\/code><\/code><\/pre>\n\n\n\n
      <\/p>\n\n\n\n
      7. Use Two Unique Identifiers For Your Models\u200a :<\/h2>\n\n\n\n
      In real world project, use two identifiers for records in a Django model, a private identifier, often the primary key (id<\/code>), and a public ID, represented by a UUID (UID). This approach offers both security and convenience, as it prevents revealing sensitive information about the data while still allowing for unique identification of records. Maintaining enumerators as private is always advisable as they reveal sensitive information about our data, such as the number of records ( e.g. products or accounts) we have, which we prefer to keep confidential:<\/p>\n\n\n\n
      import uuid\nfrom django.db import models\n\n class YourModel(models.Model):\n     id = models.AutoField(primary_key=True)\n     uid = models.UUIDField(default=uuid.uuid4, editable=False, unique=True) \n     name = models.CharField(max_length=100) \n     description = models.TextField() \n\n     def __str__(self):     \n         return f'{self.name} - {self.uid}'<\/code><\/pre>\n\n\n\n
      Don’t use UUID as primary key. <\/mark><\/strong>The issue with UUID as primary key is the inefficiency in inserts due to the non-sequential nature of UUIDs. Because the primary key is often a clustered index by default in majority of databases. It means, databases need to resort physical storage when inserting new ID with lower ordinality. With UUID it will happen almost all the time. This can lead to significant delays in inserting new records, taking seconds or even minutes as the database grows.<\/mark><\/p>\n\n\n\n
      8. Use Advanced Query Tools Instead Of Processing Records In Python<\/h2>\n\n\n\n
      Instead of working with data in Python, let Django’s advanced query tools handle this task for you. By doing this, we can not only enhance performance but also achieve cleaner and more maintainable code.  Let’s elaborate this concept with an example. Assume we need to have a list of all students whose Math scores are more than their English scores. Without Django ORM query expressions, it can be done with following code :<\/p>\n\n\n\n
      from models.students import Student\nstudents = []\nfor student in Student.objects.iterator():\n    if student.math_score > student.english_score:\n        students.append(student)<\/code><\/pre>\n\n\n\n
      The above code iterating through every Student record in the database using Python, one by one. It’s slow, memory consuming, and potentially leading to race conditions. Race conditions may arise when the script is executed concurrently with other user interactions with the same data. A more efficient and race-condition free approach is to use Django query expressions:<\/p>\n\n\n\n
      from django.db.models import F\nfrom models.students import Student\nstudents = Student.objects.filter(math_score__gt=F('english_score'))<\/code><\/pre>\n\n\n\n
      This way, we leverage the database itself to perform the comparison, enhancing project performance and stability.<\/p>\n\n\n\n
      9. Use pk instead of id<\/h2>\n\n\n\n
      In Django, the id<\/code> <\/strong>field is the default primary key, automatically generating a unique integer for each database record. The pk<\/code> <\/strong>property, however, refers to the model’s designated primary key field, whether it’s id<\/code><\/strong>, student_id<\/code><\/strong>, or something else. Using pk<\/code><\/strong> throughout your code offers flexibility, allowing you to change the primary key field without modifying your code. This makes your code more readable, self-explanatory, and consistent, regardless of the primary key’s name.<\/p>\n\n\n\n
      Example 1 \u2013 Using id:<\/strong><\/p>\n\n\n\n
      student = Student.objects.get(id=42)\nprint(student.id)<\/code><\/pre>\n\n\n\n
      Example 2 \u2013 Using pk:<\/strong><\/p>\n\n\n\n
      student = Student.objects.get(pk=42)\nprint(student.pk)<\/code><\/pre>\n\n\n\n
      I compared the performance of pk<\/code><\/strong> against id<\/code> <\/strong>in a queryset filtering and retrieval operation with 100,000 sample records. The operation time increased by only 8% in 100,000 retrieve operations, a small trade-off for the benefits of readability and consistency.<\/p>\n\n\n\n
      10. Django Model Naming<\/h2>\n\n\n\n
        \n
      • Model names should use singular nouns to represent individual entities. This helps clarify the relationships between models and minimizes potential confusion.<\/li>\n\n\n\n
      • Django models use CamelCase, a Python-based convention where each word in the name starts with an uppercase letter and no underscores are included.<\/li>\n\n\n\n
      • A ManyToManyField<\/strong> should be named with a plural noun that reflects the associated model. For example, if an Author<\/strong> model has a ManyToManyField <\/strong>linked to a Book<\/strong> model, the field might be called “books.” A OneToOneField<\/strong> should use a singular noun that mirrors the related model, showing a one-to-one relationship. For instance, a User<\/strong> model could have a one-to-one link with a Profile<\/strong> model, with the field named “profile.”<\/li>\n<\/ul>\n\n\n\n
        11. Use update_fields<\/code> with save()<\/code><\/h3>\n\n\n\n
        To update specific columns in a database record, it is better to use the update_fields<\/code> parameter when calling the save()<\/code> method. This approach allows you to specify precisely which fields should be updated.<\/p>\n\n\n\n
        product = Product.objects.get(id=1)\nproduct.name = \"new product name\"\nproduct.save(update_fields=['name'])<\/code><\/pre>\n\n\n\n
        The resulting SQL query will be:<\/p>\n\n\n\n
        UPDATE \"product\"\nSET    \"name\" = 'new product name'\nWHERE  \"product\".\"id\" = 1<\/code><\/pre>\n\n\n\n
        You can also update multiple fields at once by including additional field names in the update_fields<\/code> list.<\/p>\n\n\n\n
        Using this method is more efficient because it limits the database operation to only the specified fields, reducing unnecessary overhead and improving performance.  Another key reason to use update_fields<\/code> is to prevent data conflicts during concurrent updates. Consider a scenario with the Product<\/code> model: if one user sets the is_deleted<\/code> flag to True<\/code> while another user changes the product’s name, and these actions happen in separate processes, using the generic save()<\/code> method can lead to issues. The second process might unintentionally overwrite the is_deleted<\/code> value back to False<\/code> because it retains the outdated value in memory.<\/p>\n\n\n\n
        While projects with high levels of concurrent data modification may require more robust conflict management strategies, using update_fields<\/code> to update only the necessary fields significantly reduces the risk of unintended side effects.<\/p>\n\n\n\n
        12. Avoid count() when it is not necessary<\/h2>\n\n\n\n
        Database counts are slow. Avoid using count if it’s not necessary.  A common usage of count is cases where you only need to check if any results exist. In this case using queryset.count()<\/code> is less efficient than queryset.exists()<\/code>. The example below demonstrates a more efficient and readable approach:<\/p>\n\n\n\n
        from models import Hound  \n\nqueryset = Hound.objects.filter(pk=1)  \n\nif queryset.exists():  \n    return \"Run away!\"  \nelse:  \n    return \"The coast is clear\"  \n<\/code><\/pre>\n\n\n\n
        In contrast, the following approach using queryset.count()<\/code> is both harder to read and less efficient:<\/p>\n\n\n\n
        from models import Hound\n queryset = Hound.objects.filter(pk=1)\n if queryset.count() > 0:  # Unnecessary counting of all rows\n     return \"Run away!\"\n else:\n     return \"The coast is clear\"<\/code><\/pre>\n\n\n\n
        According to the Django documentation, you should use queryset.count()<\/code> when you need the exact number of results, and queryset.exists()<\/code> when you only need to determine if at least one result exists.<\/p>\n\n\n\n
        This distinction is crucial because queryset.count()<\/code> triggers an SQL query that scans all rows in the database table to calculate the total count. In contrast, queryset.exists()<\/code> optimizes the query by only checking for the presence of a single record, avoiding unnecessary overhead. It achieves this by:<\/p>\n\n\n\n
          \n
        • Removing ordering.<\/li>\n\n\n\n
        • Removing grouping.<\/li>\n\n\n\n
        • Clearing any developer-defined select_related<\/code> or distinct<\/code> clauses in the queryset.<\/li>\n<\/ul>\n\n\n\n
          Note that, worse than using count()<\/code> method, is checking if a queryset <\/strong>contains data like this:<\/p>\n\n\n\n
          if queryset:\n   # do smothing<\/code><\/pre>\n\n\n\n
          QuerySets in Django are lazy<\/strong>, evaluating them in a boolean context triggers a database query, which can lead to performance overhead<\/strong>.<\/p>\n\n\n\n
          13. Avoid Unique Foreign Key relation<\/h2>\n\n\n\n
          A one-to-one relationship<\/strong> links one record in a model to exactly one record in another. Instead of using ForeignKey(unique=True)<\/code>, which is less idiomatic, Django provides a more appropriate solution: OneToOneField<\/code>.<\/p>\n\n\n\n
          Example:<\/strong><\/h3>\n\n\n\n
          \u274c Avoid:<\/strong><\/p>\n\n\n\n
          from django.contrib.auth.models import User\nfrom django.db import models\n\n class Profile(models.Model):\n     user = models.ForeignKey(User, unique=True)<\/strong>\n     phone_number = models.CharField(max_length=15, blank=True, null=True)\n     birth_date = models.DateField(blank=True, null=True)\n     address = models.TextField(blank=True, null=True)\n \n<\/code><\/pre>\n\n\n\n
          \u2705 Use:<\/strong><\/p>\n\n\n\n
          from django.contrib.auth.models import User\nfrom django.db import models\n\n class Profile(models.Model):\n     user = models.OneToOneField(User, on_delete=models.CASCADE)<\/strong>\n     phone_number = models.CharField(max_length=15, blank=True, null=True)\n     birth_date = models.DateField(blank=True, null=True)\n     address = models.TextField(blank=True, null=True)\n \n<\/code><\/pre>\n\n\n\n
          The  OneToOneField<\/strong> field brings better readability, enforces the one-to-one constraint at the database level, and aligns with Django’s best practices.<\/p>\n\n\n\n
          14. Order Queryset at the Model Level<\/h3>\n\n\n\n
          If a model is supposed to be sorted in the majority of cases \u2014 for example, in list views, API endpoints, or admin pages \u2014 it’s a good practice to define a default ordering in the model\u2019s Meta<\/code> class:<\/p>\n\n\n\n
          class Product(models.Model):\n    name = models.CharField(max_length=255)\n    created_at = models.DateTimeField(auto_now_add=True)\n\n    class Meta:\n        ordering = ['-created_at']\n<\/code><\/pre>\n\n\n\n
          This ensures consistent ordering across your project without the need to explicitly add .order_by()<\/code> in every query. In other word, it helps avoid situations where developers forget to add .order_by()<\/code> in new queries leading to inconsistent or unexpected results especially during pagination.<\/p>\n\n\n\n
          Note that, this should only be applied when it really<\/em> makes sense \u2014 i.e., when most of your queries and views rely on a particular ordering.<\/p>\n\n\n\n
          15. Use select_for_update<\/code> Wisely<\/h3>\n\n\n\n
          When using select_for_update<\/strong><\/code>, it’s crucial to understand how it interacts with related models, especially when combined with select_related<\/strong><\/code>. While select_for_update<\/code> <\/strong>is an excellent way to prevent race conditions by locking rows for update, it can have unintended consequences if you’re not careful.<\/p>\n\n\n\n
          If you use select_for_update<\/code> <\/strong>in conjunction with select_related<\/strong><\/code>, Django will lock not only the rows from the base queryset model but also the rows from the related models fetched through select_related<\/strong><\/code>. This behavior can unintentionally escalate the scope of database locks and potentially lead to contention or even deadlocks.<\/p>\n\n\n\n
          Best Practice<\/strong>
          Be explicit about which related models you include in select_related<\/code> <\/strong>when using select_for_update<\/strong><\/code>. Only include the models you truly intend to lock. Avoid doing select_for_update<\/strong><\/code><\/strong>()<\/code> without arguments in such cases, as it may cause broader locking than needed.<\/p>\n\n\n\n
          # \u274c This may lock more than you expect\nBook.objects.select_related(\"author\",\"category\").select_for_update().get(pk=1)\n\n# \u2705 Better: explicitly state the relation you want to lock\nBook.objects.select_related(\"author\").select_for_update(of=('self',)).get(pk=1)\n# Note that self is a special keyword referring to queryset's model\n# which here is Book\n<\/code><\/pre>\n\n\n\n
          <\/p>\n\n\n\n
          <\/p>\n\n\n\n
          <\/p>\n\n\n\n
          The later queryset avoids locking other tables unnecessarily, leading to safer concurrency handling. It’s recommended to always explicitly mention the tables to lock even if you don’t have select_related <\/strong><\/code>at this moment, because you might have in the future.<\/p>\n\n\n\n
          16. Keep Business Logic Inside the Model<\/h2>\n\n\n\n
          One important principle when working with Django models is this: keep model-related business logic inside the model itself whenever possible.<\/strong> A common mistake is scattering model behavior across API views, serializers, forms, signals, or service functions. For example, generating a serial number for a new Device<\/code> should not happen inside the API endpoint that creates the device. The model itself should own that responsibility.<\/p>\n\n\n\n
          By placing this logic in the model layer, every piece of code that creates a Device<\/code> automatically follows the same rules, whether it comes from the Django admin, a management command, a Celery task, an API endpoint, or a test case. This improves consistency and significantly reduces the chance of bugs caused by duplicated or missing logic.<\/p>\n\n\n\n
          Following this rule aligns well with several software engineering principles:<\/p>\n\n\n\n