MariaDB Connector/Python 1.1

Overview

A summary of the MariaDB Connector/Python API:

Name

Type

Description

apilevel

Attribute

String constant stating the supported DB API level. The value for mariadb is 2.0.

Binary()

Method

Returns an object for holding a binary (long) string value

client_version

Attribute

Returns the version of MariaDB Connector/C library in use as an integer. The number has the following format: MAJOR_VERSION * 10000 + MINOR_VERSION * 1000 + PATCH_VERSION

client_version_info

Attribute

Returns the version of MariaDB Connector/C library as a tuple in the following format: (MAJOR_VERSION, MINOR_VERSION, PATCH_VERSION)

connect()

Method

Establishes a connection to a database server and returns a connection object

ConnectionPool()

Method

Create a connection pool and returns a connection pool object

Date()

Method

Returns an object for holding a date value

DateFromTicks()

Method

Returns an object for holding a date value, built from the given ticks value (seconds since the epoch)

fieldinfo()

Method

Returns a MariaDB field information object

mariadbapi_version

Attribute

String constant stating the version of the used MariaDB Connector/C library

paramstyle

Attribute

String constant stating the type of parameter marker. For mariadb the value is qmark. For compatibility reasons mariadb also supports the format and pyformat paramstyles with the limitation that they can't be mixed inside a SQL statement.

threadsafety

Attribute

Integer constant stating the level of thread safety. For mariadb the value is 1, which means threads can share the module but not the connection.

Time()

Method

Returns an object for holding a time value

TimeFromTicks()

Method

Returns an object for holding a time value, built from the given ticks value (seconds since the epoch)

Timestamp()

Method

This function constructs an object holding a time stamp value

TimestampFromTicks()

Method

Returns an object for holding a timestamp value, built from the given ticks value (seconds since the epoch)

Connection Class

Name

Type

Description

auto_reconnect

Attribute

This connection value (read/write) enables or disables automatic reconnection to the server when the connection is lost

autocommit

Attribute

This connection value (read/write) determines if commits occur automatically or manually. Default: False (automatic).

begin()

Method

Start a new transaction which can be committed by .commit() method, or cancelled by .rollback() method

change_user()

Method

Changes the user and default database of the current connection. A valid username and password pair must be provided and that user must have sufficient permissions to access the desired database. If for any reason authorization fails, the current user authentication will remain.

character_set

Attribute

This connection value (read/write) sets the character set to use

client_capabilities

Attribute

Client capability flags

close()

Method

Close the connection now (instead of when the object is destroyed)

collation

Attribute

Returns the client character set collation for the connection. (read-only)

commit()

Method

Commit any pending transaction to the database

connection_id

Attribute

Returns the (thread) id for the current connection. (read only)

cursor()

Method

Returns a new cursor object for the current connection

database

Attribute

Returns or sets the default database for the current connection. (read/write)

escape_string()

Method

Returns a backslash-escaped string that can be used inside single or double quotes in an SQL statement

get_server_version()

Method

Returns a tuple representing the version of the connected server in the following format: (MAJOR_VERSION, MINOR_VERSION, PATCH_VERSION)

kill()

Method

Asks the server to kill a database connection based on its thread ID

open

Attribute

Returns true if the connection is alive. A ping command will be send to the server for this purpose, which means this function might fail if there are still non processed pending result sets.

ping()

Method

Checks if the connection to the database server is still available and throws an exception if it is not

reconnect()

Method

Tries to make a connection object active again by reconnecting to the server using the same credentials which were specified in connect() method

reset()

Method

Resets a connection object, clearing session state and pending results. All open cursors for the connection become invalid and must be recreated to be used again.

rollback()

Method

Causes any uncommitted changes on a connection to be discarded

select_db()

Method

Gets the default database for the current connection. The default database can also be obtained or changed by database attribute.

server_capabilities

Attribute

Server capability flags

server_info

Attribute

This connection value (read-only) returns the alphanumeric version of connected database. See server_version for the numeric version.

server_name

Attribute

The server name or IP address that was used to make the connection to the database. (read-only)

server_port

Attribute

The port number that was used to make the connection to the database. (read-only)

server_status

Attribute

Return server status flags

server_version

Attribute

This connection value (read-only) returns the numeric version of the database in the form VERSION_MAJOR * 10000 + VERSION_MINOR * 100 + VERSION_PATCH

server_version_info

Attribute

Returns numeric version of connected database server in tuple format

show_warnings()

Method

