PormG.jl Documentation

PormG.jl is a Django-inspired ORM for Julia, built with an async-first architecture for high-concurrency web frameworks. It brings the expressive power of Django's query builder to Julia while leveraging Julia's performance and type system.

Why PormG?

Installation

PormG is currently in early development and is not yet registered in the Julia General Registry. Install the development version using the Julia package manager:

using Pkg
Pkg.add(url="https://github.com/PingoLee/PormG.jl")

Or develop locally:

using Pkg
Pkg.develop(url="https://github.com/PingoLee/PormG.jl")

Install a database driver

PormG does not pull in a SQL driver automatically — LibPQ (PostgreSQL), SQLite and MySQL are weak dependencies, so each app installs and loads the one it uses as a direct dependency:

using Pkg
Pkg.add("LibPQ")     # PostgreSQL backend
Pkg.add("SQLite")    # SQLite backend
Pkg.add("MySQL")     # MySQL backend (MySQL 8.4 or newer)

PostgreSQL can also run on the pure-Julia Postgres.jl driver, as an opt-in: install Postgres, load it with using PormG, Postgres, and set postgres_driver: Postgres — see Choosing the PostgreSQL driver.

Load the driver alongside PormG (using PormG, LibPQ, using PormG, SQLite or using PormG, MySQL). A bare using PormG loads the ORM but no backend, so Configuration.load raises a clear error (MissingConfigurationError) telling you which driver to load:

PormG: the PostgreSQL backend requires LibPQ. Run `using LibPQ` (or `using PormG, LibPQ`) so the PostgreSQL extension loads.

DataFrames is your app's dependency

