Importing Django Models to PormG

This tutorial provides a guide on how to migrate Django models to PormG using the import_models_from_django function.

Overview

The import_models_from_django function allows you to seamlessly convert Django model definitions from Python models.py files into PormG-compatible Julia models. This is particularly useful when:

• Migrating existing Django projects to Julia
• Maintaining consistency between Django and Julia models
• Quickly prototyping Julia models based on existing Django schemas
• Converting legacy Django models for use in Julia applications
• Creating an ETL pipeline for data processing in Julia from an existing Django application

Function Signature

Two arities: one models.py, or a whole multi-app project.

# one app
import_models_from_django(
    model_py_string::String;
    db::String = DB_PATH,
    force_replace::Bool = false,
    file::String = "automatic_models.jl",
    output_path::Union{Nothing, String} = nothing,
    django_prefix::Union{Nothing, String, Missing} = missing,
    auth_user_model::Union{Nothing, String} = nothing,
    strict_relations::Bool = false,
    strict_fields::Bool = false,
    binding_overrides::AbstractDict = Dict{String, String}(),
    autofields_ignore::Vector{String} = ["Manager"],
    parameters_ignore::Vector{String} = ["help_text"]
)

# a project — "<app_label>" => "<models.py path or source>" pairs
import_models_from_django(
    apps::AbstractVector{<:Pair};
    db::String = DB_PATH,
    force_replace::Bool = false,
    file::String = "automatic_models.jl",
    output_path::Union{Nothing, String} = nothing,
    auth_user_model::Union{Nothing, String} = nothing,
    strict_relations::Bool = false,
    strict_fields::Bool = false,
    binding_overrides::AbstractDict = Dict{String, String}(),
    autofields_ignore::Vector{String} = ["Manager"],
    parameters_ignore::Vector{String} = ["help_text"]
)

See Importing a multi-app project for the second form.

Basic Usage

Step 1: Prepare Your Django Models File

Ensure your Django models.py file follows standard Django conventions:

# models.py
from django.db import models
from django.contrib.auth.models import AbstractUser

class Category(models.Model):
    name = models.CharField(max_length=100, unique=True)
    description = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

class User(AbstractUser):
    email = models.EmailField(unique=True)
    bio = models.TextField(max_length=500, blank=True)
    birth_date = models.DateField(null=True, blank=True)

class Product(models.Model):
    name = models.CharField(max_length=200)
    category = models.ForeignKey(Category, on_delete=models.CASCADE)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    is_active = models.BooleanField(default=True)
    created_by = models.ForeignKey(User, on_delete=models.SET_NULL, null=True)

Step 2: Import Using File Path

using PormG.Migrations

import_models_from_django("/path/to/your/models.py")

Parameters Explained

Required Parameters

• model_py_string::String: The content of your Django models.py file. Can be:
  • File path to your models.py file
  • String content of the models file
  • Output from django_to_string(path)

Optional Parameters

• db::String: Database configuration key (default: DB_PATH)

  import_models_from_django(content, db="production")

• force_replace::Bool: Overwrite existing model files (default: false)

  import_models_from_django(content, force_replace=true)

• file::String: Output filename (default: "automatic_models.jl")

  import_models_from_django(content, file="my_models.jl")

• autofields_ignore::Vector{String}: Field types to ignore, named the way the models.py spells them (default: ["Manager"])

  import_models_from_django(content, autofields_ignore=["Manager", "CustomManager"])

  A dropped field still claims its column name. Dropping id = models.CharField(max_length=10) does not hand the name back to Django's implicit id: substituting a BIGINT auto-increment key there would mis-type the one column every query reads, so the model comes out with no key and a # PormG: marker saying why. If every column of a class is dropped this way the import raises, naming the list you passed — a model with no column cannot be emitted.

• parameters_ignore::Vector{String}: Field parameters to ignore (default: ["help_text"]). The list you pass replaces the default rather than adding to it, so repeat "help_text" if you still want it ignored:

  import_models_from_django(content, parameters_ignore=["help_text", "verbose_name"])

• output_path::Union{Nothing, String}: Directory to write the generated file into, overriding the resolved config's db_def_folder (default: nothing). Use it to stage a foreign Django app's models.py next to its own copy while still resolving db for the connection Settings.

• django_prefix::Union{Nothing, String, Missing}: The Django app label whose tables are being imported (default: missing). missing inherits the resolved config's django_prefix; nothing imports unprefixed; a String forces that label. See The app prefix below.

  # A foreign app staged in db_garage/, written to its own folder with its own label:
  import_models_from_django("db_garage/models.py"; db="db", file="garage_models.jl",
                            output_path="db_garage", django_prefix="garage", force_replace=true)

• auth_user_model::Union{Nothing, String}: which model settings.AUTH_USER_MODEL refers to, spelled the way Django spells it in settings.py (default: nothing, which auto-detects the single class inheriting AbstractUser).

  import_models_from_django(pairs; auth_user_model="access.User")

• strict_relations::Bool: false (the default) imports a relation whose target is not in this import as a plain column, with a # PormG: marker. true raises InvalidMigrationError instead. See Relation targets.

• strict_fields::Bool: false (the default) skips a field whose Django type PormG does not implement, or an ArrayField whose element PormG's ArrayField cannot hold, with a @warn and a # PormG: marker naming the field, its class and its models.py line. true raises InvalidMigrationError instead. The lenient default is not about tolerating one bad column — before it, a single unimplemented type aborted the import of every model in every app of the call. See the note under Supported Django Fields.

