psycopg: `TypeError` keyword not supported: `prepare`

[piotrpawlaczek]

Description
When using Django with the recommended psycopg[c] v3 adapter and Elastic APM enabled, executing a QuerySet.iterator() fails with: TypeError: keyword not supported: prepare.

This occurs because psycopg v3’s server-side cursor implementation rejects the prepare=keyword argument, which is being passed through Elastic APM's database instrumentation.

To Reproduce

1. Install Django with the recommended PostgreSQL adapter (psycopg[c] v3.2.12).
2. Enable Elastic APM in the Django project.
3. Execute a Django query using QuerySet.iterator(), for example:

for obj in MyModel.objects.iterator():
    ...

Environment

• OS: Linux, Debian
• Python version: 3.12.12
• Framework and version Django 4.2
• APM Server version: 9
• Agent version: 6.24.0
• Server side cursors: enabled

Expected behavior:
The queryset should be processed normally using a server-side cursor without errors.

Actual behavior:
TypeError is raised: keyword not supported: prepare

psycopg/_server_cursor.py in execute at line 88

   ) -> Self:
        """
        Open a cursor to execute a query to the database.
        """
        if kwargs: # <---- here {"prepare": None}
            raise TypeError(f"keyword not supported: {list(kwargs)[0]}")

        if self._pgconn.pipeline_status:
            raise e.NotSupportedError(
                "server-side cursors not supported in pipeline mode"
            )

Additional context

• The error does not occur if Elastic APM is disabled.
• The error does not occur when using the not-recommended psycopg v2
• The issue appears to be caused by Elastic APM adding a prepare=None parameter during its instrumentation of database queries.

[xrmx]

Thanks for reporting, could you please share the part of the stacktrace in pyscopg?

[piotrpawlaczek]

Thanks for reporting, could you please share the part of the stacktrace in pyscopg?

Hi, yes the elastic.psycopg and elastic.dbapi2 send invalid kwargs param to psycopg._server_coursor

See stacktrace frames, exception and in-app frames:

SYSTEM

exception
   typeTypeError


stacktrace


frame
    module `psycopg._server_cursor`
        functionexecute
            context_lineraise TypeError(f"keyword not supported: {list(kwargs)[0]}")


frame
    module `elasticapm.instrumentation.packages.dbapi2`
         function_trace_sql
             context_lineresult = method(sql, params, **kwargs)


frame
    module `elasticapm.instrumentation.packages.psycopg`
         functionexecute
              context_linereturn self._trace_sql(self.__wrapped__.execute, query, params,  prepare=prepare, binary=binary, **kwargs)


frame
    module `django.db.backends.utils`
        function_execute
            context_linereturn self.cursor.execute(sql, params)


frame
    module `django.db.backends.utils`
        function_execute_with_wrappers
             context_linereturn executor(sql, params, many, context)


frame
    module `django.db.backends.utils`
        functionexecute
            context_linereturn self._execute_with_wrappers(


frame
    module `django.db.models.sql.compiler`
        functionexecute_sql
            context_linecursor.execute(sql, params)


frame
    module `django.db.models.query`
        function__iter__
             context_lineresults = compiler.execute_sql(


frame
    module `django.db.models.query`
        function_iterator
          context_lineyield from iterable

[xrmx]

@piotrpawlaczek should be fixed on main, any chance you can give it a try?

[piotrpawlaczek]

@piotrpawlaczek should be fixed on main, any chance you can give it a try?

@xrmx The fix from main checks out on my side.
Thanks for the quick handling! Any chance we can toss a PyPI patch out?

[xrmx]

@piotrpawlaczek should be fixed on main, any chance you can give it a try?

@xrmx The fix from main checks out on my side. Thanks for the quick handling! Any chance we can toss a PyPI patch out?

Released 6.24.1 this morning