VladPolskiy/mariadb-connector-python
1
0
Fork 0
mirror of https://github.com/mariadb-corporation/mariadb-connector-python.git synced 2025-08-15 23:42:40 +00:00
Code Issues Packages Projects Releases Wiki Activity
Page: module.md
Pages
Home connection.md cursor.md install.md module.md pooling.md usage.md
Clone
2
module.md
Georg Richter edited this page 2020-05-27 10:23:07 +02:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

The mariadb module

The mariadb module supports the standard defined by DB API 2.0 (PEP-249).

mariadb.connect(**kwargs)

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

The connection parameters have to be provided as a set of keyword arguments:

connection= mariadb.connect(user="myuser", host="localhost", database="test", password="secret")

The supported connection parameters are:

  • user – username used to authenticate with the database server

  • password – password to authenticate

  • host – host name or IP address of the database server

  • database – database (schema) name to used when connecting with the database server

  • unix_socket – location of the unix socket file

  • port – port number of the database server. If not specified the default value (=3306) will be used.

  • charset – default character set to be used

  • connect_timeout – connect timeout in seconds

  • read_timeout – read timeout in seconds

  • write_timeout – write timeout in seconds

  • local_infile – Enables or disables the use of LOAD DATA LOCAL INFILE statements.

  • compress – Uses the compressed protocol for client server communication. If the

    server doesn’t support compressed protocol, the default protocol will be used

  • init_command – Command(s) which will be executed when connecting and reconnecting to

    the database server

  • default_file – Read options from the specified option file. If the file is an empty

    string, default configuration file(s) will be used

  • default_group – Read options from the specified group

  • ssl_key – Defines a path to a private key file to use for TLS. This option

    requires that you use the absolute path, not a relative path. The specified key must be in PEM format

  • ssl_cert – Defines a path to the X509 certificate file to use for TLS.

    This option requires that you use the absolute path, not a relative path. The X609 certificate must be in PEM format.

  • ssl_ca – Defines a path to a PEM file that should contain one or more X509

    certificates for trusted Certificate Authorities (CAs) to use for TLS. This option requires that you use the absolute path, not a relative path.

  • ssl_cipher – Defines a list of permitted cipher suites to use for TLS

  • ssl_crl_path – Defines a path to a PEM file that should contain one or more revoked

    X509 certificates to use for TLS. This option requires that you use the absolute path, not a relative path.

  • ssl_verify_server_cert – Enables server certificate verification.

  • ssl_enforce – Always use a secure TLS connection

mariadb.cursor(buffered=None, dictionary=None, named_tuple=None, cursor_type=0, prepared=None, prefetch_rows=1)

Returns a new cursor object for the current connection.

Parameters have to be provided as a set of keyword arguments:

  • buffered - Specifies if the entire result set will be stored. Default is None.
  • dictionary - return fetch results as a dictionary. Default is None.
  • named_tuple - return fetch results as a named tuple. Default is None.
  • cursor_type - cursor type (only supported parameters are 0 (=no cursor) and mariadb.CURSOR_TYPE_READ_ONLY
  • prefetch_rows - the number of rows for prefetch (default is 1). This can only be used cursor type mariadb.CURSOR_TYPE_READ_ONLY.

By default the result will be unbuffered, which means before executing another statement with the same connection the entire result set must be fetched.

fetch methods of the cursor class by default return result set values as a tuple, unless named_tuple or dictionary was specified. The latter one exists for compatibility reasons and should be avoided due to possible inconsistency in case two or more fields in a result set have the same name.

If cursor_type is set to mariadb.CURSOR_TYPE_READ_ONLY, a cursor is opened for the statement invoked with cursors execute() method.

mariadb.ConnectionPool(**kwargs)

Creates a connection pool and returns a ConnectionPool object.

The connection parameters have to be provided as a set of keyword arguments:

db_conf= {user="myname", password="secret", database="test", host="localhost"};
pool= mariadb.ConnectionPool(pool_name="pool1", **db_conf)

Beside pool specific parameter all parameters from connect() are supported. The supported pool parameters are:

  • pool_name – Name of the pool

  • pool_size – Size of the pool. If this value is not provided, a default size of 5 pool connections will be used.

  • pool_reset – If set to True the connection will be resetted after close() method was called.

mariadb.apilevel()

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

mariadb.threadsafety()

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.

mariadb.paramstyle()

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.

mariadb.mariadbapi_version()

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

Exceptions

Compliant to DB API 2.0 MariaDB Connector/C provides information about errors through the following exceptions:

exception mariadb.DataError()

Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc.

exception mariadb.DatabaseError()

Exception raised for errors that are related to the database

exception mariadb.InterfaceError()

Exception raised for errors that are related to the database interface rather than the database itself.

exception mariadb.Warning()

Exception raised for important warnings like data truncations while inserting, etc.

exception mariadb.PoolError()

Exception rasied for errors related to ConnectionPool class.

exception mariadb.OperationalError()

Exception raised for errors that are related to the database’s operation and not necessarily under the control of the programmer

exception mariadb.IntegrityError()

Exception raised when the relational integrity of the database is affected, e.g. a foreign key check fails.

exception mariadb.InternalError()

Exception raised when the database encounters an internal error, e.g. the cursor is not valid anymore

exception mariadb.ProgrammingError()

Exception raised for programming errors, e.g. table not found or already exists, syntax error in the SQL statement

exception mariadb.NotSupportedError()

Exception raised in case a method or database API was used which is not supported by the database

Type objects and constructors

mariadb.Binary()

This function constructs an object capable of holding a binary (long) string value

mariadb.Date(year, month, day)

This function constructs an object holding a date value

mariadb.DateFromTicks(ticks)

This function constructs an object holding a date value from the given ticks value (number of seconds since the epoch). For more information see the documentation of the standard Python time module

mariadb.Time(hour, minute, second)

This function constructs an object holding a time value

mariadb.TimeFromTicks(ticks)

This function constructs an object holding a time value from the given ticks value (number of seconds since the epoch). For more information see the documentation of the standard Python time module

mariadb.Timestamp(year, month, day, hour, minute, second)

This function constructs an object holding a time stamp value

mariadb.TimestampFromTicks(ticks)

This function constructs an object holding a time stamp value from the given ticks value (number of seconds since the epoch). For more information see the documentation of the standard Python time module

mariadb.STRING()

This type object is used to describe columns in a database that are string-based (e.g. CHAR).

mariadb.BINARY()

This type object is used to describe (long) binary columns in a database (e.g. LONG, RAW, BLOBs).

mariadb.NUMBER()

This type object is used to describe numeric columns in a database.

mariadb.DATETIME()

This type object is used to describe date/time columns in a database.

mariadb.ROWID()

This type object is used to describe the “Row ID” column in a database.

mariadb.indicator_default()

This indicator object is used to use a default value for insert/update.

mariadb.indicator_ignore()

This indicatior object is used to skip the update of a column.

mariadb.indicator_null()

This indicator object is used for NULL values.

mariadb.indicator_row()

This indicator object is used for skip the update/insert of the entire row.