Cursor Objects

class pymysql.cursors.Cursor(connection)

This is the object used to interact with the database.

Do not create an instance of a Cursor yourself. Call connections.Connection.cursor().

See Cursor in the specification.

callproc(procname, args=())

Execute stored procedure procname with args.

Parameters:

• procname (str) – Name of procedure to execute on server.

• args (tuple or list) – Sequence of parameters to use with procedure.

Returns the original args.

Compatibility warning: PEP-249 specifies that any modified parameters must be returned. This is currently impossible as they are only available by storing them in a server variable and then retrieved by a query. Since stored procedures return zero or more result sets, there is no reliable way to get at OUT or INOUT parameters via callproc. The server variables are named @_procname_n, where procname is the parameter above and n is the position of the parameter (from zero). Once all result sets generated by the procedure have been fetched, you can issue a SELECT @_procname_0, … query using .execute() to get any OUT or INOUT values.

Compatibility warning: The act of calling a stored procedure itself creates an empty result set. This appears after any result sets generated by the procedure. This is non-standard behavior with respect to the DB-API. Be sure to use nextset() to advance through all result sets; otherwise you may get disconnected.

close()

Closing a cursor just exhausts all remaining data.

execute(query, args=None)

Execute a query.

Parameters:

• query (str) – Query to execute.

• args (tuple, list or dict) – Parameters used with query. (optional)

Returns:

Number of affected rows.

Return type:

int

If args is a list or tuple, %s can be used as a placeholder in the query. If args is a dict, %(name)s can be used as a placeholder in the query.

executemany(query, args)

Run several data against one query.

Parameters:

• query (str) – Query to execute.

• args (tuple or list) – Sequence of sequences or mappings. It is used as parameter.

Returns:

Number of rows affected, if any.

Return type:

int or None

This method improves performance on multiple-row INSERT and REPLACE. Otherwise it is equivalent to looping over args with execute().

fetchall()

Fetch all the rows.

fetchmany(size=None)

Fetch several rows.

fetchone()

Fetch the next row.

max_stmt_length = 1024000

Max statement size which executemany() generates.

Max size of allowed statement is max_allowed_packet - packet_header_size. Default value of max_allowed_packet is 1048576.

mogrify(query, args=None)

Returns the exact string that would be sent to the database by calling the execute() method.

Parameters:

• query (str) – Query to mogrify.

• args (tuple, list or dict) – Parameters used with query. (optional)

Returns:

The query with argument binding applied.

Return type:

str

This method follows the extension to the DB API 2.0 followed by Psycopg.

setinputsizes(*args)

Does nothing, required by DB API.

setoutputsizes(*args)

Does nothing, required by DB API.

class pymysql.cursors.SSCursor(connection)

Unbuffered Cursor, mainly useful for queries that return a lot of data, or for connections to remote servers over a slow network.

Instead of copying every row of data into a buffer, this will fetch rows as needed. The upside of this is the client uses much less memory, and rows are returned much faster when traveling over a slow network or if the result set is very big.

There are limitations, though. The MySQL protocol doesn’t support returning the total number of rows, so the only way to tell how many rows there are is to iterate over every row returned. Also, it currently isn’t possible to scroll backwards, as only the current row is held in memory.

close()

Closing a cursor just exhausts all remaining data.

fetchall()

Fetch all, as per MySQLdb. Pretty useless for large queries, as it is buffered. See fetchall_unbuffered(), if you want an unbuffered generator version of this method.

fetchall_unbuffered()

Fetch all, implemented as a generator, which isn’t to standard, however, it doesn’t make sense to return everything in a list, as that would use ridiculous memory for large result sets.

fetchmany(size=None)

Fetch many.

fetchone()

Fetch next row.

read_next()

Read next row.

class pymysql.cursors.DictCursor(connection)

A cursor which returns results as a dictionary

class pymysql.cursors.SSDictCursor(connection)

An unbuffered cursor, which returns results as a dictionary