Add CYCLE clause support for recursive CTEs

[heinrichf-cdgnm]

Converting the USING path column to Python is involved with psycopg2. psycopg3 will convert it to a list of string tuples. I tried my best to document this in the code and in the docs.

The columns the clause adds are read through cte.col, e.g. .annotate(is_cycle=cte.col.is_cycle).

Closes #96

[heinrichf-cdgnm]

Pushed some cleanup on top.

• The cycle argument is parsed into a CycleConfig in one place now, and invalid config raises instead of silently dropping the clause.
• Column names are quoted, so mixed case names work.
• is_cycle and path are no longer annotated onto the queryset by join(). They resolve through cte.col instead: .annotate(is_cycle=cte.col.is_cycle).
• Two path assertions only held on psycopg2. They compare parsed values now.
• Both doc examples were broken. Fixed, and they run on psycopg2 and psycopg 3.

[millerdev]

@heinrichf-cdgnm Thank you for the contribution! I intend to review and hope to get this merged, but have been on vacation recently and am swamped with other work currently. Will get to it as soon as I can.

[millerdev]

There are some things I'd like to seen cleaned up before this is merged.

[millerdev]

These seem vulnerable to SQL injection. Would be better to interpret the value by type. So a Python boolean True is converted to true; a str is quoted; int, float, and datetime can be handled similarly. Maybe it could support an expression like Value or RawSQL if the user wants to do something more exotic?

[heinrichf-cdgnm]

Done. to and default take a bool, int, float, str, date or datetime, a Value, or a RawSQL without params.

Postgres only accepts constants there AFAICT, so something like a placeholder, a cast or a signed number results in a syntax error. Values are therefore written into the SQL by Python type:

• str is quoted (as an escape string constant E'...' if it contains a backslash)
• float -> float8 '1.5'
• negative int -> bigint '-1'
• date and datetime -> date '...', timestamp '...' or timestamptz '...'

The type of to then decides the output field of the mark column. For Value and RawSQL the output field is the expression's output_field,

[millerdev]

Ref #134 (comment)

[heinrichf-cdgnm]

Pushed changes according to the review, I hope I didn't miss anything. I did not resolve the conversations in case you would like to do that or there is more to be discussed.

[millerdev]

I like where this is heading. Would still like to see some changes to compile_mark_value.

[millerdev]

Is there a test for (and does it break) if cycle_value and default_value have different types? Should that be detected here and maybe raise ValueError if the types do not match?

[millerdev]

What about using Django's connection.ops.compose_sql() at SQL-compile time? It's better for a few reasons:

• Escaping: it uses the driver's own quoting, so you don't depend on the E'' / standard_conforming_strings details that quote_string handles by hand.
• Types: it formats every type the docs list (bool, int, float, str, date, datetime) with the driver's adapters.
• Invalid input: the driver rejects values it can't represent, such as strings containing NUL (e.g., "abc\x00def").

def compile_mark_value(value, connection):
    """Get the SQL of a mark column value

    PostgreSQL accepts only constants in TO and DEFAULT, not parameters
    or casts, so the literal value is written into the SQL.
    """
    return connection.ops.compose_sql("%s", [value]).replace("%", "%%")

Replacing % to %% is still necessary because the result is embedded in a query that Django later runs with params, and compose_sql returns plain SQL with single %.

compile_mark_value is currently called in CycleClause.__init__, where there's no connection. The call will need to move into as_sql/the compiler, where compiler.connection is available. That's also more correct for multi-database setups.

A separate function could be used to get the output field. Not sure if it makes sense to do that here in CycleClause.__init__, or later at compile time?