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) and SQLite 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

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

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

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

3. Define Your Models

Create db/models.jl with your model definitions.

module models
import PormG.Models

Driver = 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.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.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.Model("constructors",
    constructorid = Models.IDField(),
    name          = Models.CharField(max_length=50),
    nationality   = Models.CharField(max_length=50),
)

Result = 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
PormG.Configuration.load("db")

# 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 across both PostgreSQL and SQLite backends:

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