Documentation Home
Connectors and APIs Manual
Download this Manual
PDF (US Ltr) - 4.5Mb
PDF (A4) - 4.5Mb


6.9.2.6 MySQLConnection.cursor() Method

Syntax:

cursor = cnx.cursor([arg=value[, arg=value]...])

This method returns a MySQLCursor() object, or a subclass of it depending on the passed arguments. The returned object is a cursor.CursorBase instance. For more information about cursor objects, see Section 6.9.5, “cursor.MySQLCursor Class”, and Section 6.9.6, “Subclasses cursor.MySQLCursor”.

Arguments may be passed to the cursor() method to control what type of cursor to create:

  • If buffered is True, the cursor fetches all rows from the server after an operation is executed. This is useful when queries return small result sets. buffered can be used alone, or in combination with the dictionary or named_tuple argument.

    buffered can also be passed to connect() to set the default buffering mode for all cursors created from the connection object. See Section 6.7.1, “Connector/Python Connection Arguments”.

    For information about the implications of buffering, see Section 6.9.6.1, “cursor.MySQLCursorBuffered Class”.

  • If raw is True, the cursor skips the conversion from MySQL data types to Python types when fetching rows. A raw cursor is usually used to get better performance or when you want to do the conversion yourself.

    raw can also be passed to connect() to set the default raw mode for all cursors created from the connection object. See Section 6.7.1, “Connector/Python Connection Arguments”.

  • If dictionary is True, the cursor returns rows as dictionaries. This argument is available as of Connector/Python 2.0.0.

  • If named_tuple is True, the cursor returns rows as named tuples. This argument is available as of Connector/Python 2.0.0.

  • If prepared is True, the cursor is used for executing prepared statements. This argument is available as of Connector/Python 1.1.2. The C extension supports this as of Connector/Python 8.0.17.

  • The cursor_class argument can be used to pass a class to use for instantiating a new cursor. It must be a subclass of cursor.CursorBase.

The returned object depends on the combination of the arguments. Examples:

  • If not buffered and not raw: MySQLCursor

  • If buffered and not raw: MySQLCursorBuffered

  • If not buffered and raw: MySQLCursorRaw

  • If buffered and raw: MySQLCursorBufferedRaw