Shows error, warning and note messages from last executed command

tls_cipher

Attribute

The name of the TLS cipher used for the connection or None. (read-only)

tls_version

Attribute

The version of the TLS cipher used for the connection or None. (read-only)

tpc_begin()

Method

Begins a TPC transaction with the given transaction ID xid. This method should be called outside of a transaction (i.e., nothing may have executed since the last .commit() or .rollback()). Furthermore, it is an error to call .commit() or .rollback() within the TPC transaction. A ProgrammingError is raised, if the application calls .commit() or .rollback() during an active TPC transaction.

tpc_commit()

Method

Commit a two-phase-commit transaction that was started with tpc_begin() and validated using tpc_prepare()

tpc_prepare()

Method

Performs the verification phase of two-phase-commit transaction started with the tpc_begin() method

tpc_recover()

Method

Returns a list of pending two-phase-commit transaction IDs for the current connection

tpc_rollback()

Method

Aborts a two-phase-commit transaction that was started with tpc_begin(). A rollback can be done before or after the tpc_prepare() is called.

unix_socket

Attribute

This connection value (read-only) returns the path of the unix socket that was used for the connection or None if the connection was made via IP

user

Attribute

Returns the user name for the current connection. (read-only)

warnings

Attribute

Returns the number of warnings from the last executed statement, or zero. (read only)

xid()

Method

Returns a transaction ID object suitable for passing to the two-phase-commit functions, starting with tpc_begin()

Cursor Class

Name

Type

Description

arraysize

Attribute

This cursor value (read/write) is the number of rows that fetchmany() reads per call. The default is 1.

buffered

Attribute

This cursor value (read/write) sets if the entire result-set of a SELECT or SHOW is immediately read into memory. Default: 0 (unbuffered).

callproc()

Method

Executes a stored procedure

closed

Attribute

Indicates if the cursor is closed and can't be reused

connection

Attribute

Returns the connection object that was used to create the cursor. (read-only)

description

Attribute

Returns column (field) information for a statement that returns values, such as a SELECT or a SHOW. (read-only)

execute()

Method

Specifies a SQL statement to execute

executemany()

Method

Specifies a SQL statement to execute multiple times, based on a list of argument values

fetchall()

Method

Fetch all remaining rows of a query result, returning them as a sequence of sequences (e.g., a list of tuples). An exception will be raised if the previous call to execute() didn't produce a result set or execute() wasn't called before.

fetchmany()

Method

Fetches the number of rows specified by the size parameter

fetchone()

Method

Fetch the next row of a query result set, returning a single sequence, or None if no more data is available. An exception will be raised if the previous call to execute() didn't produce a result set or execute() wasn't called before.

lastrowid

Attribute

Returns the automatically generated ID value from an INSERT statement on a table that has an AUTO_INCREMENT column

next()

Method

Return the next row from the currently executing SQL statement using the same semantics as .fetchone()

nextset()

Method

Makes the cursor skip to the next available result-set in a query that returns multiple result-sets

paramcount

Attribute

rowcount

Attribute

Provides the number of rows returned by the last query. (read-only)

scroll()

Method

Scrolls the cursor in the result-set to a new position according to mode

setinputsizes()

Method

Required by PEP-249. Does nothing in MariaDB Connector/Python.

setoutputsize()

Method

Required by PEP-249. Does nothing in MariaDB Connector/Python.

sp_outparams

Attribute

Indicates if the current result set contains in out or out parameter from a previous executed stored procedure

statement

Attribute

Displays the last executed SQL statement. (read-only)

warnings

Attribute

Returns the number of warnings from the last executed statement, or zero. (read only)

Pool Class

Name

Type

Description

add_connection()

Method

Adds a connection object to the connection pool. In case that the pool doesn't have a free slot or is not configured a PoolError exception will be raised.

close()

Method

Closes connection pool and all connections

connection_count

Attribute

Returns the number of connections in connection pool

get_connection()

Method

Returns a connection from the connection pool or raises a PoolError exception if a connection is not available

max_size

Attribute

Returns the maximum allowed size of the connection pool. (read only)

pool_name

Attribute

Returns the name of the connection pool. (read only)

pool_reset_connection

Attribute

If set to true, the connection will be reset on both client and server side after .close() method is called. (read/write)

pool_size

Attribute

Returns the size of the connection pool

set_config()

Method

Sets the connection configuration for the connection pool. For valid connection arguments check the mariadb.connect() method.

Constants

Name