PormG depends on neither DataFrames nor CSV (#1344). A query is a Tables.jl table (A query is a Tables.jl table), and the bulk writers take any Tables.jl table (Bulk Operations). To build or read a DataFrame, add the package to your app (Pkg.add("DataFrames")) and load it, as the examples in these docs do with using DataFrames.

Quick Start

1. Initialize Your Project

using PormG
PormG.setup() # Interactive setup for database and models

This creates a db/ folder with a connection.yml template and a models.jl skeleton.

2. Configure the Database Connection

Open db/connection.yml and configure your database:

default_env: dev

dev:
  adapter: PostgreSQL
  database: your_database_name
  host: 'localhost'
  username: your_username
  password: your_password
  port: 5432
  config:
    change_db: true      # create the database if it doesn't exist
    change_data: true    # allow data modifications
    time_zone: 'America/Sao_Paulo'

For SQLite, use:

default_env: dev

dev:
  adapter: SQLite
  database: 'my_app.db'
  config:
    change_db: true      # allow schema migrations
    change_data: true    # allow data mutations

For MySQL, see Using MySQL.

3. Define Your Models

Create db/models.jl with your model definitions.

module models
import PormG.Models

Driver::Models.ModelType = Models.Model("drivers",
    driverid    = Models.IDField(),
    forename    = Models.CharField(max_length=50),
    surname     = Models.CharField(max_length=50),
    nationality = Models.CharField(max_length=50),
    dob         = Models.DateField(null=true),
)

Circuit::Models.ModelType = Models.Model("circuits",
    circuitid   = Models.IDField(),
    name        = Models.CharField(max_length=100),
    location    = Models.CharField(max_length=100),
    country     = Models.CharField(max_length=100),
)

Race::Models.ModelType = Models.Model("races",
    raceid      = Models.IDField(),
    name        = Models.CharField(max_length=255),
    year        = Models.IntegerField(),
    date        = Models.DateField(),
    circuitid   = Models.ForeignKey(Circuit, pk_field="circuitid", on_delete="CASCADE"),
)

Constructor::Models.ModelType = Models.Model("constructors",
    constructorid = Models.IDField(),
    name          = Models.CharField(max_length=50),
    nationality   = Models.CharField(max_length=50),
)

Result::Models.ModelType = Models.Model("results",
    resultid      = Models.IDField(),
    raceid        = Models.ForeignKey(Race, pk_field="raceid", on_delete="CASCADE"),
    driverid      = Models.ForeignKey(Driver, pk_field="driverid", on_delete="RESTRICT"),
    constructorid = Models.ForeignKey(Constructor, pk_field="constructorid", on_delete="RESTRICT"),
    positionorder = Models.IntegerField(),
    points        = Models.FloatField(),
)

end

4. Load Configuration and Import Models

using PormG, LibPQ, DataFrames   # LibPQ → PostgreSQL; use SQLite instead if your adapter is SQLite

# Load configuration — must happen BEFORE importing models. Outside a REPL the environment is
# stated: `env =` here, or the PORMG_ENV variable.
PormG.Configuration.load("db"; env = "dev")

# Import models with hot-reload support (Revise.jl)
PormG.@import_models "db/models.jl" models
import .models as M

5. Create and Apply Migrations

PormG.Migrations.makemigrations("db")   # Analyze models and generate migration
PormG.Migrations.migrate("db")          # Apply migration to database

6. Create Records

# Single record creation
M.Driver.objects.create(
    "forename" => "Ayrton",
    "surname"  => "Senna",
    "nationality" => "Brazilian"
)

# Bulk insert for multiple records
bulk_data = DataFrame([
    Dict("forename" => "Alain",  "surname" => "Prost",    "nationality" => "French"),
    Dict("forename" => "Nelson", "surname" => "Piquet",   "nationality" => "Brazilian"),
])
# We call bulk_insert on the .objects handler to respect the ORM boundary
bulk_insert(M.Driver.objects, bulk_data)

7. Query Your Data

using PormG: F
using PormG.Functions: Count

# Simple filter and list
drivers = M.Driver.objects.filter("nationality" => "Brazilian").order_by("surname").list()

# Chainable methods with DataFrame output (query fields in the case they were declared;
# the F1 models use lowercase, so the paths below are lowercase)
df = M.Result.objects.filter(
        "driverid__nationality" => "Brazilian",
        "positionorder"         => 1
    ).values(
        "driverid__forename",
        "driverid__surname",
        "raceid__year",
    ).order_by("-raceid__year") |> DataFrame

# Aggregations
df = M.Result.objects.filter(
        "positionorder" => 1
    ).values(
        "constructorid__name",
        "wins" => Count("resultid")
    ).order_by("-wins") |> DataFrame

# ✓ CORRECT: Trailing dot or inline
df = M.Driver.objects.
    filter("nationality" => "Brazilian").
    list()

# ✗ INCORRECT (ParseError): Leading dot
df = M.Driver.objects
    .filter("nationality" => "Brazilian")
    .list()

8. Update and Delete

# Update matching records
M.Driver.objects.filter("nationality" => "Brazilian").update("nationality" => "Brazil")

# Atomic update with F-expression (no read-modify-write race)
M.Result.objects.filter("resultid" => 1).update("points" => F("points") + 10)

# Delete matching records
M.Driver.objects.filter("surname" => "TestDriver").delete()

Django Data-Type & Compatibility Contract

PormG is designed to be fully wire-format compatible with tables managed by Django. It guarantees identical column serialization and mutation semantics on the PostgreSQL and SQLite backends. On MySQL, a DateTimeField is DATETIME(3), so a Django DATETIME(6) column holding sub-millisecond digits raises InvalidValueError when read (MySQL Guide):

• TIMESTAMPTZ Contract: Naive DateTime values are treated as UTC, while timezone-aware ZonedDateTime values preserve the exact UTC instant across backends. (SQLite stores ISO 8601 strings and normalizes on read).
• DateField Truncation: Temporal inputs like DateTime or ZonedDateTime are automatically truncated to their calendar date portion when saved into a DateField, matching Django's silent truncation behavior instead of throwing errors.
• DecimalField Precision: Underpinned by NUMERIC types, DecimalField(max_digits, decimal_places) prevents float drift in round-trips (e.g. 99.99 is retrieved precisely as 99.99 in Decimals.Decimal format). .list(:json) carries that out rather than narrowing it: the column serializes as a JSON number holding the digits the value has, not re-rounded through a Float64. On SQLite the guarantee is bounded by the engine — NUMERIC affinity converts on write and keeps fifteen significant digits exactly — so PormG refuses a DecimalField wider than max_digits = 15 there (makemigrations raises BackendCapabilityError) instead of creating a column that would silently round, and reads every column it does create back as a Decimals.Decimal too; see Serializing rows to JSON.
• Auto Temporal Fields:
  • auto_now_add=true: Automatically populated with the transaction's timezone-aware timestamp upon INSERT, then frozen during subsequent updates.
  • auto_now=true: Automatically populated upon INSERT and refreshed with the system timestamp on every UPDATE.

Architecture Overview

PormG is structured into five distinct, decoupled layers, ensuring a clean separation of concerns, high-performance execution, and cross-database dialect compatibility:

Documentation Guide

This documentation is organized into the following sections:

Database Example: Formula 1

The examples throughout this documentation use the Formula 1 World Championship dataset (Kaggle). This provides a real-world schema with multiple related tables (Driver, Race, Circuit, Constructor, Result, Status), making it ideal for demonstrating joins, aggregations, and complex queries.

# Example: Find all Brazilian race winners with circuit information
df = M.Result.objects.filter(
        "driverid__nationality" => "Brazilian",
        "positionorder"         => 1,
    ).values(
        "driverid__forename",
        "driverid__surname",
        "raceid__name",
        "raceid__circuitid__name",
        "raceid__year",
    ).order_by("-raceid__year") |> DataFrame

Contributing

Contributions to PormG are welcome! Please see the Contributing & Debugging page for the development workflow, testing conventions, and how to use @pormg_debug breakpoints.

License

PormG is licensed under the MIT License. See the LICENSE file for details.