• binding_overrides::AbstractDict: spell a generated Julia binding differently from the derived one. See Choosing your own binding.

Neither output_path nor django_prefix mutates the shared db config: when either is set, a throwaway render-only Settings (no database connection) carries them.

Relation targets

Every ForeignKey / OneToOneField / ManyToManyField target is resolved to the Julia binding of the model it names, because that is the only thing PormG can resolve at load time — set_models looks a target up as a binding in the generated module and nothing else. Four spellings work:

An unqualified name that two apps declare is an error naming both; qualify it as Django does.

Targets outside the import

A project that touches django.contrib references models it did not hand you. Those degrade rather than fail: the column is real — Django created it — so it is imported as a plain BigIntegerField and the artifact says what was lost.

# PormG: field 'created_by_id' on 'imports.ImportBatch' — ForeignKey target
#   'contenttypes.ContentType' is not in the imported app set; imported as a plain column,
#   the relation is lost.
created_by_id = Models.BigIntegerField(blank=true, null=true)

A ManyToManyField has no column of its own, so an unresolvable one — target or through= model — is dropped and marked instead.

Pass strict_relations = true to raise InvalidMigrationError on the first such target instead. That is the right setting once you believe every app is in the import; it is not the default, because it would make the importer unusable on any project that references django.contrib.

The one target that is always a hard error is settings.AUTH_USER_MODEL when the importer cannot tell which model it is (no AbstractUser subclass, or more than one, and no auth_user_model). Nearly every model in a real project points at the user model, so one omitted keyword would quietly turn the whole user graph into integer columns.

An auto-derived ManyToManyField whose join column would contain __, PormG's lookup separator, is also dropped and marked, whatever strict_relations says: the target resolves, but PormG cannot name the column. Django names those columns from the lowercased class name: <class>_id, or from_<class>_id / to_<class>_id on a self-relation. A class whose name starts or ends with _ or contains __ therefore yields one: _Driver's self-relation gives from__driver_id. Django's own checks refuse those class names too (models.E023, models.E024). To keep the relation, declare its through model by hand:

• set its db_table to Django's join table, which the marker names when the import knows it;
• give it one ForeignKey per end, each naming the column with db_column = "from__driver_id";
• pin source_field / target_field to those keys;
• when the class that declares the ManyToManyField ends with _ or contains __, also give the field a related_name, for the reason in the next paragraph.

A ManyToManyField that already declares through= on such a class is imported, not dropped. PormG would name its key from the class name too (driver__id), so the importer pins source_field / target_field to the through model's key to each end and gives the field a related_name, as the next paragraph describes. When the through model has several keys to one end and no through_fields, the field is dropped with a marker: name the two keys with through_fields in models.py.

Django's through_fields = ("team", "driver") is read on every ManyToManyField that declares through=. It becomes source_field = "team_id", target_field = "driver_id": the through model's keys, which the importer spells <field>_id for a ForeignKey. A pin that names no foreign key to its end on the through model drops the field with a marker, because set_models would refuse it. Without through= there are no through keys to name, so through_fields is dropped with a marker, as Django refuses it too (fields.E337).

A ForeignKey, OneToOneField or through= ManyToManyField on such a class keeps its column and its relation. Only its reverse name changes. With no related_name, the reverse accessor PormG derives is the lowercased model name (driver_ for Driver_, pit__stop for Pit__stop), or <model>_<field> when the model has several relations to one target. A name that ends with _ or contains __ can never be a lookup-path segment, so set_models would refuse it. The importer writes a related_name instead and says so in a marker. The name is the derived one with __ collapsed and the trailing _ removed (driver, pit_stop, driver_home_id), with a digit added when the target already uses that name (driver2). Query the reverse side by that name:

# PormG: 'Driver_.circuit_id' is imported with related_name="driver" — the reverse accessor PormG
#   derives for it on 'Circuit', 'driver_', ends with '_', so it can never be a lookup-path segment
#   (Django refuses the class name too: models.E023). …
Driver_::Models.ModelType = Models.Model(
  circuit_id = Models.ForeignKey("Circuit", pk_field="id", on_delete=CASCADE, related_name="driver"))

Importing a multi-app project

A real Django project splits its models across apps. Pass one "<app_label>" => "<models.py>" pair per app:

import_models_from_django(
  ["racing"  => "server/racing/models.py",
   "access"  => "server/access/models.py",
   "imports" => "server/imports/models.py"];
  db = "f1", file = "models.jl", force_replace = true)

Everything lands in one generated module, and each model's table carries its own app label:

Circuit::Models.ModelType     = Models.Model(db_table = "racing_circuit",     …)
User::Models.ModelType        = Models.Model(db_table = "access_user",        …)
ImportBatch::Models.ModelType = Models.Model(db_table = "imports_importbatch",
  circuit_id = Models.ForeignKey("Circuit", pk_field="id", on_delete=CASCADE),
  steward_id = Models.ForeignKey("User", pk_field="id", on_delete=PROTECT))

Importing the apps together also merges an abstract base declared in another app — the shared core.models.TimeStampedModel shape — and resolves a TextChoices enumeration the same way.

A class from another app has to be imported, exactly as Python requires. Each app's own classes win, so a name two apps both declare resolves locally, as it does in Django; anything else is looked up through that models.py's own from … import … lines:

# imports/models.py
from core.models import TimeStampedModel        # <- this line is what makes the merge happen