Description

CLIENT.BULK_OPERATIONS

Value: 1 << 34

CLIENT.CACHE_METDATA

Value: 1 << 36

CLIENT.CAN_HANDLE_EXPIRED_PASSWORDS

Connector/C CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS constant. Used to determine whether the connector is prepared to handle the expired password sandbox mode.

CLIENT.COMPRESS

Connector/C CLIENT_COMPRESS constant. Used to determine whether the connection uses compression.

CLIENT.CONNECT_ATTRS

Connector/C CLIENT_CONNECT_ATTRS constant

CLIENT.CONNECT_WITH_DB

Connector/C CLIENT_CONNECT_WITH_DB constant. Used to determine whether the connection specifies a default database.

CLIENT.EXTENDED_METADATA

Value: 1 << 35

CLIENT.FOUND_ROWS

Connector/C CLIENT_FOUND_ROWS constant. Used to determine whether the client has found rows instead of affected rows.

CLIENT.IGNORE_SPACE

Connector/C CLIENT_IGNORE_SPACE constant. Used to determine whether the client allows spaces after function names.

CLIENT.INTERACTIVE

Connector/C CLIENT_INTERACTIVE constant. Used to determine whether the client connection is interactive.

CLIENT.LOCAL_FILES

Connector/C CLIENT_LOCAL_FILES constant. Used to determine whether to allow LOAD DATA LOCAL INFILE statements.

CLIENT.LONG_FLAG

Connector/C CLIENT_LONG_FLAG constant. Used to determine whether the client retrieved all column flags.

CLIENT.LONG_PASSWORD

Value: 1

CLIENT.MULTI_RESULTS

Connector/C CLIENT_MULTI_RESULTS constant. Used to determine whether the client can handle multiple result-sets.

CLIENT.MULTI_STATEMENTS

Connector/C CLIENT_MULTI_STATEMENTS constant. Used to determine whether the client can use the semicolon to send multiple statements in one query.

CLIENT.MYSQL

Connector/C CLIENT_MYSQL constant

CLIENT.NO_SCHEMA

Connector/C CLIENT_NO_SCHEMA constant. Used to determine whether the SQL parser returns an error if the query does not specify a database.

CLIENT.PLUGIN_AUTH

Connector/C CLIENT_PLUGIN_AUTH constant. Used to represent the authentication plugin used on the connection.

CLIENT.PROGRESS

Value: 1 << 32

CLIENT.PS_MULTI_RESULTS

Connector/C CLIENT_PS_MULTI_RESULTS constant

CLIENT.REMEMBER_OPTIONS

Connector/C CLIENT_REMEMBER_OPTIONS constant

CLIENT.SECURE_CONNECTION

Connector/C CLIENT_SECURE_CONNECTION constant

CLIENT.SESSION_TRACKING

Connector/C CLIENT_SESSION_TRACKING constant

CLIENT.SSL

Connector/C CLIENT_SSL constant. Used to determine whether the client switches to TLS after the handshake.

CLIENT.SSL_VERIFY_SERVER_CERT

Connector/C CLIENT_SSL_VERIFY_SERVER_CERT constant. Used to determine whether the client should verify the TLS certificate from the Server.

CLIENT.TRANSACTIONS

Connector/C CLIENT_TRANSACTIONS constant. Used to determine whether the client is aware of transactions.

COMMAND.BINLOG_DUMP

Value: 18

COMMAND.CHANGE_USER

Value: 17

COMMAND.CONNECT

Value: 11

COMMAND.CONNECT_OUT

Value: 20,

COMMAND.CREATE_DB

Value: 5

COMMAND.DAEMON

Value: 29

COMMAND.DEBUG

Value: 13

COMMAND.DELAYED_INSERT

Value: 16

COMMAND.DROP_DB

Value: 6

COMMAND.FIELD_LIST

Value: 4

COMMAND.INIT_DB

Value: 2

COMMAND.PING

Value: 14

COMMAND.PROCESS_INFO

Value: 10

COMMAND.PROCESS_KILL

Value: 12

COMMAND.QUERY

Value: 3

COMMAND.QUIT

Value: 1

COMMAND.REFRESH

Value: 7

COMMAND.REGISTER_SLAVE

Value: 21

COMMAND.RESET_CONNECTION

Value: 31

COMMAND.SET_OPTION

Value: 27

COMMAND.SHUTDOWN

Value: 8

COMMAND.SLEEP

Value: 0

COMMAND.STATISTICS

