Error Handling

Every failure PormG raises for a domain problem is a subtype of PormGError, so one catch clause covers the whole surface:

try
    M.Result.objects.filter("driverid__surname" => "Senna").update("points" => 25)
catch e
    e isa PormGError || rethrow()
    @error "PormG rejected the write" msg=error_message(e) type=typeof(e)
end

rethrow() on anything that is not a PormGError matters: your own exceptions, and Julia-level misuse such as a missing keyword argument, still propagate as themselves. Only driver failures are wrapped into the taxonomy.

This page is the task-oriented view — which operation raises what, and how to react. For the full type-by-type reference, including every umbrella and the fields each type carries, see Error taxonomy in the API reference.

Which operation raises what

Catch the umbrella when you want a category, the concrete type when you want a reaction.

Reading

Between FilterError and InvalidValueError on a filter, the rule is: a value that would be bound as a parameter is refused with InvalidValueError; an argument that shapes the SQL is refused with FilterError. So a bad value — the part of a filter an end user usually supplies — is an InvalidValueError whichever check refuses it, the field's or the lookup's own (#988).

Writing

Transactions and connections

Configuration and migrations

Reading a caught error

Use error_message(e), not e.msg. Most types carry a msg field, but eight do not — they carry structured fields instead, and e.msg on those is a FieldError:

error_message renders any of them to a plain String, so it is always safe:

catch e
    e isa PormGError || rethrow()
    @error "failed" msg=error_message(e)
end

A database error is safe to show

IntegrityError, OperationalError and StatementError carry the reason the database gave as data, and their text is built from those fields alone: error_message(e), showerror and string(e) never contain the database's DETAIL, HINT or LINE n: excerpt, which quote the row. So error_message(e) is safe to return to a client (#987).

A field the driver does not report is nothing, and so is one the server did not send for that error: a unique violation names its constraint and table, a NOT NULL violation its table and column, a syntax error none of the three. The same holds for a bulk_copy that violates a constraint.

message is nothing for SQLSTATE class 22, a data exception: PostgreSQL builds that message from the input (invalid input syntax for type uuid: "<value>"), so the error states only the SQLSTATE. A value PormG binds as a parameter never appears. Text your app wrote itself still can — the message of a trigger's RAISE EXCEPTION (SQLSTATE P0001), or a literal typed into raw SQL that a syntax error quotes back.

Branch on the fields, not on the message:

catch e
    e isa IntegrityError && e.sqlstate == "23505" && return conflict(error_message(e))
    rethrow()
end

On MySQL a duplicate key and a missing parent both carry SQLSTATE 23000, and a CHECK violation HY000; tell a duplicate key by e.constraint, which only a duplicate key fills ("PRIMARY", or the unique key's name).

The driver's own exception, with the full text the server sent, is in e.cause. Log sprint(showerror, e.cause) only to a sink you trust with the row's data.

What reaches your logs

PormG's own log lines never carry the database's DETAIL or the value it refused: a driver message can quote the value, and a value can be a password or a token. When with_transaction fails it logs the classified type, the driver's exception type, the SQLSTATE and error_message(e) — the safe text above — then raises the error to you. A failed ROLLBACK is logged with the driver's own exception; that statement binds no values.

The LibPQ driver logs separately, through its own Memento logger. Every failed statement prints the server's full message there at warn — DETAIL included, which on a unique violation names the value:

[warn | LibPQ]: UniqueViolation: ERROR:  duplicate key value violates unique constraint "drivers_code_key"
DETAIL:  Key (code)=(SEN) already exists.

PormG does not reconfigure a driver's logging. To keep that text out of your logs, raise the logger's level once at startup — the error is still raised to your code:

using LibPQ
LibPQ.Memento.setlevel!(LibPQ.LOGGER, "critical")

The SQLite driver does not log a failed statement, and Postgres.jl logs one only in its debug mode.

Catching a whole category

The abstract umbrellas exist so a handler can name a family without listing its members:

try
    PormG.Configuration.load("db_2"; env = "prod")
    PormG.Migrations.migrate()
catch e
    if e isa ConfigurationError
        @error "Fix connection.yml and retry" msg=error_message(e)
    elseif e isa MigrationError
        @error "The migration plan was rejected" msg=error_message(e)
    else
        rethrow()
    end
end

The umbrellas are UsageError (with FieldAccessError inside it), DefinitionError, ConfigurationError, MigrationError, PoolError and DatabaseError, all under PormGError.

Refusing a bad request

UsageError is the umbrella for "PormG refused the call for what it asked": FieldAccessError and its three cases, FilterError, QueryBuildError, UnsafeMutationError and InvalidValueError, not because the database failed. The remedy is to change the call, so it is the type a web handler maps to a bad request:

function results_from(min_points)
    try
        return M.Result.objects.filter("points__@gte" => min_points).values("resultid", "points").list()
    catch e
        e isa UsageError || rethrow()
        return (status = 400, error = error_message(e))
    end
end

results_from("lots")   # (status = 400, error = "Error in filter, field `points` …")

Catch the umbrella rather than the concrete type. A value refusal was a FilterError until #971 and #988 made it an InvalidValueError: a handler that named FilterError stopped matching, and one that named UsageError did not notice. PormGError is too wide for this job — it also catches a dropped connection, an exhausted pool and a wrong connection.yml, none of which is the caller's fault.

What is not inside it: ProtectedError (the data forbids a delete), BackendCapabilityError (the backend lacks the feature — a deployment problem, not a bad request), UnsupportedConnectionError (a PormG bug, or on MySQL what has no faithful SQL there) and the DatabaseError family.

Most UsageErrors are raised while the query is built, before anything is sent, but not all: a bulk write checks each row as it goes, so a bad later row is refused after earlier chunks were sent, and delete() may already have run its cascade statements. Without a transaction of yours, the call's own transaction rolls them back. Inside run_in_transaction they are yours to roll back: a block that catches the UsageError and returns normally commits them, so rethrow it, or catch it outside the block.

DatabaseError is the boundary worth understanding: it means the statement reached the database and was refused there. A value PormG rejects before sending — a null on a non-null field, an unknown column — never gets that far and raises the query-side type instead.

Coming from an older PormG

The taxonomy replaced the untyped errors and driver-native exceptions PormG used to raise, across several releases — so a catch block written against an older version may no longer match. The deliberate clean break is spelled out in Error taxonomy.

If you are upgrading an app, the change log carries the greps and the concrete before → after edits for each step — run PormG.upgrade_guide(from = v"<your pinned version>") to see only what applies to you, and read Upgrading PormG for the workflow.