class ImportBatch(TimeStampedModel):
    note = models.CharField(max_length=40)

Without the import the base is reported as unresolved and the model keeps only its own columns — which is also what Python would do, since the name would not be defined. The lookup accepts the spellings a real project uses: an alias (import TimeStampedModel as TSM), a star import, a re-export through another app, and a nested package (from apps.core.models import …).

A module path names an app when the app's own name is followed by its models module — core.models, core.models.base — or by nothing at all, the package re-exporting through its __init__.py (from core import …). The name matched is the app's label or its package directory, because Django's AppConfig.label is frequently not the directory name: "crm" => "server/customers/models.py" resolves from customers.models import … as well as from crm.models import ….

Anything written in front of that name has to be where the app actually lives. A project laid out as apps/core/ resolves from apps.core.models import …; the same import against an app at server/core/ does not, and neither does from wagtail.core.models import Page — Wagtail is not your core app, however much the path looks alike. from core.forms import SeasonTicket is refused too: a sibling module is not the models module.

A single leading dot is this app's own package and never names another app, so from .core.models import … stays local; two or more ascend, so apps/{core,shop}/ can write from ..core.models import … and have it resolve.

A django_prefix on the connection is rejected here rather than ignored. It is one value for the whole connection, and relationship accessor names strip it — so racing_circuit would become circuit while access_user survived intact, and half the project's reverse lookups would point at names that do not exist. Remove it from the connection's config; a single-app import that still wants it can pass django_prefix= to that call.

When two apps use the same class name

Both sides are app-qualified — never just the second one:

# server/racing/models.py          # server/access/models.py
class Driver(models.Model): ...    class Driver(models.Model): ...

Racing_driver::Models.ModelType = Models.Model(db_table = "racing_driver", …)   # logical name "racing_driver"
Access_driver::Models.ModelType = Models.Model(db_table = "access_driver", …)   # logical name "access_driver"

Renaming only the loser would make the output depend on the order you listed the apps, and PormG keys a model's reverse accessor on its logical name — so one Driver would answer to driver and the other to driver2, decided by list order. The rename is lossless because db_table still names the real table. A class name only one app declares is left alone.

Names that differ only in case collide too — Spectator and SPECTATOR derive different Julia bindings but the same logical name — so both are qualified on the same rule.