Value: 9

COMMAND.STMT_BULK_EXECUTE

Value: 250

COMMAND.STMT_CLOSE

Value: 25

COMMAND.STMT_EXECUTE

Value: 23

COMMAND.STMT_FETCH

Value: 28

COMMAND.STMT_PREPARE

Value: 22

COMMAND.STMT_RESET

Value: 26

COMMAND.STMT_SEND_LONG_DATA

Value: 24

COMMAND.TABLE_DUMP

Value: 19

COMMAND.TIME

Value: 15

COMMAND.UNSUPPORTED

Value: 30

CURSOR.NONE

Value: 0

CURSOR.READ_ONLY

Value: 1

FIELD_FLAG.AUTO_INCREMENT

Value: 512

FIELD_FLAG.BINARY

Value: 128

FIELD_FLAG.BLOB

Value: 16

FIELD_FLAG.ENUM

Value: 256

FIELD_FLAG.GROUP

Value: 32768

FIELD_FLAG.MULTIPLE_KEY

Value: 8

FIELD_FLAG.NO_DEFAULT

Value: 4096

FIELD_FLAG.NOT_NULL

Value: 1

FIELD_FLAG.NUMERIC

Value: 32768

FIELD_FLAG.ON_UPDATE_NOW

Value: 8192

FIELD_FLAG.PART_OF_KEY

Value: 16384

FIELD_FLAG.PRIMARY_KEY

Value: 2

FIELD_FLAG.SET

Value: 2048

FIELD_FLAG.TIMESTAMP

Value: 1024

FIELD_FLAG.UNIQUE

Value: 65536

FIELD_FLAG.UNIQUE_KEY

Value: 4

FIELD_FLAG.UNSIGNED

Value: 32

FIELD_FLAG.ZEROFILL

Value: 64

FIELD_TYPE.BIT

Connector/C MYSQL_TYPE_BIT constant. Used to represent BIT columns.

FIELD_TYPE.BLOB

Connector/C MYSQL_TYPE_BLOB constant. Used to represent BLOB columns.

FIELD_TYPE.DATE

Connector/C MYSQL_TYPE_DATE constant. Used to represent DATE columns.

FIELD_TYPE.DATETIME

Connector/C MYSQL_TYPE_DATETIME constant. Used to represent DATETIME columns.

FIELD_TYPE.DATETIME2

Connector/C MYSQL_TYPE_DATETIME2 constant

FIELD_TYPE.DECIMAL

Connector/C MYSQL_TYPE_DECIMAL constant. Used to represent DECIMAL columns.

FIELD_TYPE.DOUBLE

Connector/C MYSQL_TYPE_DOUBLE constant. Used to represent DOUBLE columns.

FIELD_TYPE.ENUM

Connector/C MYSQL_TYPE_ENUM constant. Used to represent ENUM columns.

FIELD_TYPE.FLOAT

Connector/C MYSQL_TYPE_FLOAT constant. Used to represent FLOAT columns.

FIELD_TYPE.GEOMETRY

Value: 255

FIELD_TYPE.INT24

Connector/C MYSQL_TYPE_INT24 constant

FIELD_TYPE.JSON

Connector/C MYSQL_TYPE_JSON constant. Used to represent JSON columns.

FIELD_TYPE.LONG

Connector/C MYSQL_TYPE_LONG constant. Used to represent LONG columns.

FIELD_TYPE.LONG_BLOB

Connector/C MYSQL_TYPE_LONG_BLOB constant. Used to represent LONGBLOB columns.

FIELD_TYPE.LONGLONG

Connector/C MYSQL_TYPE_LONGLONG constant

FIELD_TYPE.MEDIUM_BLOB

Connector/C MYSQL_TYPE_MEDIUM_BLOB constant. Used to represent MEDIUMBLOB columns.

FIELD_TYPE.NEWDATE

Connector/C MYSQL_TYPE_NEWDATE constant

FIELD_TYPE.NEWDECIMAL

Connector/C MYSQL_TYPE_NEWDECIMAL constant

FIELD_TYPE.NULL

Connector/C MYSQL_TYPE_NULL constant

FIELD_TYPE.SET

Connector/C MYSQL_TYPE_SET constant

FIELD_TYPE.SHORT

Connector/C MYSQL_TYPE_SHORT constant

FIELD_TYPE.STRING

Value: 254

FIELD_TYPE.TIME

Connector/C MYSQL_TYPE_TIME constant. Used to represent TIME columns.

FIELD_TYPE.TIME2

Connector/C MYSQL_TYPE_TIME2 constant

FIELD_TYPE.TIMESTAMP

Connector/C MYSQL_TYPE_TIMESTAMP constant. Used to represent TIMESTAMP columns.

FIELD_TYPE.TIMESTAMP2

Connector/C MYSQL_TYPE_TIMESTAMP2 constant

FIELD_TYPE.TINY

Connector/C MYSQL_TYPE_TINY constant. Used to represent TINYINT columns.

FIELD_TYPE.TINY_BLOB

Connector/C MYSQL_TYPE_TINY_BLOB constant. Used to represent TINYBLOB columns.

FIELD_TYPE.VAR_STRING

Value: 253

FIELD_TYPE.VARCHAR

Connector/C MYSQL_TYPE_VARCHAR constant. Used to represent VARCHAR columns.

FIELD_TYPE.YEAR

Connector/C MYSQL_TYPE_YEAR constant. Used to represent YEAR columns.

INDICATOR.DEFAULT

Connector/C STMT_INDICATOR_DEFAULT constant. Used to indicate that the given value is the column default.

INDICATOR.IGNORE

Connector/C STMT_INDICATOR_IGNORE constant. Used to indicate whether to ignore the given value.

INDICATOR.IGNORE_ROW

Connector/C STMT_INDICATOR_IGNORE_ROW constant. Used to indicate whether skips the current row.

INDICATOR.NULL

Connector/C STMT_INDICATOR_NULL constant. Used to indicate that the value is NULL.

INFO.ASYNC_TIMEOUT

Value: 5

INFO.ASYNC_TIMEOUT_MS

Value: 6

INFO.BYTES_READ

Value: 34

INFO.BYTES_SENT

Value: 35

INFO.CHARSET_ID

Value: 0

INFO.CHARSET_INFO

Value: 7

INFO.CHARSET_NAME

Value: 1

INFO.CLIENT_CAPABILITIES

Value: 33

INFO.CLIENT_ERRORS

Value: 2

INFO.CLIENT_VERSION

Value: 3

INFO.CLIENT_VERSION_ID

Value: 4

INFO.ERROR

Value: 8

INFO.ERROR_ID

Value: 9

INFO.EXTENDED_SERVER_CAPABILITIES

Value: 32

INFO.HOST

Value: 10

INFO.INFO

Value: 11

INFO.MAX_ALLOWED_PACKET

Value: 28

INFO.NET_BUFFER_LENGTH

Value: 29

INFO.PORT

Value: 12

INFO.PROTOCOL_VERSION_ID

Value: 13

INFO.PVIO_TYPE

Value: 14

INFO.SCHEMA

Value: 15

INFO.SERVER_CAPABILITIES

Value: 31

INFO.SERVER_STATUS

Value: 30

INFO.SERVER_TYPE

Value: 16

INFO.SERVER_VERSION

Value: 17

INFO.SERVER_VERSION_ID

Value: 18

INFO.SOCKET

Value: 19

INFO.SQLSTATE

Value: 20

INFO.SSL_CIPHER

Value: 21

INFO.TLS_LIBRARY

Value: 22

INFO.TLS_VERSION

Value: 23

INFO.TLS_VERSION_ID

Value: 24

INFO.TYPE

Value: 25

INFO.UNIX_SOCKET

Value: 26

INFO.USER

Value: 27

STATUS.ANSI_QUOTES

Value: 32768

STATUS.AUTOCOMMIT

Value: 2

STATUS.CURSOR_EXISTS

Value: 64

STATUS.DB_DROPPED

Value: 256

STATUS.IN_TRANS

Value: 1

STATUS.IN_TRANS_READONLY

Value: 8192

STATUS.LAST_ROW_SENT

Value: 128

STATUS.METADATA_CHANGED

Value: 1024

STATUS.MORE_RESULTS_EXIST

Value: 8

STATUS.NO_BACKSLASH_ESCAPES

Value: 512

STATUS.PS_OUT_PARAMS

Value: 4096

STATUS.QUERY_NO_GOOD_INDEX_USED

Value: 16

STATUS.QUERY_NO_INDEX_USED

Value: 32

STATUS.QUERY_WAS_SLOW

Value: 2048

STATUS.SESSION_STATE_CHANGED

Value: 16384

TPC_STATE.NONE

Value: 0

TPC_STATE.PREPARE

Value: 2

TPC_STATE.XID

Value: 1