One residue is left, and it is reported rather than hidden: when two app-qualified names still collide (an app literally called racing_pit alongside racing's Pit), the second gets a digit suffix, and which one is second depends on the order you listed the apps. The generated file carries a # PormG: line naming what it collided with; binding_overrides picks the spelling if you care which is which.

Choosing your own binding

binding_overrides replaces the derived name for any model, collision or not:

import_models_from_django(pairs; binding_overrides = Dict("access.Driver" => "DriverLicence"))
# DriverLicence::Models.ModelType = Models.Model(db_table = "access_driver", …)   # logical name "driverlicence"

The value becomes the model's name, so the binding, the logical name and the reverse accessor all follow it, while db_table keeps naming the real table. It must be a legal, capitalized Julia identifier that no other model claims — every violation raises InvalidMigrationError rather than falling back to something else, because an override is an explicit instruction and one that silently does something different is worse than none.

The app prefix

Django names a model's table <app_label>_<lowercased class name>. PormG carries that prefix as the model's db_table, while the logical name stays the class name lowercased — left for loading to derive from the binding:

# myapp/models.py
class Pit_lane(models.Model):
    full_name = models.CharField(max_length=50)

class PitWall(models.Model):
    city = models.CharField(max_length=10)
    lanes = models.ManyToManyField(Pit_lane)

imported with django_prefix = "myapp" becomes:

Pit_lane::Models.ModelType = Models.Model(db_table = "myapp_pit_lane",
  id = Models.IDField(),
  full_name = Models.CharField(max_length=50))

PitWall::Models.ModelType = Models.Model(db_table = "myapp_pitwall",
  id = Models.IDField(),
  city = Models.CharField(max_length=10),
  lanes = Models.ManyToManyField("Pit_lane", db_table="myapp_pitwall_lanes"))

Three things to read off that output, and a fourth that shows up only when something is reported:

• The logical name is class.__name__.lower() — Django's own derivation. PitWall becomes "pitwall", with no underscore inserted, because that is what Django's table is called. Whichever class-naming convention the project uses, the derived name matches. That is also exactly what loading derives from the binding when a model has no positional name, so the importer leaves it out — the no-name form the hand-written examples use. A renamed model (a collision, binding_overrides) takes the short form too, because the new name is its binding lowercased. The one class that keeps it is a leading-underscore one (_Internal). A PormG model name never starts with _, so the importer always pins such a class's table, with or without an app label: _Internal = Models.Model("internal", db_table = "_internal", …) in an unlabelled import. The name "internal" is not what the binding _Internal derives, so it stays written. If the same import also has a plain Internal, the plain class keeps "internal" and _Internal is renamed _Internal2 with a # PormG: line, whichever class is declared first. inspectdb output always writes the name, because that file is edited by hand afterwards and a renamed binding there must not rename the model.
• The Julia binding is the class name, unchanged. It never carried the prefix, so M.Pit_lane in a consuming app is unaffected.
• An auto-derived ManyToManyField gets its join table pinned to Django's spelling, which is <the owning model's table>_<field> — so myapp_pitwall_lanes here, but f1_enrolment_legacy_crews for a class declaring Meta.db_table = "f1_enrolment_legacy". PormG's own derivation is <logical model>_<field>, which addresses a table Django never created. A db_table= written on the field is left alone, and a field with through= is skipped entirely — Django ignores db_table there, because the join table is the through model's table. Its join columns follow Django's rule too, and are pinned as source_field / target_field wherever PormG would spell them differently. A self-relation (from_driver_id / to_driver_id) is decided by name: the class the field names against the owner's class, ignoring the app label. So "self", "Driver" on Driver and "imports.Driver" on racing.Driver are self-relations, while ManyToManyField("DriverProxy") on Driver is not, because a proxy keeps its own name. Its columns are driver_id / driverproxy_id.
• Anything the importer reports names the class 'myapp.PitWall', not 'PitWall' — a django_prefix is the Django app label, so there is a label to qualify with. See Meta Options.

Without a django_prefix, no app label is known, so the models import unprefixed and there is no prefix to write into db_table. A model still gets one when the derived name would not reach its real table: an explicit Meta.db_table, a renamed model (a collision or binding_overrides), or a leading-underscore class, as described above.

Supported Django Fields

Every Django field type PormG implements is listed below, and the list is exhaustive: a models.X that is not on it has no PormG counterpart, and the note at the end of this section says what happens to it. Every entry except the three auto-key types maps by identity — same name, same column.

Text Fields

• CharField → CharField
• TextField → TextField
• EmailField → EmailField
• SlugField → SlugField
• URLField → URLField

Numeric Fields

• IntegerField → IntegerField
• PositiveIntegerField → PositiveIntegerField
• PositiveSmallIntegerField → PositiveSmallIntegerField
• BigIntegerField → BigIntegerField
• FloatField → FloatField
• DecimalField → DecimalField

Date/Time Fields

• DateField → DateField
• DateTimeField → DateTimeField
• TimeField → TimeField
• DurationField → DurationField

Boolean Fields

• BooleanField → BooleanField

Relationship Fields

• ForeignKey → ForeignKey
• OneToOneField → OneToOneField
• ManyToManyField → ManyToManyField

Special Fields

• AutoField → IDField (reported — see below)
• BigAutoField → IDField
• SmallAutoField → IDField (reported — see below) (PormG has no AutoField of its own — it was retired; see Field Types.)
• UUIDField → UUIDField
• GenericIPAddressField → GenericIPAddressField, with protocol and unpack_ipv4 (PostgreSQL only: on SQLite and MySQL, makemigrations refuses it)
• JSONField → JSONField
• BinaryField → BinaryField
• FileField → FileField
• ImageField → ImageField
• ArrayField → ArrayField, read through its element (PostgreSQL only — see below)
• SearchVectorField → SearchVectorField, bare or search.-qualified as django.contrib.postgres.search spells it (PostgreSQL only: on SQLite and MySQL, makemigrations refuses it)

from django.contrib.postgres.fields import ArrayField

class RaceStrategy(models.Model):
    tyre_compounds = ArrayField(models.CharField(max_length=10), size=8)
    pit_laps = ArrayField(models.IntegerField(), default=list)

tyre_compounds = Models.ArrayField(Models.CharField(max_length=10), size=8),
pit_laps = Models.ArrayField(Models.IntegerField(), default="{}")

class DriverCodeField(models.CharField):
    def get_prep_value(self, value):
        return value.upper() if value else value

class Driver(models.Model):
    code = DriverCodeField(max_length=3, null=True)

Field Mapping

Parameter Conversion

Django parameters are automatically converted to PormG equivalents:

Options written as a name

An option value written as a bare name — max_length=MAX_LEN, choices=STATUS_CHOICES, size=MAX_TAGS — is read as the constant it holds, when the same models.py assigns it a literal above the field, at module level or in the class body:

MAX_LEN = 10
STATUS_CHOICES = (("A", "Active"), ("I", "Inactive"))

class Driver(models.Model):
    CODE_LEN = 3
    surname = models.CharField(max_length=MAX_LEN)
    code = models.CharField(max_length=CODE_LEN)
    status = models.CharField(max_length=1, choices=STATUS_CHOICES)

imports as max_length=10, max_length=3 and the two choices. This is Python's own lookup for a class body: the class's namespace, then the module's. A name bound to another name (ALIAS = MAX_LEN) is followed. A field inherited from an abstract base reads the constants of the module the base is written in, as an enumeration does.

A name the importer cannot read as a literal is dropped and reported, never kept as text:

• a name imported from another module (from .constants import MAX_LEN) — imports are not followed, because a constants module is not part of the import. That includes a name a from … import * may have rebound;
• a name assigned only after the class, which Python would not have bound yet, or rebound later to something that is not a literal (MAX_LEN = compute()), or rebound inside an if/try block that may not have run (try: from .local_settings import MAX_LEN);
• a tuple or list built by an expression (BASE + EXTRA, a comprehension), where only a literal display is read;
• a callable such as default=uuid4.

Before this, such a value reached the schema as text: db_column=COL named a column "COL". The column survives without the option, and the # PormG: marker names the field, the class, the option and the name. Declare the option by hand if you need it. on_delete=CASCADE, a relation's to=/through=, and default=list / default=dict are symbols, not constants, and import as before.

A constant that resolves to a value the field refuses (MAX_LEN = "ten") costs that option, not the import: the field is rebuilt without it and reported, like a choices/default pair that disagrees. A field that still cannot be built stops the import with the field's own error, which names the field and the class.

Meta Options

"Reported" means two things at once: a @warn at import time and a # PormG: comment on the line above the model in the generated file. The console warning scrolls away; the comment is still there when someone reads the file six months later.

Both halves name the class app-qualified whenever an app label is known — 'imports.ImportBatch', the same "<app_label>.<Class>" spelling Django uses in a Meta reference. That is what lets a report be traced back to one model in a project where two apps declare a Spectator: the generated file holds Core_spectator and Access_spectator, and nothing called Spectator. An unlabelled single-app import — no django_prefix — has no label and nothing to disambiguate against, so it uses the bare class name.

Two things that qualification does not touch. The report names the Python class, never the Julia binding, so a model renamed by a collision or by binding_overrides is still reported under the name its models.py actually uses. And a name quoted because the source wrote it — a base class, an enum, a field — stays verbatim: only the class a report is about is qualified.

Because foreign-key fields are imported with an _id suffix (item → item_id), the importer resolves each declared member — in unique_together, constraints, indexes and index_together alike — to its imported field name automatically:

class Car_part_maker(models.Model):
    item = models.ForeignKey(Car_part, on_delete=models.CASCADE)
    maker = models.ForeignKey(Part_maker, on_delete=models.CASCADE)

    class Meta:
        unique_together = ('item', 'maker')

imports as:

Car_part_maker::Models.ModelType = Models.Model(
  id = Models.IDField(),
  item_id = Models.ForeignKey("Car_part", pk_field="id", on_delete=CASCADE),
  maker_id = Models.ForeignKey("Part_maker", pk_field="id", on_delete=CASCADE),
  constraints = [Models.UniqueConstraint(fields = ("item_id", "maker_id",))])

See Composite Uniqueness for how the constraint is materialized.

Model inheritance

A class becomes a table when its base list resolves to one — not when it matches a fixed spelling. class SeasonTicket(TimeStampedModel): is imported; so is class User(AbstractUser, SomeMixin).

A field counts toward that last rule when it is called through a model namespace: models.CharField(...), db.models.CharField(...), the fully qualified django.db.models.CharField(...), or a directly-imported bare CharField(...). A forms.CharField(...) or serializers.CharField(...) does not.

That distinction is the whole guard for a plain forms.Form or DRF serializers.Serializer — neither declares Meta.model, and their members are field-shaped, so without it both import as id-only tables that reach makemigrations as real CREATE TABLEs. Silent junk in the schema is the mirror of silent loss, and the worse of the two. One consequence worth knowing: an aliased import (from django.db import models as db_models) is not recognised, so db_models.CharField(...) does not count as a field for this rule — it only matters for a class that also has an unresolvable base and no plainly-spelled field.

Meta inheritance follows Django's rule, minus one footgun. A child that declares no Meta block at all inherits its abstract base's whole Meta. Two keys are withheld: abstract (Django resets it too), and db_table — Django does inherit that one, and the result is every child of the base pointing at a single table, so PormG refuses it and says so on each affected child.

Multi-table inheritance is refused, not approximated. For class SeasonTicket(Ticket) with a concrete Ticket, Django creates a child table whose primary key is a ticket_ptr_id one-to-one to the parent. PormG cannot express that. Merging the parent's fields would duplicate its columns; omitting them would lose the primary key. Both put a schema on disk that contradicts the live database, so the child is skipped and the generated file records why (markers are one line each; wrapped here to fit):

# PormG: model 'SeasonTicket' inherits the concrete model 'Ticket' (Django multi-table inheritance) —
#   not imported. Django keys the child table on a 'ticket_ptr_id' one-to-one to the parent, which
#   PormG cannot express.

A base in another app degrades, it does not delete. One models.py cannot see from core.models import TimeStampedModel, so the child is imported without that base's columns and says so. The walk covers abstract ancestors too — a base that is itself missing a base loses columns the same way, and it emits nothing of its own to carry the marker:

# PormG: model 'RaceReport' inherits 'TimeStampedModel', not defined in this file — any fields
#   declared there are MISSING below. Add them by hand, or pass every app of the project as
#   "<app_label>" => "<models.py>" pairs so a base in another app is merged.
RaceReport::Models.ModelType = Models.Model(
  id = Models.IDField(),
  caption = Models.CharField(max_length=80))

That is the unlabelled wording. Once the import carries an app label — a multi-app call, or a single-app one with a django_prefix — the same gap is reported as:

# PormG: model 'imports.RaceReport' inherits 'TimeStampedModel', not defined in any app of this
#   import — any fields declared there are MISSING below. Add them by hand, or add the app that
#   defines them to the pair list.

Two changes, and only the first is general: the class is app-qualified, and this particular marker also switches "this file" for "any app of this import", because with a label the advice is different. 'TimeStampedModel' stays as written either way — it is quoted from the source, not the class being reported on.

Importing the defining app alongside this one resolves it — provided this models.py really does from core.models import TimeStampedModel, which is what the lookup follows. See Importing a multi-app project.

A class with no resolvable base and no column of its own is reported, not skipped quietly. Every field it might have lives in a base the importer cannot see, so there is no evidence either way and it produces no table — but saying nothing is how a real model disappears without a trace. The marker names the module the base was imported from, which is usually all it takes to tell the two apart:

# PormG: class 'MyManager' inherits 'InheritanceManager', imported from 'model_utils.managers',
#   which nothing in this import defines, and declares no field of its own — not imported. …
# PormG: class 'SeasonTicket' inherits 'TimeStampedModel', imported from 'core.models', which nothing in
#   this import defines, and declares no field of its own — not imported. …

The first is a library and nothing is missing; the second says which app to add to the call. A base with no import line at all says that instead. A dotted base resolves when its module is an imported app's models module: class ImportBatch(core_models.TimeStampedModel) after from core import models as core_models, or class Pilot(racing.models.Driver) after import racing.models, reads exactly as the bare name would. Any other dotted base (forms.Form, serializers.Serializer) stays silent: it names a module outside the import, so it is a helper by construction, and the namespace is the same discriminator that keeps a ModelForm out of the schema.

Dropping the model instead would be the worse trade: a table that silently disappears is harder to notice than one that is present and annotated.

Choices

Both Django spellings are imported: an inline literal, and a TextChoices / IntegerChoices enumeration.

class ImportBatch(models.Model):
    class Status(models.TextChoices):
        DRAFT = "DRAFT", "Processing"
        APPLIED = "APPLIED", "Committed"
        IN_PROGRESS = "IN_PROGRESS"          # label derived: "In Progress"

    status = models.CharField(max_length=20, choices=Status.choices, default=Status.DRAFT)
    conduit = models.CharField(max_length=2, choices=(("UP", "Upload"), ("GS", "Sheets")))

imports as (fields are emitted in sorted order, so conduit precedes status):

ImportBatch::Models.ModelType = Models.Model(
  id = Models.IDField(),
  conduit = Models.CharField(max_length=2, choices=(("UP", "Upload"), ("GS", "Sheets"))),
  status = Models.CharField(max_length=20, default="DRAFT", choices=(("DRAFT", "Processing"), ("APPLIED", "Committed"), ("IN_PROGRESS", "In Progress"))))

Enumerations. An enum is found whether it is nested inside the model, declared at module level, or declared on an abstract base the model inherits. Lookup is scoped in that order, so two models may each nest a Status with different members and each resolves to its own. A nested enum can also be addressed through its owner (ImportBatch.Status.choices), as Django allows.

Scoping is per statement, in the module the statement was written in — the rule Python itself uses. This matters once an abstract base lives in a different app from the model inheriting it, because such a model's fields come from two models.py files at once:

# core/models.py
class Status(models.TextChoices):
    DRAFT = "d", "Draft"

class Base(models.Model):
    phase = models.CharField(max_length=1, choices=Status.choices)
    class Meta:
        abstract = True

# shop/models.py
from core.models import Base

class Status(models.TextChoices):      # a DIFFERENT Status
    OPEN = "o", "Open"

class SeasonTicket(Base):             # inherits `phase`
    total = models.IntegerField()

SeasonTicket.phase imports as choices=(("d", "Draft"),) — core's enumeration, because that is the module the statement was written in. shop's Status is a different name in a different namespace and never applies to it (#402).

The rule runs the other way too: a field shop declares itself cannot reach into core's module just because it inherits a base from there. Python would raise NameError — shop never imported the name — so the importer drops the option and marks it, rather than borrowing an enumeration the source never referenced.

Within one module the same ordering applies: a module-level enum outranks one nested on an abstract base, because a class body resolves a bare name against the module and never against a base class. Reach a base's enum deliberately with the qualified Base.Status.choices, which is attribute access and valid Python — addressed either by the base's own class name or by the as alias this module imported it under (CoreBase.Status.choices), since both are names your models.py actually bound. (A bare name matching only a base's nested enum is still resolved, as a convenience — Python would raise NameError there.)

The name has to be bound in the module that writes the reference — and only that. It does not have to be an as alias, and it does not have to be used as a base: from core.models import Base followed by Base.Status.choices in a class that inherits nothing resolves like any other module-level name, because that is what Python does with it.

"The module that writes the reference" is the statement's own module, not the class's. A field declared on an abstract base in core keeps resolving core's bindings when that statement is merged into a child in shop, so one statement gives one answer wherever it lands.

A name another module bound is still not resolved — shop inheriting Mixin from access does not put access's imports in shop's namespace, Python raises NameError there, and resolving it would hand a model an enumeration through a name its source never mentions (#370). The option is dropped and reported, as it is for any name the file does not define.

A module-level enum in another app follows the same rule as a base: it resolves only when the models.py that uses it imports it — alias, star import and re-export included, exactly as for a base. That gate is applied per app, so an abstract base whose own module imports its enum resolves normally when its statements are merged into a child elsewhere. Matching by name alone handed a model another app's enumeration with no marker anywhere — the wrong choices and default in the schema and nothing in the file to show it (#370).

A nested enum belongs to its owning class in its own app, so two apps may each declare a Base with its own nested Status and a child of either resolves to the right one.

The dropped row is per option, not per field: if choices=Status.choices resolves and only default=External.ACTIVE does not, the field keeps its enumeration and loses just the default. Dropping the resolvable half as well would throw away what the source did give you. The reason neither is ever passed through as a literal is that default="External.ACTIVE" against an empty choices is exactly what used to make CharField reject the field and abort the entire import.

A member's own attributes work too: Status.NEW.value resolves to the stored value, while .label and .name are display text and the member name rather than a value, so they are dropped and reported.

The same rule catches a dotted name that is not an enum at all — a module constant such as default=constants.MAX_QTY — so the diagnostic says "this file does not define" rather than naming an enumeration it cannot verify. The test is the attribute's shape: .choices, .values, .labels, .names, .value, .label, .name, or a SHOUTY_CASE member. Any other dotted default (uuid.uuid4, timezone.now, an unconventionally-spelled External.active) is kept verbatim as text, exactly as before — and reported, because an expression landing in the schema as a literal default is not something to discover later.

The same treatment reaches a default that is not dotted at all but still is not one value — a concatenation such as default='a' + 'b'. See String defaults.

A choices naming a module-level constant (choices=STATUS_CHOICES) is read when the same models.py binds it to a literal above the class; otherwise the option is dropped and reported rather than becoming an empty enumeration. See Options written as a name.

choices needs a CharField. It is the only PormG field type with a choices slot, so a Django TextField(choices=…) imports as a plain TextField with the option dropped and reported. The column is unaffected.

Both containers, both pair styles. choices may be a tuple or a list, and so may each pair — [["A", "Alpha"]] imports correctly. A comma inside a label (("APPLIED", "Committed, with caveats")) is content, not a separator. An entry that is not a (value, label) pair at all is dropped and reported, and the well-formed entries beside it survive.

A label wrapped for translation is unwrapped. ("A", _("Alpha")) — and the gettext, gettext_lazy and ugettext* spellings — imports the label Alpha, the same as a TextChoices label does. The wrapper carries no schema meaning, and leaving it on put the source text _("Alpha") into the generated file as the display string.

An entry whose value or label is not one literal is kept and reported. A concatenation, an f-string or a call in either half — ('a' + 'b', 'Labelled') — has a value PormG cannot compute, so the entry keeps the source text and earns a # PormG: marker saying exactly that:

# PormG: field 'c' on 'SeasonTicket' has a choices entry the importer cannot read as literals — kept as
#   the source text, not the value it denotes: ('a' + 'b', 'Labelled')
c = Models.CharField(max_length=20, choices=(("'a' + 'b'", "Labelled"), ("c", "Cee")))

That is a different report from the one above it, deliberately: this entry was kept, not dropped, and saying "not a (value, label) pair" about it would be a true sentence about a different problem.

Numbers are literals, so an inline [(1, "One")] earns no report — and, like a numeric enum member, it is imported as the value it denotes: [(0x1F, "Hex"), (1_000, "Thousand")] gives "31" and "1000". Carrying the source spelling instead would declare an enumeration no row can match, and would let one generated file hold two spellings of the same concept — "0x1F" from an inline list and "31" from the IntegerChoices version of it.

The field itself may be wrapped across several lines — that is what black produces, and it is read correctly. A field whose declaration the importer cannot read is reported with a warning naming the field and its source line; it is never dropped silently.

String defaults

A quoted default is imported when it is one Python string literal, and only then. Accented and non-Latin text is ordinary content and needs nothing special:

city     = models.CharField(max_length=60, default='São José')
nickname = models.CharField(max_length=60, default='Räikkönen')
city_jp  = models.CharField(max_length=60, default='日本語')

city     = Models.CharField(max_length=60, default="São José")
nickname = Models.CharField(max_length=60, default="Räikkönen")
city_jp  = Models.CharField(max_length=60, default="日本語")

Escapes. The literal's own escapes are decoded: \\, \', \", \n, \r, \t, \a, \b, \f, \v. So default='it\'s quick' imports as it's quick. The numeric and named forms — \xHH, \uXXXX, \UXXXXXXXX, \N{…} and octal \ooo — are left exactly as written, backslash included, so default='caf\u00e9' imports as the nine characters caf\u00e9 rather than as café. That boundary is deliberate: a visible escape in the generated file is something you can correct, whereas a decoder guessing wrong about surrogates or octal is silent wrong data. Write the character itself and there is nothing to decode.

One literal, or nothing. A value whose first and last characters happen to be quotes is not necessarily one string. None of these has a value PormG can compute:

ref_code   = models.TextField(default='a' + 'b')          # explicit concatenation
acronym    = models.TextField(default='it''s')            # ADJACENT literals — Python reads this as "its"
tag_line   = models.TextField(default=f'{tag_prefix}-x')  # an f-string: its value lives at runtime
filepath   = models.TextField(default=r'C:\temp')         # raw and bytes literals escape differently
block_text = models.TextField(default="""three""")         # triple-quoted

Each is kept verbatim as text and reported, the same way default=uuid.uuid4 is (markers are one line each; wrapped here to fit):

# PormG: field 'ref_code' on 'Wheelman' has `default='a' + 'b'`, which the importer cannot read as
#   one string literal — kept verbatim as text. The stored default is that source text, not the
#   value it denotes.
ref_code = Models.TextField(default="'a' + 'b'")

This matters most on CharField without choices and on TextField, the two types that accept any string: every other field type also rejects the value at construction and reports that separately.

A call is reported too. default=uuid.uuid4(), default=Decimal('0.00') and default=os.getenv('X') are values that exist only at runtime, so the source text is what gets stored — and on the two types above that string is accepted, which makes DEFAULT 'uuid.uuid4()' what a later migrate() would write:

# PormG: field 'x' on 'SeasonTicket' has `default=uuid.uuid4()`, a call the importer cannot evaluate —
#   kept verbatim as text. The stored default is that source text, not the value the call returns.
x = Models.TextField(default="uuid.uuid4()")

The bare default=uuid.uuid4 — the same name without the parentheses — is reported too, in slightly different words, because it is a different claim: a reference PormG cannot evaluate rather than a call it cannot run. The two never both fire for one value.

Note the asymmetry with choices: a translation wrapper is unwrapped in a choices label, but default=_('Blue') is reported as a call and kept verbatim. That is the same rule stated twice — a label is display text, a default is schema — and PormG will not guess at a value the column has to hold.

default=timezone.now() on a DateTimeField, DateField or TimeField is not in this category: it maps to auto_now_add=true, which is what it means. On any other field type there is no such translation, so it is reported like any other call.

n = models.CharField(max_length=60, default='line1\
line2')

Database defaults

Django's db_default takes either a literal, which Django wraps in Value(), or an expression. PormG's db_default takes only an expression, rendered verbatim into the DDL. A literal belongs in default, which PormG renders as the same DEFAULT clause. So the importer translates the option instead of copying it:

class Lap(models.Model):
    position  = models.IntegerField(default=0, db_default=0)
    status    = models.CharField(max_length=20, db_default="Finished")
    timestamp = models.DateTimeField(db_default=Now())

position  = Models.IntegerField(default=0)
status    = Models.CharField(max_length=20, default="Finished")
timestamp = Models.DateTimeField(db_default="CURRENT_TIMESTAMP")

When default and db_default differ, db_default wins. PormG takes one default per column, because its default is both rendered into the column and written by PormG's inserts. In Django, default is applied only in Python, while db_default is what the database holds. PormG's migrations compare your models with that database, so the importer keeps db_default and so converges with the column Django built. Django's default is dropped and a # PormG: comment names it:

points = models.IntegerField(default=1, db_default=0)

# PormG: field 'points' on 'Result' declares both `default=1` and `db_default=0`; PormG takes one default, so `db_default` was kept and `default` dropped. Django applies its `default` only in Python, so rows PormG writes get the database's value.
points = Models.IntegerField(default=0)

A row the Django ORM inserts without points gets 1; one PormG inserts gets 0. The two values match in the common case (default=0, db_default=0), and then nothing is reported. default=timezone.now beside db_default=Now() means the same thing twice and imports as auto_now_add=true with db_default="CURRENT_TIMESTAMP".

Automatic Additions

• Primary Key: If no primary key is defined, id = Models.IDField() is automatically added. Declaring any field primary_key=True suppresses it, as in Django — including a field named id itself, which then keeps its declared type. The addition is never a replacement: a class that declares a field named id which is not the primary key keeps that column, and no implicit id is written over it. Django rejects that shape itself (models.E004), so it can only arrive from a models.py that never passed manage.py check — the model then comes out with no primary key, reported by a @warn and a # PormG: marker, with the consequences in the warning below
• AbstractUser: For models inheriting from AbstractUser, additional fields like date_joined are added. id is not one of them: AbstractUser inherits Django's implicit id from models.Model rather than owning it, so a user model keyed on its own field — enrolment = CharField(primary_key=True) on a legacy table — has that one key and no id, like any other model

Limitations and Considerations

What survives the import

Nothing in the middle two rows is dropped in silence: each one produces a @warn at import time and a # PormG: comment in the generated file, naming the class app-qualified when a label is known (see Meta Options). That is the contract this importer holds itself to — if something did not survive, the artifact says so.

API Naming Differences from Django

PormG is inspired by Django, not a port — where an API is genuinely different, it also gets its own name rather than borrowing Django's. The one you will notice first when migrating:

bulk_insert sits beside its siblings bulk_update and bulk_copy — see Bulk Operations for the full API.

Datetime Interoperability Contract

When PormG writes into tables that are also managed by Django, timezone semantics need to be explicit.

• DateTimeField defaults are stored as Union{ZonedDateTime, DateTime, Nothing}.
• Every DateTimeField value is canonicalized to one UTC ISO-8601 string (yyyy-mm-ddTHH:MM:SS.sss+00:00) on write, bind, and filter (issue #79) — the same convention as Django USE_TZ=True. Equality/range filters return the same rows on PostgreSQL, SQLite and MySQL regardless of the input's spelling.
• A user-supplied naive Julia DateTime is serialized as UTC through the formatter path.
• A ZonedDateTime preserves the intended instant (converted to UTC for storage) and is the recommended type when the source system has a real business timezone.
• Internal auto_now and auto_now_add timestamps are generated in settings.time_zone and then canonicalized to UTC on serialization — the same instant, stored in the UTC spelling.
• If your Django app uses USE_TZ=True and TIME_ZONE = "America/Sao_Paulo", passing a plain DateTime(2026, 3, 13, 9, 0) from Julia does not mean "09:00 Sao Paulo"; it means "09:00 UTC". Use ZonedDateTime(DateTime(2026, 3, 13, 9, 0), tz"America/Sao_Paulo") when the civil timezone matters.

This will generate Julia models compatible with PormG that maintain the same structure and relationships as your original Django models.

Using Converted Models with @import_models

After converting your Django models to PormG format, load them in a script or the REPL with the @import_models macro:

using PormG, LibPQ

# The configuration first: registering models never loads it for you
PormG.Configuration.load("db"; env = "dev")

# Load the converted models
PormG.@import_models "db/models.jl" models
import .models as M

# Now you can use queries like:
# M.Product.objects.filter("price__@gt" => 100) |> DataFrame

This approach provides:

• Automatic registration of all converted models, with no manual set_models() call
• Hot-reloading during interactive development (with Revise.jl loaded)

In a package, include the models file in the module body and bind it from __init__ with PormG.Models.set_models(models, "db"; source = MODELS_FILE), as in The Bootstrap Sequence.

For more details on using models in your application, see Defining Models in PormG.