Connectors and APIs - MariaDB - Databases - Software - Computers
Connectors and APIs | ||
---|---|---|
Prev | Next |
Connectors and APIs
Table of Contents
- MySQL Connector/ODBC
- MySQL Connector/Net
- MySQL Connector/J
-
- Overview of MariaDB Connector/J
- Connector/J Versions
- Connector/J Installation
- Connector/J Examples
- Connector/J (JDBC) Reference
- JDBC Concepts
- J2EE Concepts
- Using Connector/J with Tomcat
- Using Connector/J with JBoss
- Using Connector/J with Spring
- Using Connector/J with GlassFish
- Troubleshooting Connector/J
- Connector/J Support
- Connector/J Versions
- Overview of MariaDB Connector/J
- MySQL Connector/MXJ
- MySQL Connector/C++
-
- Installing the MariaDB Connector/C++ Binary
- Installing MariaDB Connector/C++ from Source
- MySQL Connector/C++ Building Windows Applications with Microsoft Visual Studio
- MySQL Connector/C++ Building Linux Applications with NetBeans
- MySQL Connector/C++ Getting Started: Usage Examples
- MySQL Connector/C++ Tutorials
- MySQL Connector/C++ Debug Tracing
- MySQL Connector/C++ Usage Notes
- MySQL Connector/C++ Known Bugs and Issues
- MySQL Connector/C++ Feature requests
- MySQL Connector/C++ Support
- MySQL Connector/C++ FAQ
- Installing MariaDB Connector/C++ from Source
- Installing the MariaDB Connector/C++ Binary
- MySQL Connector/C
- MySQL Connector/OpenOffice.org
- libmysqld, the Embedded MariaDB Server Library
- MySQL C API
-
- C API Data Structures
- C API Function Overview
- C API Function Descriptions
- C API Prepared Statements
- C API Prepared Statement Data Structures
- C API Prepared Statement Function Overview
- C API Prepared Statement Function Descriptions
- C API Threaded Function Descriptions
- C API Embedded Server Function Descriptions
- C API Client Plugin Functions
- Common Questions and Problems When Using the C API
- Controlling Automatic Reconnection Behavior
- C API Support for Multiple Statement Execution
- C API Prepared Statement Problems
- C API Prepared Statement Handling of Date and Time Values
- C API Support for Prepared
CALL
Statements- Building Client Programs
- C API Function Overview
- C API Data Structures
- MySQL PHP API
- MySQL Perl API
- MySQL Python API
- MySQL Ruby APIs
- MySQL Python API
- MySQL Tcl API
- MySQL Eiffel Wrapper
MySQL Connectors provide connectivity to the MariaDB server for client programs. APIs provide low-level access to the MariaDB protocol and MariaDB resources. Both Connectors and the APIs enable you to connect and execute MariaDB statements from another language or environment, including Java (JDBC), ODBC, Perl, Python, PHP, Ruby, and native C and embedded MariaDB instances.Note
Connector version numbers do not correlate with MariaDB Server version numbers. See also Table 20.2, "MySQL Connector Versions and MariaDB Server Versions".
A number of connectors are developed by MySQL:
- Connector/ODBC provides driver support for connecting to a MariaDB server using the Open Database Connectivity (ODBC) API. Support is available for ODBC connectivity from Windows, Unix and Mac OS X platforms.
- Connector/Net enables developers to create .NET applications that use data stored in a MariaDB database. Connector/Net implement a fully functional ADO.NET interface and provides support for use with ADO.NET aware tools. Applications that want to use Connector/Net can be written in any of the supported .NET languages.
The MariaDB Visual Studio Plugin works with Connector/Net and Visual Studio 2005. The plugin is a MariaDB DDEX Provider, which means that you can use the schema and data manipulation tools within Visual Studio to create and edit objects within a MariaDB database.
- Connector/J provides driver support for connecting to MariaDB from a Java application using the standard Java Database Connectivity (JDBC) API.
- Connector/MXJ is a tool that enables easy deployment and management of MariaDB server and database through your Java application.
- Connector/C++ is a tool that enables easy deployment and management of MariaDB server and database through your C++ application.
- Connector/C is a standalone replacement for the MariaDB Client Library (
libmysql
). - Connector/OpenOffice.org is a tool that enables OpenOffice.org applications to connect to MariaDB server.
There are two direct access methods for using MariaDB natively within a C application:
- The C API provides low-level access to the MariaDB protocol through the
libmysql
client library; this is the primary method used to connect to an instance of the MariaDB server, and is used both by MariaDB command line clients and many of the APIs also detailed in this section. MariaDB Connector/C can now also be used for this purpose. libmysqld
is an embedded MariaDB server library that enables you to embed an instance of the MariaDB server into your C applications.
If you need to access MariaDB from a C application, or build an interface to MariaDB for a language not supported by the Connectors or APIs in this chapter, the C API is where you would start. A number of programmers utilities are available to help with the process, and also covered in this section.
The remaining APIs provide an interface to MariaDB from specific application languages. These solutions are not developed or supported by MySQL. Basic information on their usage and abilities is provided here for reference purposes only.
All the language APIs are developed using one of two methods, using libmysql
or by building a native driver. The two solutions offer different benefits:
- Using
libmysql
offers complete compatibility with MariaDB as it uses the same libraries as the MariaDB client applications. However, the feature set is limited to the implementation and interfaces exposed throughlibmysql
and the performance may be lower as data is copied between the native language, and the MariaDB API components. MariaDB Connector/C is a possible alternative to usinglibmysql
.
- Native drivers are an implementation of the MariaDB network protocol entirely within the host language or environment. Native drivers are fast, as there is less copying of data between components, and they can offer advanced functionality not available through the standard MariaDB API. Native drivers are also easier to build and deploy, as you do not need a copy of the MariaDB client libraries to build the native driver components.
A list of many of the libraries and interfaces available for MariaDB are shown in the table. See Table 20.1, "MySQL APIs and Interfaces".
Table 20.1. MariaDB APIs and Interfaces
Environment | API | Type | Notes |
---|---|---|---|
Ada | MySQL Bindings for GNU Ada | libmysql
| See MySQL Bindings for GNU Ada |
C | Connector/C | Replacement for libmysql
| See , "MySQL Connector/C". |
C++ | Connector/C++ | libmysql
| See , "MySQL Connector/C++". |
MySQL++ | libmysql
| See MySQL++ Web site. | |
MySQL wrapped | libmysql
| See MySQL wrapped. | |
Cocoa | MySQL-Cocoa | libmysql
| Compatible with the Objective-C Cocoa environment. See http://mysql-cocoa.sourceforge.net/ |
D | MySQL for D | libmysql
| See MySQL for D. |
Eiffel | Eiffel MySQL | libmysql
| See , "MySQL Eiffel Wrapper". |
Erlang | erlang-mysql-driver
| libmysql
| See erlang-mysql-driver .
|
Haskell | Haskell MariaDB Bindings | Native Driver | See Brian O'Sullivan's pure Haskell MariaDB bindings. |
hsql-mysql
| libmysql
| See MySQL driver for Haskell . | |
Java/JDBC | Connector/J | Native Driver | See , "MySQL Connector/J". |
Kaya | MyDB | libmysql
| See MyDB. |
Lua | LuaSQL | libmysql
| See LuaSQL. |
.NET/Mono | Connector/Net | Native Driver | See , "MySQL Connector/Net". |
Objective Caml | MySQL Bindings for OBjective Caml | libmysql
| See MySQL Bindings for Objective Caml. |
Octave | Database bindings for GNU Octave | libmysql
| See Database bindings for GNU Octave. |
ODBC | Connector/ODBC | libmysql
| See , "MySQL Connector/ODBC". |
OpenOffice | MySQL Connector/OpenOffice.org | libmysql
| Direct connectivity, without using JDBC/ODBC. See , "MySQL Connector/OpenOffice.org". |
Perl | DBI /DBD::mysql
| libmysql
| See , "MySQL Perl API". |
Net::MySQL
| Native Driver | See Net::MySQL at CPAN
| |
PHP | MariaDB , ext/mysql interface (deprecated)
| libmysql
| See , "Original MariaDB API (MariaDB )".
|
mysqli , ext/mysqli interface
| libmysql
| See , "MySQL Improved Extension (Mysqli )".
| |
PDO_MYSQL
| libmysql
| See , "MySQL Functions (PDO_MYSQL) (MySQL (PDO) )".
| |
PDO mysqlnd | Native Driver | See PHP PDO mysqlnd .
| |
Python | MySQLdb | libmysql
| See , "MySQL Python API". |
Ruby | MySQL/Ruby | libmysql
| Uses libmysql . See , "The MySQL/Ruby API".
|
Ruby/MySQL | Native Driver | See , "The Ruby/MySQL API". | |
Scheme | Myscsh
| libmysql
| See Myscsh .
|
SPL | sql_mysql
| libmysql
| See sql_mysql for SPL.
|
Tcl | MySQLtcl | libmysql
| See , "MySQL Tcl API". |
Table 20.2. MariaDB Connector Versions and MariaDB Server Versions
Connector | Connector version | MySQL Server version |
---|---|---|
Connector/C++ | GA | 5.6, 5.5, 5.4, 5.1 |
Connector/J | 5.1.8 | 5.6, 5.5, 5.4, 5.1, 5.0, 4.1 |
Connector/Net | 6.5 | 5.6, 5.5, 5.4, 5.1, 5.0 |
Connector/Net | 6.4 | 5.6, 5.5, 5.4, 5.1, 5.0 |
Connector/Net | 6.3 | 5.6, 5.5, 5.4, 5.1, 5.0 |
Connector/Net | (No longer supported) | 5.6, 5.5, 5.4, 5.1, 5.0 |
Connector/Net | (No longer supported) | 5.6, 5.5, 5.4, 5.1, 5.0 |
Connector/Net | (No longer supported) | 5.6, 5.5, 5.4, 5.1, 5.0 |
Connector/Net | (No longer supported) | 5.6, 5.5, 5.4, 5.1, 5.0 |
Connector/Net | (No longer supported) | 5.0, 4.0 |
Connector/ODBC | 5.1 | 5.6, 5.5, 5.4, 5.1, 5.0, 4.1.1+ |
Connector/ODBC | (Unicode not supported) | 5.6, 5.5, 5.4, 5.1, 5.0, 4.1 |
Connector/OpenOffice.org | GA | 5.6, 5.5, 5.4, 5.1, 5.0 |
MySQL Connector/ODBC
- Connector/ODBC Versions
- Connector/ODBC Introduction
- Connector/ODBC Installation
- Connector/ODBC Configuration
- Connector/ODBC Examples
- Connector/ODBC Reference
- Connector/ODBC Notes and Tips
- Connector/ODBC Support
- Connector/ODBC Introduction
The MariaDB Connector/ODBC is the name for the family of MariaDB ODBC drivers (previously called MyODBC drivers) that provide access to a MariaDB database using the industry standard Open Database Connectivity (ODBC) API. This reference covers Connector/ODBC 3.51 and Connector/ODBC 5.1. Both releases provide an ODBC compliant interface to MariaDB Server.
MySQL Connector/ODBC provides both driver-manager based and native interfaces to the MariaDB database, with full support for MariaDB functionality, including stored procedures, transactions and, with Connector/ODBC 5.1, full Unicode compliance.
For more information on the ODBC API standard and how to use it, refer to http://support.microsoft.com/kb/110093.
The application development section of the ODBC API reference assumes a good working knowledge of C, general DBMS, and a familiarity with MySQL. For more information about MariaDB functionality and its syntax, refer to http://dev.mysql.com/doc/.
Typically, you need to install Connector/ODBC only on Windows machines. For Unix and Mac OS X, you can use the native MariaDB network or named pipe to communicate with your MariaDB database. You may need Connector/ODBC for Unix or Mac OS X if you have an application that requires an ODBC interface to communicate with the database. Applications that require ODBC to communicate with MariaDB include ColdFusion, Microsoft Office, and Filemaker Pro.
Key connector/ODBC topics include:
- Installing Connector/ODBC: , "Connector/ODBC Installation".
- The configuration options: , "Connector/ODBC Connection Parameters".
- An example that connects to a MariaDB database from a Windows host: , "Step-by-step Guide to Connecting to a MariaDB Database through Connector/ODBC".
- An example that uses Microsoft Access as an interface to a MariaDB database: , "Using Connector/ODBC with Microsoft Access".
- General tips and notes, including how to obtain the last auto-increment ID: , "Connector/ODBC General Functionality".
- Application specific usage tips and notes: , "Connector/ODBC Application-Specific Tips".
- A FAQ (Frequently Asked Questions) list: , "Connector/ODBC Errors and Resolutions (FAQ)".
- Additional Connector/ODBC support options: , "Connector/ODBC Support".
Connector/ODBC Versions
There are currently two version of Connector/ODBC available:
- Connector/ODBC 5.1, currently in GA status, is a partial rewrite of the of the 3.51 code base, and is designed to work with MariaDB versions 4.1.1 and newer.
Connector/ODBC 5.1 also includes the following changes and improvements over the 3.51 release:
- Improved support on Windows 64-bit platforms.
- Full Unicode support at the driver level. This includes support for the
SQL_WCHAR
data type, and support for Unicode login, password and DSN configurations. For more information,. see Microsoft Knowledgebase Article #716246. - Support for the
SQL_NUMERIC_STRUCT
data type, which provides easier access to the precise definition of numeric values. For more information, see Microsoft Knowledgebase Article #714556 - Native Windows setup library. This replaces the Qt library based interface for configuring DSN information within the ODBC Data Sources application.
- Support for the ODBC descriptor, which improves the handling and metadata of columns and parameter data. For more information, see Microsoft Knowledgebase Article #716339.
- Connector/ODBC 3.51 is the current release of the 32-bit ODBC driver, also known as the MariaDB ODBC 3.51 driver. Connector/ODBC 3.51 has support for ODBC 3.5x specification level 1 (complete core API + level 2 features) to continue to provide all functionality of ODBC for accessing MySQL.
The manual for versions of Connector/ODBC older than 3.51 can be located in the corresponding binary or source distribution. Please note that versions of Connector/ODBC earlier than the 3.51 revision were not fully compliant with the ODBC specification.Note
From this section onward, the primary focus of this guide is the Connector/ODBC 3.51 and Connector/ODBC 5.1 drivers.Note
Version numbers for MariaDB products are formatted as X.X.X. However, Windows tools (Control Panel, properties display) may show the version numbers as XX.XX.XX. For example, the official MariaDB formatted version number 5.0.9 may be displayed by Windows tools as 5.00.09. The two versions are the same; only the number display format is different.
Connector/ODBC Introduction
ODBC (Open Database Connectivity) provides a way for client programs to access a wide range of databases or data sources. ODBC is a standardized API that enables connections to SQL database servers. It was developed according to the specifications of the SQL Access Group and defines a set of function calls, error codes, and data types that can be used to develop database-independent applications. ODBC usually is used when database independence or simultaneous access to different data sources is required.
For more information about ODBC, refer to http://support.microsoft.com/kb/110093.
General Information About ODBC and Connector/ODBC
Open Database Connectivity (ODBC) is a widely accepted application-programming interface (API) for database access. It is based on the Call-Level Interface (CLI) specifications from X/Open and ISO/IEC for database APIs and uses Structured Query Language (SQL) as its database access language.
A survey of ODBC functions supported by Connector/ODBC is given at , "Connector/ODBC API Reference". For general information about ODBC, see http://support.microsoft.com/kb/110093.
Connector/ODBC Architecture
The Connector/ODBC architecture is based on five components, as shown in the following diagram:
- Application:
The Application uses the ODBC API to access the data from the MariaDB server. The ODBC API in turn uses the communicates with the Driver Manager. The Application communicates with the Driver Manager using the standard ODBC calls. The Application does not care where the data is stored, how it is stored, or even how the system is configured to access the data. It needs to know only the Data Source Name (DSN).
A number of tasks are common to all applications, no matter how they use ODBC. These tasks are:
- Selecting the MariaDB server and connecting to it
- Submitting SQL statements for execution
- Retrieving results (if any)
- Processing errors
- Committing or rolling back the transaction enclosing the SQL statement
- Disconnecting from the MariaDB server
Because most data access work is done with SQL, the primary tasks for applications that use ODBC are submitting SQL statements and retrieving any results generated by those statements.
- Driver manager:
The Driver Manager is a library that manages communication between application and driver or drivers. It performs the following tasks:
- Resolves Data Source Names (DSN). The DSN is a configuration string that identifies a given database driver, database, database host and optionally authentication information that enables an ODBC application to connect to a database using a standardized reference.
Because the database connectivity information is identified by the DSN, any ODBC compliant application can connect to the data source using the same DSN reference. This eliminates the need to separately configure each application that needs access to a given database; instead you instruct the application to use a pre-configured DSN.
- Loading and unloading of the driver required to access a specific database as defined within the DSN. For example, if you have configured a DSN that connects to a MariaDB database then the driver manager will load the Connector/ODBC driver to enable the ODBC API to communicate with the MariaDB host.
- Processes ODBC function calls or passes them to the driver for processing.
- Resolves Data Source Names (DSN). The DSN is a configuration string that identifies a given database driver, database, database host and optionally authentication information that enables an ODBC application to connect to a database using a standardized reference.
- Connector/ODBC Driver:
The Connector/ODBC driver is a library that implements the functions supported by the ODBC API. It processes ODBC function calls, submits SQL requests to MariaDB server, and returns results back to the application. If necessary, the driver modifies an application's request so that the request conforms to syntax supported by MySQL.
- DSN Configuration:
The ODBC configuration file stores the driver and database information required to connect to the server. It is used by the Driver Manager to determine which driver to be loaded according to the definition in the DSN. The driver uses this to read connection parameters based on the DSN specified. For more information, , "Connector/ODBC Configuration".
- MySQL Server:
The MariaDB database where the information is stored. The database is used as the source of the data (during queries) and the destination for data (during inserts and updates).
ODBC Driver Managers
An ODBC Driver Manager is a library that manages communication between the ODBC-aware application and any drivers. Its main functionality includes:
- Resolving Data Source Names (DSN).
- Driver loading and unloading.
- Processing ODBC function calls or passing them to the driver.
Both Windows and Mac OS X include ODBC driver managers with the operating system. Most ODBC Driver Manager implementations also include an administration application that makes the configuration of DSN and drivers easier. Examples and information on these managers, including Unix ODBC driver managers are listed below:
- Microsoft Windows ODBC Driver Manager (
odbc32.dll
), http://support.microsoft.com/kb/110093. - Mac OS X includes
ODBC Administrator
, a GUI application that provides a simpler configuration mechanism for the Unix iODBC Driver Manager. You can configure DSN and driver information either through ODBC Administrator or through the iODBC configuration files. This also means that you can test ODBC Administrator configurations using theiodbctest
command. http://www.apple.com. unixODBC
Driver Manager for Unix (libodbc.so
). See http://www.unixodbc.org, for more information. TheunixODBC
Driver Manager includes the Connector/ODBC driver 3.51 in the installation package, starting with versionunixODBC
2.1.2.iODBC
ODBC Driver Manager for Unix (libiodbc.so
), see http://www.iodbc.org, for more information.
Connector/ODBC Installation
- Installing Connector/ODBC from a Binary Distribution on Windows
- Installing Connector/ODBC from a Binary Distribution on Unix
- Installing Connector/ODBC from a Binary Distribution on Mac OS X
- Installing Connector/ODBC from a Source Distribution on Windows
- Installing Connector/ODBC from a Source Distribution on Unix
- Installing Connector/ODBC from the Development Source Tree
- Installing Connector/ODBC from a Binary Distribution on Unix
You can install the Connector/ODBC drivers using two different methods, a binary installation and a source installation. The binary installation is the easiest and most straightforward method of installation. Use the source installation methods on platforms where a binary installation package is not available, or in situations where you want to customize or modify the installation process or Connector/ODBC drivers before installation.
Where to Get Connector/ODBC
You can get a copy of the latest version of Connector/ODBC binaries and sources from our Web site at http://dev.mysql.com/downloads/connector/odbc/.
For more information about Connector/ODBC, visit http://www.mysql.com/products/myodbc/.
For more information about licensing, visit http://www.mysql.com/company/legal/licensing/.
Supported Platforms
Connector/ODBC can be used on all major platforms supported by MySQL. You can install it on:
- Windows 95, 98, Me, NT, 2000, XP, 2003, Vista and 7
- All Unix-like Operating Systems, including: AIX, Amiga, BSDI, DEC, FreeBSD, HP-UX 10/11, Linux, NetBSD, OpenBSD, OS/2, SGI Irix, Solaris, SunOS, SCO OpenServer, SCO UnixWare, Tru64 Unix
- Mac OS X and Mac OS X Server
Using a binary distribution offers the most straightforward method for installing Connector/ODBC. If you want more control over the driver, the installation location and or to customize elements of the driver you will need to build and install from the source.
If a binary distribution is not available for a particular platform build the driver from the original source code. You can contribute the binaries you create to MariaDB by sending a mail message to <myodbc@lists.mysql.com>
, so that it becomes available for other users.Note
On all non-Windows platforms except Mac OS X, the driver is built against unixODBC
and is expecting a 2-byte SQLWCHAR
, not 4 bytes as iODBC
is using. For this reason, the binaries are only compatible with unixODBC
and you will need to recompile the driver against iODBC
to use them together. For further information see , "ODBC Driver Managers".
For further instructions:
Platform | Binary | Source |
---|---|---|
Windows | Installation Instructions | Build Instructions |
Unix/Linux | Installation Instructions | Build Instructions |
Mac OS X | Installation Instructions |
Installing Connector/ODBC from a Binary Distribution on Windows
- Installing the Windows Connector/ODBC Driver using an installer
- Installing the Windows Connector/ODBC Driver using the Zipped DLL package
Before installing the Connector/ODBC drivers on Windows, ensure that your Microsoft Data Access Components (MDAC) are up to date. You can obtain the latest version from the Microsoft Data Access and Storage Web site.
There are three available distribution types to use when installing for Windows. The contents in each case are identical, it is only the installation method which is different.
- Zipped installer consists of a Zipped package containing a standalone installation application. To install from this package, you must unzip the installer, and then run the installation application. See , "Installing the Windows Connector/ODBC Driver using an installer" to complete the installation.
- MSI installer, an installation file that can be used with the installer included in Windows 2000, Windows XP and Windows Server 2003. See , "Installing the Windows Connector/ODBC Driver using an installer" to complete the installation.
- Zipped DLL package, containing the DLL files that need must be manually installed. See , "Installing the Windows Connector/ODBC Driver using the Zipped DLL package" to complete the installation.
An OLEDB/ODBC driver for Windows 64-bit is available from Microsoft Downloads.
Installing the Windows Connector/ODBC Driver using an installer
The installer packages offer a very simple method for installing the Connector/ODBC drivers. If you have downloaded the zipped installer then you must extract the installer application. The basic installation process is identical for both installers.
Follow these steps to complete the installation:
- Double-click the standalone installer that you extracted, or the MSI file you downloaded.
- The MariaDB Connector/ODBC 3.51 - Setup Wizard will start. Click the Next button to begin the installation process.
- You will need to choose the installation type. The Typical installation provides the standard files you will need to connect to a MariaDB database using ODBC. The Complete option installs all the available files, including debug and utility components. It is recommended you choose one of these two options to complete the installation. If choose one of these methods, click Next and then proceed to step 5.
You can also choose a Custom installation, which enables you to select the individual components to install. You have chosen this method, click Next and then proceed to step 4.
- If you have chosen a custom installation, use the pop-ups to select which components to install and then click Next to install the necessary files.
- Once the files have copied to your machine, the installation is complete. Click Finish to exit the installer.
Now the installation is complete, you can continue to configure your ODBC connections using , "Connector/ODBC Configuration".
Installing the Windows Connector/ODBC Driver using the Zipped DLL package
If you have downloaded the Zipped DLL package then you must install the individual files required for Connector/ODBC operation manually. Once you have unzipped the installation files, you can either perform this operation by hand, executing each statement individually, or you can use the included Batch file to perform an installation to the default locations.Note
The following instructions will only work for 32-bit Windows systems. If you have a 64-bit Windows system you are advised to use the MSI installer, which will install both the 32-bit and 64-bit drivers to the correct locations.
To install using the Batch file:
- Unzip the Connector/ODBC Zipped DLL package.
- Open a Command Prompt.
- Change to the directory created when you unzipped the Connector/ODBC Zipped DLL package.
- Run
Install.bat:
C:\>
Install.bat
This will copy the necessary files into the default location, and then register the Connector/ODBC driver with the Windows ODBC manager.
Changing or adding a new DSN (data source name) may be accomplished using either the GUI, or from the command-line using myodbc3i.exe with Connector/ODBC 3.51, or myodbc-installer.exe with Connector/ODBC 5.1.
To copy the files to an alternative location - for example, to run or test different versions of the Connector/ODBC driver on the same machine, then you must copy the files by hand. It is however not recommended to install these files in a nonstandard location. To copy the files by hand to the default installation location, use the following steps:
- Unzip the Connector/ODBC Zipped DLL package.
- Open a Command Prompt.
- Change to the directory created when you unzipped the Connector/ODBC Zipped DLL package.
- Copy the library files to a suitable directory. The default is to copy them into the default Windows system directory
\Windows\System32
:C:\>
copy lib\myodbc3S.dll \Windows\System32
C:\>copy lib\myodbc3S.lib \Windows\System32
C:\>copy lib\myodbc3.dll \Windows\System32
C:\>copy lib\myodbc3.lib \Windows\System32
- Copy the Connector/ODBC tools. These must be placed into a directory that is in the system
PATH
. The default is to install these into the Windows system directory\Windows\System32
:C:\>
copy bin\myodbc3i.exe \Windows\System32
C:\>copy bin\myodbc3m.exe \Windows\System32
C:\>copy bin\myodbc3c.exe \Windows\System32
- Optionally copy the help files. For these files to be accessible through the help system, they must be installed in the Windows system directory:
C:\>
copy doc\*.hlp \Windows\System32
- Finally, you must register the Connector/ODBC driver with the ODBC manager:
C:\>
myodbc3i -a -d -t'MySQL ODBC 3.51 Driver;\ DRIVER=myodbc3.dll;SETUP=myodbc3S.dll'
You must change the references to the DLL files and command location in the above statement if you have not installed these files into the default location.
Installing Connector/ODBC from a Binary Distribution on Unix
- Installing Connector/ODBC from a Binary Tarball Distribution
- Installing Connector/ODBC from an RPM Distribution
There are two methods available for installing Connector/ODBC on Unix from a binary distribution. For most Unix environments you will need to use the tarball distribution. For Linux systems, there is also an RPM distribution available.Note
To install Connector/ODBC 5.1 on Unix you require unixODBC 2.2.12 or later to be installed.
Installing Connector/ODBC from a Binary Tarball Distribution
To install the driver from a tarball distribution (.tar.gz
file), download the latest version of the driver for your operating system and follow these steps that demonstrate the process using the Linux version of the tarball:
shell>su root
shell>gunzip mysql-connector-odbc-3.51.11-i686-pc-linux.tar.gz
shell>tar xvf mysql-connector-odbc-3.51.11-i686-pc-linux.tar
shell>cd mysql-connector-odbc-3.51.11-i686-pc-linux
Read the installation instructions in the INSTALL
file and execute these commands.
Then proceed on to , "Configuring a Connector/ODBC DSN on Unix", to configure the DSN for Connector/ODBC. For more information, refer to the INSTALL
file that comes with your distribution.
Installing Connector/ODBC from an RPM Distribution
To install or upgrade Connector/ODBC from an RPM distribution on Linux, simply download the RPM distribution of the latest version of Connector/ODBC and follow the instructions below. Use su root to become root
, then install the RPM file.
If you are installing for the first time:
shell>su root
shell>rpm -ivh mysql-connector-odbc-3.51.12.i386.rpm
If the driver exists, upgrade it like this:
shell>su root
shell>rpm -Uvh mysql-connector-odbc-3.51.12.i386.rpm
If there is any dependency error for MariaDB client library, libmysqlclient
, simply ignore it by supplying the --nodeps
option, and then make sure the MariaDB client shared library is in the path or set through LD_LIBRARY_PATH
.
This installs the driver libraries and related documents to /usr/local/lib
and /usr/share/doc/MyODBC
, respectively. Proceed onto , "Configuring a Connector/ODBC DSN on Unix".
To uninstall the driver, become root
and execute an rpm command:
shell>su root
shell>rpm -e mysql-connector-odbc
Installing Connector/ODBC from a Binary Distribution on Mac OS X
Mac OS X is based on the FreeBSD operating system, and you can normally use the MariaDB network port for connecting to MariaDB servers on other hosts. Installing the Connector/ODBC driver lets you connect to MariaDB databases on any platform through the ODBC interface. If your application requires an ODBC interface, install the Connector/ODBC driver. Applications that require or can use ODBC (and therefore the Connector/ODBC driver) include ColdFusion, Filemaker Pro, 4th Dimension and many other applications.
Mac OS X includes its own ODBC manager, based on the iODBC
manager. Mac OS X includes an administration tool that provides easier administration of ODBC drivers and configuration, updating the underlying iODBC
configuration files.
The method for installing Connector/ODBC on Mac OS X depends on the version on Connector/ODBC you are using. For Connector/ODBC 3.51.14 and later, the package is provided as a compressed tar archive that you must manually install. For Connector/ODBC 3.51.13 and earlier the software was provided on a compressed disk image (.dmg
) file and included an installer.
In either case, the driver is designed to work with the iODBC driver manager included with Mac OS X.
To install Connector/ODBC 3.51.14 and later:
- Download the installation file. Note that versions are available for both PowerPC and Intel platforms.
- Extract the archive:
shell> tar zxf mysql-connector-odbc-
3.51.16
-osx10.4-x86-32bit.tar.gz - The directory created will contain two subdirectories,
lib
andbin
. You need to copy these to a suitable location such as/usr/local
:shell> cp bin/* /usr/local/bin shell> cp lib/* /usr/local/lib
- Finally, you must register the driver with iODBC using the myodbc3i tool you just installed:
shell> myodbc3i -a -d -t'MySQL ODBC 3.51 Driver;Driver=/usr/local/lib/libmyodbc3.so;Setup=/usr/local/lib/libmyodbc3S.so'
You can verify the installed drivers either by using the ODBC Administrator application or the myodbc3i utility:
shell> myodbc3i -q -d
To install Connector/ODBC 3.51.13 and earlier, follow these steps:
- Download the file to your computer and double-click the downloaded image file.
- Within the disk image you will find an installer package (with the
.pkg
extension). Double-click on this file to start the Mac OS X installer. - You will be presented with the installer welcome message. Click the Continue button to begin the installation process.
- Please take the time to read the Important Information as it contains guidance on how to complete the installation process. Once you have read the notice and collected the necessary information, click Continue.
- Connector/ODBC drivers are made available under the GNU General Public License. Please read the license if you are not familiar with it before continuing installation. Click Continue to approve the license (you will be asked to confirm that decision) and continue the installation.
- Choose a location to install the Connector/ODBC drivers and the ODBC Administrator application. You must install the files onto a drive with an operating system and you may be limited in the choices available. Select the drive you want to use, and then click Continue.
- The installer will automatically select the files that need to be installed on your machine. Click Install to continue. The installer will copy the necessary files to your machine. A progress bar will be shown indicating the installation progress.
- When installation has been completed you will get a window like the one shown below. Click Close to close and quit the installer.
Installing Connector/ODBC from a Source Distribution on Windows
You only need to install Connector/ODBC from source on Windows to change or modify the source or installation. If you are unsure whether to install from source, please use the binary installation detailed in , "Installing Connector/ODBC from a Binary Distribution on Windows".
Installing Connector/ODBC from source on Windows requires a number of different tools and packages:
- MDAC, Microsoft Data Access SDK from http://support.microsoft.com/kb/110093.
- Suitable C compiler, such as Microsoft Visual C++ or the C compiler included with Microsoft Visual Studio.
Microsoft Visual Studio 7 and 8 are preferred, and well-tested.
- Connector/ODBC 5.1:
CMake
.Connector/ODBC 3.51: A compatible
make
tool. Microsoft'snmake
is used in the examples in this section. - MySQL client libraries and include files from MariaDB 4.0.0 or higher. (Preferably MariaDB 4.0.16 or higher). This is required because Connector/ODBC uses new calls and structures that exist only starting from this version of the library. To get the client libraries and include files, visit http://dev.mysql.com/downloads/.
Building Connector/ODBC 5.1
You need to have the environment variables set for the Visual Studio toolchain. Visual Studio includes a batch file to set these for you, and installs a Start menu shortcut that opens a command prompt with these variables set.
You need to set MYSQL_DIR
to the MariaDB server installation path, while using the short-style file names. For example:
C:\> set MYSQL_DIR=C:\PROGRA~1\MySQL\MYSQLS~1.0
Build Connector/ODBC using the 'cmake' command-line tool by executing the following from the source root directory (in a command prompt window):
C:\> cmake -G 'Visual Studio 8 2005'
This produces a project file that you can open with Visual Studio, or build from the command line with either of the following commands:
C:\>devenv.com MySQL_Connector_ODBC.sln /build Release
C:\>devenv.com MySQL_Connector_ODBC.sln /build RelWithDebInfo
To compile the 'Debug' build, you must set the cmake build type so that the correct version of the MariaDB client libraries are used:
C:\>cmake -G 'Visual Studio 8 2005' -DCMAKE_BUILD_TYPE=Debug
C:\>devenv.com MySQL_Connector_ODBC.sln /build Debug
Upon completion, you will find the executables in the bin/
and lib/
sub-directories.
See , "Installing the Windows Connector/ODBC Driver using the Zipped DLL package" to complete the installation.
Building Connector/ODBC 3.51
Connector/ODBC source distributions include Makefiles
that require the nmake or other make
utility. In the distribution, you can find Makefile
for building the release version and Makefile_debug
for building debugging versions of the driver libraries and DLLs.
To build the driver, use this procedure:
- Download and extract the sources to a folder, then change directory into that folder. The following command assumes the folder is named
myodbc3-src
:
C:\>
cd myodbc3-src
- Edit
Makefile
to specify the correct path for the MariaDB client libraries and header files. Then use the following commands to build and install the release version:C:\>
nmake -f Makefile
C:\>nmake -f Makefile install
nmake -f Makefile builds the release version of the driver and places the binaries in subdirectory called
Release
.nmake -f Makefile install installs (copies) the driver DLLs and libraries (
myodbc3.dll
,myodbc3.lib
) to your system directory. - To build the debug version, use
Makefile_Debug
rather thanMakefile
, as shown below:C:\>
nmake -f Makefile_debug
C:\>nmake -f Makefile_debug install
- You can clean and rebuild the driver by using:
C:\>
nmake -f Makefile clean
C:\>nmake -f Makefile install
- Make sure to specify the correct MariaDB client libraries and header files path in the Makefiles (set the
MYSQL_LIB_PATH
andMYSQL_INCLUDE_PATH
variables). The default header file path is assumed to beC:\mysql\include
. The default library path is assumed to beC:\mysql\lib\opt
for release DLLs andC:\mysql\lib\debug
for debug versions. - For the complete usage of nmake, visit http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vcce4/html/evgrfRunningNMAKE.asp.
- If you are using the Subversion tree for compiling, all Windows-specific
Makefiles
are named asWin_Makefile*
.
After the driver libraries are copied/installed to the system directory, you can test whether the libraries are properly built by using the samples provided in the samples
subdirectory:
C:\>cd samples
C:\>nmake -f Makefile all
Installing Connector/ODBC from a Source Distribution on Unix
- Typical cmake Options
- Typical configure Options
- Additional configure Options
- Building and Compilation
- Building Shared Libraries
- Installing Driver Libraries
- Testing Connector/ODBC on Unix
- Building Connector/ODBC from Source on Mac OS X
- Building Connector/ODBC from Source on HP-UX
- Building Connector/ODBC from Source on AIX
- Typical configure Options
As of Connector/5.1.9, the build system on Linux changed, and now uses CMake instead of autoconf (configure). The manual refers to both methods.
You need the following tools to build MariaDB from source on Unix:
- A working ANSI C++ compiler. GCC 4.2.1 or later, Sun Studio 10 or later, Visual Studio 2008 or later, and many current vendor-supplied compilers are known to work.
- A good make program. GNU make is always recommended and is sometimes required.
- CMake, as of Connector/ODBC 5.1.9.
- MySQL client libraries and include files from MariaDB 4.0.0 or higher. (Preferably MariaDB 4.0.16 or higher). This is required because Connector/ODBC uses new calls and structures that exist only starting from this version of the library. To get the client libraries and include files, visit http://dev.mysql.com/downloads/.
If you have built your own MariaDB server or client libraries from source using the GNU autotools, you must use the
--enable-thread-safe-client
option to configure when the libraries were built. No special option is needed if you configure with CMake.Also, ensure that the
libmysqlclient
library was built and installed as a shared library. - A compatible ODBC manager must be installed. Connector/ODBC is known to work with the
iODBC
andunixODBC
managers. See , "ODBC Driver Managers", for more information. - If you are using a character set that isn't compiled into the MariaDB client library, install the MariaDB character definitions from the
charsets
directory intoSHAREDIR
(by default,/usr/local/mysql/share/mysql/charsets
). These should be in place if you have installed the MariaDB server on the same machine. See , "Character Set Support" for more information on character set support.
Once you have all the required files, unpack the source files to a separate directory, you then have to run configure and build the library using make.
Typical cmake Options
CMake support on Unix exists as of Connector/ODBC 5.1.9.
iODBC
is the default ODBC library used by Connector/ODBC. Alternatively, unixODBC
may be used by passing in the appropriate option to CMake. For example:
shell> cmake -G 'Unix Makefiles' -DWITH_UNIXODBC=1
When you run cmake, you might add options to the command line. Here are some examples:
-DODBC_INCLUDES=
: Used when the ODBC include directory is not found within the system's PATH.dir_name
-DODBC_LIB_DIR=
: Used when the ODBC library directory is not found within the system's PATH.dir_name
-DWITH_UNIXODBC=
: Enables unixODBC support.1
Typical configure Options
autoconf (configure) is supported on Unix in Connector/ODBC 5.1.8 and below.
The configure script gives you a great deal of control over how you configure your Connector/ODBC build. Typically you do this using options on the configure command line. You can also affect configure using certain environment variables. For a list of options and environment variables supported by configure, run this command:
shell> ./configure --help
Some of the more commonly used configure options are described here:
- To compile Connector/ODBC, you need to supply the MariaDB client include and library files path using the
--with-mysql-path=
option, whereDIR
DIR
is the directory where MariaDB is installed.
MySQL compile options can be determined by running
.DIR
/bin/mysql_config - Supply the standard header and library files path for your ODBC Driver Manager (
iODBC
orunixODBC
).- If you are using
iODBC
andiODBC
is not installed in its default location (/usr/local
), you might have to use the--with-iodbc=
option, whereDIR
DIR
is the directory whereiODBC
is installed.
If the
iODBC
headers do not reside in
, you can use theDIR
/include--with-iodbc-includes=
option to specify their location.INCDIR
The applies to libraries. If they are not in
, you can use theDIR
/lib--with-iodbc-libs=
option.LIBDIR
- If you are using
unixODBC
, use the--with-unixODBC=
option (case sensitive) to make configure look forDIR
unixODBC
instead ofiODBC
by default,DIR
is the directory whereunixODBC
is installed.If the
unixODBC
headers and libraries aren't located in
andDIR
/include
, use theDIR
/lib--with-unixODBC-includes=
andINCDIR
--with-unixODBC-libs=
options.LIBDIR
- If you are using
- You might specify an installation prefix other than
/usr/local
. For example, to install the Connector/ODBC drivers in/usr/local/odbc/lib
, use the--prefix=/usr/local/odbc
option.
The final configuration command looks something like this:
shell>./configure --prefix=/usr/local \
--with-iodbc=/usr/local \
--with-mysql-path=/usr/local/mysql
Additional configure Options
There are a number of other options that you need, or want, to set when configuring the Connector/ODBC driver before it is built.
- To link the driver with MariaDB thread safe client libraries
libmysqlclient_r.so
orlibmysqlclient_r.a
, you must specify the following configure option:
--enable-thread-safe
and can be disabled (default) using
--disable-thread-safe
This option enables the building of the driver thread-safe library
libmyodbc3_r.so
from by linking with MariaDB thread-safe client librarylibmysqlclient_r.so
(The extensions are OS dependent).If the compilation with the thread-safe option fails, it may be because the correct thread-libraries on the system could not be located. Set the value of
LIBS
to point to the correct thread library for your system.LIBS='-lpthread' ./configure ..
- You can enable or disable the shared and static versions of Connector/ODBC using these options:
--enable-shared[=yes/no] --disable-shared --enable-static[=yes/no] --disable-static
- By default, all the binary distributions are built as nondebugging versions (configured with
--without-debug
).To enable debugging information, build the driver from a source distribution with the proper configuration option to enable debugging support. See , "MySQL Source-Configuration Options".
- This option is available only for source trees that have been obtained from the Subversion repository. This option does not apply to the packaged source distributions.
By default, the driver is built with the
--without-docs
option. If you would like the documentation to be built, then execute configure with:--with-docs
Building and Compilation
To build the driver libraries, you have to just execute make.
shell> make
If any errors occur, correct them and continue the build process. If you aren't able to build, then send a detailed email to <myodbc@lists.mysql.com>
for further assistance.
Building Shared Libraries
On most platforms, MariaDB does not build or support .so
(shared) client libraries by default. This is based on our experience of problems when building shared libraries.
In cases like this, you have to download the MariaDB distribution and configure it with these options:
--without-server --enable-shared
To build shared driver libraries, you must specify the --enable-shared
option for configure. By default, configure does not enable this option.
If you have configured with the --disable-shared
option, you can build the .so
file from the static libraries using the following commands:
shell>cd mysql-connector-odbc-3.51.01
shell>make
shell>cd driver
shell>CC=/usr/bin/gcc \
$CC -bundle -flat_namespace -undefined error \
-o .libs/libmyodbc3-3.51.01.so \
catalog.o connect.o cursor.o dll.o error.o execute.o \
handle.o info.o misc.o myodbc3.o options.o prepare.o \
results.o transact.o utility.o \
-L/usr/local/mysql/lib/mysql/ \
-L/usr/local/iodbc/lib/ \
-lz -lc -lmysqlclient -liodbcinst
Make sure to change -liodbcinst
to -lodbcinst
if you are using unixODBC
instead of iODBC
, and configure the library paths accordingly.
This builds and places the libmyodbc3-3.51.01.so
file in the .libs
directory. Copy this file to the Connector/ODBC library installation directory (/usr/local/lib
(or the lib
directory under the installation directory that you supplied with the --prefix
).
shell>cd .libs
shell>cp libmyodbc3-3.51.01.so /usr/local/lib
shell>cd /usr/local/lib
shell>ln -s libmyodbc3-3.51.01.so libmyodbc3.so
To build the thread-safe driver library:
shell>CC=/usr/bin/gcc \
$CC -bundle -flat_namespace -undefined error
-o .libs/libmyodbc3_r-3.51.01.so
catalog.o connect.o cursor.o dll.o error.o execute.o
handle.o info.o misc.o myodbc3.o options.o prepare.o
results.o transact.o utility.o
-L/usr/local/mysql/lib/mysql/
-L/usr/local/iodbc/lib/
-lz -lc -lmysqlclient_r -liodbcinst
Installing Driver Libraries
To install the driver libraries, execute the following command:
shell> make install
That command installs one of the following sets of libraries:
For Connector/ODBC 3.51:
libmyodbc3.so
libmyodbc3-3.51.01.so
, where 3.51.01 is the version of the driverlibmyodbc3.a
For thread-safe Connector/ODBC 3.51:
libmyodbc3_r.so
libmyodbc3-3_r.51.01.so
libmyodbc3_r.a
For more information on build process, refer to the INSTALL
file that comes with the source distribution. Note that if you are trying to use the make from Sun, you may end up with errors. On the other hand, GNU gmake should work fine on all platforms.
Testing Connector/ODBC on Unix
To run the basic samples provided in the distribution with the libraries that you built, use the following command:
shell> make test
Before running the tests, create the DSN 'myodbc3' in odbc.ini
and set the environment variable ODBCINI
to the correct odbc.ini
file; and MariaDB server is running. You can find a sample odbc.ini
with the driver distribution.
You can even modify the samples/run-samples
script to pass the desired DSN, UID, and PASSWORD values as the command-line arguments to each sample.
Building Connector/ODBC from Source on Mac OS X
To build the driver on Mac OS X (Darwin), make use of the following configure example:
shell>./configure --prefix=/usr/local
--with-unixODBC=/usr/local
--with-mysql-path=/usr/local/mysql
--disable-shared
--enable-gui=no
--host=powerpc-apple
The command assumes that the unixODBC
and MariaDB are installed in the default locations. If not, configure accordingly.
On Mac OS X, --enable-shared
builds .dylib
files by default. You can build .so
files like this:
shell>make
shell>cd driver
shell>CC=/usr/bin/gcc \
$CC -bundle -flat_namespace -undefined error
-o .libs/libmyodbc3-3.51.01.so *.o
-L/usr/local/mysql/lib/
-L/usr/local/iodbc/lib
-liodbcinst -lmysqlclient -lz -lc
To build the thread-safe driver library:
shell>CC=/usr/bin/gcc \
$CC -bundle -flat_namespace -undefined error
-o .libs/libmyodbc3-3.51.01.so *.o
-L/usr/local/mysql/lib/
-L/usr/local/iodbc/lib
-liodbcinst -lmysqlclienti_r -lz -lc -lpthread
Make sure to change the -liodbcinst
to -lodbcinst
in case of using unixODBC
instead of iODBC
and configure the libraries path accordingly.
In Apple's version of GCC, both cc and gcc are actually symbolic links to gcc3.
Copy this library to the $prefix/lib
directory and symlink to libmyodbc3.so
.
You can cross-check the output shared-library properties using this command:
shell> otool -LD .libs/libmyodbc3-3.51.01.so
Building Connector/ODBC from Source on HP-UX
To build the driver on HP-UX 10.x or 11.x, make use of the following configure example:
If using cc:
shell>CC='cc' \
CFLAGS='+z' \
LDFLAGS='-Wl,+b:-Wl,+s' \
./configure --prefix=/usr/local
--with-unixodbc=/usr/local
--with-mysql-path=/usr/local/mysql/lib/mysql
--enable-shared
--enable-thread-safe
If using gcc:
shell>CC='gcc' \
LDFLAGS='-Wl,+b:-Wl,+s' \
./configure --prefix=/usr/local
--with-unixodbc=/usr/local
--with-mysql-path=/usr/local/mysql
--enable-shared
--enable-thread-safe
Once the driver is built, cross-check its attributes using chatr .libs/libmyodbc3.sl to determine whether you need to have set the MariaDB client library path using the SHLIB_PATH
environment variable. For static versions, ignore all shared-library options and run configure with the --disable-shared
option.
Building Connector/ODBC from Source on AIX
To build the driver on AIX, make use of the following configure example:
shell>Note./configure --prefix=/usr/local
--with-unixodbc=/usr/local
--with-mysql-path=/usr/local/mysql
--disable-shared
--enable-thread-safe
For more information about how to build and set up the static and shared libraries across the different platforms refer to ' Using static and shared libraries across platforms'.
Installing Connector/ODBC from the Development Source Tree
CautionRead this section only if you are interested in helping us test our new code. To just get MariaDB Connector/ODBC up and running on your system, use a standard release distribution.
To obtain the most recent development source tree, first download and install Bazaar from the Bazaar VCS Web site. Bazaar is supported by any platform that supports Python, and is therefore compatible with any Linux, Unix, Windows or Mac OS X host. Instructions for downloading and installing Bazaar on the different platforms are available on the Bazaar Web site.
Build from the source trees requires the following tools:
- autoconf 2.52 (or newer)
- automake 1.4 (or newer)
- libtool 1.4 (or newer)
- m4
The most recent development source tree is available from our public Subversion trees at http://dev.mysql.com/tech-resources/sources.html.
To check out out the Connector/ODBC sources, change to the directory where you want the copy of the Connector/ODBC tree to be stored, then use the following command:
shell> bzr branch lp:myodbc
You should now have a copy of the entire Connector/ODBC source tree in the directory connector-odbc3
. To build from this source tree on Unix or Linux, follow these steps:
shell>cd myodbc
shell>aclocal
shell>autoheader
shell>libtoolize -c -f
shell>autoconf
shell>automake;
shell>./configure # Add your favorite options here
shell>make
For more information on how to build, refer to the INSTALL
file located in the same directory. For more information on options to configure, see , "Typical configure Options"
When the build is done, run make install to install the Connector/ODBC 3.51 driver on your system.
If you have gotten to the make stage and the distribution does not compile, please report it to <myodbc@lists.mysql.com>
.
On Windows, make use of Windows Makefiles WIN-Makefile
and WIN-Makefile_debug
in building the driver. For more information, see , "Installing Connector/ODBC from a Source Distribution on Windows".
After the initial checkout operation to get the source tree, run bzr pull periodically to update your source according to the latest version.
Connector/ODBC Configuration
- Data Source Names
- Connector/ODBC Connection Parameters
- Configuring a Connector/ODBC DSN on Windows
- Configuring a Connector/ODBC DSN on Mac OS X
- Configuring a Connector/ODBC DSN on Unix
- Connecting Without a Predefined DSN
- ODBC Connection Pooling
- Getting an ODBC Trace File
- Connector/ODBC Connection Parameters
Before you connect to a MariaDB database using the Connector/ODBC driver you must configure an ODBC Data Source Name. The DSN associates the various configuration parameters required to communicate with a database to a specific name. You use the DSN in an application to communicate with the database, rather than specifying individual parameters within the application itself. DSN information can be user specific, system specific, or provided in a special file. ODBC data source names are configured in different ways, depending on your platform and ODBC driver.
Data Source Names
A Data Source Name associates the configuration parameters for communicating with a specific database. Generally a DSN consists of the following parameters:
- Name
- Host Name
- Database Name
- Login
- Password
In addition, different ODBC drivers, including Connector/ODBC, may accept additional driver-specific options and parameters.
There are three types of DSN:
- A System DSN is a global DSN definition that is available to any user and application on a particular system. A System DSN can normally only be configured by a systems administrator, or by a user who has specific permissions that let them create System DSNs.
- A User DSN is specific to an individual user, and can be used to store database connectivity information that the user regularly uses.
- A File DSN uses a simple file to define the DSN configuration. File DSNs can be shared between users and machines and are therefore more practical when installing or deploying DSN information as part of an application across many machines.
DSN information is stored in different locations depending on your platform and environment.
Connector/ODBC Connection Parameters
You can specify the parameters in the following tables for Connector/ODBC when configuring a DSN:
Users on Windows can use the Options and Advanced panels when configuring a DSN to set these parameters; see the table for information on which options relate to which fields and check boxes. On Unix and Mac OS X, use the parameter name and value as the keyword/value pair in the DSN configuration. Alternatively, you can set these parameters within the InConnectionString
argument in the SQLDriverConnect()
call.
Table 20.3. Connector/ODBC DSN Configuration Options
Parameter | Default Value | Comment |
---|---|---|
user
| ODBC | The user name used to connect to MariaDB. |
uid
| ODBC | Synonymous with user . Added in 3.51.16.
|
server
| localhost
| The host name of the MariaDB server. |
database
| The default database. | |
option
| 0 | Options that specify how Connector/ODBC works. See below. |
port
| 3306 | The TCP/IP port to use if server is not localhost .
|
initstmt
| Initial statement. A statement to execute when connecting to MariaDB. In version 3.51 the parameter is called stmt . Note, the driver supports the initial statement being executed only at the time of the initial connection.
| |
password
| The password for the user account on server .
| |
pwd
| Synonymous with password . Added in 3.51.16.
| |
socket
| The Unix socket file or Windows named pipe to connect to if server is localhost .
| |
sslca
| The path to a file with a list of trust SSL CAs. Added in 3.51.16. | |
sslcapath
| The path to a directory that contains trusted SSL CA certificates in PEM format. Added in 3.51.16. | |
sslcert
| The name of the SSL certificate file to use for establishing a secure connection. Added in 3.51.16. | |
sslcipher
| A list of permissible ciphers to use for SSL encryption. The cipher list has the same format as the openssl ciphers command Added in 3.51.16.
| |
sslkey
| The name of the SSL key file to use for establishing a secure connection. Added in 3.51.16. | |
charset
| The character set to use for the connection. Added in 3.51.17. | |
sslverify
| If set to 1, the SSL certificate will be verified when used with the MariaDB connection. If not set, then the default behavior is to ignore SSL certificate verification. | |
readtimeout
| The timeout in seconds for attempts to read from the server. Each attempt uses this timeout value and there are retries if necessary, so the total effective timeout value is three times the option value. You can set the value so that a lost connection can be detected earlier than the TCP/IP Close_Wait_Timeout value of 10 minutes. This option works only for TCP/IP connections, and only for Windows prior to MariaDB 5.1.12. Corresponds to the MYSQL_OPT_READ_TIMEOUT option of the MariaDB Client Library. This option was added in Connector/ODBC 3.51.27.
| |
writetimeout
| The timeout in seconds for attempts to write to the server. Each attempt uses this timeout value and there are net_retry_count retries if necessary, so the total effective timeout value is net_retry_count times the option value. This option works only for TCP/IP connections, and only for Windows prior to MariaDB 5.1.12. Corresponds to the MYSQL_OPT_WRITE_TIMEOUT option of the MariaDB Client Library. This option was added in Connector/ODBC 3.51.27.
| |
interactive
| Enables the CLIENT_INTERACTIVE connection option of mysql_real_connect . |
The SSL configuration parameters can also be automatically loaded from a my.ini
or my.cnf
file.
The option
argument is used to tell Connector/ODBC that the client isn't 100% ODBC compliant. On Windows, you normally select options by toggling the check boxes in the connection screen, but you can also select them in the option
argument. The following options are listed in the order in which they appear in the Connector/ODBC connect screen.
Table 20.4. Connector/ODBC Option Flags
Flag Name | GUI Option | Constant Value | Description |
---|---|---|---|
FLAG_FIELD_LENGTH
| Do not Optimize Column Width | The client cannot handle that Connector/ODBC returns the real width of a column. This option was removed in 3.51.18. | |
FLAG_FOUND_ROWS
| Return Matching Rows | 2 | The client cannot handle that MariaDB returns the true value of affected rows. If this flag is set, MariaDB returns "found rows" instead. You must have MariaDB 3.21.14 or newer to get this to work. |
FLAG_DEBUG
| Trace Driver Calls To myodbc.log | Make a debug log in C:\myodbc.log on Windows, or /tmp/myodbc.log on Unix variants. This option was removed in Connector/ODBC 3.51.18.
| |
FLAG_BIG_PACKETS
| Allow Big Results | 8 | Do not set any packet limit for results and bind parameters. Without this option, parameter binding will be truncated to 255 characters. |
FLAG_NO_PROMPT
| Do not Prompt Upon Connect | 16 | Do not prompt for questions even if driver would like to prompt. |
FLAG_DYNAMIC_CURSOR
| Enable Dynamic Cursor | 32 | Enable or disable the dynamic cursor support. |
FLAG_NO_SCHEMA
| Ignore # in Table Name | 64 | Ignore use of database name in db_name.tbl_name.col_name .
|
FLAG_NO_DEFAULT_CURSOR
| User Manager Cursors | 128 | Force use of ODBC manager cursors (experimental). |
FLAG_NO_LOCALE
| Do not Use Set Locale | 256 | Disable the use of extended fetch (experimental). |
FLAG_PAD_SPACE
| Pad Char To Full Length | 512 | Pad CHAR columns to full column length.
|
FLAG_FULL_COLUMN_NAMES
| Return Table Names for SQLDescribeCol | 1024 | SQLDescribeCol() returns fully qualified column names.
|
FLAG_COMPRESSED_PROTO
| Use Compressed Protocol | 2048 | Use the compressed client/server protocol. |
FLAG_IGNORE_SPACE
| Ignore Space After Function Names | 4096 | Tell server to ignore space after function name and before "( " (needed by PowerBuilder). This makes all function names keywords.
|
FLAG_NAMED_PIPE
| Force Use of Named Pipes | 8192 | Connect with named pipes to a mysqld server running on NT. |
FLAG_NO_BIGINT
| Change BIGINT Columns to Int | 16384 | Change BIGINT columns to INT columns (some applications cannot handle BIGINT ).
|
FLAG_NO_CATALOG
| No Catalog | 32768 | Forces results from the catalog functions, such as SQLTables , to always return NULL and the driver to report that catalogs are not supported.
|
FLAG_USE_MYCNF
| Read Options From my.cnf
| 65536 | Read parameters from the [client] and [odbc] groups from my.cnf .
|
FLAG_SAFE
| Safe | 131072 | Add some extra safety checks. |
FLAG_NO_TRANSACTIONS
| Disable transactions | 262144 | Disable transactions. |
FLAG_LOG_QUERY
| Save queries to myodbc.sql
| 524288 | Enable query logging to c:\myodbc.sql (/tmp/myodbc.sql ) file. (Enabled only in debug mode.)
|
FLAG_NO_CACHE
| Do not Cache Result (forward only cursors) | 1048576 | Do not cache the results locally in the driver, instead read from server (mysql_use_result() ). This works only for forward-only cursors. This option is very important in dealing with large tables when you do not want the driver to cache the entire result set.
|
FLAG_FORWARD_CURSOR
| Force Use Of Forward Only Cursors | 2097152 | Force the use of Forward-only cursor type. In case of applications setting the default static/dynamic cursor type, and one wants the driver to use noncache result sets, then this option ensures the forward-only cursor behavior.
|
FLAG_AUTO_RECONNECT
| Enable auto-reconnect. | 4194304 | Enables auto-reconnection functionality. Do not use this option with transactions, since a auto reconnection during a incomplete transaction may cause corruption. Note that an auto-reconnected connection will not inherit the same settings and environment as the original. This option was added in Connector/ODBC 3.51.13. |
FLAG_AUTO_IS_NULL
| Flag Auto Is Null | 8388608 | When FLAG_AUTO_IS_NULL is set, the driver does not change the default value of sql_auto_is_null , leaving it at 1, so you get the MariaDB default, not the SQL standard behavior.
When Thus, omitting the flag disables the compatibility option and forces SQL standard behavior. See |
FLAG_ZERO_DATE_TO_MIN
| Return SQL_NULL_DATA for zero date | 16777216 | Translates zero dates (XXXX-00-00 ) into the minimum date values supported by ODBC, XXXX-01-01 . This resolves an issue where some statements will not work because the date returned and the minimum ODBC date value are incompatible. This option was added in Connector/ODBC 3.51.17.
|
FLAG_MIN_DATE_TO_ZERO
| Bind minimal date as zero date | 33554432 | Translates the minimum ODBC date value (XXXX-01-01 ) to the zero date format supported by MariaDB (XXXX-00-00 ). This resolves an issue where some statements will not work because the date returned and the minimum ODBC date value are incompatible. This option was added in Connector/ODBC 3.51.17.
|
FLAG_MULTI_STATEMENTS
| Allow multiple statements | 67108864 | Enables support for batched statements. This option was added in Connector/ODBC 3.51.18. |
FLAG_COLUMN_SIZE_S32
| Limit column size to 32-bit value | 134217728 | Limits the column size to a signed 32-bit value to prevent problems with larger column sizes in applications that do not support them. This option is automatically enabled when working with ADO applications. This option was added in Connector/ODBC 3.51.22. |
FLAG_NO_BINARY_RESULT
| Always handle binary function results as character data | 268435456 | When set this option disables charset 63 for columns with an empty org_table . This option was added in Connector/ODBC 3.51.26.
|
FLAG_DFLT_BIGINT_BIND_STR
| 536870912 | Causes BIGINT parameters to be bound as strings. Microsoft Access treats BIGINT as a string on linked tables. The value is read correctly, but bound as a string. This option is used automatically if the driver is used by Microsoft Access.
| |
FLAG_NO_INFORMATION_SCHEMA
| 1073741824 | Tells catalog functions not to use INFORMATION_SCHEMA , but rather use legacy algorithms. The trade-off here is usually speed for information quality. Using INFORMATION_SCHEMA is often slow, but the information obtained is more complete. |
To select multiple options, add together their values, using the numbers from the Constant Value
column in the table.Note
From version of MariaDB Connector/ODBC 5.1.6 onwards, you can use the flag name directly as a parameter in the connection string, by specifying the flag name without the FLAG_ prefix. So, in addition to using the options
parameter with various flags set, it is now possible to use the flags directly as parameters. For example, FIELD_LENGTH
, FOUND_ROWS
and DEBUG
could all be used as parameters.
The following table shows some recommended option
values for various configurations.
Configuration | Option Value |
---|---|
Microsoft Access, Visual Basic | 3 |
Driver trace generation (Debug mode) | 4 |
Microsoft Access (with improved DELETE queries) | 35 |
Large tables with too many rows | 2049 |
Sybase PowerBuilder | 135168 |
Query log generation (Debug mode) | 524288 |
Generate driver trace as well as query log (Debug mode) | 524292 |
Large tables with no-cache results | 3145731 |
Configuring a Connector/ODBC DSN on Windows
- Configuring a Connector/ODBC 3.51 DSN on Windows
- Configuring a Connector/ODBC 3.51 DSN on Windows, using the command-line
- Configuring a Connector/ODBC 5.1 DSN on Windows
- Configuring a Connector/ODBC 5.1 DSN on Windows, using the command-line
- Troubleshooting ODBC Connection Problems
- Configuring a Connector/ODBC 3.51 DSN on Windows, using the command-line
The ODBC Data Source Administrator
within Windows lets you create DSNs, check driver installation and configure ODBC systems such as tracing (used for debugging) and connection pooling.
Different editions and versions of Windows store the ODBC Data Source Administrator
in different locations depending on the version of Windows that you are using.
To open the ODBC Data Source Administrator
in Windows Server 2003:Tip
Because it is possible to create DSN using either the 32-bit or 64-bit driver, but using the same DNS identifier, it is advisable to include the driver being used within the DSN identifier. This will help you to identify the DSN when using it from applications such as Excel that are only compatible with the 32-bit driver. For example, you might add Using32bitCODBC
to the DSN identifier for the 32-bit interface and Using64bitCODBC
for those using the 64-bit Connector/ODBC driver.
- On the
Start
menu, chooseAdministrative Tools
, and then clickData Sources (ODBC)
.
To open the ODBC Data Source Administrator
in Windows 2000 Server or Windows 2000 Professional:
- On the
Start
menu, chooseSettings
, and then clickControl Panel
. - In
Control Panel
, clickAdministrative Tools
. - In
Administrative Tools
, clickData Sources (ODBC)
.
To open the ODBC Data Source Administrator
on Windows XP:
- On the
Start
menu, clickControl Panel
. - In the
Control Panel
when inCategory View
clickPerformance and Maintenance
and then clickAdministrative Tools.
. If you are viewing theControl Panel
inClassic View
, clickAdministrative Tools
. - In
Administrative Tools
, clickData Sources (ODBC)
.
Irrespective of your Windows version, you should be presented the ODBC Data Source Administrator
window:
Within Windows XP, you can add the Administrative Tools
folder to your Start menu to make it easier to locate the ODBC Data Source Administrator. To do this:
- Right-click the Start menu.
- Select
Properties
. - Click Customize....
- Select the Advanced tab.
- Within
Start menu items
, within theSystem Administrative Tools
section, selectDisplay on the All Programs menu
.
Within both Windows Server 2003 and Windows XP, consider permanently adding the ODBC Data Source Administrator
to your Start menu. To do this, locate the Data Sources (ODBC)
icon using the methods shown, then right-click on the icon and then choose Pin to Start Menu.
The interfaces for the 3.51 and 5.1 versions of the Connector/ODBC driver are different, although the fields and information that you need to enter remain the same.
To configure a DSN using Connector/ODBC 3.51.x or Connector/ODBC 5.1.0, see , "Configuring a Connector/ODBC 3.51 DSN on Windows".
To configure a DSN using Connector/ODBC 5.1.1 or later, see , "Configuring a Connector/ODBC 5.1 DSN on Windows".
Configuring a Connector/ODBC 3.51 DSN on Windows
To add or configure a Connector/ODBC 3.51 DSN on Windows, use either the command-line, or the ODBC Data Source Administrator
GUI.
- Open the
ODBC Data Source Administrator
. - To create a System DSN (which will be available to all users) , select the
System DSN
tab. To create a User DSN, which will be unique only to the current user, click the Add... button. - You will need to select the ODBC driver for this DSN.
Select
MySQL ODBC 3.51 Driver
, then click Finish. - You now need to configure the specific fields for the DSN you are creating through the
Add Data Source Name
dialog.In the Data Source Name box, enter the name of the data source to access. It can be any valid name that you choose.
- In the Description box, enter some text to help identify the connection.
- In the Server field, enter the name of the MariaDB server host to access. By default, it is
localhost
. - In the User field, enter the user name to use for this connection.
- In the Password field, enter the corresponding password for this connection.
- The Database pop-up should automatically populate with the list of databases that the user has permissions to access.
- Click OK to save the DSN.
A completed DSN configuration may look like this:
You can verify the connection using the parameters you have entered by clicking the Test button. If the connection could be made successfully, you will be notified with a Success; connection was made!
dialog.
If the connection failed, you can obtain more information on the test and why it may have failed by clicking the Diagnostics... button to show additional error messages.
You can configure a number of options for a specific DSN by using either the Connect Options or Advanced tabs in the DSN configuration dialog.
The three options you can configure are:
- Port sets the TCP/IP port number to use when communicating with MySQL. Communication with MariaDB uses port 3306 by default. If your server is configured to use a different TCP/IP port, you must specify that port number here.
- Socket sets the name or location of a specific socket or Windows pipe to use when communicating with MySQL.
- Initial Statement defines an SQL statement that will be executed when the connection to MariaDB is opened. You can use this to set MariaDB options for your connection, such as disabling autocommit.
- Character Set is a pop-up list from which you can select the default character set to be used with this connection. The Character Set option was added in 3.5.17.
The Advanced tab lets you configure Connector/ODBC connection parameters. Refer to , "Connector/ODBC Connection Parameters", for information about the meaning of these options.
Configuring a Connector/ODBC 3.51 DSN on Windows, using the command-line
Use myodbc3i.exe when configuring Connector/ODBC 3.51 from the command-line.
Execute myodbc3i.exe without arguments to view a list of available options.
Configuring a Connector/ODBC 5.1 DSN on Windows
The DSN configuration when using Connector/ODBC 5.1.1 and later has a slightly different layout. Also, due to the native Unicode support within Connector/ODBC 5.1, you no longer need to specify the initial character set to be used with your connection.
To add or configure a Connector/ODBC 5.1 DSN on Windows, use either the command-line, or the ODBC Data Source Administrator
GUI.
- Open the
ODBC Data Source Administrator
. - To create a System DSN (which will be available to all users) , select the System DSN tab. To create a User DSN, which will be unique only to the current user, click the Add... button.
- You will need to select the ODBC driver for this DSN.
Select
MySQL ODBC 5.1 Driver
, then click Finish. - You now need to configure the specific fields for the DSN you are creating through the
Connection Parameters
dialog.In the Data Source Name box, enter the name of the data source to access. It can be any valid name that you choose.
- In the Description box, enter some text to help identify the connection.
- In the Server field, enter the name of the MariaDB server host to access. By default, it is
localhost
. - In the User field, enter the user name to use for this connection.
- In the Password field, enter the corresponding password for this connection.
- The Database pop-up should automatically populate with the list of databases that the user has permissions to access.
- To communicate over a different TCP/IP port than the default (3306), change the value of the Port.
- Click OK to save the DSN.
You can verify the connection using the parameters you have entered by clicking the Test button. If the connection could be made successfully, you will be notified with a Success; connection was made!
dialog.
You can configure a number of options for a specific DSN by using the Details button.
The Details button opens a tabbed display where you set additional options:
- Flags 1, Flags 2, and Flags 3 enable you to select the additional flags for the DSN connection. For more information on these flags, see , "Connector/ODBC Connection Parameters".
- Debug lets you turn on ODBC debugging to record the queries you execute through the DSN to the
myodbc.sql
file. For more information, see , "Getting an ODBC Trace File". - SSL Settings configures the additional options required for using the Secure Sockets Layer (SSL) when communicating with MariaDB server. Note that you must have enabled SSL and configured the MariaDB server with suitable certificates to communicate over SSL.
The Advanced tab lets you configure Connector/ODBC connection parameters. Refer to , "Connector/ODBC Connection Parameters", for information about the meaning of these options.
Configuring a Connector/ODBC 5.1 DSN on Windows, using the command-line
Use myodbc-installer.exe when configuring Connector/ODBC 5.1 or later from the command-line.
Execute myodbc-installer.exe without arguments to view a list of available options.
Troubleshooting ODBC Connection Problems
This section answers Connector/ODBC connection-related questions.
- While configuring a Connector/ODBC DSN, a
Could Not Load Translator or Setup Library
error occurs
For more information, refer to MS KnowledgeBase Article(Q260558). Also, make sure you have the latest valid
ctl3d32.dll
in your system directory. - On Windows, the default
myodbc3.dll
is compiled for optimal performance. To debug Connector/ODBC 3.51 (for example, to enable tracing), instead usemyodbc3d.dll
. To install this file, copymyodbc3d.dll
over the installedmyodbc3.dll
file. Make sure to revert back to the release version of the driver DLL once you are done with the debugging, because the debug version may cause performance issues. Note that themyodbc3d.dll
isn't included in Connector/ODBC 3.51.07 through 3.51.11. If you are using one of these versions, copy that DLL from a previous version (for example, 3.51.06).
Configuring a Connector/ODBC DSN on Mac OS X
To configure a DSN on Mac OS X, you can either use the command-line utility (myodbc3i with connector/OCBC 3.51, or myodbc-installer with connector/ODBC 5.1), edit the odbc.ini
file within the Library/ODBC
directory of the user, or use the ODBC Administrator GUI. If you have Mac OS X 10.2 or earlier, refer to , "Configuring a Connector/ODBC DSN on Unix". Select whether to create a User DSN or a System DSN. When adding a System DSN, you might need to authenticate with the system. Click the padlock and enter a user and password with administrator privileges.
For correct operation of ODBC Administrator, ensure that the /Library/ODBC/odbc.ini
file used to set up ODBC connectivity and DSNs are writable by the admin
group. If this file is not writable by this group, then the ODBC Administrator may fail, or may appear to work but not generate the correct entry.Warning
There are known issues with the OS X ODBC Administrator and Connector/ODBC that may prevent you from creating a DSN using this method. In this case, use the command-line or edit the odbc.ini
file directly. Note that existing DSNs or those that you create using the myodbc3i or myodbc-installer tool can still be checked and edited using ODBC Administrator.
To create a DSN using the myodbc3i utility, you need only specify the DSN type and the DSN connection string. For example:
shell> myodbc3i -a -s -t'DSN=mydb;DRIVER=MySQL ODBC 3.51 Driver;SERVER=mysql;USER=username;PASSWORD=pass'
To use ODBC Administrator:
- Open the ODBC Administrator from the
Utilities
folder in theApplications
folder.
- On the User DSN or System DSN panel, click Add.
- Select the Connector/ODBC driver and click OK.
- You will be presented with the
Data Source Name
dialog. Enter TheData Source Name
and an optionalDescription
for the DSN. - Click Add to add a new keyword/value pair to the panel. Configure at least four pairs to specify the
server
,username
,password
anddatabase
connection parameters. See , "Connector/ODBC Connection Parameters". - Click OK to add the DSN to the list of configured data source names.
A completed DSN configuration may look like this:
You can configure other ODBC options in your DSN by adding further keyword/value pairs and setting the corresponding values. See , "Connector/ODBC Connection Parameters".
Configuring a Connector/ODBC DSN on Unix
On Unix
, you configure DSN entries directly in the odbc.ini
file. Here is a typical odbc.ini
file that configures myodbc3
as the DSN name for Connector/ODBC 3.51:
; ; odbc.ini configuration for Connector/ODBC and Connector/ODBC 3.51 drivers ; [ODBC Data Sources] myodbc3 = MyODBC 3.51 Driver DSN [myodbc3] Driver = /usr/local/lib/libmyodbc3.so Description = Connector/ODBC 3.51 Driver DSN SERVER = localhost PORT = USER = root Password = Database = test OPTION = 3 SOCKET = [Default] Driver = /usr/local/lib/libmyodbc3.so Description = Connector/ODBC 3.51 Driver DSN SERVER = localhost PORT = USER = root Password = Database = test OPTION = 3 SOCKET =
Refer to the , "Connector/ODBC Connection Parameters", for the list of connection parameters that can be supplied.Note
If you are using unixODBC
, you can use the following tools to set up the DSN:
- ODBCConfig GUI tool(HOWTO: ODBCConfig)
- odbcinst
In some cases when using unixODBC
, you might get this error:
Data source name not found and no default driver specified
If this happens, make sure the ODBCINI
and ODBCSYSINI
environment variables are pointing to the right odbc.ini
file. For example, if your odbc.ini
file is located in /usr/local/etc
, set the environment variables like this:
export ODBCINI=/usr/local/etc/odbc.ini export ODBCSYSINI=/usr/local/etc
Connecting Without a Predefined DSN
You can connect to the MariaDB server using SQLDriverConnect, by specifying the DRIVER
name field. Here are the connection strings for Connector/ODBC using DSN-Less connections:
For Connector/ODBC 3.51:
ConnectionString = 'DRIVER={MySQL ODBC 3.51 Driver};\ SERVER=localhost;\ DATABASE=test;\ USER=venu;\ PASSWORD=venu;\ OPTION=3;'
If your programming language converts backslash followed by whitespace to a space, it is preferable to specify the connection string as a single long string, or to use a concatenation of multiple strings that does not add spaces in between. For example:
ConnectionString = 'DRIVER={MySQL ODBC 3.51 Driver};' 'SERVER=localhost;' 'DATABASE=test;' 'USER=venu;' 'PASSWORD=venu;' 'OPTION=3;'
Note. Note that on Mac OS X you may need to specify the full path to the Connector/ODBC driver library.
Refer to the , "Connector/ODBC Connection Parameters", for the list of connection parameters that can be supplied.
ODBC Connection Pooling
Connection pooling enables the ODBC driver to re-use existing connections to a given database from a pool of connections, instead of opening a new connection each time the database is accessed. By enabling connection pooling you can improve the overall performance of your application by lowering the time taken to open a connection to a database in the connection pool.
For more information about connection pooling: http://support.microsoft.com/default.aspx?scid=kb;EN-US;q169470.
Getting an ODBC Trace File
- Enabling ODBC Tracing on Windows
- Enabling ODBC Tracing on Mac OS X
- Enabling ODBC Tracing on Unix
- Enabling a Connector/ODBC Log
- Enabling ODBC Tracing on Mac OS X
If you encounter difficulties or problems with Connector/ODBC, start by making a log file from the ODBC Manager
and Connector/ODBC. This is called tracing, and is enabled through the ODBC Manager. The procedure for this differs for Windows, Mac OS X and Unix.
Enabling ODBC Tracing on Windows
To enable the trace option on Windows:
- The
Tracing
tab of the ODBC Data Source Administrator dialog box lets you configure the way ODBC function calls are traced.
- When you activate tracing from the
Tracing
tab, theDriver Manager
logs all ODBC function calls for all subsequently run applications. - ODBC function calls from applications running before tracing is activated are not logged. ODBC function calls are recorded in a log file you specify.
- Tracing ceases only after you click
Stop Tracing Now
. Remember that while tracing is on, the log file continues to increase in size and that tracing affects the performance of all your ODBC applications.
Enabling ODBC Tracing on Mac OS X
To enable the trace option on Mac OS X 10.3 or later, use the Tracing
tab within ODBC Administrator .
- Open the ODBC Administrator.
- Select the
Tracing
tab. - Select the
Enable Tracing
check box. - Enter the location to save the Tracing log. To append information to an existing log file, click the Choose... button.
Enabling ODBC Tracing on Unix
To enable the trace option on Mac OS X 10.2 (or earlier) or Unix you must add the trace
option to the ODBC configuration:
- On Unix, you need to explicitly set the
Trace
option in theODBC.INI
file.
Set the tracing
ON
orOFF
by usingTraceFile
andTrace
parameters inodbc.ini
as shown below:TraceFile = /tmp/odbc.trace Trace = 1
TraceFile
specifies the name and full path of the trace file andTrace
is set toON
orOFF
. You can also use1
orYES
forON
and0
orNO
forOFF
. If you are using ODBCConfig fromunixODBC
, then follow the instructions for tracingunixODBC
calls at HOWTO-ODBCConfig.
Enabling a Connector/ODBC Log
To generate a Connector/ODBC log, do the following:
- Within Windows, enable the
Trace Connector/ODBC
option flag in the Connector/ODBC connect/configure screen. The log is written to fileC:\myodbc.log
. If the trace option is not remembered when you are going back to the above screen, it means that you are not using themyodbcd.dll
driver, see , "Troubleshooting ODBC Connection Problems".
On Mac OS X, Unix, or if you are using DSN-Less connection, then you need to supply
OPTION=4
in the connection string or set the corresponding keyword/value pair in the DSN. - Start your application and try to get it to fail. Then check the Connector/ODBC trace file to find out what could be wrong.
If you need help determining what is wrong, see , "Connector/ODBC Community Support".
Connector/ODBC Examples
- Basic Connector/ODBC Application Steps
- Step-by-step Guide to Connecting to a MariaDB Database through Connector/ODBC
- Connector/ODBC and Third-Party ODBC Tools
- Using Connector/ODBC with Microsoft Access
- Using Connector/ODBC with Microsoft Word or Excel
- Using Connector/ODBC with Crystal Reports
- Connector/ODBC Programming
- Step-by-step Guide to Connecting to a MariaDB Database through Connector/ODBC
Once you have configured a DSN to provide access to a database, how you access and use that connection is dependent on the application or programming language. As ODBC is a standardized interface, any application or language that supports ODBC can use the DSN and connect to the configured database.
Basic Connector/ODBC Application Steps
Interacting with a MariaDB server from an applications using the Connector/ODBC typically involves the following operations:
- Configure the Connector/ODBC DSN
- Connect to MariaDB server
- Initialization operations
- Execute SQL statements
- Retrieve results
- Perform Transactions
- Disconnect from the server
Most applications use some variation of these steps. The basic application steps are shown in the following diagram:
Step-by-step Guide to Connecting to a MariaDB Database through Connector/ODBC
A typical situation where you would install Connector/ODBC is to access a database on a Linux or Unix host from a Windows machine.
As an example of the process required to set up access between two machines, the steps below take you through the basic steps. These instructions assume that you connect to system ALPHA from system BETA with a user name and password of myuser
and mypassword
.
On system ALPHA (the MariaDB server) follow these steps:
- Start the MariaDB server.
- Use
GRANT
to set up an account with a user name ofmyuser
that can connect from system BETA using a password ofmyuser
to the databasetest
:GRANT ALL ON test.* to 'myuser'@'BETA' IDENTIFIED BY 'mypassword';
For more information about MariaDB privileges, refer to , "MySQL User Account Management".
On system BETA (the Connector/ODBC client), follow these steps:
- Configure a Connector/ODBC DSN using parameters that match the server, database and authentication information that you have just configured on system ALPHA.
Parameter Value Comment DSN remote_test A name to identify the connection. SERVER ALPHA The address of the remote server. DATABASE test The name of the default database. USER myuser The user name configured for access to this database. PASSWORD mypassword The password for myuser
. - Using an ODBC-capable application, such as Microsoft Office, connect to the MariaDB server using the DSN you have just created. If the connection fails, use tracing to examine the connection process. See , "Getting an ODBC Trace File", for more information.
Connector/ODBC and Third-Party ODBC Tools
Once you have configured your Connector/ODBC DSN, you can access your MariaDB database through any application that supports the ODBC interface, including programming languages and third-party applications. This section contains guides and help on using Connector/ODBC with various ODBC-compatible tools and applications, including Microsoft Word, Microsoft Excel and Adobe/Macromedia ColdFusion.
Connector/ODBC has been tested with the following applications.
Publisher | Application | Notes |
---|---|---|
Adobe | ColdFusion | Formerly Macromedia ColdFusion |
Borland | C++ Builder | |
Builder 4 | ||
Delphi | ||
Business Objects | Crystal Reports | |
Claris | Filemaker Pro | |
Corel | Paradox | |
Computer Associates | Visual Objects | Also known as CAVO |
AllFusion ERwin Data Modeler | ||
Gupta | Team Developer | Previously known as Centura Team Developer; Gupta SQL/Windows |
Gensym | G2-ODBC Bridge | |
Inline | iHTML | |
Lotus | Notes | Versions 4.5 and 4.6 |
Microsoft | Access | |
Excel | ||
Visio Enterprise | ||
Visual C++ | ||
Visual Basic | ||
ODBC.NET | Using C#, Visual Basic, C++ | |
FoxPro | ||
Visual Interdev | ||
OpenOffice.org | OpenOffice.org | |
Perl | DBD::ODBC | |
Pervasive Software | DataJunction | |
Sambar Technologies | Sambar Server | |
SPSS | SPSS | |
SoftVelocity | Clarion | |
SQLExpress | SQLExpress for Xbase++ | |
Sun | StarOffice | |
SunSystems | Vision | |
Sybase | PowerBuilder | |
PowerDesigner | ||
theKompany.com | Data Architect |
If you know of any other applications that work with Connector/ODBC, please send mail to <myodbc@lists.mysql.com>
about them.
Using Connector/ODBC with Microsoft Access
- Exporting Access Data to MySQL
- Importing MariaDB Data to Access
- Using Microsoft Access as a Front-end to MySQL
- Importing MariaDB Data to Access
You can use MariaDB database with Microsoft Access using Connector/ODBC. The MariaDB database can be used as an import source, an export source, or as a linked table for direct use within an Access application, so you can use Access as the front-end interface to a MariaDB database.
Exporting Access Data to MariaDB
To export a table of data from an Access database to MySQL, follow these instructions:
- When you open an Access database or an Access project, a Database window appears. It displays shortcuts for creating new database objects and opening existing objects.
- Click the name of the
table
orquery
to export, and then in theFile
menu, selectExport
. - In the
Export Object Type
dialog box, in theObject name
ToSave As Type
box, selectODBC Databases ()
as shown here: - In the
Export
dialog box, enter a name for the file (or use the suggested name), and then selectOK
. - The Select Data Source dialog box is displayed; it lists the defined data sources for any ODBC drivers installed on your computer. Click either the File Data Source or Machine Data Source tab, and then double-click the Connector/ODBC or Connector/ODBC 3.51 data source to export to. To define a new data source for Connector/ODBC, please , "Configuring a Connector/ODBC DSN on Windows".
Ensure that the information that you are exporting to the MariaDB table is valid for the corresponding MariaDB data types. Values that are outside of the supported range of the MariaDB data type but valid within Access may trigger an "overflow" error during the export.
Microsoft Access connects to the MariaDB Server through this data source and exports new tables and or data.
Importing MariaDB Data to Access
To import a table or tables from MariaDB to Access, follow these instructions:
- Open a database, or switch to the Database window for the open database.
- To import tables, on the
File
menu, point toGet External Data
, and then clickImport
. - In the
Import
dialog box, in the Files Of Type box, select ODBC Databases (). The Select Data Source dialog box lists the defined data sources The Select Data Source dialog box is displayed; it lists the defined data source names. - If the ODBC data source that you selected requires you to log on, enter your login ID and password (additional information might also be required), and then click
OK
. - Microsoft Access connects to the MariaDB server through
ODBC data source
and displays the list of tables that you canimport
. - Click each table to
import
, and then clickOK
.
Using Microsoft Access as a Front-end to MariaDB
You can use Microsoft Access as a front end to a MariaDB database by linking tables within your Microsoft Access database to tables that exist within your MariaDB database. When a query is requested on a table within Access, ODBC is used to execute the queries on the MariaDB database instead.
To create a linked table:
- Open the Access database that you want to link to MariaDB.
- From the File, choose Get External Data->Link Tables.
- From the browser, choose ODBC Databases () from the Files of type pop-up.
- In the Select Data Source window, choose an existing DSN, either from a File Data Source or Machine Data Source.You can also create a new DSN using the New... button. For more information on creating a DSN see , "Configuring a Connector/ODBC DSN on Windows".
- In the Link Tables dialog, select one or more tables from the MariaDB database. A link will be created to each table that you select from this list.
- If Microsoft Access is unable to determine the unique record identifier for a table automatically then it may ask you to confirm the column, or combination of columns, to be used to uniquely identify each row from the source table. Select the columns to use and click OK.
Once the process has been completed, you can now build interfaces and queries to the linked tables just as you would for any Access database.
Use the following procedure to view or to refresh links when the structure or location of a linked table has changed. The Linked Table Manager lists the paths to all currently linked tables.
To view or refresh links:
- Open the database that contains links to MariaDB tables.
- On the
Tools
menu, point toAdd-ins
(Database Utilities
in Access 2000 or newer), and then clickLinked Table Manager
. - Select the check box for the tables whose links you want to refresh.
- Click OK to refresh the links.
Microsoft Access confirms a successful refresh or, if the table wasn't found, displays the Select New Location of
<table name> dialog box in which you can specify its the table's new location. If several selected tables have moved to the new location that you specify, the Linked Table Manager searches that location for all selected tables, and updates all links in one step.
To change the path for a set of linked tables:
- Open the database that contains links to tables.
- On the
Tools
menu, point toAdd-ins
(Database Utilities
in Access 2000 or newer), and then clickLinked Table Manager
. - Select the
Always Prompt For A New Location
check box. - Select the check box for the tables whose links you want to change, and then click
OK
. - In the
Select New Location of
<table name> dialog box, specify the new location, clickOpen
, and then clickOK
.
Using Connector/ODBC with Microsoft Word or Excel
You can use Microsoft Word and Microsoft Excel to access information from a MariaDB database using Connector/ODBC. Within Microsoft Word, this facility is most useful when importing data for mailmerge, or for tables and data to be included in reports. Within Microsoft Excel, you can execute queries on your MariaDB server and import the data directly into an Excel Worksheet, presenting the data as a series of rows and columns.
With both applications, data is accessed and imported into the application using Microsoft Query, which lets you execute a query though an ODBC source. You use Microsoft Query to build the SQL statement to be executed, selecting the tables, fields, selection criteria and sort order. For example, to insert information from a table in the World test database into an Excel spreadsheet, using the DSN samples shown in , "Connector/ODBC Configuration":
- Create a new Worksheet.
- From the
Data
menu, chooseImport External Data
, and then selectNew Database Query
. - Microsoft Query will start. First, you need to choose the data source, by selecting an existing Data Source Name.
- Within the
Query Wizard
, you must choose the columns to import. The list of tables available to the user configured through the DSN is shown on the left, the columns that will be added to your query are shown on the right. The columns you choose are equivalent to those in the first section of aSELECT
query. Click Next to continue. - You can filter rows from the query (the equivalent of a
WHERE
clause) using theFilter Data
dialog. Click Next to continue. - Select an (optional) sort order for the data. This is equivalent to using a
ORDER BY
clause in your SQL query. You can select up to three fields for sorting the information returned by the query. Click Next to continue. - Select the destination for your query. You can select to return the data Microsoft Excel, where you can choose a worksheet and cell where the data will be inserted; you can continue to view the query and results within Microsoft Query, where you can edit the SQL query and further filter and sort the information returned; or you can create an OLAP Cube from the query, which can then be used directly within Microsoft Excel. Click Finish.
The same process can be used to import data into a Word document, where the data will be inserted as a table. This can be used for mail merge purposes (where the field data is read from a Word table), or where you want to include data and reports within a report or other document.
Using Connector/ODBC with Crystal Reports
Crystal Reports can use an ODBC DSN to connect to a database from which you to extract data and information for reporting purposes.Note
There is a known issue with certain versions of Crystal Reports where the application is unable to open and browse tables and fields through an ODBC connection. Before using Crystal Reports with MySQL, please ensure that you have update to the latest version, including any outstanding service packs and hotfixes. For more information on this issue, see the Business) Objects Knowledgebase for more information.
For example, to create a simple crosstab report within Crystal Reports XI, follow these steps:
- Create a DSN using the
Data Sources (ODBC)
tool. You can either specify a complete database, including user name and password, or you can build a basic DSN and use Crystal Reports to set the user name and password.
For the purposes of this example, a DSN that provides a connection to an instance of the MariaDB Sakila sample database has been created.
- Open Crystal Reports and create a new project, or an open an existing reporting project into which you want to insert data from your MariaDB data source.
- Start the Cross-Tab Report Wizard, either by clicking the option on the Start Page. Expand the Create New Connection folder, then expand the ODBC (RDO) folder to obtain a list of ODBC data sources.
You will be asked to select a data source.
- When you first expand the ODBC (RDO) folder you will be presented the Data Source Selection screen. From here you can select either a pre-configured DSN, open a file-based DSN or enter and manual connection string. For this example, the Sakila DSN will be used.
If the DSN contains a user name/password combination, or you want to use different authentication credentials, click Next to enter the user name and password that you want to use. Otherwise, click Finish to continue the data source selection wizard.
- You will be returned the Cross-Tab Report Creation Wizard. You now need to select the database and tables that you want to include in your report. For our example, we will expand the selected Sakila database. Click the
city
table and use the > button to add the table to the report. Then repeat the action with thecountry
table. Alternatively you can select multiple tables and add them to the report.Finally, you can select the parent Sakila resource and add of the tables to the report.
Once you have selected the tables you want to include, click Next to continue.
- Crystal Reports will now read the table definitions and automatically identify the links between the tables. The identification of links between tables enables Crystal Reports to automatically lookup and summarize information based on all the tables in the database according to your query. If Crystal Reports is unable to perform the linking itself, you can manually create the links between fields in the tables you have selected.
Click Next to continue the process.
- You can now select the columns and rows that to include within the Cross-Tab report. Drag and drop or use the > buttons to add fields to each area of the report. In the example shown, we will report on cities, organized by country, incorporating a count of the number of cities within each country. If you want to browse the data, select a field and click the Browse Data... button.
Click Next to create a graph of the results. Since we are not creating a graph from this data, click Finish to generate the report.
- The finished report will be shown, a sample of the output from the Sakila sample database is shown below.
Once the ODBC connection has been opened within Crystal Reports, you can browse and add any fields within the available tables into your reports.
Connector/ODBC Programming
With a suitable ODBC Manager and the Connector/ODBC driver installed, any programming language or environment that can support ODBC can connect to a MariaDB database through Connector/ODBC.
This includes, but is not limited to, Microsoft support languages (including Visual Basic, C# and interfaces such as ODBC.NET), Perl (through the DBI module, and the DBD::ODBC driver).
Using Connector/ODBC with Visual Basic Using ADO, DAO and RDO
- ADO:
rs.addNew
,rs.delete
, andrs.update
- DAO:
rs.addNew
,rs.update
, and Scrolling- RDO:
rs.addNew
andrs.update
- DAO:
This section contains simple examples of the use of MariaDB ODBC 3.51 Driver with ADO, DAO and RDO.
ADO: rs.addNew
, rs.delete
, and rs.update
The following ADO (ActiveX Data Objects) example creates a table my_ado
and demonstrates the use of rs.addNew
, rs.delete
, and rs.update
.
Private Sub myodbc_ado_Click() Dim conn As ADODB.Connection Dim rs As ADODB.Recordset Dim fld As ADODB.Field Dim sql As String 'connect to MariaDB server using MariaDB ODBC 3.51 Driver Set conn = New ADODB.Connection conn.ConnectionString = 'DRIVER={MySQL ODBC 3.51 Driver};'_ & 'SERVER=localhost;'_ & ' DATABASE=test;'_ & 'UID=venu;PWD=venu; OPTION=3' conn.Open 'create table conn.Execute 'DROP TABLE IF EXISTS my_ado' conn.Execute 'CREATE TABLE my_ado(id int not null primary key, name varchar(20),' _ & 'txt text, dt date, tm time, ts timestamp)' 'direct insert conn.Execute 'INSERT INTO my_ado(id,name,txt) values(1,100,'venu')' conn.Execute 'INSERT INTO my_ado(id,name,txt) values(2,200,'MySQL')' conn.Execute 'INSERT INTO my_ado(id,name,txt) values(3,300,'Delete')' Set rs = New ADODB.Recordset rs.CursorLocation = adUseServer 'fetch the initial table .. rs.Open 'SELECT * FROM my_ado', conn Debug.Print rs.RecordCount rs.MoveFirst Debug.Print String(50, '-') & 'Initial my_ado Result Set ' & String(50, '-') For Each fld In rs.Fields Debug.Print fld.Name, Next Debug.Print Do Until rs.EOF For Each fld In rs.Fields Debug.Print fld.Value, Next rs.MoveNext Debug.Print Loop rs.Close 'rs insert rs.Open 'select * from my_ado', conn, adOpenDynamic, adLockOptimistic rs.AddNew rs!Name = 'Monty' rs!txt = 'Insert row' rs.Update rs.Close 'rs update rs.Open 'SELECT * FROM my_ado' rs!Name = 'update' rs!txt = 'updated-row' rs.Update rs.Close 'rs update second time.. rs.Open 'SELECT * FROM my_ado' rs!Name = 'update' rs!txt = 'updated-second-time' rs.Update rs.Close 'rs delete rs.Open 'SELECT * FROM my_ado' rs.MoveNext rs.MoveNext rs.Delete rs.Close 'fetch the updated table .. rs.Open 'SELECT * FROM my_ado', conn Debug.Print rs.RecordCount rs.MoveFirst Debug.Print String(50, '-') & 'Updated my_ado Result Set ' & String(50, '-') For Each fld In rs.Fields Debug.Print fld.Name, Next Debug.Print Do Until rs.EOF For Each fld In rs.Fields Debug.Print fld.Value, Next rs.MoveNext Debug.Print Loop rs.Close conn.Close End Sub
DAO: rs.addNew
, rs.update
, and Scrolling
The following DAO (Data Access Objects) example creates a table my_dao
and demonstrates the use of rs.addNew
, rs.update
, and result set scrolling.
Private Sub myodbc_dao_Click() Dim ws As Workspace Dim conn As Connection Dim queryDef As queryDef Dim str As String 'connect to MariaDB using MariaDB ODBC 3.51 Driver Set ws = DBEngine.CreateWorkspace('', 'venu', 'venu', dbUseODBC) str = 'odbc;DRIVER={MySQL ODBC 3.51 Driver};'_ & 'SERVER=localhost;'_ & ' DATABASE=test;'_ & 'UID=venu;PWD=venu; OPTION=3' Set conn = ws.OpenConnection('test', dbDriverNoPrompt, False, str) 'Create table my_dao Set queryDef = conn.CreateQueryDef('', 'drop table if exists my_dao') queryDef.Execute Set queryDef = conn.CreateQueryDef('', 'create table my_dao(Id INT AUTO_INCREMENT PRIMARY KEY, ' _ & 'Ts TIMESTAMP(14) NOT NULL, Name varchar(20), Id2 INT)') queryDef.Execute 'Insert new records using rs.addNew Set rs = conn.OpenRecordset('my_dao') Dim i As Integer For i = 10 To 15 rs.AddNew rs!Name = 'insert record' & i rs!Id2 = i rs.Update Next i rs.Close 'rs update.. Set rs = conn.OpenRecordset('my_dao') rs.Edit rs!Name = 'updated-string' rs.Update rs.Close 'fetch the table back... Set rs = conn.OpenRecordset('my_dao', dbOpenDynamic) str = 'Results:' rs.MoveFirst While Not rs.EOF str = ' ' & rs!Id & ' , ' & rs!Name & ', ' & rs!Ts & ', ' & rs!Id2 Debug.Print 'DATA:' & str rs.MoveNext Wend 'rs Scrolling rs.MoveFirst str = ' FIRST ROW: ' & rs!Id & ' , ' & rs!Name & ', ' & rs!Ts & ', ' & rs!Id2 Debug.Print str rs.MoveLast str = ' LAST ROW: ' & rs!Id & ' , ' & rs!Name & ', ' & rs!Ts & ', ' & rs!Id2 Debug.Print str rs.MovePrevious str = ' LAST-1 ROW: ' & rs!Id & ' , ' & rs!Name & ', ' & rs!Ts & ', ' & rs!Id2 Debug.Print str 'free all resources rs.Close queryDef.Close conn.Close ws.Close End Sub
RDO: rs.addNew
and rs.update
The following RDO (Remote Data Objects) example creates a table my_rdo
and demonstrates the use of rs.addNew
and rs.update
.
Dim rs As rdoResultset Dim cn As New rdoConnection Dim cl As rdoColumn Dim SQL As String 'cn.Connect = 'DSN=test;' cn.Connect = 'DRIVER={MySQL ODBC 3.51 Driver};'_ & 'SERVER=localhost;'_ & ' DATABASE=test;'_ & 'UID=venu;PWD=venu; OPTION=3' cn.CursorDriver = rdUseOdbc cn.EstablishConnection rdDriverPrompt 'drop table my_rdo SQL = 'drop table if exists my_rdo' cn.Execute SQL, rdExecDirect 'create table my_rdo SQL = 'create table my_rdo(id int, name varchar(20))' cn.Execute SQL, rdExecDirect 'insert - direct SQL = 'insert into my_rdo values (100,'venu')' cn.Execute SQL, rdExecDirect SQL = 'insert into my_rdo values (200,'MySQL')' cn.Execute SQL, rdExecDirect 'rs insert SQL = 'select * from my_rdo' Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect) rs.AddNew rs!id = 300 rs!Name = 'Insert1' rs.Update rs.Close 'rs insert SQL = 'select * from my_rdo' Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect) rs.AddNew rs!id = 400 rs!Name = 'Insert 2' rs.Update rs.Close 'rs update SQL = 'select * from my_rdo' Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect) rs.Edit rs!id = 999 rs!Name = 'updated' rs.Update rs.Close 'fetch back... SQL = 'select * from my_rdo' Set rs = cn.OpenResultset(SQL, rdOpenStatic, rdConcurRowVer, rdExecDirect) Do Until rs.EOF For Each cl In rs.rdoColumns Debug.Print cl.Value, Next rs.MoveNext Debug.Print Loop Debug.Print 'Row count="; rs.RowCount "close rs.Close cn.Close End Sub
Using Connector/ODBC with .NET
- Using Connector/ODBC with ODBC.NET and C# (C sharp)
- Using Connector/ODBC with ODBC.NET and Visual Basic
This section contains simple examples that demonstrate the use of Connector/ODBC drivers with ODBC.NET.
Using Connector/ODBC with ODBC.NET and C# (C sharp)
The following sample creates a table my_odbc_net
and demonstrates its use in C#.
/**
* @sample : mycon.cs
* @purpose : Demo sample for ODBC.NET using Connector/ODBC
* @author : Venu, <myodbc@lists.mysql.com>
*
* (C) Copyright MariaDB Foundation, 1995-2006
*
**/
/* build command
*
* csc /t:exe
* /out:mycon.exe mycon.cs
* /r:Microsoft.Data.Odbc.dll
*/
using Console = System.Console;
using Microsoft.Data.Odbc;
namespace myodbc3
{
class mycon
{
static void Main(string[] args)
{
try
{
//Connection string for Connector/ODBC 3.51
string MyConString = 'DRIVER={MySQL ODBC 3.51 Driver};' +
'SERVER=localhost;' +
'DATABASE=test;' +
'UID=venu;' +
'PASSWORD=venu;' +
'OPTION=3';
//Connect to MariaDB using Connector/ODBC
OdbcConnection MyConnection = new OdbcConnection(MyConString);
MyConnection.Open();
Console.WriteLine('\n !!! success, connected successfully !!!\n');
//Display connection information
Console.WriteLine('Connection Information:');
Console.WriteLine('\tConnection String:' +
MyConnection.ConnectionString);
Console.WriteLine('\tConnection Timeout:' +
MyConnection.ConnectionTimeout);
Console.WriteLine('\tDatabase:' +
MyConnection.Database);
Console.WriteLine('\tDataSource:' +
MyConnection.DataSource);
Console.WriteLine('\tDriver:' +
MyConnection.Driver);
Console.WriteLine('\tServerVersion:' +
MyConnection.ServerVersion);
//Create a sample table
OdbcCommand MyCommand =
new OdbcCommand('DROP TABLE IF EXISTS my_odbc_net',
MyConnection);
MyCommand.ExecuteNonQuery();
MyCommand.CommandText =
'CREATE TABLE my_odbc_net(id int, name varchar(20), idb bigint)';
MyCommand.ExecuteNonQuery();
//Insert
MyCommand.CommandText =
'INSERT INTO my_odbc_net VALUES(10,'venu', 300)';
Console.WriteLine('INSERT, Total rows affected:' +
MyCommand.ExecuteNonQuery());;
//Insert
MyCommand.CommandText =
'INSERT INTO my_odbc_net VALUES(20,'mysql',400)';
Console.WriteLine('INSERT, Total rows affected:' +
MyCommand.ExecuteNonQuery());
//Insert
MyCommand.CommandText =
'INSERT INTO my_odbc_net VALUES(20,'mysql',500)';
Console.WriteLine('INSERT, Total rows affected:' +
MyCommand.ExecuteNonQuery());
//Update
MyCommand.CommandText =
'UPDATE my_odbc_net SET id=999 WHERE id=20';
Console.WriteLine('Update, Total rows affected:' +
MyCommand.ExecuteNonQuery());
//COUNT(*)
MyCommand.CommandText =
'SELECT COUNT(*) as TRows FROM my_odbc_net';
Console.WriteLine('Total Rows:' +
MyCommand.ExecuteScalar());
//Fetch
MyCommand.CommandText = 'SELECT * FROM my_odbc_net';
OdbcDataReader MyDataReader;
MyDataReader = MyCommand.ExecuteReader();
while (MyDataReader.Read())
{
if(string.Compare(MyConnection.Driver,'myodbc3.dll') == 0) {
//Supported only by Connector/ODBC 3.51
Console.WriteLine('Data:' + MyDataReader.GetInt32(0) + ' ' +
MyDataReader.GetString(1) + ' ' +
MyDataReader.GetInt64(2));
}
else {
//BIGINTs not supported by Connector/ODBC
Console.WriteLine('Data:' + MyDataReader.GetInt32(0) + ' ' +
MyDataReader.GetString(1) + ' ' +
MyDataReader.GetInt32(2));
}
}
//Close all resources
MyDataReader.Close();
MyConnection.Close();
}
catch (OdbcException MyOdbcException) //Catch any ODBC exception ..
{
for (int i=0; i < MyOdbcException.Errors.Count; i++)
{
Console.Write('ERROR #' + i + '\n' +
'Message: ' +
MyOdbcException.Errors[i].Message + '\n' +
'Native: ' +
MyOdbcException.Errors[i].NativeError.ToString() + '\n' +
'Source: ' +
MyOdbcException.Errors[i].Source + '\n' +
'SQL: ' +
MyOdbcException.Errors[i].SQLState + '\n');
}
}
}
}
}
Using Connector/ODBC with ODBC.NET and Visual Basic
The following sample creates a table my_vb_net
and demonstrates the use in VB.
' @sample : myvb.vb
' @purpose : Demo sample for ODBC.NET using Connector/ODBC
' @author : Venu, <myodbc@lists.mysql.com>
'
' (C) Copyright MariaDB Foundation, 1995-2006
'
'
'
' build command
'
' vbc /target:exe
' /out:myvb.exe
' /r:Microsoft.Data.Odbc.dll
' /r:System.dll
' /r:System.Data.dll
'
Imports Microsoft.Data.Odbc Imports System Module myvb
Sub Main()
Try
'Connector/ODBC 3.51 connection string
Dim MyConString As String = 'DRIVER={MySQL ODBC 3.51 Driver};' & _
'SERVER=localhost;' & _
'DATABASE=test;' & _
'UID=venu;' & _
'PASSWORD=venu;' & _
'OPTION=3;'
'Connection
Dim MyConnection As New OdbcConnection(MyConString)
MyConnection.Open()
Console.WriteLine('Connection State::' & MyConnection.State.ToString)
'Drop
Console.WriteLine('Dropping table')
Dim MyCommand As New OdbcCommand()
MyCommand.Connection = MyConnection
MyCommand.CommandText = 'DROP TABLE IF EXISTS my_vb_net'
MyCommand.ExecuteNonQuery()
'Create
Console.WriteLine('Creating....')
MyCommand.CommandText = 'CREATE TABLE my_vb_net(id int, name varchar(30))'
MyCommand.ExecuteNonQuery()
'Insert
MyCommand.CommandText = 'INSERT INTO my_vb_net VALUES(10,'venu')'
Console.WriteLine('INSERT, Total rows affected:' & _
MyCommand.ExecuteNonQuery())
'Insert
MyCommand.CommandText = 'INSERT INTO my_vb_net VALUES(20,'mysql')'
Console.WriteLine('INSERT, Total rows affected:' & _
MyCommand.ExecuteNonQuery())
'Insert
MyCommand.CommandText = 'INSERT INTO my_vb_net VALUES(20,'mysql')'
Console.WriteLine('INSERT, Total rows affected:' & _
MyCommand.ExecuteNonQuery())
'Insert
MyCommand.CommandText = 'INSERT INTO my_vb_net(id) VALUES(30)'
Console.WriteLine('INSERT, Total rows affected:' & _
MyCommand.ExecuteNonQuery())
'Update
MyCommand.CommandText = 'UPDATE my_vb_net SET id=999 WHERE id=20'
Console.WriteLine('Update, Total rows affected:' & _
MyCommand.ExecuteNonQuery())
'COUNT(*)
MyCommand.CommandText = 'SELECT COUNT(*) as TRows FROM my_vb_net'
Console.WriteLine('Total Rows:' & MyCommand.ExecuteScalar())
'Select
Console.WriteLine('Select * FROM my_vb_net')
MyCommand.CommandText = 'SELECT * FROM my_vb_net'
Dim MyDataReader As OdbcDataReader
MyDataReader = MyCommand.ExecuteReader
While MyDataReader.Read
If MyDataReader('name') Is DBNull.Value Then
Console.WriteLine('id = ' & _
CStr(MyDataReader('id')) & ' name = ' & _
'NULL')
Else
Console.WriteLine('id = ' & _
CStr(MyDataReader('id')) & ' name = ' & _
CStr(MyDataReader('name')))
End If
End While
'Catch ODBC Exception
Catch MyOdbcException As OdbcException
Dim i As Integer
Console.WriteLine(MyOdbcException.ToString)
'Catch program exception
Catch MyException As Exception
Console.WriteLine(MyException.ToString)
End Try
End Sub
Connector/ODBC Reference
This section provides reference material for the Connector/ODBC API, showing supported functions and methods, supported MariaDB column types and the corresponding native type in Connector/ODBC, and the error codes returned by Connector/ODBC when a fault occurs.
Connector/ODBC API Reference
This section summarizes ODBC routines, categorized by functionality.
For the complete ODBC API reference, please refer to the ODBC Programmer's Reference at http://msdn.microsoft.com/en-us/library/ms714177.aspx.
An application can call SQLGetInfo
function to obtain conformance information about Connector/ODBC. To obtain information about support for a specific function in the driver, an application can call SQLGetFunctions
.Note
For backward compatibility, the Connector/ODBC 3.51 driver supports all deprecated functions.
The following tables list Connector/ODBC API calls grouped by task:
Connecting to a data source
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLAllocHandle
| Yes | ISO 92 | Obtains an environment, connection, statement, or descriptor handle. |
SQLConnect
| Yes | ISO 92 | Connects to a specific driver by data source name, user ID, and password. |
SQLDriverConnect
| Yes | ODBC | Connects to a specific driver by connection string or requests that the Driver Manager and driver display connection dialog boxes for the user. |
SQLAllocEnv
| Yes | Deprecated | Obtains an environment handle allocated from driver. |
SQLAllocConnect
| Yes | Deprecated | Obtains a connection handle |
Obtaining information about a driver and data source
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLDataSources
| No | ISO 92 | Returns the list of available data sources, handled by the Driver Manager |
SQLDrivers
| No | ODBC | Returns the list of installed drivers and their attributes, handles by Driver Manager |
SQLGetInfo
| Yes | ISO 92 | Returns information about a specific driver and data source. |
SQLGetFunctions
| Yes | ISO 92 | Returns supported driver functions. |
SQLGetTypeInfo
| Yes | ISO 92 | Returns information about supported data types. |
Setting and retrieving driver attributes
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLSetConnectAttr
| Yes | ISO 92 | Sets a connection attribute. |
SQLGetConnectAttr
| Yes | ISO 92 | Returns the value of a connection attribute. |
SQLSetConnectOption
| Yes | Deprecated | Sets a connection option |
SQLGetConnectOption
| Yes | Deprecated | Returns the value of a connection option |
SQLSetEnvAttr
| Yes | ISO 92 | Sets an environment attribute. |
SQLGetEnvAttr
| Yes | ISO 92 | Returns the value of an environment attribute. |
SQLSetStmtAttr
| Yes | ISO 92 | Sets a statement attribute. |
SQLGetStmtAttr
| Yes | ISO 92 | Returns the value of a statement attribute. |
SQLSetStmtOption
| Yes | Deprecated | Sets a statement option |
SQLGetStmtOption
| Yes | Deprecated | Returns the value of a statement option |
Preparing SQL requests
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLAllocStmt
| Yes | Deprecated | Allocates a statement handle |
SQLPrepare
| Yes | ISO 92 | Prepares an SQL statement for later execution. |
SQLBindParameter
| Yes | ODBC | Assigns storage for a parameter in an SQL statement. |
SQLGetCursorName
| Yes | ISO 92 | Returns the cursor name associated with a statement handle. |
SQLSetCursorName
| Yes | ISO 92 | Specifies a cursor name. |
SQLSetScrollOptions
| Yes | ODBC | Sets options that control cursor behavior. |
Submitting requests
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLExecute
| Yes | ISO 92 | Executes a prepared statement. |
SQLExecDirect
| Yes | ISO 92 | Executes a statement |
SQLNativeSql
| Yes | ODBC | Returns the text of an SQL statement as translated by the driver. |
SQLDescribeParam
| Yes | ODBC | Returns the description for a specific parameter in a statement. |
SQLNumParams
| Yes | ISO 92 | Returns the number of parameters in a statement. |
SQLParamData
| Yes | ISO 92 | Used in conjunction with SQLPutData to supply parameter data at execution time. (Useful for long data values.)
|
SQLPutData
| Yes | ISO 92 | Sends part or all of a data value for a parameter. (Useful for long data values.) |
Retrieving results and information about results
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLRowCount
| Yes | ISO 92 | Returns the number of rows affected by an insert, update, or delete request. |
SQLNumResultCols
| Yes | ISO 92 | Returns the number of columns in the result set. |
SQLDescribeCol
| Yes | ISO 92 | Describes a column in the result set. |
SQLColAttribute
| Yes | ISO 92 | Describes attributes of a column in the result set. |
SQLColAttributes
| Yes | Deprecated | Describes attributes of a column in the result set. |
SQLFetch
| Yes | ISO 92 | Returns multiple result rows. |
SQLFetchScroll
| Yes | ISO 92 | Returns scrollable result rows. |
SQLExtendedFetch
| Yes | Deprecated | Returns scrollable result rows. |
SQLSetPos
| Yes | ODBC | Positions a cursor within a fetched block of data and enables an application to refresh data in the rowset or to update or delete data in the result set. |
SQLBulkOperations
| Yes | ODBC | Performs bulk insertions and bulk bookmark operations, including update, delete, and fetch by bookmark. |
Retrieving error or diagnostic information
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLError
| Yes | Deprecated | Returns additional error or status information |
SQLGetDiagField
| Yes | ISO 92 | Returns additional diagnostic information (a single field of the diagnostic data structure). |
SQLGetDiagRec
| Yes | ISO 92 | Returns additional diagnostic information (multiple fields of the diagnostic data structure). |
Obtaining information about the data source's system tables (catalog functions) item
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLColumnPrivileges
| Yes | ODBC | Returns a list of columns and associated privileges for one or more tables. |
SQLColumns
| Yes | X/Open | Returns the list of column names in specified tables. |
SQLForeignKeys
| Yes | ODBC | Returns a list of column names that make up foreign keys, if they exist for a specified table. |
SQLPrimaryKeys
| Yes | ODBC | Returns the list of column names that make up the primary key for a table. |
SQLSpecialColumns
| Yes | X/Open | Returns information about the optimal set of columns that uniquely identifies a row in a specified table, or the columns that are automatically updated when any value in the row is updated by a transaction. |
SQLStatistics
| Yes | ISO 92 | Returns statistics about a single table and the list of indexes associated with the table. |
SQLTablePrivileges
| Yes | ODBC | Returns a list of tables and the privileges associated with each table. |
SQLTables
| Yes | X/Open | Returns the list of table names stored in a specific data source. |
Performing transactions
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLTransact
| Yes | Deprecated | Commits or rolls back a transaction |
SQLEndTran
| Yes | ISO 92 | Commits or rolls back a transaction. |
Terminating a statement
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLFreeStmt
| Yes | ISO 92 | Ends statement processing, discards pending results, and, optionally, frees all resources associated with the statement handle. |
SQLCloseCursor
| Yes | ISO 92 | Closes a cursor that has been opened on a statement handle. |
SQLCancel
| Yes | ISO 92 | Cancels an SQL statement. |
Terminating a connection
Function name | C/ODBC 3.51 | Standard | Purpose |
---|---|---|---|
SQLDisconnect
| Yes | ISO 92 | Closes the connection. |
SQLFreeHandle
| Yes | ISO 92 | Releases an environment, connection, statement, or descriptor handle. |
SQLFreeConnect
| Yes | Deprecated | Releases connection handle |
SQLFreeEnv
| Yes | Deprecated | Releases an environment handle |
Connector/ODBC Data Types
The following table illustrates how driver maps the server data types to default SQL and C data types.
Native Value | SQL Type | C Type |
---|---|---|
bigint unsigned
| SQL_BIGINT
| SQL_C_UBIGINT
|
bigint
| SQL_BIGINT
| SQL_C_SBIGINT
|
bit
| SQL_BIT
| SQL_C_BIT
|
bit
| SQL_CHAR
| SQL_C_CHAR
|
blob
| SQL_LONGVARBINARY
| SQL_C_BINARY
|
bool
| SQL_CHAR
| SQL_C_CHAR
|
char
| SQL_CHAR
| SQL_C_CHAR
|
date
| SQL_DATE
| SQL_C_DATE
|
datetime
| SQL_TIMESTAMP
| SQL_C_TIMESTAMP
|
decimal
| SQL_DECIMAL
| SQL_C_CHAR
|
double precision
| SQL_DOUBLE
| SQL_C_DOUBLE
|
double
| SQL_FLOAT
| SQL_C_DOUBLE
|
enum
| SQL_VARCHAR
| SQL_C_CHAR
|
float
| SQL_REAL
| SQL_C_FLOAT
|
int unsigned
| SQL_INTEGER
| SQL_C_ULONG
|
int
| SQL_INTEGER
| SQL_C_SLONG
|
integer unsigned
| SQL_INTEGER
| SQL_C_ULONG
|
integer
| SQL_INTEGER
| SQL_C_SLONG
|
long varbinary
| SQL_LONGVARBINARY
| SQL_C_BINARY
|
long varchar
| SQL_LONGVARCHAR
| SQL_C_CHAR
|
longblob
| SQL_LONGVARBINARY
| SQL_C_BINARY
|
longtext
| SQL_LONGVARCHAR
| SQL_C_CHAR
|
mediumblob
| SQL_LONGVARBINARY
| SQL_C_BINARY
|
mediumint unsigned
| SQL_INTEGER
| SQL_C_ULONG
|
mediumint
| SQL_INTEGER
| SQL_C_SLONG
|
mediumtext
| SQL_LONGVARCHAR
| SQL_C_CHAR
|
numeric
| SQL_NUMERIC
| SQL_C_CHAR
|
real
| SQL_FLOAT
| SQL_C_DOUBLE
|
set
| SQL_VARCHAR
| SQL_C_CHAR
|
smallint unsigned
| SQL_SMALLINT
| SQL_C_USHORT
|
smallint
| SQL_SMALLINT
| SQL_C_SSHORT
|
text
| SQL_LONGVARCHAR
| SQL_C_CHAR
|
time
| SQL_TIME
| SQL_C_TIME
|
timestamp
| SQL_TIMESTAMP
| SQL_C_TIMESTAMP
|
tinyblob
| SQL_LONGVARBINARY
| SQL_C_BINARY
|
tinyint unsigned
| SQL_TINYINT
| SQL_C_UTINYINT
|
tinyint
| SQL_TINYINT
| SQL_C_STINYINT
|
tinytext
| SQL_LONGVARCHAR
| SQL_C_CHAR
|
varchar
| SQL_VARCHAR
| SQL_C_CHAR
|
year
| SQL_SMALLINT
| SQL_C_SHORT |
Connector/ODBC Error Codes
The following tables lists the error codes returned by the driver apart from the server errors.
Native Code | SQLSTATE 2 | SQLSTATE 3 | Error Message |
---|---|---|---|
500 | 01000 | 01000 | General warning |
501 | 01004 | 01004 | String data, right truncated |
502 | 01S02 | 01S02 | Option value changed |
503 | 01S03 | 01S03 | No rows updated/deleted |
504 | 01S04 | 01S04 | More than one row updated/deleted |
505 | 01S06 | 01S06 | Attempt to fetch before the result set returned the first row set |
506 | 07001 | 07002 | SQLBindParameter not used for all parameters
|
507 | 07005 | 07005 | Prepared statement not a cursor-specification |
508 | 07009 | 07009 | Invalid descriptor index |
509 | 08002 | 08002 | Connection name in use |
510 | 08003 | 08003 | Connection does not exist |
511 | 24000 | 24000 | Invalid cursor state |
512 | 25000 | 25000 | Invalid transaction state |
513 | 25S01 | 25S01 | Transaction state unknown |
514 | 34000 | 34000 | Invalid cursor name |
515 | S1000 | HY000 | General driver defined error |
516 | S1001 | HY001 | Memory allocation error |
517 | S1002 | HY002 | Invalid column number |
518 | S1003 | HY003 | Invalid application buffer type |
519 | S1004 | HY004 | Invalid SQL data type |
520 | S1009 | HY009 | Invalid use of null pointer |
521 | S1010 | HY010 | Function sequence error |
522 | S1011 | HY011 | Attribute can not be set now |
523 | S1012 | HY012 | Invalid transaction operation code |
524 | S1013 | HY013 | Memory management error |
525 | S1015 | HY015 | No cursor name available |
526 | S1024 | HY024 | Invalid attribute value |
527 | S1090 | HY090 | Invalid string or buffer length |
528 | S1091 | HY091 | Invalid descriptor field identifier |
529 | S1092 | HY092 | Invalid attribute/option identifier |
530 | S1093 | HY093 | Invalid parameter number |
531 | S1095 | HY095 | Function type out of range |
532 | S1106 | HY106 | Fetch type out of range |
533 | S1117 | HY117 | Row value out of range |
534 | S1109 | HY109 | Invalid cursor position |
535 | S1C00 | HYC00 | Optional feature not implemented |
0 | 21S01 | 21S01 | Column count does not match value count |
0 | 23000 | 23000 | Integrity constraint violation |
0 | 42000 | 42000 | Syntax error or access violation |
0 | 42S02 | 42S02 | Base table or view not found |
0 | 42S12 | 42S12 | Index not found |
0 | 42S21 | 42S21 | Column already exists |
0 | 42S22 | 42S22 | Column not found |
0 | 08S01 | 08S01 | Communication link failure |
Connector/ODBC Notes and Tips
- Connector/ODBC General Functionality
- Connector/ODBC Application-Specific Tips
- Connector/ODBC Errors and Resolutions (FAQ)
- Connector/ODBC Application-Specific Tips
Here are some common notes and tips for using Connector/ODBC within different environments, applications and tools. The notes provided here are based on the experiences of Connector/ODBC developers and users.
Connector/ODBC General Functionality
- Obtaining Auto-Increment Values
- Dynamic Cursor Support
- Connector/ODBC Performance
- Setting ODBC Query Timeout in Windows
- Dynamic Cursor Support
This section provides help with common queries and areas of functionality in MariaDB and how to use them with Connector/ODBC.
Obtaining Auto-Increment Values
Obtaining the value of column that uses AUTO_INCREMENT
after an INSERT
statement can be achieved in a number of different ways. To obtain the value immediately after an INSERT
, use a SELECT
query with the LAST_INSERT_ID()
function.
For example, using Connector/ODBC you would execute two separate statements, the INSERT
statement and the SELECT
query to obtain the auto-increment value.
INSERT INTO tbl (auto,text) VALUES(NULL,'text'); SELECT LAST_INSERT_ID();
If you do not require the value within your application, but do require the value as part of another INSERT
, the entire process can be handled by executing the following statements:
INSERT INTO tbl (auto,text) VALUES(NULL,'text'); INSERT INTO tbl2 (id,text) VALUES(LAST_INSERT_ID(),'text');
Certain ODBC applications (including Delphi and Access) may have trouble obtaining the auto-increment value using the previous examples. In this case, try the following statement as an alternative:
SELECT * FROM tbl WHERE auto IS NULL;
This alternative method requires that sql-auto-is-null
variable is not set to 0. See , "Server System Variables".
See also , "How to Get the Unique ID for the Last Inserted Row".
Dynamic Cursor Support
Support for the dynamic cursor
is provided in Connector/ODBC 3.51, but dynamic cursors are not enabled by default. You can enable this function within Windows by selecting the Enable Dynamic Cursor
check box within the ODBC Data Source Administrator.
On other platforms, you can enable the dynamic cursor by adding 32
to the OPTION
value when creating the DSN.
Connector/ODBC Performance
The Connector/ODBC driver has been optimized to provide very fast performance. If you experience problems with the performance of Connector/ODBC, or notice a large amount of disk activity for simple queries, there are a number of aspects to check:
- Ensure that
ODBC Tracing
is not enabled. With tracing enabled, a lot of information is recorded in the tracing file by the ODBC Manager. You can check, and disable, tracing within Windows using the Tracing panel of the ODBC Data Source Administrator. Within Mac OS X, check the Tracing panel of ODBC Administrator. See , "Getting an ODBC Trace File". - Make sure you are using the standard version of the driver, and not the debug version. The debug version includes additional checks and reporting measures.
- Disable the Connector/ODBC driver trace and query logs. These options are enabled for each DSN, so make sure to examine only the DSN that you are using in your application. Within Windows, you can disable the Connector/ODBC and query logs by modifying the DSN configuration. Within Mac OS X and Unix, ensure that the driver trace (option value 4) and query logging (option value 524288) are not enabled.
Setting ODBC Query Timeout in Windows
For more information on how to set the query timeout on Microsoft Windows when executing queries through an ODBC connection, read the Microsoft knowledgebase document at http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B153756.
Connector/ODBC Application-Specific Tips
- Using Connector/ODBC with Microsoft Applications
- Using Connector/ODBC with Borland Applications
- Using Connector/ODBC with ColdFusion
- Using Connector/ODBC with OpenOffice.org
- Using Connector/ODBC with Sambar Server
- Using Connector/ODBC with Pervasive Software DataJunction
- Using Connector/ODBC with SunSystems Vision
- Using Connector/ODBC with Borland Applications
Most programs should work with Connector/ODBC, but for each of those listed here, there are specific notes and tips to improve or enhance the way you work with Connector/ODBC and these applications.
With all applications, ensure that you are using the latest Connector/ODBC drivers, ODBC Manager and any supporting libraries and interfaces used by your application. For example, on Windows, using the latest version of Microsoft Data Access Components (MDAC) will improve the compatibility with ODBC in general, and with the Connector/ODBC driver.
Using Connector/ODBC with Microsoft Applications
- Microsoft Access
- Microsoft Excel and Column Types
- Microsoft Visual Basic
- Microsoft Visual InterDev
- Visual Objects
- Microsoft ADO
- Using Connector/ODBC with Active Server Pages (ASP)
- Using Connector/ODBC with Visual Basic (ADO, DAO and RDO) and ASP
- Microsoft Excel and Column Types
The majority of Microsoft applications have been tested with Connector/ODBC, including Microsoft Office, Microsoft Access and the various programming languages supported within ASP and Microsoft Visual Studio.
Microsoft Access
To improve the integration between Microsoft Access and MariaDB through Connector/ODBC:
- For all versions of Access, enable the Connector/ODBC
Return matching rows
option. For Access 2.0, also enable theSimulate ODBC 1.0
option. - Include a
TIMESTAMP
column in all tables that you want to be able to update. For maximum portability, do not use a length specification in the column declaration (which is unsupported within MariaDB in versions earlier than 4.1). - Include a primary key in each MariaDB table you want to use with Access. If not, new or updated rows may show up as
#DELETED#
. - Use only
DOUBLE
float fields. Access fails when comparing with single-precision floats. The symptom usually is that new or updated rows may show up as#DELETED#
or that you cannot find or update rows. - If you are using Connector/ODBC to link to a table that has a
BIGINT
column, the results are displayed as#DELETED#
. The work around solution is:- Have one more dummy column with
TIMESTAMP
as the data type. - Select the
Change BIGINT columns to INT
option in the connection dialog in ODBC DSN Administrator. - Delete the table link from Access and re-create it.
Old records may still display as
#DELETED#
, but newly added/updated records are displayed properly. - Have one more dummy column with
- If you still get the error
Another user has changed your data
after adding aTIMESTAMP
column, the following trick may help you:Do not use a
table
data sheet view. Instead, create a form with the fields you want, and use thatform
data sheet view. Set theDefaultValue
property for theTIMESTAMP
column toNOW()
. Consider hiding theTIMESTAMP
column from view so your users are not confused. - In some cases, Access may generate SQL statements that MariaDB cannot understand. You can fix this by selecting
'Query|SQLSpecific|Pass-Through'
from the Access menu. - On Windows NT, Access reports
BLOB
columns asOLE OBJECTS
. If you want to haveMEMO
columns instead, changeBLOB
columns toTEXT
withALTER TABLE
. - Access cannot always handle the MariaDB
DATE
column properly. If you have a problem with these, change the columns toDATETIME
. - If you have in Access a column defined as
BYTE
, Access tries to export this asTINYINT
instead ofTINYINT UNSIGNED
. This gives you problems if you have values larger than 127 in the column. - If you have very large (long) tables in Access, it might take a very long time to open them. Or you might run low on virtual memory and eventually get an
ODBC Query Failed
error and the table cannot open. To deal with this, select the following options:- Return Matching Rows (2)
- Allow BIG Results (8).
These add up to a value of 10 (
OPTION=10
).
Some external articles and tips that may be useful when using Access, ODBC and Connector/ODBC:
- Read How to Trap ODBC Login Error Messages in Access
- Optimizing Access ODBC Applications
- For a list of tools that can be used with Access and ODBC data sources, refer to http://www.mysql.com/portal/software/convertors/ section for list of available tools.
Microsoft Excel and Column Types
If you have problems importing data into Microsoft Excel, particularly numeric, date, and time values, this is probably because of a bug in Excel, where the column type of the source data is used to determine the data type when that data is inserted into a cell within the worksheet. The result is that Excel incorrectly identifies the content and this affects both the display format and the data when it is used within calculations.
To address this issue, use the CONCAT()
function in your queries. The use of CONCAT()
forces Excel to treat the value as a string, which Excel will then parse and usually correctly identify the embedded information.
However, even with this option, some data may be incorrectly formatted, even though the source data remains unchanged. Use the Format Cells
option within Excel to change the format of the displayed information.
Microsoft Visual Basic
To be able to update a table, you must define a primary key for the table.
Visual Basic with ADO cannot handle big integers. This means that some queries like SHOW PROCESSLIST
do not work properly. The fix is to use OPTION=16384
in the ODBC connect string or to select the Change BIGINT columns to INT
option in the Connector/ODBC connect screen. You may also want to select the Return matching rows
option.
Microsoft Visual InterDev
If you have a BIGINT
in your result, you may get the error [Microsoft][ODBC Driver Manager] Driver does not support this parameter
. Try selecting the Change BIGINT columns to INT
option in the Connector/ODBC connect screen.
Visual Objects
Select the Don't optimize column widths
option.
Microsoft ADO
When you are coding with the ADO API and Connector/ODBC, you need to pay attention to some default properties that aren't supported by the MariaDB server. For example, using the CursorLocation Property
as adUseServer
returns a result of -1 for the RecordCount Property
. To have the right value, you need to set this property to adUseClient
, as shown in the VB code here:
Dim myconn As New ADODB.Connection Dim myrs As New Recordset Dim mySQL As String Dim myrows As Long myconn.Open 'DSN=MyODBCsample' mySQL = 'SELECT * from user' myrs.Source = mySQL Set myrs.ActiveConnection = myconn myrs.CursorLocation = adUseClient myrs.Open myrows = myrs.RecordCount myrs.Close myconn.Close
Another workaround is to use a SELECT COUNT(*)
statement for a similar query to get the correct row count.
To find the number of rows affected by a specific SQL statement in ADO, use the RecordsAffected
property in the ADO execute method. For more information on the usage of execute method, refer to http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ado270/htm/mdmthcnnexecute.asp.
For information, see ActiveX Data Objects(ADO) Frequently Asked Questions.
Using Connector/ODBC with Active Server Pages (ASP)
Select the Return matching rows
option in the DSN.
For more information about how to access MariaDB through ASP using Connector/ODBC, refer to the following articles:
A Frequently Asked Questions list for ASP can be found at http://support.microsoft.com/default.aspx?scid=/Support/ActiveServer/faq/data/adofaq.asp.
Using Connector/ODBC with Visual Basic (ADO, DAO and RDO) and ASP
Some articles that may help with Visual Basic and ASP:
- MySQL BLOB columns and Visual Basic 6 by Mike Hillyer (
<mike@openwin.org>
). - How to map Visual basic data type to MariaDB types by Mike Hillyer (
<mike@openwin.org>
).
Using Connector/ODBC with Borland Applications
- Using Connector/ODBC with Borland Builder 4
- Using Connector/ODBC with Delphi
- Using Connector/ODBC with C++ Builder
- Using Connector/ODBC with Delphi
With all Borland applications where the Borland Database Engine (BDE) is used, follow these steps to improve compatibility:
- Update to BDE 3.2 or newer.
- Enable the
Don't optimize column widths
option in the DSN. - Enabled the
Return matching rows
option in the DSN.
Using Connector/ODBC with Borland Builder 4
When you start a query, you can use the Active
property or the Open
method. Note that Active
starts by automatically issuing a SELECT * FROM ...
query. That may not be a good thing if your tables are large.
Using Connector/ODBC with Delphi
Also, here is some potentially useful Delphi code that sets up both an ODBC entry and a BDE entry for Connector/ODBC. The BDE entry requires a BDE Alias Editor that is free at a Delphi Super Page near you. (Thanks to Bryan Brunton <bryan@flesherfab.com>
for this):
fReg:= TRegistry.Create; fReg.OpenKey('\Software\ODBC\ODBC.INI\DocumentsFab', True); fReg.WriteString('Database', 'Documents'); fReg.WriteString('Description', ' '); fReg.WriteString('Driver', 'C:\WINNT\System32\myodbc.dll'); fReg.WriteString('Flag', '1'); fReg.WriteString('Password', ''); fReg.WriteString('Port', ' '); fReg.WriteString('Server', 'xmark'); fReg.WriteString('User', 'winuser'); fReg.OpenKey('\Software\ODBC\ODBC.INI\ODBC Data Sources', True); fReg.WriteString('DocumentsFab', 'MySQL'); fReg.CloseKey; fReg.Free; Memo1.Lines.Add('DATABASE NAME="); Memo1.Lines.Add("USER NAME="); Memo1.Lines.Add("ODBC DSN=DocumentsFab'); Memo1.Lines.Add('OPEN MODE=READ/WRITE'); Memo1.Lines.Add('BATCH COUNT=200'); Memo1.Lines.Add('LANGDRIVER='); Memo1.Lines.Add('MAX ROWS=-1'); Memo1.Lines.Add('SCHEMA CACHE DIR="); Memo1.Lines.Add("SCHEMA CACHE SIZE=8'); Memo1.Lines.Add('SCHEMA CACHE TIME=-1'); Memo1.Lines.Add('SQLPASSTHRU MODE=SHARED AUTOCOMMIT'); Memo1.Lines.Add('SQLQRYMODE='); Memo1.Lines.Add('ENABLE SCHEMA CACHE=FALSE'); Memo1.Lines.Add('ENABLE BCD=FALSE'); Memo1.Lines.Add('ROWSET SIZE=20'); Memo1.Lines.Add('BLOBS TO CACHE=64'); Memo1.Lines.Add('BLOB SIZE=32'); AliasEditor.Add('DocumentsFab','MySQL',Memo1.Lines);
Using Connector/ODBC with C++ Builder
Tested with BDE 3.0. The only known problem is that when the table schema changes, query fields are not updated. BDE, however, does not seem to recognize primary keys, only the index named PRIMARY
, although this has not been a problem.
Using Connector/ODBC with ColdFusion
The following information is taken from the ColdFusion documentation:
Use the following information to configure ColdFusion Server for Linux to use the unixODBC
driver with Connector/ODBC for MariaDB data sources. You can download Connector/ODBC at http://dev.mysql.com/downloads/connector/odbc/.
ColdFusion version 4.5.1 lets you use the ColdFusion Administrator to add the MariaDB data source. However, the driver is not included with ColdFusion version 4.5.1. Before the MariaDB driver appears in the ODBC data sources drop-down list, you must build and copy the Connector/ODBC driver to /opt/coldfusion/lib/libmyodbc.so
.
The Contrib directory contains the program mydsn-
which lets you build and remove the DSN registry file for the Connector/ODBC driver on ColdFusion applications.
xxx
.zip
For more information and guides on using ColdFusion and Connector/ODBC, see the following external sites:
Using Connector/ODBC with OpenOffice.org
Open Office (http://www.openoffice.org) How-to: MariaDB + OpenOffice. How-to: OpenOffice + MyODBC + unixODBC.
Using Connector/ODBC with Sambar Server
Sambar Server (http://www.sambarserver.info) How-to: MyODBC + SambarServer + MySQL.
Using Connector/ODBC with Pervasive Software DataJunction
You have to change it to output VARCHAR
rather than ENUM
, as it exports the latter in a manner that causes MariaDB problems.
Using Connector/ODBC with SunSystems Vision
Select the Return matching rows
option.
Connector/ODBC Errors and Resolutions (FAQ)
The following section details some common errors and their suggested fix or alternative solution. If you are still experiencing problems, use the Connector/ODBC mailing list; see , "Connector/ODBC Community Support".
Many problems can be resolved by upgrading your Connector/ODBC drivers to the latest available release. On Windows, make sure that you have the latest versions of the Microsoft Data Access Components (MDAC) installed.
Questions
- : I have installed Connector/ODBC on Windows XP x64 Edition or Windows Server 2003 R2 x64. The installation completed successfully, but the Connector/ODBC driver does not appear in
ODBC Data Source Administrator
. - : When connecting or using the Test button in
ODBC Data Source Administrator
I get error 10061 (Cannot connect to server) - : The following error is reported when using transactions:
Transactions are not enabled
- : Access reports records as
#DELETED#
when inserting or updating records in linked tables. - : How do I handle Write Conflicts or Row Location errors?
- : Exporting data from Access 97 to MariaDB reports a
Syntax Error
. - : Exporting data from Microsoft DTS to MariaDB reports a
Syntax Error
. - : Using ODBC.NET with Connector/ODBC, while fetching empty string (0 length), it starts giving the SQL_NO_DATA exception.
- : Using
SELECT COUNT(*) FROM
within Visual Basic and ASP returns an error.tbl_name
- : Using the
AppendChunk()
orGetChunk()
ADO methods, theMultiple-step operation generated errors. Check each status value
error is returned. - : Access Returns
Another user had modified the record that you have modified
while editing records on a Linked Table. - : When linking an application directly to the Connector/ODBC library under Unix/Linux, the application crashes.
- : Applications in the Microsoft Office suite are unable to update tables that have
DATE
orTIMESTAMP
columns. - : When connecting Connector/ODBC 5.x (Beta) to a MariaDB 4.x server, the error
Access denied for user 'xxx'@'%' to database 'information_schema'
is returned. - : When calling
SQLTables
, the errorS1T00
is returned, but I cannot find this in the list of error numbers for Connector/ODBC. - : When linking to tables in Access 2000 and generating links to tables programmatically, rather than through the table designer interface, you may get errors about tables not existing.
- : When I try to use batched statements, the execution of the batched statements fails.
- : When connecting to a MariaDB server using ADODB and Excel, occasionally the application fails to communicate with the server and the error
Got an error reading communication packets
appears in the error log. - : When using some applications to access a MariaDB server using C/ODBC and outer joins, an error is reported regarding the Outer Join Escape Sequence.
- : I can correctly store extended characters in the database (Hebrew/CJK) using C/ODBC 5.1, but when I retrieve the data, the text is not formatted correctly and I get garbled characters.
- : I have a duplicate MariaDB Connector/ODBC entry within my Installed Programs list, but I cannot delete one of them.
- : When submitting queries with parameter binding using
UPDATE
, my field values are being truncated to 255 characters. - : Is it possible to disable data-at-execution using a flag?
- : When you call
SQLColumns()
for a table column that isAUTO_INCREMENT
, theNULLABLE
column of the result set is alwaysSQL_NULLABLE (1)
.
Questions and Answers
21.1.7.3.1: I have installed Connector/ODBC on Windows XP x64 Edition or Windows Server 2003 R2 x64. The installation completed successfully, but the Connector/ODBC driver does not appear in ODBC Data Source Administrator
.
This is not a bug, but is related to the way Windows x64 editions operate with the ODBC driver. On Windows x64 editions, the Connector/ODBC driver is installed in the %SystemRoot%\SysWOW64
folder. However, the default ODBC Data Source Administrator
that is available through the Administrative Tools
or Control Panel
in Windows x64 Editions is located in the %SystemRoot%\system32
folder, and only searches this folder for ODBC drivers.
On Windows x64 editions, use the ODBC administration tool located at %SystemRoot%\SysWOW64\odbcad32.exe
, this will correctly locate the installed Connector/ODBC drivers and enable you to create a Connector/ODBC DSN.
This issue was originally reported as Bug #20301.
21.1.7.3.2: When connecting or using the Test button in ODBC Data Source Administrator
I get error 10061 (Cannot connect to server)
This error can be raised by a number of different issues, including server problems, network problems, and firewall and port blocking problems. For more information, see "Can't connect to [local] MariaDB server
".
21.1.7.3.3: The following error is reported when using transactions: Transactions are not enabled
This error indicates that you are trying to use transactions with a MariaDB table that does not support transactions. Transactions are supported within MariaDB when using the InnoDB
database engine. In versions of MariaDB before Mysql 5.1 you may also use the BDB
engine.
Check the following before continuing:
- Verify that your MariaDB server supports a transactional database engine. Use
SHOW ENGINES
to obtain a list of the available engine types. - Verify that the tables you are updating use a transaction database engine.
- Ensure that you have not enabled the
disable transactions
option in your DSN.
21.1.7.3.4: Access reports records as #DELETED#
when inserting or updating records in linked tables.
If the inserted or updated records are shown as #DELETED#
in the access, then:
- If you are using Access 2000, get and install the newest (version 2.6 or higher) Microsoft MDAC (
Microsoft Data Access Components
) from http://support.microsoft.com/kb/110093. This fixes a bug in Access that when you export data to MySQL, the table and column names aren't specified.
Also, get and apply the Microsoft Jet 4.0 Service Pack 5 (SP5), which can be found at http://support.microsoft.com/default.aspx?scid=kb;EN-US;q239114. This fixes some cases where columns are marked as
#DELETED#
in Access. - For all versions of Access, enable the Connector/ODBC
Return matching rows
option. For Access 2.0, also enable theSimulate ODBC 1.0
option. - Include a
TIMESTAMP
in all tables that you want to be able to update. - Include a primary key in the table. If not, new or updated rows may show up as
#DELETED#
. - Use only
DOUBLE
float fields. Access fails when comparing with single-precision floats. The symptom usually is that new or updated rows may show up as#DELETED#
or that you cannot find or update rows. - If you are using Connector/ODBC to link to a table that has a
BIGINT
column, the results are displayed as#DELETED
. The work around solution is:- Have one more dummy column with
TIMESTAMP
as the data type. - Select the
Change BIGINT columns to INT
option in the connection dialog in ODBC DSN Administrator. - Delete the table link from Access and re-create it.
Old records still display as
#DELETED#
, but newly added/updated records are displayed properly. - Have one more dummy column with
21.1.7.3.5: How do I handle Write Conflicts or Row Location errors?
If you see the following errors, select the Return Matching Rows
option in the DSN configuration dialog, or specify OPTION=2
, as the connection parameter:
Write Conflict. Another user has changed your data. Row cannot be located for updating. Some values may have been changed since it was last read.
21.1.7.3.6: Exporting data from Access 97 to MariaDB reports a Syntax Error
.
This error is specific to Access 97 and versions of Connector/ODBC earlier than 3.51.02. Update to the latest version of the Connector/ODBC driver to resolve this problem.
21.1.7.3.7: Exporting data from Microsoft DTS to MariaDB reports a Syntax Error
.
This error occurs only with MariaDB tables using the TEXT
or VARCHAR
data types. You can fix this error by upgrading your Connector/ODBC driver to version 3.51.02 or higher.
21.1.7.3.8: Using ODBC.NET with Connector/ODBC, while fetching empty string (0 length), it starts giving the SQL_NO_DATA exception.
You can get the patch that addresses this problem from http://support.microsoft.com/default.aspx?scid=kb;EN-US;q319243.
21.1.7.3.9: Using SELECT COUNT(*) FROM
within Visual Basic and ASP returns an error.
tbl_name
This error occurs because the COUNT(*)
expression is returning a BIGINT
, and ADO cannot make sense of a number this big. Select the Change BIGINT columns to INT
option (option value 16384).
21.1.7.3.10: Using the AppendChunk()
or GetChunk()
ADO methods, the Multiple-step operation generated errors. Check each status value
error is returned.
The GetChunk()
and AppendChunk()
methods from ADO doesn't work as expected when the cursor location is specified as adUseServer
. On the other hand, you can overcome this error by using adUseClient
.
A simple example can be found from http://www.dwam.net/iishelp/ado/docs/adomth02_4.htm
21.1.7.3.11: Access Returns Another user had modified the record that you have modified
while editing records on a Linked Table.
In most cases, this can be solved by doing one of the following things:
- Add a primary key for the table if one doesn't exist.
- Add a timestamp column if one doesn't exist.
- Only use double-precision float fields. Some programs may fail when they compare single-precision floats.
If these strategies do not help, start by making a log file from the ODBC manager (the log you get when requesting logs from ODBCADMIN) and a Connector/ODBC log to help you figure out why things go wrong. For instructions, see , "Getting an ODBC Trace File".
21.1.7.3.12: When linking an application directly to the Connector/ODBC library under Unix/Linux, the application crashes.
Connector/ODBC 3.51 under Unix/Linux is not compatible with direct application linking. You must use a driver manager, such as iODBC or unixODBC to connect to an ODBC source.
21.1.7.3.13: Applications in the Microsoft Office suite are unable to update tables that have DATE
or TIMESTAMP
columns.
This is a known issue with Connector/ODBC. You must ensure that the field has a default value (rather than NULL
and that the default value is nonzero (that is, the default value is not 0000-00-00 00:00:00
).
21.1.7.3.14: When connecting Connector/ODBC 5.x (Beta) to a MariaDB 4.x server, the error 1044 Access denied for user 'xxx'@'%' to database 'information_schema'
is returned.
Connector/ODBC 5.x is designed to work with MariaDB 5.0 or later, taking advantage of the INFORMATION_SCHEMA
database to determine data definition information. Support for MariaDB is planned for the final release.
21.1.7.3.15: When calling SQLTables
, the error S1T00
is returned, but I cannot find this in the list of error numbers for Connector/ODBC.
The S1T00
error indicates that a general timeout has occurred within the ODBC system and is not a MariaDB error. Typically it indicates that the connection you are using is stale, the server is too busy to accept your request or that the server has gone away.
21.1.7.3.16: When linking to tables in Access 2000 and generating links to tables programmatically, rather than through the table designer interface, you may get errors about tables not existing.
There is a known issue with a specific version of the msjet40.dll
that exhibits this issue. The version affected is 4.0.9025.0. Reverting to an older version will enable you to create the links. If you have recently updated your version, check your WINDOWS
directory for the older version of the file and copy it to the drivers directory.
21.1.7.3.17: When I try to use batched statements, the execution of the batched statements fails.
Batched statement support was added in 3.51.18. Support for batched statements is not enabled by default. You must enable option FLAG_MULTI_STATEMENTS
, value 67108864, or select the Allow multiple statements flag within a GUI configuration.
21.1.7.3.18: When connecting to a MariaDB server using ADODB and Excel, occasionally the application fails to communicate with the server and the error Got an error reading communication packets
appears in the error log.
This error may be related to Keyboard Logger 1.1 from PanteraSoft.com, which is known to interfere with the network communication between MariaDB Connector/ODBC and MySQL.
21.1.7.3.19: When using some applications to access a MariaDB server using C/ODBC and outer joins, an error is reported regarding the Outer Join Escape Sequence.
This is a known issue with MariaDB Connector/ODBC which is not correctly parsing the 'Outer Join Escape Sequence', as per the specs at Microsoft ODBC Specs. Currently, Connector/ODBC will return value > 0 when asked for SQL_OJ_CAPABILITIES
even though no parsing takes place in the driver to handle the outer join escape sequence.
21.1.7.3.20: I can correctly store extended characters in the database (Hebrew/CJK) using C/ODBC 5.1, but when I retrieve the data, the text is not formatted correctly and I get garbled characters.
When using ASP and UTF8 characters, add the following to your ASP files to ensure that the data returned is correctly encoded:
Response.CodePage = 65001 Response.CharSet = 'utf-8'
21.1.7.3.21: I have a duplicate MariaDB Connector/ODBC entry within my Installed Programs list, but I cannot delete one of them.
This problem can occur when you upgrade an existing Connector/ODBC installation, rather than removing and then installing the updated version.Warning
To fix the problem, use any working uninstallers to remove existing installations and then may have to edit the contents of the registry. Make sure you have a backup of your registry information before attempting any editing of the registry contents.
21.1.7.3.22: When submitting queries with parameter binding using UPDATE
, my field values are being truncated to 255 characters.
Ensure that the FLAG_BIG_PACKETS
option is set for your connection. This removes the 255 character limitation on bound parameters.
21.1.7.3.23: Is it possible to disable data-at-execution using a flag?
If you do not want to use data-at-execution, simply remove the corresponding calls. For example:
SQLLEN ylen = SQL_LEN_DATA_AT_EXEC(10); SQLBindCol(hstmt,2,SQL_C_BINARY, buf, 10, &ylen);
Would become:
SQLBindCol(hstmt,2,SQL_C_BINARY, buf, 10, NULL);
Note that in the call to SQLBindCol()
, &ylen has been replaced by NULL.
For further information please refer to the MSDN documentation for SQLBindCol()
.
21.1.7.3.24: When you call SQLColumns()
for a table column that is AUTO_INCREMENT
, the NULLABLE
column of the result set is always SQL_NULLABLE (1)
.
This is because MariaDB reports the DEFAULT
value for such a column as NULL
. It means, if you insert a NULL
value into the column, you will get the next integer value for the table's auto_increment
counter.
Connector/ODBC Support
- Connector/ODBC Community Support
- How to Report Connector/ODBC Problems or Bugs
- How to Submit a Connector/ODBC Patch
- Connector/ODBC Change History
- Credits
- How to Report Connector/ODBC Problems or Bugs
There are many different places where you can get support for using Connector/ODBC. Always try the Connector/ODBC Mailing List or Connector/ODBC Forum. See , "Connector/ODBC Community Support", for help before reporting a specific bug or issue to MariaDB.
Connector/ODBC Community Support
Oracle provides assistance to the user community by means of its mailing lists. For Connector/ODBC-related issues, you can get help from experienced users by using the <myodbc@lists.mysql.com>
mailing list. Archives are available online at http://lists.mysql.com/myodbc.
For information about subscribing to MariaDB mailing lists or to browse list archives, visit http://lists.mysql.com/. See , "MySQL Mailing Lists".
Community support from experienced users is also available through the ODBC Forum. You may also find help from other users in the other MariaDB Forums, located at http://forums.mysql.com. See , "MySQL Community Support at the MariaDB Forums".
How to Report Connector/ODBC Problems or Bugs
If you encounter difficulties or problems with Connector/ODBC, start by making a log file from the ODBC Manager
(the log you get when requesting logs from ODBC ADMIN
) and Connector/ODBC. The procedure for doing this is described in , "Getting an ODBC Trace File".
Check the Connector/ODBC trace file to find out what could be wrong. Determine what statements were issued by searching for the string >mysql_real_query
in the myodbc.log
file.
Also, try issuing the statements from the mysql client program or from admndemo
. This helps you determine whether the error is in Connector/ODBC or MySQL.
If you find out something is wrong, please only send the relevant rows (maximum 40 rows) to the myodbc
mailing list. See , "MySQL Mailing Lists". Please never send the whole Connector/ODBC or ODBC log file!
Ideally, include the following information with the email:
- Operating system and version
- Connector/ODBC version
- ODBC Driver Manager type and version
- MySQL server version
- ODBC trace from Driver Manager
- Connector/ODBC log file from Connector/ODBC driver
- Simple reproducible sample
Remember that the more information you can supply to us, the more likely it is that we can fix the problem!
Also, before posting the bug, check the MyODBC mailing list archive at http://lists.mysql.com/myodbc.
If you are unable to find out what is wrong, the last option is to create an archive in tar or Zip format that contains a Connector/ODBC trace file, the ODBC log file, and a README
file that explains the problem. You can send this to ftp://ftp.mysql.com/pub/mysql/upload/. Only MariaDB engineers have access to the files you upload, and we are very discreet with the data.
If you can create a program that also demonstrates the problem, please include it in the archive as well.
If the program works with another SQL server, include an ODBC log file where you perform exactly the same SQL statements so that we can compare the results between the two systems.
Remember that the more information you can supply to us, the more likely it is that we can fix the problem.
How to Submit a Connector/ODBC Patch
You can send a patch or suggest a better solution for any existing code or problems by sending a mail message to <myodbc@lists.mysql.com>
.
Connector/ODBC Change History
The Connector/ODBC Change History (Changelog) is located with the main Changelog for MySQL. See "MySQL Connector/ODBC (MyODBC) Change History".
Credits
These are the developers that have worked on the Connector/ODBC and Connector/ODBC 3.51 Drivers from MariaDB Foundation.
- Michael (Monty) Widenius
- Venu Anuganti
- Peter Harvey
MySQL Connector/Net
- Connector/Net Versions
- Connector/Net Installation
- Connector/Net Visual Studio Integration
- Connector/Net Tutorials
- Connector/Net Programming
- Connector/Net Connection String Options Reference
- Connector/Net API Reference
- Connector/Net Support
- Connector/Net FAQ
- Connector/Net Installation
Connector/Net lets you easily develop .NET applications that require secure, high-performance data connectivity with MySQL. It implements the required ADO.NET interfaces and integrates into ADO.NET aware tools. Developers can build applications using their choice of .NET languages. Connector/Net is a fully managed ADO.NET driver written in 100% pure C#.
Connector/Net includes full support for:
- Features provided by MariaDB Server up to and including MariaDB Server version 5.5.
- Large-packet support for sending and receiving rows and BLOBs up to 2 gigabytes in size.
- Protocol compression, which enables compressing the data stream between the client and server.
- Connections using TCP/IP sockets, named pipes, or shared memory on Windows.
- Connections using TCP/IP sockets or Unix sockets on Unix.
- The Open Source Mono framework developed by Novell.
- Fully managed, does not utilize the MariaDB client library.
This document is intended as a user's guide to Connector/Net and includes a full syntax reference. Syntax information is also included within the Documentation.chm
file included with the Connector/Net distribution.
If you are using MariaDB 5.0 or later, and Visual Studio as your development environment, you can also use the MariaDB Visual Studio Plugin. The plugin acts as a DDEX (Data Designer Extensibility) provider: you can use the data design tools within Visual Studio to manipulate the schema and objects within a MariaDB database. For more information, see , "Connector/Net Visual Studio Integration".Note
Connector/Net 5.1.2 and later include the Visual Studio Plugin by default.
MySQL Connector/Net supports full versions of Visual Studio 2005, 2008, and 2010, although certain features are only available in Visual Studio 2010 when using MariaDB Connector/Net version 6.3.2 and later. Note that MariaDB Connector/Net does not currently support Express versions of Microsoft products, including Microsoft Visual Web Developer.
Key topics:
- For connection string properties when using the
MySqlConnection
class, see , "Connector/Net Connection String Options Reference".
Connector/Net Versions
There are several versions of Connector/Net available:
- Connector/Net 6.5 includes support for MariaDB Server 5.6, 5.5, 5.1, and 5.0. Important new features include interceptor classes for exceptions and commands, support for the MariaDB 5.6 fractional seconds feature, better partial-trust support, and better IntelliSense, including auto-completion when editing stored procedures or
.mysql
files. - Connector/Net 6.4 includes support for MariaDB Server 5.5, 5.1, and 5.0. Important new features include support for Windows authentication (when connecting to MariaDB Server 5.5+), table caching on the client side, simple connection fail-over support, and improved SQL generation from the Entity Framework provider.
- Connector/Net 6.3 includes support for MariaDB Server 5.5, 5.1, and 5.0. Important new features include integration with Visual Studio 2010, such as availability of DDL T4 template for Entity Framework, and a custom MariaDB SQL Editor. Other features include refactored transaction scope: Connector/Net now supports nested transactions in a scope where they use the same connection string.
- Connector/Net 6.2 includes support for MariaDB Server 5.5, 5.1, 5.0, and 4.1. Important new features include a new logging system and client SSL certificates.
- Connector/Net 6.1 includes support for MariaDB Server 5.5, 5.1, 5.0, and 4.1. Important new features include the MariaDB Website Configuration Tool and a Session State Provider.
- Connector/Net 6.0 includes support for MariaDB Server 5.5, 5.1, 5.0, and 4.1.
This version of Connector/Net is no longer supported.
- Connector/Net 5.2 includes support for MariaDB Server 5.5, 5.1, 5.0, and 4.1 features. Connector/Net 5.2 also includes support for a new membership/role provider, Compact Framework 2.0, a new stored procedure parser and improvements to
GetSchema
. Connector/Net 5.2 also includes the Visual Studio Plugin as a standard installable component.This version of Connector/Net is no longer supported.
- Connector/Net 5.1 includes support for MariaDB Server 5.5, 5.1, 5.0, 4.1, and 4.0 features. Connector/Net 5.1 also includes support for a new membership/role provider, Compact Framework 2.0, a new stored procedure parser and improvements to
GetSchema
. Connector/Net 5.1 also includes the Visual Studio Plugin as a standard installable component.This version of Connector/Net is no longer supported.
- Connector/Net 5.0 includes support for MariaDB Server 5.1, 5.0, 4.1 and 4.0 features. Connector/Net 5.0 also includes full support for the ADO.Net 2.0 interfaces and subclasses, includes support for the usage advisor and performance monitor (PerfMon) hooks.
This version of Connector/Net is no longer supported.
- Connector/Net 1.0 includes support for MariaDB Server 5.0, 4.1, and 4.0 features, and full compatibility with the ADO.NET driver interface.
This version of Connector/Net is no longer supported.
The latest source code for Connector/Net can be downloaded from the MariaDB public Subversion server. For further details, see , "Installing Connector/Net from the source code".
The following tables shows the .NET Framework version required, and the MariaDB Server version supported by Connector/Net:
Table 20.5. Connector/Net Requirements for Related Products
Connector/Net version | ADO.NET version supported | .NET Framework version required | MySQL Server version supported | Currently supported |
---|---|---|---|---|
6.4 | 2.x+ | 2.x+, 4.x+ for VS 2010 support | 5.5, 5.1, 5.0 | Yes |
6.3 | 2.x+ | 2.x+, 4.x+ for VS 2010 support | 5.5, 5.1, 5.0 | Yes |
6.2 | 2.x+ | 2.x+ | 5.5, 5.1, 5.0, 4.1 | Yes |
6.1 | 2.x+ | 2.x+ | 5.5, 5.1, 5.0, 4.1 | Yes |
6.0 | 2.x+ | 2.x+ | 5.5, 5.1, 5.0, 4.1 | Critical issues only |
5.2 | 2.x+ | 2.x+ | 5.5, 5.1, 5.0, 4.1 | No |
5.1 | 2.x+ | 2.x+ | 5.5, 5.1, 5.0, 4.1, 4.0 | No |
5.0 | 2.x+ | 2.x+ | 5.0, 4.1, 4.0 | No |
1.0 | 1.x | 1.x | 5.0, 4.1, 4.0 | No |
Version numbers for MariaDB products are formatted as X.Y.Z, where Z=0 indicates alpha, Z=1 indicates beta, and Z>=2 indicates GA. However, Windows tools (Control Panel, properties display) may show the version numbers as XX.YY.ZZ. For example, the official MariaDB formatted version number 5.0.9 may be displayed by Windows tools as 5.00.09. The two versions are the same; only the number display format is different.
Connector/Net Installation
- Installing Connector/Net on Windows
- Installing Connector/Net on Unix with Mono
- Installing Connector/Net from the source code
- Installing Connector/Net on Unix with Mono
Connector/Net runs on any platform that supports the .NET framework. The .NET framework is primarily supported on recent versions of Microsoft Windows, and is supported on Linux through the Open Source Mono framework (see http://www.mono-project.com).
Connector/Net is available for download from http://dev.mysql.com/downloads/connector/net/.
Installing Connector/Net on Windows
On Windows, installation is supported either through a binary installation process or by downloading a Zip file with the Connector/Net components.
Before installing, ensure that your system is up to date, including installing the latest version of the .NET Framework.
Installing Connector/Net using the Installer
Using the installer is the most straightforward method of installing Connector/Net on Windows and the installed components include the source code, test code and full reference documentation.
Connector/Net is installed through the use of a Windows Installer (.msi
) installation package, which can be used to install Connector/Net on all Windows operating systems. The MSI package in contained within a Zip archive named mysql-connector-net-
, where version
.zipversion
indicates the Connector/Net version.
To install Connector/Net:
- Double-click the MSI installer file extracted from the Zip you downloaded. Click Next to start the installation.
- You must choose the type of installation to perform.
For most situations, the Typical installation is suitable. Click the Typical button and proceed to Step 5. A Complete installation installs all the available files. To conduct a Complete installation, click the Complete button and proceed to step 5. To customize your installation, including choosing the components to install and some installation options, click the Custom button and proceed to Step 3.
The Connector/Net installer will register the connector within the Global Assembly Cache (GAC) - this will make the Connector/Net component available to all applications, not just those where you explicitly reference the Connector/Net component. The installer will also create the necessary links in the Start menu to the documentation and release notes.
- If you have chosen a custom installation, you can select the individual components to install, including the core interface component, supporting documentation (a CHM file) samples and examples, and the source code. Select the items, and their installation level, and then click Next to continue the installation.Note
For Connector/Net 1.0.8 or lower and Connector 5.0.4 and lower the installer will attempt to install binaries for both 1.x and 2.x of the .NET Framework. If you only have one version of the framework installed, the connector installation may fail. If this happens, you can choose the framework version to be installed through the custom installation step.
- You will be given a final opportunity to confirm the installation. Click Install to copy and install the files onto your machine.
- Once the installation has been completed, click Finish to exit the installer.
Unless you choose otherwise, Connector/Net is installed in C:\Program Files\MySQL\MySQL Connector Net
, where X.X.X
X.X.X
is replaced with the version of Connector/Net you are installing. New installations do not overwrite existing versions of Connector/Net.
Depending on your installation type, the installed components will include some or all of the following components:
bin
: Connector/Net MariaDB libraries for different versions of the .NET environment.docs
: Connector/Net documentation in CHM format.samples
: Sample code and applications that use the Connector/Net component.src
: The source code for the Connector/Net component.
You may also use the /quiet
or /q
command-line option with the msiexec
tool to install the Connector/Net package automatically (using the default options) with no notification to the user. Using this method the user cannot select options. Additionally, no prompts, messages or dialog boxes will be displayed.
C:\> msiexec /package connector-net.msi /quiet
To provide a progress bar to the user during automatic installation, use the /passive
option.
Installing Connector/Net using the Zip packages
If you are having problems running the installer, you can download a Zip file without an installer as an alternative. That file is called mysql-connector-net-
. Once downloaded, you can extract the files to a location of your choice.
version
-noinstall.zip
The file contains the following directories:
bin
: Connector/Net MariaDB libraries for different versions of the .NET environment.Docs
: Connector/Net documentation in CHM format.Samples
: Sample code and applications that use the Connector/Net component.
Connector/Net 6.0.x has a different directory structure:
Assemblies
: A collection of DLLs that make up the connector functionality.Documentation
: Connector/Net documentation in CHM format.Samples
: sample code and applications that use the Connector/Net component.
There is also another Zip file available for download called mysql-connector-net-
. This file contains the source code distribution.
version
-src.zip
The file contains the following directories:
Documentation
: Source files to build the documentation into the compiled HTML (CHM) format.Installer
: Source files to build the Connector/Net installer program.MySql.Data
: Source files for the core data provider.MySql.VisualStudio
: Source files for the Microsoft Visual Studio extensions.MySql.Web
: Source files for the web providers. This includes code for the membership provider, role provider and profile provider. These are used in ASP.NET web sites.Samples
: Source files for several example applications.Tests
: A spreadsheet listing test cases.VisualStudio
: Resources used by the Visual Studio plugin.
Finally, ensure that MySql.Data.dll
is accessible to your program at build time (and run time). If using Microsoft Visual Studio, add MySql.Data
as a Reference to your project.Note
If using MariaDB Connector/Net 6.3.5 and above, the MySql.Data
file provided will work with both .NET Framework 2.x and 4.x.
Installing Connector/Net on Unix with Mono
There is no installer available for installing the Connector/Net component on your Unix installation. Before installing, please ensure that you have a working Mono project installation. You can test whether your system has Mono installed by typing:
shell> mono --version
The version of the Mono JIT compiler is displayed.
To compile C# source code, make sure a Mono C# compiler is installed. Note that there are two Mono C# compilers available, mcs
, which accesses the 1.0-profile libraries, and gmcs
, which accesses the 2.0-profile libraries.
To install Connector/Net on Unix/Mono:
- Download the
mysql-connector-net-
and extract the contents to a directory of your choice, for example:version
-noinstall.zip~/connector-net/
. - In the directory where you unzipped the connector to, change into the
bin
directory. Ensure the fileMySql.Data.dll
is present. - You must register the Connector/Net component,
MySql.Data
, in the Global Assembly Cache (GAC). In the current directory enter thegacutil
command:root-shell> gacutil /i MySql.Data.dll
This will register
MySql.Data
into the GAC. You can check this by listing the contents of/usr/lib/mono/gac
, where you will findMySql.Data
if the registration has been successful.
You are now ready to compile your application. You must ensure that when you compile your application you include the Connector/Net component using the -r:
command-line option. For example:
shell> gmcs -r:System.dll -r:System.Data.dll -r:MySql.Data.dll HelloWorld.cs
Note, the assemblies that are referenced depend on the requirements of the application, but applications using Connector/Net must provide -r:MySql.Data
as a minimum.
You can further check your installation by running the compiled program, for example:
shell> mono HelloWorld.exe
Installing Connector/Net from the source code
CautionRead this section only if you are interested in helping us test our new code. If you just want to get Connector/Net up and running on your system, use a standard release distribution.
Obtaining the source code
To obtain the most recent development source tree, you first need to download and install Bazaar. You can obtain Bazaar from the Bazaar VCS Website. Bazaar is supported by any platform that supports Python, and is therefore compatible with any Linux, Unix, Windows or Mac OS X host. Instructions for downloading and installing Bazaar on the different platforms are available on the Bazaar Web site.
The most recent development source tree is available from our public Subversion trees at http://dev.mysql.com/tech-resources/sources.html.
To check out out the Connector/Net sources, change to the directory where you want the copy of the Connector/Net tree to be stored, then use the following command:
shell> bzr branch lp:connectornet/trunk
To download a specific version of Connector/Net, specify the version number instead of trunk
. For example, to obtain a copy of the 6.0 version of the source tree:
shell> bzr branch lp:connectornet/6.0
Source packages are also available on the downloads page.
Building the source code on Windows
The following procedure can be used to build the connector on Microsoft Windows.
- Obtain the source code, either from the Subversion server, or through one of the prepared source code packages.
- Navigate to the root of the source code tree.
- A Microsoft Visual Studio 2005 solution file is available to build the connector, this is called
MySQL-VS2005.sln
. Click this file to load the solution into Visual Studio. - Select Build, Build Solution from the main menu to build the solution.
Building the source code on Unix
Support for building Connector/Net on Mono/Unix is currently not available.
Connector/Net Visual Studio Integration
- Making a Connection
- Using IntelliSense in the SQL Editor
- Editing Tables
- Editing Views
- Editing Stored Procedures and Functions
- Editing Triggers
- Editing User Defined Functions (UDF)
- Cloning Database Objects
- Dropping Database Objects
- Using the ADO.NET Entity Framework
- MySQL Website Configuration Tool
- MySQL SQL Editor
- DDL T4 Template Macro
- Using IntelliSense in the SQL Editor
When MariaDB Connector/Net is installed on Microsoft Windows, Visual Studio integration components are also installed and initialized. This enables the developer to work seamlessly with MariaDB Connector/Net in the familiar Visual Studio environment, as described in the following sections of the manual.
MySQL Connector/Net supports Visual Studio versions 2005, 2008, and 2010. However, only MariaDB Connector/Net version 6.3 and higher fully integrate with Visual Studio 2010, although applications using earlier versions of the connector can be built with the Visual Studio 2010 environment using .NET 2.x frameworks.
Visual Studio 2010 support was introduced with MariaDB Connector/Net 6.3.2. From version 6.3.2 the connector ships with both .NET 2.x and .NET 4.x versions of the entity framework support files, mysql.data.ef.dll
and mysql.visualstudio.dll
. The .NET 4.x versions are required to enable new integration features supported in Visual Studio 2010, including:
- New DDL T4 template for the Entity Framework (EF) - This enables developers to design an EF model from scratch and use the native Visual Studio 2010 facility to generate MariaDB DDL from that model. This is done by creating the model, and with the model open, choosing the SSDLToMySQL template in the properties window. The correct DDL is then generated. The developer can then save this code as a
.mysql
file in their project and execute it against the MariaDB server. - New SQL Editor - A new SQL editor has been included that enables connections to servers to execute SQL. This is activated by creating a new file with a
.mysql
extension. A new template is also included to allow creation of this file type using the Visual Studio 2010 main menu item File, New. Note that the MariaDB SQL Editor is also available in 2005 and 2008.
Making a Connection
Once the connector is installed, you can use it to create, modify, and delete connections to MariaDB databases. To create a connection with a MariaDB database, perform the following steps:
- Start Visual Studio, and open the Server Explorer window (View, Server Explorer option in the main Visual Studio menu, or Control+W, L keyboard shortcuts).
- Right-click the Data Connections node, and choose the Add Connection... menu item.
- Add Connection dialog opens. Press the Change button to choose MariaDB Database as a data source.
Figure 20.1. Add Connection Context Menu
- Change Data Source dialog opens. Choose MariaDB Database in the list of data sources (or the
<other>
option, if MariaDB Database is absent), and then choose .NET Framework Data Provider for MariaDB in the combo box of data providers.Figure 20.2. Choose Data Source
- Input the connection settings: the server host name (for example, localhost if the MariaDB server is installed on the local machine), the user name, the password, and the default schema name. Note that you must specify the default schema name to open the connection.
Figure 20.3. Add Connection Dialog
- You can also set the port to connect with the MariaDB server by pressing the Advanced button. To test connection with the MariaDB server, set the server host name, the user name, and the password, and press the Test Connection button. If the test succeeds, the success confirmation dialog opens.
- After you set all settings and test the connection, press OK. The newly created connection is displayed in Server Explorer. Now you can work with the MariaDB server through standard Server Explorer GUI.
Figure 20.4. New Data Connection
After the connection is successfully established, all settings are saved for future use. When you start Visual Studio for the next time, open the connection node in Server Explorer to establish a connection to the MariaDB server again.
To modify and delete a connection, use the Server Explorer context menu for the corresponding node. You can modify any of the settings by overwriting the existing values with new ones. Note that the connection may be modified or deleted only if no active editor for its objects is opened: otherwise, you may lose your data.
Using IntelliSense in the SQL Editor
IntelliSense support is available starting in Connector/Net 6.5. Once you have established a connection, for example, using the Connect to MySql toolbar button, you can get autocompletion as you type, or by pressing Control+J. Depending on the context, the autocompletion dialog can show the list of available tables, table columns, or stored procedures (with the routine's signature as a tooltip). Typing some characters before pressing Control+J filters the choices to those items starting with that prefix.
Editing Tables
Connector/Net contains a table editor, which enables the visual creation and modification of tables.
The Table Designer can be accessed through a mouse action on table-type node of Server Explorer. To create a new table, right-click the Tables node (under the connection node) and choose the Create Table command from the context menu.
To modify an existing table, double-click the node of the table to modify, or right-click this node and choose the Design item from the context menu. Either of the commands opens the Table Designer.
The table editor is implemented in the manner of the well-known Query Browser Table Editor, but with minor differences.
Figure 20.5. Editing New Table

Table Designer consists of the following parts:
- Columns Editor - a data grid on top of the Table Designer. Use the Columns grid for column creation, modification, and deletion.
- Indexes tab - a tab on bottom of the Table Designer. Use the Indexes tab for indexes management.
- Foreign Keys tab - a tab on bottom of the Table Designer. Use the Foreign Keys tab for foreign keys management.
- Column Details tab - a tab on bottom of the Table Designer. Use the Column Details tab to set advanced column options.
- Properties window - a standard Visual Studio Properties window, where the properties of the edited table are displayed. Use the Properties window to set the table properties.
Each of these areas is discussed in more detail in subsequent sections.
To save changes you have made in the Table Designer, use either Save or Save All button of the Visual Studio main toolbar, or press Control+S. If you have not already named the table, you will be prompted to do so.
Figure 20.6. Choose Table Name

Once the table is created, you can view it in the Server Explorer.
Figure 20.7. Newly Created Table

The Table Designer main menu enables you to set a Primary Key column, edit Relationships such as Foreign Keys, and create Indexes.
Figure 20.8. Table Designer Main Menu

Column Editor
You can use the Column Editor to set or change the name, data type, default value, and other properties of a table column. To set the focus to a needed cell of a grid, use the mouse click. Also you can move through the grid using Tab and Shift+Tab keys.
To set or change the name, data type, default value and comment of a column, activate the appropriate cell and type the desired value.
To set or unset flag-type column properties (NOT NULL
, auto incremented, flags), check or uncheck the corresponding check boxes. Note that the set of column flags depends on its data type.
To reorder columns, index columns or foreign key columns in the Column Editor, select the whole column to reorder by clicking the selector column on the left of the column grid. Then move the column by using Control+Up (to move the column up) or Control+Down (to move the column down) keys.
To delete a column, select it by clicking the selector column on the left of the column grid, then press the Delete button on a keyboard.
Editing Indexes
Indexes management is performed using the Indexes/Keys dialog.
To add an index, select Table Designer, Indexes/Keys... from the main menu, and click Add to add a new index. You can then set the index name, index kind, index type, and a set of index columns.
Figure 20.9. Indexes Dialog

To remove an index, select it in the list box on the left, and click the Delete button.
To change index settings, select the needed index in the list box on the left. The detailed information about the index is displayed in the panel on the right hand side. Change the desired values.
Editing Foreign Keys
Foreign Keys management is performed using the Foreign Key Relationships dialog.
To add a foreign key, select Table Designer, Relationships... from the main menu. This displays the Foreign Key Relationship dialog. Click Add. You can then set the foreign key name, referenced table name, foreign key columns, and actions upon update and delete.
To remove a foreign key, select it in the list box on the left, and click the Delete button.
To change foreign key settings, select the required foreign key in the list box on the left. The detailed information about the foreign key is displayed in the right hand panel. Change the desired values.
Figure 20.10. Foreign Key Relationships Dialog

Column Properties
The Column Properties tab can be used to set column options. In addition to the general column properties presented in the Column Editor, in the Column Properties tab you can set additional properties such as Character Set, Collation and Precision.
Table Properties
To bring up Table Properties select the table and right-click to activate the context menu. Select Properties. The Table Properties dockable window will be displayed.
Figure 20.11. Table Properties Menu Item

The following table properties can be set:
- Auto Increment
- Average Row Length
- Character Set
- Collation
- Comment
- Data Directory
- Index Directory
- Maximum Rows
- Minimum Rows
- Name
- Row Format
- Schema
- Storage Engine
The property Schema
is read-only.
Figure 20.12. Table Properties

Editing Views
To create a new view, right-click the Views node under the connection node in Server Explorer. From the node's context menu, choose the Create View command. This command opens the SQL Editor.
Figure 20.13. Editing View SQL

You can then enter the SQL for your view.
Figure 20.14. View SQL Added

To modify an existing view, double-click a node of the view to modify, or right-click this node and choose the Alter View command from a context menu. Either of the commands opens the SQL Editor.
All other view properties can be set in the Properties window. These properties are:
- Catalog
- Check Option
- Definer
- Definition
- Definer
- Is Updatable
- Name
- Schema
- Security Type
Some of these properties can have arbitrary text values, others accept values from a predefined set. In the latter case, set the desired value with an embedded combobox.
The properties Is Updatable
and Schema
are readonly.
To save changes you have made, use either Save or Save All buttons of the Visual Studio main toolbar, or press Control+S.
Figure 20.15. View SQL Saved

Editing Stored Procedures and Functions
To create a new stored procedure, right-click the Stored Procedures node under the connection node in Server Explorer. From the node's context menu, choose the Create Routine command. This command opens the SQL Editor.
Figure 20.16. Edit Stored Procedure SQL

To create a new stored function, right-click the Functions node under the connection node in Server Explorer. From the node's context menu, choose the Create Routine command.
To modify an existing stored routine (procedure or function), double-click the node of the routine to modify, or right-click this node and choose the Alter Routine command from the context menu. Either of the commands opens the SQL Editor.
To create or alter the routine definition using SQL Editor, type this definition in the SQL Editor using standard SQL. All other routine properties can be set in the Properties window. These properties are:
- Body
- Catalog
- Comment
- Creation Time
- Data Access
- Definer
- Definition
- External Name
- External Language
- Is Deterministic
- Last Modified
- Name
- Parameter Style
- Returns
- Schema
- Security Type
- Specific Name
- SQL Mode
- SQL Path
- Type
Some of these properties can have arbitrary text values, others accept values from a predefined set. In the latter case, set the desired value using the embedded combo box.
You can also set all the options directly in the SQL Editor, using the standard CREATE PROCEDURE
or CREATE FUNCTION
statement. However, it is recommended to use the Properties window instead.
To save changes you have made, use either Save or Save All buttons of the Visual Studio main toolbar, or press Control+S.
Figure 20.17. Stored Procedure SQL Saved

Editing Triggers
To create a new trigger, right-click the node of the table in which to add the trigger. From the node's context menu, choose the Create Trigger command. This command opens the SQL Editor.
To modify an existing trigger, double-click the node of the trigger to modify, or right-click this node and choose the Alter Trigger command from the context menu. Either of the commands opens the SQL Editor.
To create or alter the trigger definition using SQL Editor, type the trigger statement in the SQL Editor using standard SQL.Note
Enter only the trigger statement, that is, the part of the CREATE TRIGGER
query that is placed after the FOR EACH ROW
clause.
All other trigger properties are set in the Properties window. These properties are:
- Definer
- Event Manipulation
- Name
- Timing
Some of these properties can have arbitrary text values, others accept values from a predefined set. In the latter case, set the desired value using the embedded combo box.
The properties Event Table
, Schema
, and Server
in the Properties window are read-only.
To save changes you have made, use either Save or Save All buttons of the Visual Studio main toolbar, or press Control+S. Before changes are saved, you will be asked to confirm the execution of the corresponding SQL query in a confirmation dialog.
Editing User Defined Functions (UDF)
To create a new User Defined Function (UDF), right-click the UDFs node under the connection node in Server Explorer. From the node's context menu, choose the Create UDF command. This command opens the UDF Editor.
To modify an existing UDF, double-click the node of the UDF to modify, or right-click this node and choose the Alter UDF command from the context menu. Either of these commands opens the UDF Editor.
The UDF editor enables you to set the following properties:
- Name
- So-name (DLL name)
- Return type
- Is Aggregate
There are text fields for both names, a combo box for the return type, and a check box to indicate if the UDF is aggregate. All these options are also accessible using the Properties window.
The property Server
in the Properties window is read-only.
To save changes you have made, use either Save or Save All buttons of the Visual Studio main toolbar, or press Control+S. Before changes are saved, you will be asked to confirm the execution of the corresponding SQL query in a confirmation dialog.
Cloning Database Objects
Tables, views, stored procedures, and functions can be cloned using the appropriate Clone command from the context menu: Clone Table, Clone View, Clone Routine. The clone commands open the corresponding editor for a new object: the Table Editor for cloning a table, and the SQL Editor for cloning a view or a routine.
The editor is filled with values of the original object. You can modify these values in a usual manner.
To save the cloned object, use either Save or Save All buttons of the Visual Studio main toolbar, or press Control+S. Before changes are saved, you will be asked to confirm the execution of the corresponding SQL query in a confirmation dialog.
Dropping Database Objects
Tables, views, stored routines, triggers, and UDFs can be dropped with the appropriate Drop command selected from its context menu: Drop Table, Drop View, Drop Routine, Drop Trigger, Drop UDF.
You will be asked to confirm the execution of the corresponding drop query in a confirmation dialog.
Dropping of multiple objects is not supported.
Using the ADO.NET Entity Framework
Connector/Net 6.0 introduced support for the ADO.NET Entity Framework. ADO.NET Entity Framework was included with .NET Framework 3.5 Service Pack 1, and Visual Studio 2008 Service Pack 1. ADO.NET Entity Framework was released on 11th August 2008.
ADO.NET Entity Framework provides an Object Relational Mapping (ORM) service, mapping the relational database schema to objects. The ADO.NET Entity Framework defines several layers, these can be summarized as:
- Logical - this layer defines the relational data and is defined by the Store Schema Definition Language (SSDL).
- Conceptual - this layer defines the .NET classes and is defined by the Conceptual Schema Definition Language (CSDL)
- Mapping - this layer defines the mapping from .NET classes to relational tables and associations, and is defined by Mapping Specification Language (MSL).
Connector/Net integrates with Visual Studio 2008 to provide a range of helpful tools to assist the developer.
A full treatment of ADO.NET Entity Framework is beyond the scope of this manual. If you are unfamiliar with ADO.NET, review the Microsoft ADO.NET Entity Framework documentation.
Tutorials on getting started with ADO.NET Entity Framework are available. See , "Tutorial: Using an Entity Framework Entity as a Windows Forms Data Source" and , "Tutorial: Databinding in ASP.NET using LINQ on Entities".
MySQL Website Configuration Tool
MySQL Connector/Net 6.1 introduced the MariaDB Website Configuration Tool. This is a facility available in Visual Studio that enables you to configure the Membership, Role, Session State and Profile Provider, without having to resort to editing configuration files. You set your configuration options within the tool, and the tool modifies your web.config
file accordingly.
The MariaDB Website Configuration Tool appears as a small icon on the Solution Explorer toolbar in Visual Studio, as show by the following screenshot:
Figure 20.18. MariaDB Website Configuration Tool

Clicking the Website Configuration Tool icon launches the wizard and displays the first screen:
Figure 20.19. MariaDB Website Configuration Tool - Membership

This allows you to enable use of the MariaDB Membership Provider. Click the check box to enable this. You can now enter the name of the application that you are creating the configuration for. You can also enter a description for the application.
You can then click the Edit... button to launch the Connection String Editor:
Figure 20.20. MariaDB Website Configuration Tool - Connection String Editor

Note that if you have already defined a connection string for the providers manually in web.config
, or previously using the tool, this will be automatically loaded and displayed, and can then be modified in this dialog.
You can also ensure that the necessary schemas are created automatically for you by selecting the Autogenerate Schema check box. These schemas are used to store membership information. The database used to storage is the one specified in the connection string.
You can also ensure that exceptions generated by the application will be written to the event log by selecting the Write exceptions to event log check box.
Clicking the Advanced... button launches a dialog that enables you to set Membership Options. These options dictate such variables as password length required when a user signs up, whether the password is encrypted and whether the user can reset their password or not.
Figure 20.21. MariaDB Website Configuration Tool - Advanced Options

Once information has been set up as required for configuration of the Membership Provider, the Next button can be clicked to display the Roles Provider screen:
Figure 20.22. MariaDB Website Configuration Tool - Roles

Again the connection string can be edited, a description added and Autogenerate Schema can be enabled before clicking Next to go to the Profiles Provider screen:
Figure 20.23. MariaDB Website Configuration Tool - Profiles

This screen display similar options to the previous screens.
Click Next to proceed to the Session State configuration page:
Figure 20.24. MariaDB Website Configuration Tool - Session State

Once you have set up the Session State Provider as required, click Finish to exit the wizard.
At this point, it is necessary to select the Authentication Type to From Internet. Launch the ASP.NET Configuration Tool and select the Security tab. Click the Select authentication type link and ensure that the From the internet radio button is selected. You can now examine the database you created to store membership information. All the necessary tables will have been created for you:
Figure 20.25. MariaDB Website Configuration Tool - Tables

MySQL SQL Editor
MySQL Connector/Net 6.3.2 introduced a new MariaDB SQL Editor. The easiest way to invoke the editor is by selecting the New, File menu item from the Visual Studio main menu. This displays the New File dialog:
Figure 20.26. MariaDB SQL Editor - New File

From the New File dialog, select the MariaDB template, and then double-click the MariaDB SQL Script document, or click the Open button.
The MariaDB SQL Editor will be displayed. You can now enter SQL code as required, or connect to a MariaDB server. Click the Connect to MariaDB button in the MariaDB SQL Editor toolbar. You can enter the connection details into the Connect to MariaDB dialog that is displayed. You can enter the server name, user ID, password and database to connect to, or click the Advanced button to select other connection string options. Click the Connect button to connect to the MariaDB server. To execute your SQL code against the server, click the Run SQL button on the toolbar.
Figure 20.27. MariaDB SQL Editor - Query

The results from any queries are displayed on the Results tab. Any errors are displayed on the Messages tab.
DDL T4 Template Macro
MySQL Connector/Net 6.3 introduced the ability to convert an Entity Framework model to MariaDB DDL code. Starting with a blank model, an entity model can be developed in Visual Studio's designer. Once the model has been created, the model's properties can be selected, and in the Database Script Generation category of the model's properties, the property DDL Generation can be found. The value SSDLToMySQL.tt(VS) can then be selected from the drop-down listbox.
Figure 20.28. DDL T4 Template Macro - Model Properties

Right-clicking the model design area will display a context-sensitive menu. Selecting Generate Database from Model from the menu will display the Generate Database Wizard. The wizard can then be used to generate MariaDB DDL code.
Figure 20.29. DDL T4 Template Macro - Generate Database Wizard

Connector/Net Tutorials
- Tutorial: An Introduction to Connector/Net Programming
- Tutorial: MariaDB Connector/Net ASP.NET Membership and Role Provider
- Tutorial: MariaDB Connector/Net ASP.NET Session State Provider
- Tutorial: MariaDB Connector/Net ASP.NET Profile Provider
- Tutorial: Using an Entity Framework Entity as a Windows Forms Data Source
- Tutorial: Databinding in ASP.NET using LINQ on Entities
- Tutorial: Using SSL with MariaDB Connector/Net
- Tutorial: Using MySqlScript
- Tutorial: Generating MariaDB DDL from an Entity Framework Model
- Tutorial: MariaDB Connector/Net ASP.NET Membership and Role Provider
Tutorial: An Introduction to Connector/Net Programming
- The MySqlConnection Object
- The MySqlCommand Object
- Working with Decoupled Data
- Working with Parameters
- Working with Stored Procedures
- The MySqlCommand Object
This section provides a gentle introduction to programming with Connector/Net. The example code is written in C#, and is designed to work on both Microsoft .NET Framework and Mono.
This tutorial is designed to get you up and running with Connector/Net as quickly as possible, it does not go into detail on any particular topic. However, the following sections of this manual describe each of the topics introduced in this tutorial in more detail. In this tutorial you are encouraged to type in and run the code, modifying it as required for your setup.
This tutorial assumes you have MariaDB and Connector/Net already installed. It also assumes that you have installed the World example database, which can be downloaded from the MySQL Documentation page. You can also find details on how to install the database on the same page.Note
Before compiling the example code, make sure that you have added References to your project as required. The References required are System
, System.Data
and MySql.Data
.
The MySqlConnection Object
For your Connector/Net application to connect to a MariaDB database, it must establish a connection by using a MySqlConnection
object.
The MySqlConnection
constructor takes a connection string as one of its parameters. The connection string provides necessary information to make the connection to the MariaDB database. The connection string is discussed more fully in , "Connecting to MariaDB Using Connector/Net". For a list of supported connection string options, see , "Connector/Net Connection String Options Reference".
The following code shows how to create a connection object:
using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial1 { public static void Main() { string connStr = 'server=localhost;user=root;database=world;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); // Perform database operations } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine('Done.'); } }
When the MySqlConnection
constructor is invoked, it returns a connection object, which is used for subsequent database operations. Open the connection before any other operations take place. Before the application exits, close the connection to the database by calling Close
on the connection object.
Sometimes an attempt to perform an Open
on a connection object can fail, generating an exception that can be handled using standard exception handling code.
In this section you have learned how to create a connection to a MariaDB database, and open and close the corresponding connection object.
The MySqlCommand Object
Once a connection has been established with the MariaDB database, the next step is do carry out the desired database operations. This can be achieved through the use of the MySqlCommand
object.
You will see how to create a MySqlCommand
object. Once it has been created, there are three main methods of interest that you can call:
- ExecuteReader - used to query the database. Results are usually returned in a
MySqlDataReader
object, created byExecuteReader
. - ExecuteNonQuery - used to insert and delete data.
- ExecuteScalar - used to return a single value.
Once a MySqlCommand
object has been created, you will call one of the above methods on it to carry out a database operation, such as perform a query. The results are usually returned into a MySqlDataReader
object, and then processed, for example the results might be displayed. The following code demonstrates how this could be done.
using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial2 { public static void Main() { string connStr = 'server=localhost;user=root;database=world;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); string sql = 'SELECT Name, HeadOfState FROM Country WHERE Continent="Oceania"'; MySqlCommand cmd = new MySqlCommand(sql, conn); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr[0]+' -- '+rdr[1]); } rdr.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine('Done.'); } }
When a connection has been created and opened, the code then creates a MySqlCommand
object. Note that the SQL query to be executed is passed to the MySqlCommand
constructor. The ExecuteReader
method is then used to generate a MySqlReader
object. The MySqlReader
object contains the results generated by the SQL executed on the command object. Once the results have been obtained in a MySqlReader
object, the results can be processed. In this case, the information is printed out by a while
loop. Finally, the MySqlReader
object is disposed of by running its Close
method on it.
In the next example, you will see how to use the ExecuteNonQuery
method.
The procedure for performing an ExecuteNonQuery
method call is simpler, as there is no need to create an object to store results. This is because ExecuteNonQuery
is only used for inserting, updating and deleting data. The following example illustrates a simple update to the Country
table:
using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial3 { public static void Main() { string connStr = 'server=localhost;user=root;database=world;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); string sql = 'INSERT INTO Country (Name, HeadOfState, Continent) VALUES ('Disneyland','Mickey Mouse', 'North America')'; MySqlCommand cmd = new MySqlCommand(sql, conn); cmd.ExecuteNonQuery(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine('Done.'); } }
The query is constructed, the command object created and the ExecuteNonQuery
method called on the command object. You can access your MariaDB database with the mysql command interpreter and verify that the update was carried out correctly.
Finally, you will see how the ExecuteScalar
method can be used to return a single value. Again, this is straightforward, as a MySqlDataReader
object is not required to store results, a simple variable will do. The following code illustrates how to use ExecuteScalar
:
using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial4 { public static void Main() { string connStr = 'server=localhost;user=root;database=world;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); string sql = 'SELECT COUNT(*) FROM Country'; MySqlCommand cmd = new MySqlCommand(sql, conn); object result = cmd.ExecuteScalar(); if (result != null) { int r = Convert.ToInt32(result); Console.WriteLine('Number of countries in the World database is: ' + r); } } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine('Done.'); } }
This example uses a simple query to count the rows in the Country
table. The result is obtained by calling ExecuteScalar
on the command object.
Working with Decoupled Data
Previously, when using MySqlDataReader
, the connection to the database was continually maintained, unless explicitly closed. It is also possible to work in a manner where a connection is only established when needed. For example, in this mode, a connection could be established to read a chunk of data, the data could then be modified by the application as required. A connection could then be reestablished only if and when the application writes data back to the database. This decouples the working data set from the database.
This decoupled mode of working with data is supported by Connector/Net. There are several parts involved in allowing this method to work:
- Data Set - The Data Set is the area in which data is loaded to read or modify it. A
DataSet
object is instantiated, which can store multiple tables of data. - Data Adapter - The Data Adapter is the interface between the Data Set and the database itself. The Data Adapter is responsible for efficiently managing connections to the database, opening and closing them as required. The Data Adapter is created by instantiating an object of the
MySqlDataAdapter
class. TheMySqlDataAdapter
object has two main methods:Fill
which reads data into the Data Set, andUpdate
, which writes data from the Data Set to the database. - Command Builder - The Command Builder is a support object. The Command Builder works in conjunction with the Data Adapter. When a
MySqlDataAdapter
object is created, it is typically given an initial SELECT statement. From thisSELECT
statement the Command Builder can work out the correspondingINSERT
,UPDATE
andDELETE
statements that would be required to update the database. To create the Command Builder, an object of the classMySqlCommandBuilder
is created.
Each of these classes will now be discussed in more detail.
Instantiating a DataSet object
A DataSet
object can be created simply, as shown in the following example code snippet:
DataSet dsCountry; ... dsCountry = new DataSet();
Although this creates the DataSet
object, it has not yet filled it with data. For that, a Data Adapter is required.
Instantiating a MySqlDataAdapter object
The MySqlDataAdapter
can be created as illustrated by the following example:
MySqlDataAdapter daCountry; ... string sql = 'SELECT Code, Name, HeadOfState FROM Country WHERE Continent="North America"'; daCountry = new MySqlDataAdapter (sql, conn);
Note, the MySqlDataAdapter
is given the SQL specifying the data to work with.
Instantiating a MySqlCommandBuilder object
Once the MySqlDataAdapter
has been created, it is necessary to generate the additional statements required for inserting, updating and deleting data. There are several ways to do this, but in this tutorial you will see how this can most easily be done with MySqlCommandBuilder
. The following code snippet illustrates how this is done:
MySqlCommandBuilder cb = new MySqlCommandBuilder(daCountry);
Note that the MySqlDataAdapter
object is passed as a parameter to the command builder.
Filling the Data Set
To do anything useful with the data from your database, you need to load it into a Data Set. This is one of the jobs of the MySqlDataAdapter
object, and is carried out with its Fill
method. The following example code illustrates this:
DataSet dsCountry; ... dsCountry = new DataSet(); ... daCountry.Fill(dsCountry, 'Country');
Note the Fill
method is a MySqlDataAdapter
method, the Data Adapter knows how to establish a connec tion with the database and retrieve the required data, and then populates the Data Set when the Fill
method is called. The second parameter "Country" is the table in the Data Set to update.
Updating the Data Set
The data in the Data Set can now be manipulated by the application as required. At some point, changes to data will need to be written back to the database. This is achieved through a MySqlDataAdapter
method, the Update
method.
daCountry.Update(dsCountry, 'Country');
Again, the Data Set and the table within the Data Set to update are specified.
Working Example
The interactions between the DataSet
, MySqlDataAdapter
and MySqlCommandBuilder
classes can be a little confusing, so their operation can perhaps be best illustrated by working code.
In this example, data from the World database is read into a Data Grid View control. Here, the data can be viewed and changed before clicking an update button. The update button then activates code to write changes back to the database. The code uses the principles explained above. The application was built using the Microsoft Visual Studio to place and create the user interface controls, but the main code that uses the key classes described above is shown below, and is portable.
using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; using System.Drawing; using System.Linq; using System.Text; using System.Windows.Forms; using MySql.Data; using MySql.Data.MySqlClient; namespace WindowsFormsApplication5 { public partial class Form1 : Form { MySqlDataAdapter daCountry; DataSet dsCountry; public Form1() { InitializeComponent(); } private void Form1_Load(object sender, EventArgs e) { string connStr = 'server=localhost;user=root;database=world;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { label2.Text = 'Connecting to MariaDB...'; string sql = 'SELECT Code, Name, HeadOfState FROM Country WHERE Continent="North America"'; daCountry = new MySqlDataAdapter (sql, conn); MySqlCommandBuilder cb = new MySqlCommandBuilder(daCountry); dsCountry = new DataSet(); daCountry.Fill(dsCountry, 'Country'); dataGridView1.DataSource = dsCountry; dataGridView1.DataMember = 'Country'; } catch (Exception ex) { label2.Text = ex.ToString(); } } private void button1_Click(object sender, EventArgs e) { daCountry.Update(dsCountry, 'Country'); label2.Text = 'MySQL Database Updated!'; } } }
The application running is shown below:
Figure 20.30. World Database Application

Working with Parameters
This part of the tutorial shows you how to use parameters in your Connector/Net application.
Although it is possible to build SQL query strings directly from user input, this is not advisable as it does not prevent erroneous or malicious information being entered. It is safer to use parameters as they will be processed as field data only. For example, imagine the following query was constructed from user input:
string sql = 'SELECT Name, HeadOfState FROM Country WHERE Continent = '+user_continent;
If the string user_continent
came from a Text Box control, there would potentially be no control over the string entered by the user. The user could enter a string that generates a run time error, or in the worst case actually harms the system. When using parameters it is not possible to do this because a parameter is only ever treated as a field parameter, rather than an arbitrary piece of SQL code.
The same query written user a parameter for user input would be:
string sql = 'SELECT Name, HeadOfState FROM Country WHERE Continent = @Continent';
Note that the parameter is preceded by an '@' symbol to indicate it is to be treated as a parameter.
As well as marking the position of the parameter in the query string, it is necessary to add a parameter to the Command object. This is illustrated by the following code snippet:
cmd.Parameters.AddWithValue('@Continent', 'North America');
In this example the string 'North America' is supplied as the parameter value statically, but in a more practical example it would come from a user input control.
A further example illustrates the complete process:
using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial5 { public static void Main() { string connStr = 'server=localhost;user=root;database=world;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); string sql = 'SELECT Name, HeadOfState FROM Country WHERE Continent=@Continent'; MySqlCommand cmd = new MySqlCommand(sql, conn); Console.WriteLine('Enter a continent e.g. 'North America', 'Europe': '); string user_input = Console.ReadLine(); cmd.Parameters.AddWithValue('@Continent', user_input); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr['Name']+' --- '+rdr['HeadOfState']); } rdr.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine('Done.'); } }
In this part of the tutorial you have see how to use parameters to make your code more secure.
Working with Stored Procedures
In this section, you will see how to work with stored procedures. This section assumes you have a basic understanding of what a stored procedure is, and how to create one.
For the purposes of this tutorial, you will create a simple Stored Procedure to see how it can be called from Connector/Net. In the MariaDB Client program, connect to the World database and enter the following stored procedure:
DELIMITER // CREATE PROCEDURE country_hos (IN con CHAR(20)) BEGIN SELECT Name, HeadOfState FROM Country WHERE Continent = con; END // DELIMITER ;
Test that the stored procedure works as expected by typing the following into the mysql command interpreter:
CALL country_hos('Europe');
Note that The stored routine takes a single parameter, which is the continent to restrict your search to.
Having confirmed that the stored procedure is present and correct, you can see how to access it from Connector/Net.
Calling a stored procedure from your Connector/Net application is similar to techniques you have seen earlier in this tutorial. A MySqlCommand
object is created, but rather than taking an SQL query as a parameter, it takes the name of the stored procedure to call. Set the MySqlCommand
object to the type of stored procedure, as shown by the following code snippet:
string rtn = 'country_hos'; MySqlCommand cmd = new MySqlCommand(rtn, conn); cmd.CommandType = CommandType.StoredProcedure;
In this case, the stored procedure requires you to pass a parameter. This can be achieved using the techniques seen in the previous section on parameters, , "Working with Parameters", as shown in the following code snippet:
cmd.Parameters.AddWithValue('@con', 'Europe');
The value of the parameter @con
could more realistically have come from a user input control, but for simplicity it is set as a static string in this example.
At this point, everything is set up and you can call the routine using techniques also learned in earlier sections. In this case, the ExecuteReader
method of the MySqlCommand
object is used.
Complete working code for the stored procedure example is shown below:
using System; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; public class Tutorial6 { public static void Main() { string connStr = 'server=localhost;user=root;database=world;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); string rtn = 'country_hos'; MySqlCommand cmd = new MySqlCommand(rtn, conn); cmd.CommandType = CommandType.StoredProcedure; cmd.Parameters.AddWithValue('@con', 'Europe'); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr[0] + ' --- ' + rdr[1]); } rdr.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine('Done.'); } }
In this section, you have seen how to call a stored procedure from Connector/Net. For the moment, this concludes our introductory tutorial on programming with Connector/Net.
Tutorial: MariaDB Connector/Net ASP.NET Membership and Role Provider
Many web sites feature the facility for the user to create a user account. They can then log into the web site and enjoy a personalized experience. This requires that the developer creates database tables to store user information, along with code to gather and process this data. This represents a burden on the developer, and there is the possibility for security issues to creep into the developed code. However, ASP.NET 2.0 introduced the Membership system. This system is designed around the concept of Membership, Profile and Role Providers, which together provide all of the functionality to implement a user system, that previously would have to have been created by the developer from scratch.
Currently, MariaDB Connector/Net provides Membership, Role, Profile and Session State Providers.
This tutorial shows you how to set up your ASP.NET web application to use the MariaDB Connector/Net Membership and Role Providers. It assumes that you have MariaDB Server installed, along with MariaDB Connector/Net and Microsoft Visual Studio. This tutorial was tested with MariaDB Connector/Net 6.0.4 and Microsoft Visual Studio 2008 Professional Edition. It is recommended you use 6.0.4 or above for this tutorial.
- Create a new database in the MariaDB Server using the MariaDB Command Line Client program (
MariaDB
), or other suitable tool. It does not matter what name is used for the database, but record it. You specify it in the connection string constructed later in this tutorial. This database contains the tables, automatically created for you later, used to store data about users and roles. - Create a new ASP.NET Web Site in Visual Studio. If you are not sure how to do this, refer to , "Tutorial: Databinding in ASP.NET using LINQ on Entities", which demonstrates how to create a simple ASP.NET web site.
- Add References to
MySql.Data
andMySql.Web
to the web site project. - Locate the
machine.config
file on your system, which is the configuration file for the .NET Framework. - Search the
machine.config
file to find the membership providerMySQLMembershipProvider
. - Add the attribute
autogenerateschema='true'
. The appropriate section should now resemble the following (note: for the sake of brevity some information has been excluded):<membership> <providers> <add name="AspNetSqlMembershipProvider" type="System.Web.Security.SqlMembershipProvider" ... connectionStringName="LocalSqlServer" ... /> <add name="MySQLMembershipProvider" autogenerateschema="true" type="MySql.Web.Security.MySQLMembershipProvider, MySql.Web, Version=6.0.4.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d" connectionStringName="LocalMySqlServer" ... /> </providers> </membership>
Note that the name for the connection string to be used to connect to the server that contains the membership database is
LocalMySqlServer
.The
autogenerateschema='true'
attribute will cause MariaDB Connector/Net to silently create, or upgrade, the schema on the database server, to contain the required tables for storing membership information. - It is now necessary to create the connection string referenced in the previous step. Load the web site's
web.config
file into Visual Studio. - Locate the section marked
<connectionStrings>
. Add the following connection string information:<connectionStrings> <remove name="LocalMySqlServer"/> <add name="LocalMySqlServer" connectionString="Datasource=localhost;Database=users;uid=root;pwd=password;" providerName="MySql.Data.MySqlClient"/> </connectionStrings>
The database specified is the one created in the first step. You could alternatively have used an existing database.
- At this point build the solution to ensure no errors are present. This can be done by selecting Build, Build Solution from the main menu, or pressing F6.
- ASP.NET supports the concept of locally and remotely authenticated users. With local authentication the user is validated using their Windows credentials when they attempt to access the web site. This can be useful in an Intranet environment. With remote authentication, a user is prompted for their login details when accessing the web site, and these credentials are checked against the membership information stored in a database server such as MariaDB Server. You will now see how to choose this form of authentication.
Start the ASP.NET Web Site Administration Tool. This can be done quickly by clicking the small hammer/Earth icon in the Solution Explorer. You can also launch this tool by selecting Website, ASP.NET Configuration from the main menu.
- In the ASP.NET Web Site Administration Tool click the Security tab.
- Now click the User Authentication Type link.
- Select the From the internet radio button. The web site will now need to provide a form to allow the user to enter their login details. These will be checked against membership information stored in the MariaDB database.
Figure 20.31. Authentication Type
- You now need to specify the Role and Membership Provider to be used. Click the Provider tab.
- Click the Select a different provider for each feature (advanced) link.
- Now select the MySQLMembershipProvider and the MySQLRoleProvider radio buttons.
Figure 20.32. Select Membership and Role Provider
- In Visual Studio, rebuild the solution by selecting Build, Rebuild Solution from the main menu.
- Check that the necessary schema has been created. This can be achieved using the mysql command interpreter.
Figure 20.33. Membership and Role Provider Tables
- Assuming all is present and correct, you can now create users and roles for your web application. The easiest way to do this is with the ASP.NET Web Site Administration Tool. However, many web applications contain their own modules for creating roles and users. For simplicity, the ASP.NET Web Site Administration Tool will be used in this tutorial.
- In the ASP.NET Web Site Administration Tool, click the Security tab. Now that both the Membership and Role Provider are enabled, you will see links for creating roles and users. Click the Create or Manage Roles link.
Figure 20.34. Security Tab
- You can now enter the name of a new Role and click Add Role to create the new Role. Create new Roles as required.
- Click the Back button.
- Click the Create User link. You can now fill in information about the user to be created, and also allocate that user to one or more Roles.
Figure 20.35. Create User
- Using the mysql command interpreter, you can check that your database has been correctly populated with the Membership and Role data.
Figure 20.36. Membership and Roles Table Contents
In this tutorial, you have seen how to set up the MariaDB Connector/Net Membership and Role Providers for use in your ASP.NET web application.
Tutorial: MariaDB Connector/Net ASP.NET Session State Provider
MySQL Connector/Net from version 6.1 has included a MariaDB Session State Provider. This provider enables you to store session state in a MariaDB database. The following tutorial shows you how to prepare to use the MariaDB Session State Provider, and then store session data into the MariaDB database. This tutorial uses Microsoft Visual Studio 2008 Professional Edition, MariaDB Connector/Net 6.1.1 and MariaDB Server 5.1. This tutorial also assumes you have created an empty database, for example test
, where you will store session data. You could do this using the mysql command interpreter.
- In Visual Studio, create a new ASP.NET web site. If you are not sure how to do this, refer to the tutorial , "Tutorial: Databinding in ASP.NET using LINQ on Entities", which demonstrates how to do this.
- Launch the MariaDB MySQL Website Configuration tool. Due to a bug in 6.1.1, this may not appear unless you are connected to a server in the Server Explorer. If you are unfamiliar with the MariaDB Website Configuration tool, consider first working through the tutorial in , "MySQL Website Configuration Tool".
- Navigate through the wizard to the Session State page. Make sure the check box Use MariaDB to manage my ASP.NET session data is selected.
- On the same page, configure the connection string to the database that will contain your session data. If this database is empty, MariaDB Connector/Net will create the schema required to store session data.
- Ensure that the check box Autogenerate Schema is selected so that MariaDB Connector/Net will create the schema in your database to store the session data correctly.
- Enter the name of your application.
- Click Finish. The MariaDB Website Configuration tool will now update your application's
web.config
file with information about the connection string and default providers to be used. In this case, we have selected the MariaDB Session State Provider.
At this point, you are ready to use the MariaDB database to store session data. To test that the set up has worked, you can write a simple program that uses session variables.
- Open
Default.aspx.cs
. In thePage_Load
method, add the following code:
Session['SessionVariable1'] = 'Test string';
- Build your solution.
- Run the solution (without debugging). When the application runs, the provider will autogenerate tables required in the database you chose when setting up the application.
- Check that the schema was in fact created. Using the MariaDB Command Line Client use the target database and then type
SHOW TABLES;
. You will see that MariaDB Connector/Net has created the required schema automatically, as we selected this to happen in the MariaDB Website Configuration tool. - Now view the contents of these tables by typing
SELECT * FROM my_aspnet_sessions;
in the mysql command interpreter. This will display the session data our application used. Note that this is stored in binary format so some data may not display as expected.
At this point, you have installed the Session State Provider and carried out a preliminary test of the installation. You will now work a bit more with the Session State Provider.
In this part of the tutorial, you will set and retrieve a session variable. You can work with your existing project.
- Select the
Default.aspx
and switch to Design View. Add a text box and three buttons. Change the text property for the buttons to "Store Session Variable", "Clear Textbox", and "Show Session Variable". These will beButton1
,Button2
andButton3
respectively. Build your solution to ensure that no errors have been introduced. - Still in the Design View, double-click
Button1
. Now to theButton1_Click
event handler add code some the handler resembles the following:protected void Button1_Click(object sender, EventArgs e) { Session['SessionString'] = TextBox1.Text; }
You have created a new Session variable accessed using the key "SessionString". This will be set to the text that was entered into the text box when
Button1
is clicked. - In Design View, double-click
Button2
to add its click event handler. This button needs to clear text from the text box. The code to do this is as follows:protected void Button2_Click(object sender, EventArgs e) { TextBox1.Text = ''; }
The code simply assigns an empty string to the
Text
property of the text box. - In the Design View double-click
Button3
and modify the click handler as follows:protected void Button3_Click(object sender, EventArgs e) { TextBox1.Text = (String)Session['SessionString']; }
This will retrieve the session string and display it in the text box.
- Now modify the
Page_Load
method as follows:protected void Page_Load(object sender, EventArgs e) { if (!IsPostBack) { TextBox1.Text = 'Enter some text'; } }
This ensures that when the page loads the text box
Text
property is reset. - Ensure that the solution is saved and then rebuild the solution.
- Run the solution without debugging.
- The form will be displayed. Enter some text into the text box. Now click Store Session Variable. At this point you have stored the string in a session variable.
- Now click Clear Text to clear the text box.
- Now click Show Session Variable to retrieve and display the session variable.
- Refresh the page to destroy the form and display a new form.
- Click Show Session Variable the text box will display the stored session variable, demonstrating that the refreshing the page does not destroy the session variable.
This illustrates that the session state data is not destroyed when a page is reloaded.
Tutorial: MariaDB Connector/Net ASP.NET Profile Provider
This tutorial shows you how to use the MariaDB Profile Provider to store user profile information in a MariaDB database. The tutorial uses MariaDB Connector/Net 6.1.1, MariaDB Server 5.1 and Microsoft Visual Studio 2008 Professional Edition.
Many modern web sites allow the user to create a personal profile. This requires a significant amount of code, but ASP.NET reduces this considerable by including the functionality in its Profile classes. The Profile Provider provides an abstraction between these classes and a data source. The MariaDB Profile Provider enables profile data to be stored in a MariaDB database. This enables the profile properties to be written to a persistent store, and be retrieved when required. The Profile Provider also enables profile data to be managed effectively, for example it enables profiles that have not been accessed since a specific date to be deleted.
The following steps show you how you can select the MariaDB Profile Provider.
- Create a new ASP.NET web project.
- Select the MariaDB Website Configuration tool. Due to a bug in 6.1.1 you may have to first connect to a server in Server Explorer before the tool's icon will display in the toolbar of the Solution Explorer.
- In the MariaDB Website Configuration tool navigate through the tool to the Profiles page.
- Select the Use MariaDB to manage my profiles check box.
- Select the Autogenerate Schema check box.
- Click the Edit... button and configure a connection string for the database that will be used to store user profile information.
- Navigate to the last page of the tool and click Finish to save your changes and exit the tool.
At this point you are now ready to start using the MariaDB Profile Provider. With the following steps you can carry out a preliminary test of your installation.
- Open your
web.config
file. - Add a simple profile such as the following:
<system.web> <anonymousIdentification enabled="true"/> <profile defaultProvider="MySQLProfileProvider"> ... <properties> <add name="Name" allowAnonymous="true"/> <add name="Age" allowAnonymous="true" type="System.UInt16"/> <group name="UI"> <add name="Color" allowAnonymous="true" defaultValue="Blue"/> <add name="Style" allowAnonymous="true" defaultValue="Plain"/> </group> </properties> </profile> ...
Note that
anonymousIdentification
has been set to true. This enables users who have not been authenticated to use profiles. They are identified by a GUID in a cookie rather than by user name.
Now that the simple profile has been defined in web.config
, the next step is to write some code to test the profile.
- In Design View design a simple page with the following controls:
Figure 20.37. Simple Profile Application
These will allow the user to enter some profile information. The user can also use the buttons to save their profile, clear the page, and restore their profile data.
- In the Code View add code as follows:
... protected void Page_Load(object sender, EventArgs e) { if (!IsPostBack) { TextBox1.Text = Profile.Name; TextBox2.Text = Profile.Age.ToString(); Label1.Text = Profile.UI.Color; } } // Store Profile protected void Button1_Click(object sender, EventArgs e) { Profile.Name = TextBox1.Text; Profile.Age = UInt16.Parse(TextBox2.Text); } // Clear Form protected void Button2_Click(object sender, EventArgs e) { TextBox1.Text = ''; TextBox2.Text = ''; Label1.Text = ''; } // Retrieve Profile protected void Button3_Click(object sender, EventArgs e) { TextBox1.Text = Profile.Name; TextBox2.Text = Profile.Age.ToString(); Label1.Text = Profile.UI.Color; } protected void DropDownList1_SelectedIndexChanged(object sender, EventArgs e) { Profile.UI.Color = DropDownList1.SelectedValue; } ...
- Save all files and build the solution to check that no errors have been introduced.
- Run the application.
- Enter your name, age and select a color from the listbox. Now store this information in your profile by clicking Store Profile. Note that if you do not select a color from the listbox your profile will use the default color
Blue
that was specified in theweb.config
file. - Click Clear Form to clear text from the textboxes and the label that displays your chosen color.
- Now click Retrieve Profile to restore your profile data from the MariaDB database.
- Now exit the browser to terminate the application.
- Run the application again. Note that when the page loads your profile information is restored from the MariaDB database.
In this tutorial you have seen how to using the MariaDB Profile Provider with MariaDB Connector/Net.
Tutorial: Using an Entity Framework Entity as a Windows Forms Data Source
In this tutorial you will learn how to create a Windows Forms Data Source from an Entity in an Entity Data Model. This tutorial assumes that you have installed the World example database, which can be downloaded from the MySQL Documentation page. You can also find details on how to install the database on the same page. It will also be convenient for you to create a connection to the World database after it is installed. For instructions on how to do this see , "Making a Connection".
Creating a new Windows Forms application
The first step is to create a new Windows Forms application.
- In Visual Studio, select File, New, Project from the main menu.
- Choose the Windows Forms Application installed template. Click OK. The solution is created.
Adding an Entity Data Model
You will now add an Entity Data Model to your solution.
- In the Solution Explorer, right-click your application and select Add, New Item.... From Visual Studio installed templates select ADO.NET Entity Data Model. Click Add.
Figure 20.38. Add Entity Data Model
- You will now see the Entity Data Model Wizard. You will use the wizard to generate the Entity Data Model from the world example database. Select the icon Generate from database. Click Next.
Figure 20.39. Entity Data Model Wizard Screen 1
- You can now select the connection you made earlier to the World database. If you have not already done so, you can create the new connection at this time by clicking New Connection.... For further instructions on creating a connection to a database see , "Making a Connection".
Figure 20.40. Entity Data Model Wizard Screen 2
- Make a note of the entity connection settings to be used in App.Config, as these will be used later to write the necessary control code.
- Click Next.
- The Entity Data Model Wizard connects to the database. You are then presented with a tree structure of the database. From this you can select the object you would like to include in your model. If you had created Views and Stored Routines these will be displayed along with any tables. In this example you just need to select the tables. Click Finish to create the model and exit the wizard.
Figure 20.41. Entity Data Model Wizard Screen 3
- Visual Studio will generate the model and then display it.
Figure 20.42. Entity Data Model Diagram
- From the Visual Studio main menu select Build, Build Solution, to ensure that everything compiles correctly so far.
Adding a new Data Source
You will now add a new Data Source to your project and see how it can be used to read and write to the database.
- From the Visual Studio main menu select Data, Add New Data Source.... You will be presented with the Data Source Configuration Wizard.
Figure 20.43. Entity Data Source Configuration Wizard Screen 1
- Select the Object icon. Click Next.
- You will now select the Object to bind to. Expand the tree. In this tutorial, you will select the city table. Once the city table has been selected click Next.
Figure 20.44. Entity Data Source Configuration Wizard Screen 2
- The wizard will confirm that the city object is to be added. Click Finish.
Figure 20.45. Entity Data Source Configuration Wizard Screen 3
- The city object will be display in the Data Sources panel. If the Data Sources panel is not displayed, select Data, Show Data Sources from the Visual Studio main menu. The docked panel will then be displayed.
Figure 20.46. Data Sources
Using the Data Source in a Windows Form
You will now learn how to use the Data Source in a Windows Form.
- In the Data Sources panel select the Data Source you just created and drag and drop it onto the Form Designer. By default the Data Source object will be added as a Data Grid View control. Note that the Data Grid View control is bound to the
cityBindingSource
and the Navigator control is bound tocityBindingNavigator
.
Figure 20.47. Data Form Designer
- Save and rebuild the solution before continuing.
Adding Code to Populate the Data Grid View
You are now ready to add code to ensure that the Data Grid View control will be populated with data from the City database table.
- Double-click the form to access its code.
- Add code to instatiate the Entity Data Model's EntityContainer object and retrieve data from the database to populate the control.
Figure 20.48. Adding Code to the Form
- Save and rebuild the solution.
- Run the solution. Ensure the grid is populated and you can navigate the database.
Figure 20.49. The Populated Grid Control
Adding Code to Save Changes to the Database
You will now add code to enable you to save changes to the database.
The Binding source component ensures that changes made in the Data Grid View control are also made to the Entity classes bound to it. However, that data needs to be saved back from the entities to the database itself. This can be achieved by the enabling of the Save button in the Navigator control, and the addition of some code.
- In the Form Designer, click the Save icon in the Form toolbar and ensure that its Enabled property is set to True.
Figure 20.50. Save Button Enabled
- Double-click the Save icon in the Form toolbar to display its code.
- You now need to add code to ensure that data is saved to the database when the save button is clicked in the application.
Figure 20.51. Adding Save Code to the Form
- Once the code has been added, save the solution and rebuild it. Run the application and verify that changes made in the grid are saved.
Tutorial: Databinding in ASP.NET using LINQ on Entities
In this tutorial you create an ASP.NET web page that binds LINQ queries to entities using the Entity Framework mapping.
If you have not already done so, install the World example database prior to attempting this tutorial. See the tutorial , "Tutorial: Using an Entity Framework Entity as a Windows Forms Data Source" for instructions on downloading and installing this database.
Creating an ASP.NET web site
In this part of the tutorial, you will create an ASP.NET web site. The web site will use the World database. The main web page will feature a drop down list from which you can select a country, data about that country's cities will then be displayed in a grid view control.
- From the Visual Studio main menu select File, New, Web Site....
- From the Visual Studio installed templates select ASP.NET Web Site. Click OK. You will be presented with the Source view of your web page by default.
- Click the Design view tab situated underneath the Source view panel.
Figure 20.52. The Design Tab
- In the Design view panel, enter some text to decorate the blank web page.
- Click Toolbox. From the list of controls select DropDownList. Drag and drop the control to a location beneath the text on your web page.
Figure 20.53. Drop Down List
- From the DropDownList control's context menu, ensure that the Enable AutoPostBack check box is enabled. This will ensure the control's event handler is called when an item is selected. The user's choice will in turn be used to populate the GridView control.
Figure 20.54. Enable AutoPostBack
- From the Toolbox select the GridView control.
Figure 20.55. Grid View Control
Drag and drop the Grid Vew control to a location just below the Drop Down List you already placed.
Figure 20.56. Placed Grid Vew Control
- At this point it is recommended that you save your solution, and build the solution to ensure that there are no errors.
- If you run the solution you will see that the text and drop down list are displayed, but the list is empty. Also, the grid view does not appear at all. Adding this functionality is described in the following sections.
At this stage you have a web site that will build, but further functionality is required. The next step will be to use the Entity Framework to create a mapping from the World database into entities that you can control programmatically.
Creating an ADO.NET Entity Data Model
In this stage of the tutorial you will add an ADO.NET Entity Data Model to your project, using the World database at the storage level. The procedure for doing this is described in the tutorial , "Tutorial: Using an Entity Framework Entity as a Windows Forms Data Source", and so will not be repeated here.
Populating a Drop Data List Box with using the results of a entity LINQ query
In this part of the tutorial you will write code to populate the DropDownList control. When the web page loads the data to populate the list will be achieved by using the results of a LINQ query on the model created previously.
- In the Design view panel, double-click any blank area. This brings up the
Page_Load
method. - Modify the relevant section of code according to the following listing:
... public partial class _Default : System.Web.UI.Page { worldModel.worldEntities we; protected void Page_Load(object sender, EventArgs e) { we = new worldModel.worldEntities(); if (!IsPostBack) { var countryQuery = from c in we.country orderby c.Name select new { c.Code, c.Name }; DropDownList1.DataValueField = 'Code'; DropDownList1.DataTextField = 'Name'; DropDownList1.DataSource = countryQuery; DataBind(); } } ...
Note that the list control only needs to be populated when the page first loads. The conditional code ensures that if the page is subsequently reloaded, the list control is not repopulated, which would cause the user selection to be lost.
- Save the solution, build it and run it. You should see the list control has been populated. You can select an item, but as yet the grid view control does not appear.
At this point you have a working Drop Down List control, populated by a LINQ query on your entity data model.
Populating a Grid View control using an entity LINQ query
In the last part of this tutorial you will populate the Grid View Control using a LINQ query on your entity data model.
- In the Design view, double-click the DropDownList control. This causes its
SelectedIndexChanged
code to be displayed. This method is called when a user selects an item in the list control and thus fires an AutoPostBack event. - Modify the relevant section of code accordingly to the following listing:
... protected void DropDownList1_SelectedIndexChanged(object sender, EventArgs e) { var cityQuery = from c in we.city where c.CountryCode == DropDownList1.SelectedValue orderby c.Name select new { c.Name, c.Population, c.CountryCode }; GridView1.DataSource = cityQuery; DataBind(); } ...
The grid view control is populated from the result of the LINQ query on the entity data model.
- As a check compare your code to that shown in the following screenshot:
Figure 20.57. Source Code
- Save, build and run the solution. As you select a country you will see its cities are displayed in the grid view control.
Figure 20.58. The Working Web Site
In this tutorial you have seen how to create an ASP.NET web site, you have also seen how you can access a MariaDB database using LINQ queries on an entity data model.
Tutorial: Using SSL with MariaDB Connector/Net
In this tutorial you will learn how you can use MariaDB Connector/Net to connect to a MariaDB server configured to use SSL. Support for SSL client certificates was added with MariaDB Connector/Net 6.2.
MySQL Server uses the PEM format for certificates and private keys. This tutorial will use the test certificates from the server test suite by way of example. You can obtain the MariaDB Server source code from MySQL Downloads. The certificates can be found in the directory ./mysql-test/std_data
.
To carry out the steps in this tutorial, you must have Open SSL installed. This can be downloaded for Microsoft Windows at no charge from Shining Light Productions.
Further details on the connection string options used in this tutorial can be found at , "Connector/Net Connection String Options Reference".
Configuring the MariaDB Server to use SSL
- In the MariaDB Server configuration file, set the SSL parameters as follows:
ssl-ca=path/to/repo/mysql-test/std_data/cacert.pem ssl-cert=path/to/repo/mysql-test/std_data/server-cert.pem ssl-key=path/to/repo/mysql-test/std_data/server-key.pem
Adjust the directories according to the location in which you installed the MariaDB source code.
- In this step you create a test user and set the user to require SSL.
Using the MariaDB Command Line Client, connect as root and create the user
sslclient
. - To set privileges and requirements, issue the following command:
GRANT ALL PRIVILEGES ON *.* TO sslclient@'%' REQUIRE SSL;
Creating a certificate file to use with the .NET client
- The .NET client does not use the PEM file format, as .NET does not support this format natively. You will be using test client certificates from the same server repository, for the purposes of this example. Convert these to PFX format first. This format is also known as PKCS#12. An article describing this procedure can be found at the Citrix website. From the directory
, issue the following command:server-repository-root
/mysql-test/std_data
openssl pkcs12 -export -in client-cert.pem -inkey client-key.pem -certfile cacert.pem -out client.pfx
- When asked for an export password, enter the password "pass". The file
client.pfx
will be generated. This file is used in the remainder of the tutorial.
Connecting to the server using a file-based certificate
- You will use PFX file,
client.pfx
you created in the previous step to authenticate the client. The following example demonstrates how to connect using theSSL Mode
,CertificateFile
andCertificatePassword
connection string options:
using (MySqlConnection connection = new MySqlConnection( 'database=test;user=sslclient;' + 'CertificateFile=H:\\bzr\\mysql-trunk\\mysqlest\\std_data\\client.pfx' + 'CertificatePassword=pass;' + 'SSL Mode=Required ')) { connection.Open(); }
The path to the certificate file will need to be changed to reflect your individual installation.
Connecting to the server using a store-based certificate
- The first step is to import the PFX file,
client.pfx
, into the Personal Store. Double-click the file in Windows explorer. This launches the Certificate Import Wizard. - Follow the steps dictated by the wizard, and when prompted for the password for the PFX file, enter "pass".
- Click Finish to close the wizard and import the certificate into the personal store.
Examine certificates in the Personal Store
- Start the Microsoft Management Console by entering
mmc.exe
at a command prompt. - Select File, Add/Remove snap-in. Click Add. Select Certificates from the list of available snap-ins in the dialog.
- Click Add button in the dialog, and select the My user account radio button. This is used for personal certificates.
- Click the Finish button.
- Click OK to close the Add/Remove Snap-in dialog.
- You will now have Certificates - Current User displayed in the left panel of the Microsoft Management Console. Expand the Certificates - Current User tree item and select Personal, Certificates. The right-hand panel will display a certificate issued to MariaDB. This is the certificate that was previously imported. Double-click the certificate to display its details.
- After you have imported the certificate to the Personal Store, you can use a more succint connection string to connect to the database, as illustrated by the following code:
using (MySqlConnection connection = new MySqlConnection( 'database=test;user=sslclient;' + 'Certificate Store Location=CurrentUser;' + 'SSL Mode=Required')) { connection.Open(); }
Certificate Thumbprint Parameter
If you have a large number of certificates in your store, and many have the same Issuer, this can be a source of confusion and result in the wrong certificate being used. To alleviate this situation, there is an optional Certificate Thumbprint parameter that can additionally be specified as part of the connection string. As mentioned before, you can double-click a certificate in the Microsoft Management Console to display the certificate's details. When the Certificate dialog is displayed click the Details tab and scroll down to see the thumbprint. The thumbprint will typically be a number such as 47 94 36 00 9a 40 f3 01 7a 14 5c f8 47 9e 76 94 d7 aa de f0
. This thumbprint can be used in the connection string, as the following code illustrates:
using (MySqlConnection connection = new MySqlConnection( 'database=test;user=sslclient;' + 'Certificate Store Location=CurrentUser;' + 'Certificate Thumbprint=479436009a40f3017a145cf8479e7694d7aadef0;'+ 'SSL Mode=Required')) { connection.Open(); }
Spaces in the thumbprint parameter are optional and the value is case-insensitive.
Tutorial: Using MySqlScript
This tutorial teaches you how to use the MySqlScript
class. This class enables you to execute a series of statements. Depending on the circumstances, this can be more convenient than using the MySqlCommand
approach.
Further details of the MySqlScript
class can be found in the reference documentation supplied with MariaDB Connector/Net.
To run the example programs in this tutorial, set up a simple test database and table using the mysql Command Line Client or MariaDB Workbench. Commands for the mysql Command Line Client are given here:
CREATE DATABASE TestDB;
USE TestDB;
CREATE TABLE TestTable (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100));
The main method of the MySqlScript
class is the Execute
method. This method causes the script (sequence of statements) assigned to the Query property of the MySqlScript object to be executed. Note the Query property can be set through the MySqlScript
constructor or using the Query property. Execute
returns the number of statements executed.
The MySqlScript
object will execute the specified script on the connection set using the Connection property. Again, this property can be set directly or through the MySqlScript
constructor. The following code snippets illustrate this:
string sql = 'SELECT * FROM TestTable'; ... MySqlScript script = new MySqlScript(conn, sql); ... MySqlScript script = new MySqlScript(); script.Query = sql; script.Connection = conn; ... script.Execute();
The MySqlScript class has several events associated with it. There are:
- Error - generated if an error occurs.
- ScriptCompleted - generated when the script successfully completes execution.
- StatementExecuted - generated after each statement is executed.
It is possible to assign event handlers to each of these events. These user-provided routines are called back when the connected event occurs. The following code shows how the event handlers are set up.
script.Error += new MySqlScriptErrorEventHandler(script_Error); script.ScriptCompleted += new EventHandler(script_ScriptCompleted); script.StatementExecuted += new MySqlStatementExecutedEventHandler(script_StatementExecuted);
In VisualStudio, you can save typing by using tab completion to fill out stub routines. Start by typing, for example, "script.Error +=". Then press TAB, and then press TAB again. The assignment is completed, and a stub event handler created. A complete working example is shown below:
using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; namespace MySqlScriptTest { class Program { static void Main(string[] args) { string connStr = 'server=localhost;user=root;database=TestDB;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); string sql = 'INSERT INTO TestTable(name) VALUES ('Superman');' + 'INSERT INTO TestTable(name) VALUES ('Batman');' + 'INSERT INTO TestTable(name) VALUES ('Wolverine');' + 'INSERT INTO TestTable(name) VALUES ('Storm');'; MySqlScript script = new MySqlScript(conn, sql); script.Error += new MySqlScriptErrorEventHandler(script_Error); script.ScriptCompleted += new EventHandler(script_ScriptCompleted); script.StatementExecuted += new MySqlStatementExecutedEventHandler(script_StatementExecuted); int count = script.Execute(); Console.WriteLine('Executed ' + count + ' statement(s).'); Console.WriteLine('Delimiter: ' + script.Delimiter); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine('Done.'); } static void script_StatementExecuted(object sender, MySqlScriptEventArgs args) { Console.WriteLine('script_StatementExecuted'); } static void script_ScriptCompleted(object sender, EventArgs e) { /// EventArgs e will be EventArgs.Empty for this method Console.WriteLine('script_ScriptCompleted!'); } static void script_Error(Object sender, MySqlScriptErrorEventArgs args) { Console.WriteLine('script_Error: ' + args.Exception.ToString()); } } }
Note that in the script_ScriptCompleted
event handler, the EventArgs
parameter e
will be EventArgs.Empty
. In the case of the ScriptCompleted
event there is no additional data to be obtained, which is why the event object is EventArgs.Empty
.
Using Delimiters with MySqlScript
Depending on the nature of the script, you may need control of the delimiter used to separate the statements that will make up a script. The most common example of this is where you have a multi-statement stored routine as part of your script. In this case if the default delimiter of ";" is used you will get an error when you attempt to execute the script. For example, consider the following stored routine:
CREATE PROCEDURE test_routine() BEGIN SELECT name FROM TestTable ORDER BY name; SELECT COUNT(name) FROM TestTable; END
This routine actually needs to be executed on the MariaDB Server as a single statement. However, with the default delimiter of ";", the MySqlScript
class would interpret the above as two statements, the first being:
CREATE PROCEDURE test_routine() BEGIN SELECT name FROM TestTable ORDER BY name;
Executing this as a statement would generate an error. To solve this problem MySqlScript
supports the ability to set a different delimiter. This is achieved through the Delimiter property. For example, you could set the delimiter to "??", in which case the above stored routine would no longer generate an error when executed. Multiple statements can be delimited in the script, so for example, you could have a three statement script such as:
string sql = 'DROP PROCEDURE IF EXISTS test_routine??' + 'CREATE PROCEDURE test_routine() ' + 'BEGIN ' + 'SELECT name FROM TestTable ORDER BY name;' + 'SELECT COUNT(name) FROM TestTable;' + 'END??' + 'CALL test_routine()';
You can change the delimiter back at any point by setting the Delimiter property. The following code shows a complete working example:
using System; using System.Collections.Generic; using System.Linq; using System.Text; using MySql.Data; using MySql.Data.MySqlClient; namespace ConsoleApplication8 { class Program { static void Main(string[] args) { string connStr = 'server=localhost;user=root;database=TestDB;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); string sql = 'DROP PROCEDURE IF EXISTS test_routine??' + 'CREATE PROCEDURE test_routine() ' + 'BEGIN ' + 'SELECT name FROM TestTable ORDER BY name;' + 'SELECT COUNT(name) FROM TestTable;' + 'END??' + 'CALL test_routine()'; MySqlScript script = new MySqlScript(conn); script.Query = sql; script.Delimiter = '??'; int count = script.Execute(); Console.WriteLine('Executed ' + count + ' statement(s)'); script.Delimiter = ';'; Console.WriteLine('Delimiter: ' + script.Delimiter); Console.WriteLine('Query: ' + script.Query); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine('Done.'); } } }
Tutorial: Generating MariaDB DDL from an Entity Framework Model
In this tutorial, you will learn how to create MariaDB DDL from an Entity Framework model. Use Visual Studio 2010 and MariaDB Connector/Net 6.3 to carry out this tutorial.
- Create a new console application in Visual Studio 2010.
- Using the Solution Explorer, add a reference to
MySql.Data.Entity
. - From the Solution Explorer select Add, New Item. In the Add New Item dialog select Online Templates. Select ADO.NET Entity Data Model and click Add. The Entity Data Model dialog will be displayed.
- In the Entity Data Model dialog select Empty Model. Click Finish. A blank model will be created.
- Create a simple model. A single Entity will do for the purposes of this tutorial.
- In the Properties panel select ConceptualEntityModel from the drop-down listbox.
- In the Properties panel, locate the DDL Generation Template in the category Database Script Generation.
- For the DDL Generation property select SSDLToMySQL.tt(VS) from the drop-down listbox.
- Save the solution.
- Right-click an empty space in the model design area. The context-sensitive menu will be displayed.
- From the context-sensitive menu select Generate Database from Model. The Generate Database Wizard dialog will be displayed.
- In the Generate Database Wizard dialog select an existing connection, or create a new connection to a server. Select an appropriate radio button to show or hide sensitive data. For the purposes of this tutorial you can select Yes (although you might skip this for commercial applications).
- Click Next. MariaDB compatible DDL code will be generated. Click Finish to exit the wizard.
You have seen how to create MariaDB DDL code from an Entity Framework model.
Connector/Net Programming
- Connecting to MariaDB Using Connector/Net
- Creating a Connector/Net Connection String
- Using MySqlCommand
- Using Connector/Net with Connection Pooling
- Using the Windows Native Authentication Plugin
- Using Connector/Net with Table Caching
- Using the Connector/Net with Prepared Statements
- Accessing Stored Procedures with Connector/Net
- Handling BLOB Data With Connector/Net
- Using the Connector/Net Interceptor Classes
- Handling Date and Time Information in Connector/Net
- Using the
MySqlBulkLoader
Class- Using the MariaDB Connector/Net Trace Source Object
- Binary/Nonbinary Issues
- Character Set Considerations for Connector/Net
- Using Connector/Net with Crystal Reports
- ASP.NET Provider Model
- Working with Partial Trust
- Creating a Connector/Net Connection String
Connector/Net comprises several classes that are used to connect to the database, execute queries and statements, and manage query results.
The following are the major classes of Connector/Net:
MySqlCommand
: Represents an SQL statement to execute against a MariaDB database.MySqlCommandBuilder
: Automatically generates single-table commands used to reconcile changes made to a DataSet with the associated MariaDB database.MySqlConnection
: Represents an open connection to a MariaDB Server database.MySqlDataAdapter
: Represents a set of data commands and a database connection that are used to fill a data set and update a MariaDB database.MySqlDataReader
: Provides a means of reading a forward-only stream of rows from a MariaDB database.MySqlException
: The exception that is thrown when MariaDB returns an error.MySqlHelper
: Helper class that makes it easier to work with the provider.MySqlTransaction
: Represents an SQL transaction to be made in a MariaDB database.
In the following sections, you will learn about some common use cases for Connector/Net, including BLOB handling, date handling, and using Connector/Net with common tools such as Crystal Reports.
Connecting to MariaDB Using Connector/Net
Introduction
All interaction between a .NET application and the MariaDB server is routed through a MySqlConnection
object. Before your application can interact with the server, a MySqlConnection
object must be instantiated, configured, and opened.
Even when using the MySqlHelper
class, a MySqlConnection
object is created by the helper class.
In this section, we will describe how to connect to MariaDB using the MySqlConnection
object.
Creating a Connector/Net Connection String
The MySqlConnection
object is configured using a connection string. A connection string contains several key/value pairs, separated by semicolons. Each key/value pair is joined with an equal sign.
The following is a sample connection string:
Server=127.0.0.1;Uid=root;Pwd=12345;Database=test;
In this example, the MySqlConnection
object is configured to connect to a MariaDB server at 127.0.0.1
, with a user name of root
and a password of 12345
. The default database for all statements will be the test
database. All other options may be found here: , "Connector/Net Connection String Options Reference".Note
Using the '@' symbol for parameters is now the preferred approach although the old pattern of using '?' is still supported.
Please be aware however that using '@' can cause conflicts when user variables are also used. To help with this situation please see the documentation on the Allow User Variables
connection string option, which can be found here: , "Connector/Net Connection String Options Reference". The Old Syntax
connection string option has now been deprecated.
Opening a Connection
Once you have created a connection string it can be used to open a connection to the MariaDB server.
The following code is used to create a MySqlConnection
object, assign the connection string, and open the connection.
Connector/NET can also connect using the native Windows authentication plugin. See , "Using the Windows Native Authentication Plugin" for further information.
Visual Basic Example
Dim conn As New MySql.Data.MySqlClient.MySqlConnection Dim myConnectionString as String myConnectionString = 'server=127.0.0.1;' _ & 'uid=root;' _ & 'pwd=12345;' _ & 'database=test;' Try conn.ConnectionString = myConnectionString conn.Open() Catch ex As MySql.Data.MySqlClient.MySqlException MessageBox.Show(ex.Message) End Try
C# Example
MySql.Data.MySqlClient.MySqlConnection conn; string myConnectionString; myConnectionString = 'server=127.0.0.1;uid=root;' + 'pwd=12345;database=test;'; try { conn = new MySql.Data.MySqlClient.MySqlConnection(); conn.ConnectionString = myConnectionString; conn.Open(); } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show(ex.Message); }
You can also pass the connection string to the constructor of the MySqlConnection
class:
Visual Basic Example
Dim myConnectionString as String myConnectionString = 'server=127.0.0.1;' _ & 'uid=root;' _ & 'pwd=12345;' _ & 'database=test;' Try Dim conn As New MySql.Data.MySqlClient.MySqlConnection(myConnectionString) conn.Open() Catch ex As MySql.Data.MySqlClient.MySqlException MessageBox.Show(ex.Message) End Try
C# Example
MySql.Data.MySqlClient.MySqlConnection conn; string myConnectionString; myConnectionString = 'server=127.0.0.1;uid=root;' + 'pwd=12345;database=test;'; try { conn = new MySql.Data.MySqlClient.MySqlConnection(myConnectionString); conn.Open(); } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show(ex.Message); }
Once the connection is open it can be used by the other Connector/Net classes to communicate with the MariaDB server.
Handling Connection Errors
Because connecting to an external server is unpredictable, it is important to add error handling to your .NET application. When there is an error connecting, the MySqlConnection
class will return a MySqlException
object. This object has two properties that are of interest when handling errors:
Message
: A message that describes the current exception.Number
: The MariaDB error number.
When handling errors, you can your application's response based on the error number. The two most common error numbers when connecting are as follows:
0
: Cannot connect to server.1045
: Invalid user name and/or password.
The following code shows how to adapt the application's response based on the actual error:
Visual Basic Example
Dim myConnectionString as String myConnectionString = 'server=127.0.0.1;' _ & 'uid=root;' _ & 'pwd=12345;' _ & 'database=test;' Try Dim conn As New MySql.Data.MySqlClient.MySqlConnection(myConnectionString) conn.Open() Catch ex As MySql.Data.MySqlClient.MySqlException Select Case ex.Number Case 0 MessageBox.Show('Cannot connect to server. Contact administrator') Case 1045 MessageBox.Show('Invalid username/password, please try again') End Select End Try
C# Example
MySql.Data.MySqlClient.MySqlConnection conn; string myConnectionString; myConnectionString = 'server=127.0.0.1;uid=root;' + 'pwd=12345;database=test;'; try { conn = new MySql.Data.MySqlClient.MySqlConnection(myConnectionString); conn.Open(); } catch (MySql.Data.MySqlClient.MySqlException ex) { switch (ex.Number) { case 0: MessageBox.Show('Cannot connect to server. Contact administrator'); case 1045: MessageBox.Show('Invalid username/password, please try again'); } }Important
Note that if you are using multilanguage databases you must specify the character set in the connection string. If you do not specify the character set, the connection defaults to the latin1
charset. You can specify the character set as part of the connection string, for example:
MySqlConnection myConnection = new MySqlConnection('server=127.0.0.1;uid=root;' + 'pwd=12345;database=test;Charset=latin1;');
Using GetSchema on a Connection
The GetSchema()
method of the connection object can be used to retrieve schema information about the database currently connected to. The schema information is returned in the form of a DataTable
. The schema information is organized into a number of collections. Different forms of the GetSchema()
method can be used depending on the information required. There are three forms of the GetSchema()
method:
GetSchema()
- This call will return a list of available collections.GetSchema(String)
- This call returns information about the collection named in the string parameter. If the string "MetaDataCollections" is used then a list of all available collections is returned. This is the same as callingGetSchema()
without any parameters.GetSchema(String, String[])
- In this call the first string parameter represents the collection name, and the second parameter represents a string array of restriction values. Restriction values limit the amount of data that will be returned. Restriction values are explained in more detail in the Microsoft .NET documentation.
Collections
The collections can be broadly grouped into two types: collections that are common to all data providers, and collections specific to a particular provider.
Common
The following collections are common to all data providers:
- MetaDataCollections
- DataSourceInformation
- DataTypes
- Restrictions
- ReservedWords
Provider-specific
The following are the collections currently provided by MariaDB Connector/Net, in addition to the common collections above:
- Databases
- Tables
- Columns
- Users
- Foreign Keys
- IndexColumns
- Indexes
- Foreign Key Columns
- UDF
- Views
- ViewColumns
- Procedure Parameters
- Procedures
- Triggers
Example Code
A list of available collections can be obtained using the following code:
using System; using System.Data; using System.Text; using MySql.Data; using MySql.Data.MySqlClient; namespace ConsoleApplication2 { class Program { private static void DisplayData(System.Data.DataTable table) { foreach (System.Data.DataRow row in table.Rows) { foreach (System.Data.DataColumn col in table.Columns) { Console.WriteLine('{0} = {1}', col.ColumnName, row[col]); } Console.WriteLine('============================'); } } static void Main(string[] args) { string connStr = 'server=localhost;user=root;database=world;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); DataTable table = conn.GetSchema('MetaDataCollections'); //DataTable table = conn.GetSchema('UDF'); DisplayData(table); conn.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } Console.WriteLine('Done.'); } } }
Further information on the GetSchema()
method and schema collections can be found in the Microsoft .NET documentation.
Using MySqlCommand
A MySqlCommand
has the CommandText
and CommandType
properties associated with it. The CommandText
will be handled differently depending on the setting of CommandType
. CommandType
can be one of:
- Text - A SQL text command (default)
- StoredProcedure - The name of a Stored Procedure
- TableDirect - The name of a table (new in Connector/Net 6.2)
The default CommandType
, Text
, is used for executing queries and other SQL commands. Some example of this can be found in the following section , "The MySqlCommand Object".
If CommandType
is set to StoredProcedure
, set CommandText
to the name of the Stored Procedure to access.
If CommandType
is set to TableDirect
, all rows and columns of the named table will be returned when you call one of the Execute methods. In effect, this command performs a SELECT *
on the table specified. The CommandText
property is set to the name of the table to query. This is illustrated by the following code snippet:
... MySqlCommand cmd = new MySqlCommand(); cmd.CommandText = 'mytable'; cmd.Connection = someConnection; cmd.CommandType = CommandType.TableDirect; MySqlDataReader reader = cmd.ExecuteReader(); while (reader.Read()) { Console.WriteLn(reader[0], reader[1]...); } ...
Examples of using the CommandType of StoredProcedure can be found in the section , "Accessing Stored Procedures with Connector/Net".
Commands can have a timeout associated with them. This is useful as you may not want a situation were a command takes up an excessive amount of time. A timeout can be set using the CommandTimeout
property. The following code snippet sets a timeout of one minute:
MySqlCommand cmd = new MySqlCommand(); cmd.CommandTimeout = 60;
The default value is 30 seconds. Avoid a value of 0, which indicates an indefinite wait. To change the default command timeout, use the connection string option Default Command Timeout
.
Prior to MariaDB Connector/Net 6.2, MySqlCommand.CommandTimeout
included user processing time, that is processing time not related to direct use of the connector. Timeout was implemented through a .NET Timer, that triggered after CommandTimeout
seconds. This timer consumed a thread.
MySQL Connector/Net 6.2 introduced timeouts that are aligned with how Microsoft handles SqlCommand.CommandTimeout
. This property is the cumulative timeout for all network reads and writes during command execution or processing of the results. A timeout can still occur in the MySqlReader.Read
method after the first row is returned, and does not include user processing time, only IO operations. The 6.2 implementation uses the underlying stream timeout facility, so is more efficient in that it does not require the additional timer thread as was the case with the previous implementation.
Further details on this can be found in the relevant Microsoft documentation.
Using Connector/Net with Connection Pooling
The Connector/Net supports connection pooling. This is enabled by default. You can turn it off or adjust its performance characteristics using the connection string options Pooling
, Connection Reset
, Connection Lifetime
, Cache Server Properties
, Max Pool Size
and Min Pool Size
. See , "Creating a Connector/Net Connection String" for further information.
Connection pooling works by keeping the native connection to the server live when the client disposes of a MySqlConnection
. Subsequently, if a new MySqlConnection
object is opened, it will be created from the connection pool, rather than creating a new native connection. This improves performance.
To work as designed, it is best to let the connection pooling system manage all connections. Do not create a globally accessible instance of MySqlConnection
and then manually open and close it. This interferes with the way the pooling works and can lead to unpredictable results or even exceptions.
One approach that simplifies things is to avoid manually creating a MySqlConnection
object. Instead use the overloaded methods that take a connection string as an argument. Using this approach, Connector/Net will automatically create, open, close and destroy connections, using the connection pooling system for best performance.
Typed Datasets and the MembershipProvider
and RoleProvider
classes use this approach. Most classes that have methods that take a MySqlConnection
as an argument, also have methods that take a connection string as an argument. This includes MySqlDataAdapter
.
Instead of manually creating MySqlCommand
objects, you can use the static methods of the MySqlHelper
class. These take a connection string as an argument, and they fully support connection pooling.
Starting with MariaDB Connector/Net 6.2, there is a background job that runs every three minutes and removes connections from pool that have been idle (unused) for more than three minutes. The pool cleanup frees resources on both client and server side. This is because on the client side every connection uses a socket, and on the server side every connection uses a socket and a thread.
Prior to this change, connections were never removed from the pool, and the pool always contained the peak number of open connections. For example, a web application that peaked at 1000 concurrent database connections would consume 1000 threads and 1000 open sockets at the server, without ever freeing up those resources from the connection pool. Note, connections, no matter how old, will not be closed if the number of connections in the pool is less than or equal to the value set by the Min Pool Size
connection string parameter.
Using the Windows Native Authentication Plugin
Connector/Net applications can authenticate to a MariaDB server using the Windows Native Authentication Plugin as of Connector/NET 6.4.4 and MariaDB 5.5.16. Users who have logged in to Windows can connect from MariaDB client programs to the server based on the information in their environment without specifying an additional password. For background and usage information about the authentication plugin, see, The Windows Native Authentication Plugin.
The interface matches the MySql.Data.MySqlClient object. To enable, pass in Integrated Security
to the connection string with a value of yes
or sspi
.
Passing in a user ID is optional. When Windows authentication is set up, a MariaDB user is created and configured to be used by Windows authentication. By default, this user ID is named auth_windows
, but can be defined using a different name. If the default name is used, then passing the user ID to the connection string from Connector/NET is optional, because it will use the auth_windows
user. Otherwise, the name must be passed to the connection string using the standard user ID element.
Using Connector/Net with Table Caching
This feature exists with Connector/NET versions 6.4 and above.
Table caching is a feature that can be used to cache slow-changing datasets on the client side. This is useful for applications that are designed to use readers, but still want to minimize trips to the server for slow-changing tables.
This feature is transparent to the application, and is disabled by default.
Configuration
- To enable table caching, add
'table cache = true'
to the connection string. - Optionally, specify the
'Default Table Cache Age'
connection string option, which represents the number of seconds a table is cached before the cached data is discarded. The default value is60
. - You can turn caching on and off and set caching options at runtime, on a per-command basis.
Using the Connector/Net with Prepared Statements
Introduction
As of MySQL, it is possible to use prepared statements with Connector/Net. Use of prepared statements can provide significant performance improvements on queries that are executed more than once.
Prepared execution is faster than direct execution for statements executed more than once, primarily because the query is parsed only once. In the case of direct execution, the query is parsed every time it is executed. Prepared execution also can provide a reduction of network traffic because for each execution of the prepared statement, it is necessary only to send the data for the parameters.
Another advantage of prepared statements is that it uses a binary protocol that makes data transfer between client and server more efficient.
Preparing Statements in Connector/Net
To prepare a statement, create a command object and set the .CommandText
property to your query.
After entering your statement, call the .Prepare
method of the MySqlCommand
object. After the statement is prepared, add parameters for each of the dynamic elements in the query.
After you enter your query and enter parameters, execute the statement using the .ExecuteNonQuery()
, .ExecuteScalar()
, or .ExecuteReader
methods.
For subsequent executions, you need only modify the values of the parameters and call the execute method again, there is no need to set the .CommandText
property or redefine the parameters.
Visual Basic Example
Dim conn As New MySqlConnection Dim cmd As New MySqlCommand conn.ConnectionString = strConnection Try conn.Open() cmd.Connection = conn cmd.CommandText = 'INSERT INTO myTable VALUES(NULL, @number, @text)' cmd.Prepare() cmd.Parameters.AddWithValue('@number', 1) cmd.Parameters.AddWithValue('@text', 'One') For i = 1 To 1000 cmd.Parameters('@number').Value = i cmd.Parameters('@text').Value = 'A string value' cmd.ExecuteNonQuery() Next Catch ex As MySqlException MessageBox.Show('Error ' & ex.Number & ' has occurred: ' & ex.Message, 'Error', MessageBoxButtons.OK, MessageBoxIcon.Error) End Try
C# Example
MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); conn.ConnectionString = strConnection; try { conn.Open(); cmd.Connection = conn; cmd.CommandText = 'INSERT INTO myTable VALUES(NULL, @number, @text)'; cmd.Prepare(); cmd.Parameters.AddWithValue('@number', 1); cmd.Parameters.AddWithValue('@text', 'One'); for (int i=1; i <= 1000; i++) { cmd.Parameters['@number'].Value = i; cmd.Parameters['@text'].Value = 'A string value'; cmd.ExecuteNonQuery(); } } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show('Error ' + ex.Number + ' has occurred: ' + ex.Message, 'Error', MessageBoxButtons.OK, MessageBoxIcon.Error); }
Accessing Stored Procedures with Connector/Net
Introduction
MySQL server version 5 and up supports stored procedures with the SQL 2003 stored procedure syntax.
A stored procedure is a set of SQL statements that is stored in the server. Clients make a single call to the stored procedure, passing parameters that can influence the procedure logic and query conditions, rather than issuing individual hardcoded SQL statements.
Stored procedures can be particularly useful in situations such as the following:
- Stored procedures can act as an API or abstraction layer, allowing multiple client applications to perform the same database operations. The applications can be written in different languages and run on different platforms. The applications do not need to hardcode table and column names, complicated queries, and so on. When you extend and optimize the queries in a stored procedure, all the applications that call the procedure automatically receive the benefits.
- When security is paramount, stored procedures keep applications from directly manipulating tables, or even knowing details such as table and column names. Banks, for example, use stored procedures for all common operations. This provides a consistent and secure environment, and procedures can ensure that each operation is properly logged. In such a setup, applications and users would not get any access to the database tables directly, but can only execute specific stored procedures.
Connector/Net supports the calling of stored procedures through the MySqlCommand
object. Data can be passed in and out of a MariaDB stored procedure through use of the MySqlCommand.Parameters
collection.Note
When you call a stored procedure, the command object makes an additional SELECT
call to determine the parameters of the stored procedure. You must ensure that the user calling the procedure has the SELECT
privilege on the mysql.proc
table to enable them to verify the parameters. Failure to do this will result in an error when calling the procedure.
This section will not provide in-depth information on creating Stored Procedures. For such information, please refer to http://dev.mysql.com/doc/mysql/en/stored-routines.html.
A sample application demonstrating how to use stored procedures with Connector/Net can be found in the Samples
directory of your Connector/Net installation.
Using Stored Routines from Connector/Net
Stored procedures in MariaDB can be created using a variety of tools. First, stored procedures can be created using the mysql command-line client. Second, stored procedures can be created using MariaDB Workbench. Finally, stored procedures can be created using the .ExecuteNonQuery
method of the MySqlCommand
object.
Unlike the command-line and GUI clients, you are not required to specify a special delimiter when creating stored procedures in Connector/Net.
To call a stored procedure using Connector/Net, you create a MySqlCommand
object and pass the stored procedure name as the .CommandText
property. You then set the .CommandType
property to CommandType.StoredProcedure
.
After the stored procedure is named, you create one MySqlCommand
parameter for every parameter in the stored procedure. IN
parameters are defined with the parameter name and the object containing the value, OUT
parameters are defined with the parameter name and the data type that is expected to be returned. All parameters need the parameter direction defined.
After defining the parameters, you call the stored procedure by using the MySqlCommand.ExecuteNonQuery()
method.
Once the stored procedure is called, the values of the output parameters can be retrieved by using the .Value
property of the MySqlConnector.Parameters
collection.Note
When a stored procedure is called using MySqlCommand.ExecuteReader
, and the stored procedure has output parameters, the output parameters are only set after the MySqlDataReader
returned by ExecuteReader
is closed.
The following C# example code demonstrates the use of stored procedures. It assumes the database 'employees' has already been created:
using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; namespace UsingStoredRoutines { class Program { static void Main(string[] args) { MySqlConnection conn = new MySqlConnection(); conn.ConnectionString = 'server=localhost;user=root;database=employees;port=3306;password=******;'; MySqlCommand cmd = new MySqlCommand(); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); cmd.Connection = conn; cmd.CommandText = 'DROP PROCEDURE IF EXISTS add_emp'; cmd.ExecuteNonQuery(); cmd.CommandText = 'DROP TABLE IF EXISTS emp'; cmd.ExecuteNonQuery(); cmd.CommandText = 'CREATE TABLE emp (empno INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, first_name VARCHAR(20), last_name VARCHAR(20), birthdate DATE)'; cmd.ExecuteNonQuery(); cmd.CommandText = 'CREATE PROCEDURE add_emp(' + 'IN fname VARCHAR(20), IN lname VARCHAR(20), IN bday DATETIME, OUT empno INT)' + 'BEGIN INSERT INTO emp(first_name, last_name, birthdate) ' + 'VALUES(fname, lname, DATE(bday)); SET empno = LAST_INSERT_ID(); END'; cmd.ExecuteNonQuery(); } catch (MySqlException ex) { Console.WriteLine ('Error ' + ex.Number + ' has occurred: ' + ex.Message); } conn.Close(); Console.WriteLine('Connection closed.'); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); cmd.Connection = conn; cmd.CommandText = 'add_emp'; cmd.CommandType = CommandType.StoredProcedure; cmd.Parameters.AddWithValue('@lname', 'Jones'); cmd.Parameters['@lname'].Direction = ParameterDirection.Input; cmd.Parameters.AddWithValue('@fname', 'Tom'); cmd.Parameters['@fname'].Direction = ParameterDirection.Input; cmd.Parameters.AddWithValue('@bday', '1940-06-07'); cmd.Parameters['@bday'].Direction = ParameterDirection.Input; cmd.Parameters.AddWithValue('@empno', MySqlDbType.Int32); cmd.Parameters['@empno'].Direction = ParameterDirection.Output; cmd.ExecuteNonQuery(); Console.WriteLine('Employee number: '+cmd.Parameters['@empno'].Value); Console.WriteLine('Birthday: ' + cmd.Parameters['@bday'].Value); } catch (MySql.Data.MySqlClient.MySqlException ex) { Console.WriteLine('Error ' + ex.Number + ' has occurred: ' + ex.Message); } conn.Close(); Console.WriteLine('Done.'); } } }
The following code shows the same application in Visual Basic:
Imports System Imports System.Collections.Generic Imports System.Linq Imports System.Text Imports System.Data Imports MySql.Data Imports MySql.Data.MySqlClient Module Module1 Sub Main() Dim conn As New MySqlConnection() conn.ConnectionString = 'server=localhost;user=root;database=world;port=3306;password=******;' Dim cmd As New MySqlCommand() Try Console.WriteLine('Connecting to MariaDB...') conn.Open() cmd.Connection = conn cmd.CommandText = 'DROP PROCEDURE IF EXISTS add_emp' cmd.ExecuteNonQuery() cmd.CommandText = 'DROP TABLE IF EXISTS emp' cmd.ExecuteNonQuery() cmd.CommandText = 'CREATE TABLE emp (empno INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, first_name VARCHAR(20), last_name VARCHAR(20), birthdate DATE)' cmd.ExecuteNonQuery() cmd.CommandText = 'CREATE PROCEDURE add_emp(' & 'IN fname VARCHAR(20), IN lname VARCHAR(20), IN bday DATETIME, OUT empno INT)' & 'BEGIN INSERT INTO emp(first_name, last_name, birthdate) ' & 'VALUES(fname, lname, DATE(bday)); SET empno = LAST_INSERT_ID(); END' cmd.ExecuteNonQuery() Catch ex As MySqlException Console.WriteLine(('Error ' & ex.Number & ' has occurred: ') + ex.Message) End Try conn.Close() Console.WriteLine('Connection closed.') Try Console.WriteLine('Connecting to MariaDB...') conn.Open() cmd.Connection = conn cmd.CommandText = 'add_emp' cmd.CommandType = CommandType.StoredProcedure cmd.Parameters.AddWithValue('@lname', 'Jones') cmd.Parameters('@lname').Direction = ParameterDirection.Input cmd.Parameters.AddWithValue('@fname', 'Tom') cmd.Parameters('@fname').Direction = ParameterDirection.Input cmd.Parameters.AddWithValue('@bday', '1940-06-07') cmd.Parameters('@bday').Direction = ParameterDirection.Input cmd.Parameters.AddWithValue('@empno', MySqlDbType.Int32) cmd.Parameters('@empno').Direction = ParameterDirection.Output cmd.ExecuteNonQuery() Console.WriteLine('Employee number: ' & cmd.Parameters('@empno').Value) Console.WriteLine('Birthday: ' & cmd.Parameters('@bday').Value) Catch ex As MySql.Data.MySqlClient.MySqlException Console.WriteLine(('Error ' & ex.Number & ' has occurred: ') + ex.Message) End Try conn.Close() Console.WriteLine('Done.') End Sub End Module
Handling BLOB Data With Connector/Net
- Preparing the MariaDB Server
- Writing a File to the Database
- Reading a BLOB from the Database to a File on Disk
- Writing a File to the Database
One common use for MariaDB is the storage of binary data in BLOB
columns. MariaDB supports four different BLOB data types: TINYBLOB
, BLOB
, MEDIUMBLOB
, and LONGBLOB
, all described in , "The BLOB
and TEXT
Types" and , "Data Type Storage Requirements".
Data stored in a BLOB
column can be accessed using Connector/Net and manipulated using client-side code. There are no special requirements for using Connector/Net with BLOB
data.
Simple code examples will be presented within this section, and a full sample application can be found in the Samples
directory of the Connector/Net installation.
Preparing the MariaDB Server
The first step is using MariaDB with BLOB
data is to configure the server. Let's start by creating a table to be accessed. In my file tables, I usually have four columns: an AUTO_INCREMENT
column of appropriate size (UNSIGNED SMALLINT
) to serve as a primary key to identify the file, a VARCHAR
column that stores the file name, an UNSIGNED MEDIUMINT
column that stores the size of the file, and a MEDIUMBLOB
column that stores the file itself. For this example, I will use the following table definition:
CREATE TABLE file( file_id SMALLINT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY, file_name VARCHAR(64) NOT NULL, file_size MEDIUMINT UNSIGNED NOT NULL, file MEDIUMBLOB NOT NULL);
After creating a table, you might need to modify the max_allowed_packet
system variable. This variable determines how large of a packet (that is, a single row) can be sent to the MariaDB server. By default, the server only accepts a maximum size of 1MB from the client application. If you intend to exceed 1MB in your file transfers, increase this number.
The max_allowed_packet
option can be modified using MariaDB Administrator's Startup Variables screen. Adjust the Maximum permitted option in the Memory section of the Networking tab to an appropriate setting. After adjusting the value, click the Apply Changes button and restart the server using the Service Control
screen of MariaDB Administrator. You can also adjust this value directly in the my.cnf
file (add a line that reads max_allowed_packet=
), or use the xx
MSET max_allowed_packet=
syntax from within MySQL.
xx
M;
Try to be conservative when setting max_allowed_packet
, as transfers of BLOB data can take some time to complete. Try to set a value that will be adequate for your intended use and increase the value if necessary.
Writing a File to the Database
To write a file to a database, we need to convert the file to a byte array, then use the byte array as a parameter to an INSERT
query.
The following code opens a file using a FileStream object, reads it into a byte array, and inserts it into the file
table:
Visual Basic Example
Dim conn As New MySqlConnection Dim cmd As New MySqlCommand Dim SQL As String Dim FileSize As UInt32 Dim rawData() As Byte Dim fs As FileStream conn.ConnectionString = 'server=127.0.0.1;' _ & 'uid=root;' _ & 'pwd=12345;' _ & 'database=test' Try fs = New FileStream('c:\image.png', FileMode.Open, FileAccess.Read) FileSize = fs.Length rawData = New Byte(FileSize) {} fs.Read(rawData, 0, FileSize) fs.Close() conn.Open() SQL = 'INSERT INTO file VALUES(NULL, @FileName, @FileSize, @File)' cmd.Connection = conn cmd.CommandText = SQL cmd.Parameters.AddWithValue('@FileName', strFileName) cmd.Parameters.AddWithValue('@FileSize', FileSize) cmd.Parameters.AddWithValue('@File', rawData) cmd.ExecuteNonQuery() MessageBox.Show('File Inserted into database successfully!', _ 'Success!', MessageBoxButtons.OK, MessageBoxIcon.Asterisk) conn.Close() Catch ex As Exception MessageBox.Show('There was an error: ' & ex.Message, 'Error', _ MessageBoxButtons.OK, MessageBoxIcon.Error) End Try
C# Example
MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); string SQL; UInt32 FileSize; byte[] rawData; FileStream fs; conn.ConnectionString = 'server=127.0.0.1;uid=root;' + 'pwd=12345;database=test;'; try { fs = new FileStream(@'c:\image.png', FileMode.Open, FileAccess.Read); FileSize = fs.Length; rawData = new byte[FileSize]; fs.Read(rawData, 0, FileSize); fs.Close(); conn.Open(); SQL = 'INSERT INTO file VALUES(NULL, @FileName, @FileSize, @File)'; cmd.Connection = conn; cmd.CommandText = SQL; cmd.Parameters.AddWithValue('@FileName', strFileName); cmd.Parameters.AddWithValue('@FileSize', FileSize); cmd.Parameters.AddWithValue('@File', rawData); cmd.ExecuteNonQuery(); MessageBox.Show('File Inserted into database successfully!', 'Success!', MessageBoxButtons.OK, MessageBoxIcon.Asterisk); conn.Close(); } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show('Error ' + ex.Number + ' has occurred: ' + ex.Message, 'Error', MessageBoxButtons.OK, MessageBoxIcon.Error); }
The Read
method of the FileStream
object is used to load the file into a byte array which is sized according to the Length
property of the FileStream
object.
After assigning the byte array as a parameter of the MySqlCommand
object, the ExecuteNonQuery
method is called and the BLOB
is inserted into the file
table.
Reading a BLOB from the Database to a File on Disk
Once a file is loaded into the file
table, we can use the MySqlDataReader
class to retrieve it.
The following code retrieves a row from the file
table, then loads the data into a FileStream
object to be written to disk:
Visual Basic Example
Dim conn As New MySqlConnection Dim cmd As New MySqlCommand Dim myData As MySqlDataReader Dim SQL As String Dim rawData() As Byte Dim FileSize As UInt32 Dim fs As FileStream conn.ConnectionString = 'server=127.0.0.1;' _ & 'uid=root;' _ & 'pwd=12345;' _ & 'database=test' SQL = 'SELECT file_name, file_size, file FROM file' Try conn.Open() cmd.Connection = conn cmd.CommandText = SQL myData = cmd.ExecuteReader If Not myData.HasRows Then Throw New Exception('There are no BLOBs to save') myData.Read() FileSize = myData.GetUInt32(myData.GetOrdinal('file_size')) rawData = New Byte(FileSize) {} myData.GetBytes(myData.GetOrdinal('file'), 0, rawData, 0, FileSize) fs = New FileStream('C:\newfile.png', FileMode.OpenOrCreate, FileAccess.Write) fs.Write(rawData, 0, FileSize) fs.Close() MessageBox.Show('File successfully written to disk!', 'Success!', MessageBoxButtons.OK, MessageBoxIcon.Asterisk) myData.Close() conn.Close() Catch ex As Exception MessageBox.Show('There was an error: ' & ex.Message, 'Error', MessageBoxButtons.OK, MessageBoxIcon.Error) End Try
C# Example
MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; MySql.Data.MySqlClient.MySqlDataReader myData; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); string SQL; UInt32 FileSize; byte[] rawData; FileStream fs; conn.ConnectionString = 'server=127.0.0.1;uid=root;' + 'pwd=12345;database=test;'; SQL = 'SELECT file_name, file_size, file FROM file'; try { conn.Open(); cmd.Connection = conn; cmd.CommandText = SQL; myData = cmd.ExecuteReader(); if (! myData.HasRows) throw new Exception('There are no BLOBs to save'); myData.Read(); FileSize = myData.GetUInt32(myData.GetOrdinal('file_size')); rawData = new byte[FileSize]; myData.GetBytes(myData.GetOrdinal('file'), 0, rawData, 0, (int)FileSize); fs = new FileStream(@'C:\newfile.png', FileMode.OpenOrCreate, FileAccess.Write); fs.Write(rawData, 0, (int)FileSize); fs.Close(); MessageBox.Show('File successfully written to disk!', 'Success!', MessageBoxButtons.OK, MessageBoxIcon.Asterisk); myData.Close(); conn.Close(); } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show('Error ' + ex.Number + ' has occurred: ' + ex.Message, 'Error', MessageBoxButtons.OK, MessageBoxIcon.Error); }
After connecting, the contents of the file
table are loaded into a MySqlDataReader
object. The GetBytes
method of the MySqlDataReader
is used to load the BLOB
into a byte array, which is then written to disk using a FileStream
object.
The GetOrdinal
method of the MySqlDataReader can be used to determine the integer index of a named column. Use of the GetOrdinal method prevents errors if the column order of the SELECT
query is changed.
Using the Connector/Net Interceptor Classes
An interceptor is a software design pattern that provides a transparent way to extend or modify some aspect of a program, similar to a user exit. No recompiling is required. With Connector/Net, the interceptors are enabled and disabled by updating the connection string to refer to different sets of interceptor classes that you instantiate.
Connector/Net includes the following interceptor classes:
- The
BaseCommandInterceptor
lets you perform additional operations when a program issues a SQL command. For example, you can examine the SQL statement for logging or debugging purposes, substitute your own result set to implement a caching mechanism, and so on. Depending on the use case, your code can supplement the SQL command or replace it entirely.
The
BaseCommandInterceptor
class has these methods that you can override:public virtual bool ExecuteScalar(string sql, ref object returnValue); public virtual bool ExecuteNonQuery(string sql, ref int returnValue); public virtual bool ExecuteReader(string sql, CommandBehavior behavior, ref MySqlDataReader returnValue); public virtual void Init(MySqlConnection connection);
If your interceptor overrides one of the
Execute...
methods, set thereturnValue
output parameter and returntrue
if you handled the event, orfalse
if you did not handle the event. The SQL command is processed normally only when all command interceptors returnfalse
.The connection passed to the
Init
method is the connection that is attached to this interceptor. - The
BaseExceptionInterceptor
lets you perform additional operations when a program encounters a SQL exception. The exception interception mechanism is modeled after the Connector/J model. You can code an interceptor class and connect it to an existing program without recompiling, and intercept exceptions when they are created. You can then change the exception type and optionally attach information to it. This capability lets you turn on and off logging and debugging code without hardcoding anything in the application. This technique applies to exceptions raised at the SQL level, not to lower-level system or I/O errors.You develop an exception interceptor first by creating a subclass of the
BaseExceptionInterceptor
class. You must override theInterceptException()
method. You can also override theInit()
method to do some one-time initialization.Each exception interceptor has 2 methods:
public abstract Exception InterceptException(Exception exception, MySqlConnection connection); public virtual void Init(MySqlConnection connection);
The connection passed to
Init()
is the connection that is attached to this interceptor.Each interceptor is required to override
InterceptException
and return an exception. It can return the exception it is given, or it can wrap it in a new exception. We currently do not offer the ability to suppress the exception.
Here are examples of using the FQN (fully qualified name) on the connection string:
MySqlConnection c1 = new MySqlConnection(@'server=localhost;pooling=false; commandinterceptors=CommandApp.MyCommandInterceptor,CommandApp'); MySqlConnection c2 = new MySqlConnection(@'server=localhost;pooling=false; exceptioninterceptors=ExceptionStackTraceTest.MyExceptionInterceptor,ExceptionStackTraceTest');
In this example, the command interceptor is called CommandApp.MyCommandInterceptor
and exists in the CommandApp
assembly. The exception interceptor is called ExceptionStackTraceTest.MyExceptionInterceptor
and exists in the ExceptionStackTraceTest
assembly.
To shorten the connection string, you can register your exception interceptors in your app.config
or web.config
file like this:
<configSections> <section name="MySQL" type="MySql.Data.MySqlClient.MySqlConfiguration, MySql.Data"/> </configSections> <MySQL> <CommandInterceptors> <add name="myC" type="CommandApp.MyCommandInterceptor,CommandApp" /> </CommandInterceptors> </MySQL> <configSections> <section name="MySQL" type="MySql.Data.MySqlClient.MySqlConfiguration, MySql.Data"/> </configSections> <MySQL> <ExceptionInterceptors> <add name="myE" type='ExceptionStackTraceTest.MyExceptionInterceptor,ExceptionStackTraceTest' /> </ExceptionInterceptors> </MySQL>
Once you have done that, your connection strings can look like these:
MySqlConnection c1 = new MySqlConnection(@'server=localhost;pooling=false; commandinterceptors=myC'); MySqlConnection c2 = new MySqlConnection(@'server=localhost;pooling=false; exceptioninterceptors=myE');
Handling Date and Time Information in Connector/Net
- Fractional Seconds
- Problems when Using Invalid Dates
- Restricting Invalid Dates
- Handling Invalid Dates
- Handling NULL Dates
- Problems when Using Invalid Dates
Introduction
MySQL and the .NET languages handle date and time information differently, with MariaDB allowing dates that cannot be represented by a .NET data type, such as '0000-00-00 00:00:00
'. These differences can cause problems if not properly handled.
The following sections demonstrate how to properly handle date and time information when using Connector/Net.
Fractional Seconds
Connector/Net 6.5 and higher support the fractional seconds feature introduced in MariaDB 5.6.4. Fractional seconds could always be specified in a date literal or passed back and forth as parameters and return values, but the fractional part was always stripped off when stored in a table column. In MariaDB 5.6.4 and higher, the fractional part is now preserved in data stored and retrieved through SQL. For fractional second handling in MariaDB 5.6.4 and higher, see , "Fractional Seconds in Time Values". For the behavior of fractional seconds prior to MariaDB 5.6.4, see Fractional Seconds in Time Values.
To use the more precise date and time types, specify a value from 1 to 6 when creating the table column, for example TIME(3)
or DATETIME(6)
, representing the number of digits of precision after the decimal point. Specifying a precision of 0 leaves the fractional part out entirely. In your C# or Visual Basic code, refer to the Millisecond
member to retrieve the fractional second value from the MySqlDateTime
object returned by the GetMySqlDateTime
function. The DateTime
object returned by the GetDateTime
function also contains the fractional value, but only the first 3 digits.
For related code examples, see the following blog post: https://blogs.oracle.com/MySqlOnWindows/entry/milliseconds_value_support_on_datetime
Problems when Using Invalid Dates
The differences in date handling can cause problems for developers who use invalid dates. Invalid MariaDB dates cannot be loaded into native .NET DateTime
objects, including NULL
dates.
Because of this issue, .NET DataSet
objects cannot be populated by the Fill
method of the MySqlDataAdapter
class as invalid dates will cause a System.ArgumentOutOfRangeException
exception to occur.
Restricting Invalid Dates
The best solution to the date problem is to restrict users from entering invalid dates. This can be done on either the client or the server side.
Restricting invalid dates on the client side is as simple as always using the .NET DateTime
class to handle dates. The DateTime
class will only allow valid dates, ensuring that the values in your database are also valid. The disadvantage of this is that it is not useful in a mixed environment where .NET and non .NET code are used to manipulate the database, as each application must perform its own date validation.
Users of MariaDB 5.0.2 and higher can use the new traditional
SQL mode to restrict invalid date values. For information on using the traditional
SQL mode, see , "Server SQL Modes".
Handling Invalid Dates
Although it is strongly recommended that you avoid the use of invalid dates within your .NET application, it is possible to use invalid dates by means of the MySqlDateTime
data type.
The MySqlDateTime
data type supports the same date values that are supported by the MariaDB server. The default behavior of Connector/Net is to return a .NET DateTime object for valid date values, and return an error for invalid dates. This default can be modified to cause Connector/Net to return MySqlDateTime
objects for invalid dates.
To instruct Connector/Net to return a MySqlDateTime
object for invalid dates, add the following line to your connection string:
Allow Zero Datetime=True
Please note that the use of the MySqlDateTime
class can still be problematic. The following are some known issues:
- Data binding for invalid dates can still cause errors (zero dates like 0000-00-00 do not seem to have this problem).
- The
ToString
method return a date formatted in the standard MariaDB format (for example,2005-02-23 08:50:25
). This differs from theToString
behavior of the .NET DateTime class. - The
MySqlDateTime
class supports NULL dates, while the .NET DateTime class does not. This can cause errors when trying to convert a MySQLDateTime to a DateTime if you do not check for NULL first.
Because of the known issues, the best recommendation is still to use only valid dates in your application.
Handling NULL Dates
The .NET DateTime
data type cannot handle NULL
values. As such, when assigning values from a query to a DateTime
variable, you must first check whether the value is in fact NULL
.
When using a MySqlDataReader
, use the .IsDBNull
method to check whether a value is NULL
before making the assignment:
Visual Basic Example
If Not myReader.IsDBNull(myReader.GetOrdinal('mytime')) Then myTime = myReader.GetDateTime(myReader.GetOrdinal('mytime')) Else myTime = DateTime.MinValue End If
C# Example
if (! myReader.IsDBNull(myReader.GetOrdinal('mytime'))) myTime = myReader.GetDateTime(myReader.GetOrdinal('mytime')); else myTime = DateTime.MinValue;
NULL
values will work in a data set and can be bound to form controls without special handling.
Using the MySqlBulkLoader
Class
MySQL Connector/Net features a bulk loader class that wraps the MariaDB statement LOAD DATA INFILE
. This gives MariaDB Connector/Net the ability to load a data file from a local or remote host to the server. The class concerned is MySqlBulkLoader
. This class has various methods, the main one being load
to cause the specified file to be loaded to the server. Various parameters can be set to control how the data file is processed. This is achieved through setting various properties of the class. For example, the field separator used, such as comma or tab, can be specified, along with the record terminator, such as newline.
The following code shows a simple example of using the MySqlBulkLoader
class. First an empty table needs to be created, in this case in the test
database:
CREATE TABLE Career ( Name VARCHAR(100) NOT NULL, Age INTEGER, Profession VARCHAR(200) );
A simple tab-delimited data file is also created (it could use any other field delimiter such as comma):
Table Career in Test Database Name Age Profession Tony 47 Technical Writer Ana 43 Nurse Fred 21 IT Specialist Simon 45 Hairy Biker
Note that with this test file the first three lines will need to be ignored, as they do not contain table data. This can be achieved using the NumberOfLinesToSkip
property. This file can then be loaded and used to populate the Career
table in the test
database:
using System; using System.Text; using MySql.Data; using MySql.Data.MySqlClient; namespace ConsoleApplication1 { class Program { static void Main(string[] args) { string connStr = 'server=localhost;user=root;database=test;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); MySqlBulkLoader bl = new MySqlBulkLoader(conn); bl.TableName = 'Career'; bl.FieldTerminator = '\t'; bl.LineTerminator = '\n'; bl.FileName = 'c:/career_data.txt'; bl.NumberOfLinesToSkip = 3; try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); // Upload data from file int count = bl.Load(); Console.WriteLine(count + ' lines uploaded.'); string sql = 'SELECT Name, Age, Profession FROM Career'; MySqlCommand cmd = new MySqlCommand(sql, conn); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr[0] + ' -- ' + rdr[1] + ' -- ' + rdr[2]); } rdr.Close(); conn.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } Console.WriteLine('Done.'); } } }
Further information on LOAD DATA INFILE
can be found in , "LOAD DATA INFILE
Syntax". Further information on MySqlBulkLoader
can be found in the reference documentation that was included with your connector.
Using the MariaDB Connector/Net Trace Source Object
MySQL Connector/Net 6.2 introduced support for .NET 2.0 compatible tracing, using TraceSource
objects.
The .NET 2.0 tracing architecture consists of four main parts:
- Source - This is the originator of the trace information. The source is used to send trace messages. The name of the source provided by MariaDB Connector/Net is
MariaDB
. - Switch - This defines the level of trace information to emit. Typically, this is specified in the
app.config
file, so that it is not necessary to recompile an application to change the trace level. - Listener - Trace listeners define where the trace information will be written to. Supported listeners include, for example, the Visual Studio Output window, the Windows Event Log, and the console.
- Filter - Filters can be attached to listeners. Filters determine the level of trace information that will be written. While a switch defines the level of information that will be written to all listeners, a filter can be applied on a per-listener basis, giving finer grained control of trace information.
To use tracing a TraceSource
object first needs to be created. To create a TraceSource
object in MariaDB Connector/Net you would use code similar to the following:
TraceSource ts = new TraceSource('mysql');
To enable trace messages, configure a trace switch. There are three main switch classes, BooleanSwitch
, SourceSwitch
, and TraceSwitch
. Trace switches also have associated with them a trace level enumeration, these are Off
, Error
, Warning
, Info
, and Verbose
. The following code snippet illustrates creating a switch:
ts.Switch = new SourceSwitch('MySwitch', 'Verbose');
This creates a SourceSwitch
, called MySwitch
, and sets the trace level to Verbose
, meaning that all trace messages will be written.
It is convenient to be able to change the trace level without having to recompile the code. This is achieved by specifying the trace level in application configuration file, app.config
. You then simply need to specify the desired trace level in the configuration file and restart the application. The trace source is configured within the system.diagnostics
section of the file. The following XML snippet illustrates this:
<configuration> ... <system.diagnostics> <sources> <source name="mysql" switchName="MySwitch" switchType="System.Diagnostics.SourceSwitch" /> ... </sources> <switches> <add name="MySwitch" value="Verbose"/> ... </switches> </system.diagnostics> ... </configuration>
By default, trace information is written to the Output window of Microsoft Visual Studio. There are a wide range of listeners that can be attached to the trace source, so that trace messages can be written out to various destinations. You can also create custom listeners to allow trace messages to be written to other destinations as mobile devices and web services. A commonly used example of a listener is ConsoleTraceListener
, which writes trace messages to the console.
To add a listener at run time, use code such as the following:
ts.Listeners.Add(new ConsoleTraceListener());
Then, call methods on the trace source object to generate trace information. For example, the TraceInformation()
, TraceEvent()
, or TraceData()
methods can be used.
The TraceInformation()
method simply prints a string passed as a parameter. The TraceEvent()
method, as well as the optional informational string, requires a TraceEventType
value to be passed to indicate the trace message type, and also an application specific ID. The TraceEventType
can have a value of Verbose
, Information
, Warning
, Error
, and Critical
. Using the TraceData()
method you can pass any object, for example an exception object, instead of a message.
To ensure than these generated trace messages gets flushed from the trace source buffers to listeners, invoke the Flush()
method. When you are finished using a trace source, call the Close()
method. The Close()
method first calls Flush()
, to ensure any remaining data is written out. It then frees up resources, and closes the listeners associated with the trace source.
ts.TraceInformation('Informational message'); ts.TraceEvent(TraceEventType.Error, 3, 'Optional error message'); ts.TraceData(TraceEventType.Error, 3, ex); // pass exception object ts.Flush(); ... ts.Close();
Viewing MariaDB Trace Information
This section describes how to set up your application to view MariaDB trace information.
The first thing you need to do is create a suitable app.config
file for your application. An example is shown in the following code:
<?xml version="1.0" encoding="utf-8" ?> <configuration> <system.diagnostics> <sources> <source name="mysql" switchName="SourceSwitch" switchType="System.Diagnostics.SourceSwitch" > <listeners> <add name="console" /> <remove name ='Default' /> </listeners> </source> </sources> <switches> <!-- You can set the level at which tracing is to occur --> <add name="SourceSwitch" value="Verbose" /> <!-- You can turn tracing off --> <!--add name="SourceSwitch" value="Off" --> </switches> <sharedListeners> <add name="console" type="System.Diagnostics.ConsoleTraceListener" initializeData="false"/> </sharedListeners> </system.diagnostics> </configuration>
This ensures a suitable trace source is created, along with a switch. The switch level in this case is set to Verbose
to display the maximum amount of information.
In the application the only other step required is to add logging=true
to the connection string. An example application could be:
using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Diagnostics; using MySql.Data; using MySql.Data.MySqlClient; using MySql.Web; namespace ConsoleApplication1 { class Program { static void Main(string[] args) { string connStr = 'server=localhost;user=root;database=world;port=3306;password=******;logging=true;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); string sql = 'SELECT Name, HeadOfState FROM Country WHERE Continent="Oceania"'; MySqlCommand cmd = new MySqlCommand(sql, conn); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr[0] + ' -- ' + rdr[1]); } rdr.Close(); conn.Close(); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } Console.WriteLine('Done.'); } } }
This simple application will then generate the following output:
Connecting to MariaDB... mysql Information: 1 : 1: Connection Opened: connection string = 'server=localhost;User Id=root;database=world;port=3306 ;password=******;logging=True' mysql Information: 3 : 1: Query Opened: SHOW VARIABLES mysql Information: 4 : 1: Resultset Opened: field(s) = 2, affected rows = -1, inserted id = -1 mysql Information: 5 : 1: Resultset Closed. Total rows=272, skipped rows=0, size (bytes)=7058 mysql Information: 6 : 1: Query Closed mysql Information: 3 : 1: Query Opened: SHOW COLLATION mysql Information: 4 : 1: Resultset Opened: field(s) = 6, affected rows = -1, inserted id = -1 mysql Information: 5 : 1: Resultset Closed. Total rows=127, skipped rows=0, size (bytes)=4102 mysql Information: 6 : 1: Query Closed mysql Information: 3 : 1: Query Opened: SET character_set_results=NULL mysql Information: 4 : 1: Resultset Opened: field(s) = 0, affected rows = 0, inserted id = 0 mysql Information: 5 : 1: Resultset Closed. Total rows=0, skipped rows=0, size (bytes)=0 mysql Information: 6 : 1: Query Closed mysql Information: 10 : 1: Set Database: world mysql Information: 3 : 1: Query Opened: SELECT Name, HeadOfState FROM Country WHERE Continent="Oceania" mysql Information: 4 : 1: Resultset Opened: field(s) = 2, affected rows = -1, inserted id = -1 American Samoa -- George W. Bush Australia -- Elisabeth II ... Wallis and Futuna -- Jacques Chirac Vanuatu -- John Bani United States Minor Outlying Islands -- George W. Bush mysql Information: 5 : 1: Resultset Closed. Total rows=28, skipped rows=0, size (bytes)=788 mysql Information: 6 : 1: Query Closed Done. mysql Information: 2 : 1: Connection Closed
The first number displayed in the trace message corresponds to the MariaDB event type:
Event | Description |
---|---|
1 | ConnectionOpened: connection string |
2 | ConnectionClosed: |
3 | QueryOpened: mysql server thread id, query text |
4 | ResultOpened: field count, affected rows (-1 if select), inserted id (-1 if select) |
5 | ResultClosed: total rows read, rows skipped, size of resultset in bytes |
6 | QueryClosed: |
7 | StatementPrepared: prepared sql, statement id |
8 | StatementExecuted: statement id, mysql server thread id |
9 | StatementClosed: statement id |
10 | NonQuery: [varies] |
11 | UsageAdvisorWarning: usage advisor flag. NoIndex = 1, BadIndex = 2, SkippedRows = 3, SkippedColumns = 4, FieldConversion = 5. |
12 | Warning: level, code, message |
13 | Error: error number, error message |
The second number displayed in the trace message is the connection count.
Although this example uses the ConsoleTraceListener
, any of the other standard listeners could have been used. Another possibility is to create a custom listener that uses the information passed using the TraceEvent
method. For example, a custom trace listener could be created to perform active monitoring of the MariaDB event messages, rather than simply writing these to an output device.
It is also possible to add listeners to the MariaDB Trace Source at run time. This can be done with the following code:
MySqlTrace.Listeners.Add(new ConsoleTraceListener());
MySQL Connector/Net 6.3.2 introduced the ability to switch tracing on and off at run time. This can be achieved using the calls MySqlTrace.EnableQueryAnalyzer(string host, int postInterval)
and MySqlTrace.DisableQueryAnalyzer()
. The parameter host
is the URL of the MariaDB Enterprise Monitor server to monitor. The parameter postInterval
is how often to post the data to MariaDB Enterprise Monitor, in seconds.
Building Custom Listeners
To build custom listeners that work with the MariaDB Connector/Net Trace Source, it is necessary to understand the key methods used, and the event data formats used.
The main method involved in passing trace messages is the TraceSource.TraceEvent
method. This has the prototype:
public void TraceEvent( TraceEventType eventType, int id, string format, params Object[] args )
This trace source method will process the list of attached listeners and call the listener's TraceListener.TraceEvent method. The prototype for the TraceListener.TraceEvent
method is as follows:
public virtual void TraceEvent( TraceEventCache eventCache, string source, TraceEventType eventType, int id, string format, params Object[] args )
The first three parameters are used in the standard as defined by Microsoft. The last three parameters contain MySQL-specific trace information. Each of these parameters is now discussed in more detail.
int id
This is a MySQL-specific identifier. It identifies the MariaDB event type that has occurred, resulting in a trace message being generated. This value is defined by the MySqlTraceEventType
public enum contained in the MariaDB Connector/Net code:
public enum MySqlTraceEventType : int { ConnectionOpened = 1, ConnectionClosed, QueryOpened, ResultOpened, ResultClosed, QueryClosed, StatementPrepared, StatementExecuted, StatementClosed, NonQuery, UsageAdvisorWarning, Warning, Error }
The MariaDB event type also determines the contents passed using the parameter params Object[] args
. The nature of the args
parameters are described in further detail in the following material.
string format
This is the format string that contains zero or more format items, which correspond to objects in the args array. This would be used by a listener such as ConsoleTraceListener
to write a message to the output device.
params Object[] args
This is a list of objects that depends on the MariaDB event type, id
. However, the first parameter passed using this list is always the driver id. The driver id is a unique number that is incremented each time the connector is opened. This enables groups of queries on the same connection to be identified. The parameters that follow driver id depend of the MariaDB event id, and are as follows:
MySQL-specific event type | Arguments (params Object[] args) |
---|---|
ConnectionOpened | Connection string |
ConnectionClosed | No additional parameters |
QueryOpened | mysql server thread id, query text |
ResultOpened | field count, affected rows (-1 if select), inserted id (-1 if select) |
ResultClosed | total rows read, rows skipped, size of resultset in bytes |
QueryClosed | No additional parameters |
StatementPrepared | prepared sql, statement id |
StatementExecuted | statement id, mysql server thread id |
StatementClosed | statement id |
NonQuery | Varies |
UsageAdvisorWarning | usage advisor flag. NoIndex = 1, BadIndex = 2, SkippedRows = 3, SkippedColumns = 4, FieldConversion = 5. |
Warning | level, code, message |
Error | error number, error message |
This information will allow you to create custom trace listeners that can actively monitor the MySQL-specific events.
Binary/Nonbinary Issues
There are certain situations where MariaDB will return incorrect metadata about one or more columns. More specifically, the server will sometimes report that a column is binary when it is not and vice versa. In these situations, it becomes practically impossible for the connector to be able to correctly identify the correct metadata.
Some examples of situations that may return incorrect metadata are:
- Execution of
SHOW PROCESSLIST
. Some of the columns will be returned as binary even though they only hold string data. - When a temporary table is used to process a resultset, some columns may be returned with incorrect binary flags.
- Some server functions such
DATE_FORMAT
will incorrectly return the column as binary.
With the availability of BINARY
and VARBINARY
data types, it is important that we respect the metadata returned by the server. However, we are aware that some existing applications may break with this change, so we are creating a connection string option to enable or disable it. By default, Connector/Net 5.1 respects the binary flags returned by the server. You might need to make small changes to your application to accommodate this change.
In the event that the changes required to your application would be too large, adding 'respect binary flags=false'
to your connection string causes the connector to use the prior behavior: any column that is marked as string, regardless of binary flags, will be returned as string. Only columns that are specifically marked as a BLOB
will be returned as BLOB
.
Character Set Considerations for Connector/Net
Treating Binary Blobs As UTF8
MySQL doesn't currently support 4-byte UTF8 sequences. This makes it difficult to represent some multi-byte languages such as Japanese. To try and alleviate this, Connector/Net now supports a mode where binary blobs can be treated as strings.
To do this, you set the 'Treat Blobs As UTF8'
connection string keyword to yes
. This is all that needs to be done to enable conversion of all binary blobs to UTF8 strings. To convert only some of your BLOB columns, you can make use of the 'BlobAsUTF8IncludePattern'
and'BlobAsUTF8ExcludePattern'
keywords. Set these to a regular expression pattern that matches the column names to include or exclude respectively.
When the regular expression patterns both match a single column, the include pattern is applied before the exclude pattern. The result, in this case, would be that the column would be excluded. Also, be aware that this mode does not apply to columns of type BINARY
or VARBINARY
and also do not apply to nonbinary BLOB
columns.
Currently, this mode only applies to reading strings out of MySQL. To insert 4-byte UTF8 strings into blob columns, use the .NET Encoding.GetBytes
function to convert your string to a series of bytes. You can then set this byte array as a parameter for a BLOB
column.
Using Connector/Net with Crystal Reports
Introduction
Crystal Reports is a common tool used by Windows application developers to perform reporting and document generation. In this section we will show how to use Crystal Reports XI with MariaDB and Connector/Net.
Creating a Data Source
When creating a report in Crystal Reports there are two options for accessing the MariaDB data while designing your report.
The first option is to use Connector/ODBC as an ADO data source when designing your report. You will be able to browse your database and choose tables and fields using drag and drop to build your report. The disadvantage of this approach is that additional work must be performed within your application to produce a data set that matches the one expected by your report.
The second option is to create a data set in VB.NET and save it as XML. This XML file can then be used to design a report. This works quite well when displaying the report in your application, but is less versatile at design time because you must choose all relevant columns when creating the data set. If you forget a column you must re-create the data set before the column can be added to the report.
The following code can be used to create a data set from a query and write it to disk:
Visual Basic Example
Dim myData As New DataSet Dim conn As New MySqlConnection Dim cmd As New MySqlCommand Dim myAdapter As New MySqlDataAdapter conn.ConnectionString = 'server=127.0.0.1;' _ & 'uid=root;' _ & 'pwd=12345;' _ & 'database=world' Try conn.Open() cmd.CommandText = 'SELECT city.name AS cityName, city.population AS CityPopulation, ' _ & 'country.name, country.population, country.continent ' _ & 'FROM country, city ORDER BY country.continent, country.name' cmd.Connection = conn myAdapter.SelectCommand = cmd myAdapter.Fill(myData) myData.WriteXml('C:\dataset.xml', XmlWriteMode.WriteSchema) Catch ex As Exception MessageBox.Show(ex.Message, 'Report could not be created', MessageBoxButtons.OK, MessageBoxIcon.Error) End Try
C# Example
DataSet myData = new DataSet(); MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; MySql.Data.MySqlClient.MySqlDataAdapter myAdapter; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); myAdapter = new MySql.Data.MySqlClient.MySqlDataAdapter(); conn.ConnectionString = 'server=127.0.0.1;uid=root;' + 'pwd=12345;database=test;'; try { cmd.CommandText = 'SELECT city.name AS cityName, city.population AS CityPopulation, ' + 'country.name, country.population, country.continent ' + 'FROM country, city ORDER BY country.continent, country.name'; cmd.Connection = conn; myAdapter.SelectCommand = cmd; myAdapter.Fill(myData); myData.WriteXml(@'C:\dataset.xml', XmlWriteMode.WriteSchema); } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show(ex.Message, 'Report could not be created', MessageBoxButtons.OK, MessageBoxIcon.Error); }
The resulting XML file can be used as an ADO.NET XML datasource when designing your report.
If you choose to design your reports using Connector/ODBC, it can be downloaded from dev.mysql.com.
Creating the Report
For most purposes, the Standard Report wizard helps with the initial creation of a report. To start the wizard, open Crystal Reports and choose the New > Standard Report option from the File menu.
The wizard first prompts you for a data source. If you use Connector/ODBC as your data source, use the OLEDB provider for ODBC option from the OLE DB (ADO) tree instead of the ODBC (RDO) tree when choosing a data source. If using a saved data set, choose the ADO.NET (XML) option and browse to your saved data set.
The remainder of the report creation process is done automatically by the wizard.
After the report is created, choose the Report Options... entry of the File menu. Un-check the Save Data With Report option. This prevents saved data from interfering with the loading of data within our application.
Displaying the Report
To display a report we first populate a data set with the data needed for the report, then load the report and bind it to the data set. Finally we pass the report to the crViewer control for display to the user.
The following references are needed in a project that displays a report:
- CrystalDecisions.CrystalReports.Engine
- CrystalDecisions.ReportSource
- CrystalDecisions.Shared
- CrystalDecisions.Windows.Forms
The following code assumes that you created your report using a data set saved using the code shown in , "Creating a Data Source", and have a crViewer control on your form named myViewer
.
Visual Basic Example
Imports CrystalDecisions.CrystalReports.Engine Imports System.Data Imports MySql.Data.MySqlClient Dim myReport As New ReportDocument Dim myData As New DataSet Dim conn As New MySqlConnection Dim cmd As New MySqlCommand Dim myAdapter As New MySqlDataAdapter conn.ConnectionString = _ 'server=127.0.0.1;' _ & 'uid=root;' _ & 'pwd=12345;' _ & 'database=test' Try conn.Open() cmd.CommandText = 'SELECT city.name AS cityName, city.population AS CityPopulation, ' _ & 'country.name, country.population, country.continent ' _ & 'FROM country, city ORDER BY country.continent, country.name' cmd.Connection = conn myAdapter.SelectCommand = cmd myAdapter.Fill(myData) myReport.Load('.\world_report.rpt') myReport.SetDataSource(myData) myViewer.ReportSource = myReport Catch ex As Exception MessageBox.Show(ex.Message, 'Report could not be created', MessageBoxButtons.OK, MessageBoxIcon.Error) End Try
C# Example
using CrystalDecisions.CrystalReports.Engine; using System.Data; using MySql.Data.MySqlClient; ReportDocument myReport = new ReportDocument(); DataSet myData = new DataSet(); MySql.Data.MySqlClient.MySqlConnection conn; MySql.Data.MySqlClient.MySqlCommand cmd; MySql.Data.MySqlClient.MySqlDataAdapter myAdapter; conn = new MySql.Data.MySqlClient.MySqlConnection(); cmd = new MySql.Data.MySqlClient.MySqlCommand(); myAdapter = new MySql.Data.MySqlClient.MySqlDataAdapter(); conn.ConnectionString = 'server=127.0.0.1;uid=root;' + 'pwd=12345;database=test;'; try { cmd.CommandText = 'SELECT city.name AS cityName, city.population AS CityPopulation, ' + 'country.name, country.population, country.continent ' + 'FROM country, city ORDER BY country.continent, country.name'; cmd.Connection = conn; myAdapter.SelectCommand = cmd; myAdapter.Fill(myData); myReport.Load(@'.\world_report.rpt'); myReport.SetDataSource(myData); myViewer.ReportSource = myReport; } catch (MySql.Data.MySqlClient.MySqlException ex) { MessageBox.Show(ex.Message, 'Report could not be created', MessageBoxButtons.OK, MessageBoxIcon.Error); }
A new data set it generated using the same query used to generate the previously saved data set. Once the data set is filled, a ReportDocument is used to load the report file and bind it to the data set. The ReportDocument is the passed as the ReportSource of the crViewer.
This same approach is taken when a report is created from a single table using Connector/ODBC. The data set replaces the table used in the report and the report is displayed properly.
When a report is created from multiple tables using Connector/ODBC, a data set with multiple tables must be created in our application. This enables each table in the report data source to be replaced with a report in the data set.
We populate a data set with multiple tables by providing multiple SELECT
statements in our MySqlCommand object. These SELECT
statements are based on the SQL query shown in Crystal Reports in the Database menu's Show SQL Query option. Assume the following query:
SELECT `country`.`Name`, `country`.`Continent`, `country`.`Population`, `city`.`Name`, `city`.`Population` FROM `world`.`country` `country` LEFT OUTER JOIN `world`.`city` `city` ON `country`.`Code`=`city`.`CountryCode` ORDER BY `country`.`Continent`, `country`.`Name`, `city`.`Name`
This query is converted to two SELECT
queries and displayed with the following code:
Visual Basic Example
Imports CrystalDecisions.CrystalReports.Engine Imports System.Data Imports MySql.Data.MySqlClient Dim myReport As New ReportDocument Dim myData As New DataSet Dim conn As New MySqlConnection Dim cmd As New MySqlCommand Dim myAdapter As New MySqlDataAdapter conn.ConnectionString = 'server=127.0.0.1;' _ & 'uid=root;' _ & 'pwd=12345;' _ & 'database=world' Try conn.Open() cmd.CommandText = 'SELECT name, population, countrycode FROM city ORDER BY countrycode, name; ' _ & 'SELECT name, population, code, continent FROM country ORDER BY continent, name' cmd.Connection = conn myAdapter.SelectCommand = cmd myAdapter.Fill(myData) myReport.Load('.\world_report.rpt') myReport.Database.Tables(0).SetDataSource(myData.Tables(0)) myReport.Database.Tables(1).SetDataSource(myData.Tables(1)) myViewer.ReportSource = myReport Catch ex As Exception MessageBox.Show(ex.Message, 'Report could not be created', MessageBoxButtons.OK, MessageBoxIcon.Error) End Try
C# Example
using CrystalDecisions.CrystalReports.Engine;
using System.Data;
using MySql.Data.MySqlClient;
ReportDocument myReport = new ReportDocument();
DataSet myData = new DataSet();
MySql.Data.MySqlClient.MySqlConnection conn;
MySql.Data.MySqlClient.MySqlCommand cmd;
MySql.Data.MySqlClient.MySqlDataAdapter myAdapter;
conn = new MySql.Data.MySqlClient.MySqlConnection();
cmd = new MySql.Data.MySqlClient.MySqlCommand();
myAdapter = new MySql.Data.MySqlClient.MySqlDataAdapter();
conn.ConnectionString = 'server=127.0.0.1;uid=root;' +
'pwd=12345;database=test;';
try
{
cmd.CommandText = 'SELECT name, population, countrycode FROM city ORDER ' +
'BY countrycode, name; SELECT
name, population, code, continent FROM ' +
'country ORDER BY continent, name';
cmd.Connection = conn;
myAdapter.SelectCommand = cmd;
myAdapter.Fill(myData);
myReport.Load(@'.\world_report.rpt');
myReport.Database.Tables(0).SetDataSource(myData.Tables(0));
myReport.Database.Tables(1).SetDataSource(myData.Tables(1));
myViewer.ReportSource = myReport;
}
catch (MySql.Data.MySqlClient.MySqlException ex)
{
MessageBox.Show(ex.Message, 'Report could not be created',
MessageBoxButtons.OK, MessageBoxIcon.Error);
}
It is important to order the SELECT
queries in alphabetic order, as this is the order the report will expect its source tables to be in. One SetDataSource statement is needed for each table in the report.
This approach can cause performance problems because Crystal Reports must bind the tables together on the client-side, which will be slower than using a pre-saved data set.
ASP.NET Provider Model
MySQL Connector/Net provides support for the ASP.NET 2.0 provider model. This model enables application developers to focus on the business logic of their application instead of having to recreate such boilerplate items as membership and roles support.
MySQL Connector/Net supplies the following providers:
- Membership Provider
- Role Provider
- Profile Provider
- Session State Provider (MySQL Connector/Net 6.1 and later)
The following tables show the supported providers, their default provider and the corresponding MariaDB provider.
Membership Provider
Default Provider | MySQL Provider |
---|---|
System.Web.Security.SqlMembershipProvider | MySql.Web.Security.MySQLMembershipProvider |
Role Provider
Default Provider | MySQL Provider |
---|---|
System.Web.Security.SqlRoleProvider | MySql.Web.Security.MySQLRoleProvider |
Profile Provider
Default Provider | MySQL Provider |
---|---|
System.Web.Profile.SqlProfileProvider | MySql.Web.Profile.MySQLProfileProvider |
SessionState Provider
Default Provider | MySQL Provider |
---|---|
System.Web.SessionState.InProcSessionStateStore | MySql.Web.SessionState.MySqlSessionStateStore |
The MariaDB Session State provider uses slightly different capitalization on the class name compared to the other MariaDB providers.
Installing The Providers
The installation of Connector/Net 5.1 or later will install the providers and register them in your machine's .NET configuration file, machine.config
. The additional entries created will result in the system.web
section appearing similar to the following code:
<system.web> <processModel autoConfig="true" /> <httpHandlers /> <membership> <providers> <add name="AspNetSqlMembershipProvider" type="System.Web.Security.SqlMembershipProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" connectionStringName="LocalSqlServer" enablePasswordRetrieval="false" enablePasswordReset="true" requiresQuestionAndAnswer="true" applicationName="/" requiresUniqueEmail="false" passwordFormat="Hashed" maxInvalidPasswordAttempts="5" minRequiredPasswordLength="7" minRequiredNonalphanumericCharacters='1' passwordAttemptWindow="10" passwordStrengthRegularExpression='' /> <add name="MySQLMembershipProvider" type="MySql.Web.Security.MySQLMembershipProvider, MySql.Web, Version=6.1.1.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d" connectionStringName="LocalMySqlServer" enablePasswordRetrieval="false" enablePasswordReset="true" requiresQuestionAndAnswer="true" applicationName="/" requiresUniqueEmail="false" passwordFormat="Clear" maxInvalidPasswordAttempts="5" minRequiredPasswordLength="7" minRequiredNonalphanumericCharacters='1' passwordAttemptWindow="10" passwordStrengthRegularExpression='' /> </providers> </membership> <profile> <providers> <add name="AspNetSqlProfileProvider" connectionStringName="LocalSqlServer" applicationName="/" type="System.Web.Profile.SqlProfileProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" /> <add name="MySQLProfileProvider" type="MySql.Web.Profile.MySQLProfileProvider, MySql.Web, Version=6.1.1.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d" connectionStringName="LocalMySqlServer" applicationName="/" /> </providers> </profile> <roleManager> <providers> <add name="AspNetSqlRoleProvider" connectionStringName="LocalSqlServer" applicationName="/" type="System.Web.Security.SqlRoleProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" /> <add name="AspNetWindowsTokenRoleProvider" applicationName="/" type="System.Web.Security.WindowsTokenRoleProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" /> <add name="MySQLRoleProvider" type="MySql.Web.Security.MySQLRoleProvider, MySql.Web, Version=6.1.1.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d" connectionStringName="LocalMySqlServer" applicationName="/" /> </providers> </roleManager> </system.web>
Each provider type can have multiple provider implementations. The default provider can also be set here using the defaultProvider
attribute, but usually this is set in the web.config
file either manually or by using the ASP.NET configuration tool.
At time of writing, the MySqlSessionStateStore
is not added to machine.config
at install time, and so add the following:
<sessionState> <providers> <add name="MySqlSessionStateStore" type="MySql.Web.SessionState.MySqlSessionStateStore, MySql.Web, Version=6.1.1.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d" connectionStringName="LocalMySqlServer" applicationName="/" /> </providers> </sessionState>
The SessionState Provider uses the customProvider
attribute, rather than defaultProvider
, to set the provider as the default. A typical web.config
file might contain:
<system.web> <membership defaultProvider="MySQLMembershipProvider" /> <roleManager defaultProvider="MySQLRoleProvider" /> <profile defaultProvider="MySQLProfileProvider" /> <sessionState customProvider="MySqlSessionStateStore" /> <compilation debug="false"> ...
This sets the MariaDB Providers as the defaults to be used in this web application.
The providers are implemented in the file mysql.web.dll
and this file can be found in your MariaDB Connector/Net installation folder. There is no need to run any type of SQL script to set up the database schema, as the providers create and maintain the proper schema automatically.
Using The Providers
The easiest way to start using the providers is to use the ASP.NET configuration tool that is available on the Solution Explorer toolbar when you have a website project loaded.
In the web pages that open, you can select the MariaDB membership and roles providers by picking a custom provider for each area.
When the provider is installed, it creates a dummy connection string named LocalMySqlServer
. Although this has to be done so that the provider will work in the ASP.NET configuration tool, you override this connection string in your web.config
file. You do this by first removing the dummy connection string and then adding in the proper one, as shown in the following example:
<connectionStrings> <remove name="LocalMySqlServer"/> <add name="LocalMySqlServer" connectionString="server=xxx;uid=xxx;pwd=xxx;database=xxx;"/> </connectionStrings>
Note the database to connect to must be specified.
Rather than manually editing configuration files, consider using the MariaDB Website Configuration tool to configure your desired provider setup. From MariaDB Connector/Net 6.1.1 onwards, all providers can be selected and configured from this wizard. The tool modifies your website.config
file to the desired configuration. A tutorial on doing this is available in the following section , "MySQL Website Configuration Tool".
A tutorial demonstrating how to use the Membership and Role Providers can be found in the following section , "Tutorial: MariaDB Connector/Net ASP.NET Membership and Role Provider".
Deployment
To use the providers on a production server, distribute the MySql.Data
and the MySql.Web
assemblies, and either register them in the remote systems Global Assembly Cache or keep them in your application's bin/
directory.
Working with Partial Trust
.NET applications operate under a given trust level. Normal desktop applications operate under full trust, while web applications that are hosted in shared environments are normally run under the partial trust level (also known as "medium trust"). Some hosting providers host shared applications in their own app pools and allow the application to run under full trust, but this configuration is relatively rare. The Connector/Net support for partial trust has improved over time to simplify the configuration and deployment process for hosting providers.
6.5.1 and Above: Full Support for Partial Trust
Connector/Net 6.5 fully enables our provider to run in a partial trust environment when the library is installed in the Global Assembly Cache (GAC). The new MySqlClientPermission
class, derived from the .NET DBDataPermission
class, helps to simplify the permission setup.
Starting from 6.5 you can use the Connector/Net library inside any medium-trust level environment without any issue.
The following list shows steps and code fragments needed to run a Connector/Net application in a partial trust environment. For illustration purposes, we use the Pipe Connections protocol in this example.
- Configure the MariaDB server to accept pipe connections, by adding the
--enable-named-pipe
option on the command line. If you need more information about this, see , "Installing MariaDB on Microsoft Windows". - Confirm that the hosting provider has installed the Connector/Net library (
MySql.Data.dll
) in the GAC. - Optionally, the hosting provider can avoid granting permissions globally by using the new
MySqlClientPermission
class in the trust policies. (The alternative is to globally enable the permissionsSystem.Net.SocketPermission
,System.Security.Permissions.ReflectionPermission
,System.Net.DnsPermission
, andSystem.Security.Permissions.SecurityPermission
.) - Create a simple web application using Visual Studio 2010.
- Add the reference in your application for the
MySql.Data.MySqlClient
library. - Edit your
web.config
file so that your application runs using a Medium trust level:<system.web> <trust level="Medium"/> </system.web>
- Add the
MySql.Data.MySqlClient
namespace to your server-code page. - Define the connection string:
MySqlConnectionStringBuilder myconnString = new MySqlConnectionStringBuilder('server=localhost;User Id=root;database=test;' ); myconnString.PipeName = 'MySQL55'; myconnString.ConnectionProtocol = MySqlConnectionProtocol.Pipe;
- Define the
MySqlConnection
to use:MySqlConnection myconn = new MySqlConnection(myconnString.ConnectionString); myconn.Open();
- Retrieve some data from your tables:
MySqlCommand cmd = new MySqlCommand('Select * from products', myconn); MySqlDataAdapter da = new MySqlDataAdapter(cmd); DataSet1 tds = new DataSet1(); da.Fill(tds, tds.Tables[0].TableName); GridView1.DataSource = tds; GridView1.DataBind(); myconn.Close()
- Run the program. It should execute successfully, without requiring any special code or encountering any security problems.
5.0.8 / 5.1.3 and Above: Partial Trust Requires Socket Permissions
Starting with these versions, Connector/Net can be used under partial trust hosting that has been modified to allow the use of sockets for communication. By default, partial trust does not include SocketPermission
. Connector/Net uses sockets to talk with the MariaDB server so the hosting provider must create a new trust level that is an exact clone of partial trust but that has the following permissions added:
System.Net.SocketPermission
System.Security.Permissions.ReflectionPermission
System.Net.DnsPermission
System.Security.Permissions.SecurityPermission
Prior to 5.0.8 / 5.1.3: Partial Trust Not Supported
Connector/Net versions prior to 5.0.8 and 5.1.3 were not compatible with partial trust hosting.
Connector/Net Connection String Options Reference
For usage information about connection strings, see , "Creating a Connector/Net Connection String". The first table list options that apply generally to all server configurations. The options related to systems using a connection pool are split into a separate table.
General Options
Name | Default | Description |
---|---|---|
Allow Batch , AllowBatch
| true | When true, multiple SQL statements can be sent with one command execution. Note: starting with MariaDB, batch statements should be separated by the server-defined separator character. Commands sent to earlier versions of MariaDB should be separated with ';'. |
Allow User Variables , AllowUserVariables
| false | Setting this to true indicates that the provider expects user variables in the SQL. This option was added in Connector/Net version 5.2.2.
|
Allow Zero Datetime , AllowZeroDateTime
| false | If set to True , MySqlDataReader.GetValue() returns a MySqlDateTime object for date or datetime columns that have disallowed values, such as zero datetime values, and a System.DateTime object for valid values. If set to False (the default setting) it will cause a System.DateTime object to be returned for all legal values and an exception to be thrown for disallowed values, such as zero datetime values.
|
Auto Enlist , AutoEnlist
| true | If AutoEnlist is set to true , which is the default, a connection opened using TransactionScope participates in this scope, it commits when the scope commits and rolls back if TransactionScope does not commit. However, this feature is considered security sensitive and therefore cannot be used in a medium trust environment.
|
BlobAsUTF8ExcludePattern
| null | A POSIX-style regular expression that matches the names of BLOB columns that do not contain UTF-8 character data. See , "Character Set Considerations for Connector/Net" for usage details. |
BlobAsUTF8IncludePattern
| null | A POSIX-style regular expression that matches the names of BLOB columns containing UTF-8 character data. See , "Character Set Considerations for Connector/Net" for usage details. |
Certificate File , CertificateFile
| null | This option specifies the path to a certificate file in PKCS #12 format (.pfx ). For an example of usage, see , "Tutorial: Using SSL with MariaDB Connector/Net". Was introduced with 6.2.1.
|
Certificate Password , CertificatePassword
| null | Specifies a password that is used in conjunction with a certificate specified using the option CertificateFile . For an example of usage, see , "Tutorial: Using SSL with MariaDB Connector/Net". Was introduced with 6.2.1.
|
Certificate Store Location , CertificateStoreLocation
| null | Enables you to access a certificate held in a personal store, rather than use a certificate file and password combination. For an example of usage, see , "Tutorial: Using SSL with MariaDB Connector/Net". Was introduced with 6.2.1. |
Certificate Thumbprint , CertificateThumbprint
| null | Specifies a certificate thumbprint to ensure correct identification of a certificate contained within a personal store. For an example of usage, see , "Tutorial: Using SSL with MariaDB Connector/Net". Was introduced with 6.2.1. |
CharSet , Character Set , CharacterSet
| Specifies the character set that should be used to encode all queries sent to the server. Resultsets are still returned in the character set of the result data. | |
Check Parameters , CheckParameters
| true | Indicates if stored routine parameters should be checked against the server. |
Command Interceptors , CommandInterceptors
| The list of interceptors that can intercept SQL command operations. | |
Connect Timeout , Connection Timeout , ConnectionTimeout
| 15 | The length of time (in seconds) to wait for a connection to the server before terminating the attempt and generating an error. |
Convert Zero Datetime , ConvertZeroDateTime
| false | True to have MySqlDataReader.GetValue() and MySqlDataReader.GetDateTime() return DateTime.MinValue for date or datetime columns that have disallowed values.
|
Default Command Timeout , DefaultCommandTimeout
| 30 | Sets the default value of the command timeout to be used. This does not supercede the individual command timeout property on an individual command object. If you set the command timeout property, that will be used. This option was added in Connector/Net 5.1.4 |
Default Table Cache Age , DefaultTableCacheAge
| 60 | Specifies how long a TableDirect result should be cached, in seconds. For usage information about table caching, see , "Using Connector/Net with Table Caching". This option was added in Connector/Net 6.4.
|
Encrypt , UseSSL
| false | For Connector/Net 5.0.3 and later, when true , SSL encryption is used for all data sent between the client and server if the server has a certificate installed. Recognized values are true , false , yes , and no . In versions before 5.0.3, this option had no effect. From version 6.2.1, this option is deprecated and is replaced by SSL Mode . The option still works if used. If this option is set to true, it is equivalent to SSL Mode = Preferred .
|
Exception Interceptors , ExceptionInterceptors
| The list of interceptors that can triage thrown MySqlException exceptions.
| |
Functions Return String , FunctionsReturnString
| false | Causes the connector to return binary/varbinary values as strings, if they do not have a tablename in the metadata. |
Host , Server , Data Source , DataSource , Address , Addr , Network Address
| localhost | The name or network address of the instance of MariaDB to which to connect. Multiple hosts can be specified separated by commas. This can be useful where multiple MariaDB servers are configured for replication and you are not concerned about the precise server you are connecting to. No attempt is made by the provider to synchronize writes to the database, so take care when using this option. In Unix environment with Mono, this can be a fully qualified path to a MariaDB socket file. With this configuration, the Unix socket will be used instead of the TCP/IP socket. Currently, only a single socket name can be given, so accessing MariaDB in a replicated environment using Unix sockets is not currently supported. |
Ignore Prepare , IgnorePrepare
| true | When true, instructs the provider to ignore any calls to MySqlCommand.Prepare() . This option is provided to prevent issues with corruption of the statements when used with server-side prepared statements. If you use server-side prepare statements, set this option to false. This option was added in Connector/Net 5.0.3 and Connector/Net 1.0.9.
|
Initial Catalog , Database
| mysql | The case-sensitive name of the database to use initially. |
Interactive , Interactive Session , InteractiveSession
| false | If set to true, the client is interactive. An interactive client is one where the server variable CLIENT_INTERACTIVE is set. If an interactive client is set, the wait_timeout variable is set to the value of interactive_timeout . The client will then timeout after this period of inactivity. More details can be found in the server manual , "Server System Variables".
|
Integrated Security , IntegratedSecurity
| no | Use Windows authentication when connecting to server. By default, it is turned off. To enable, specify a value of yes . (You can also use the value sspi as an alternative to yes .) For details, see , "Using the Windows Native Authentication Plugin". This option was introduced in Connector/Net 6.4.4.
|
Keep Alive , Keepalive
| 0 | For TCP connections, idle connection time measured in seconds, before the first keepalive packet is sent. A value of 0 indicates that keepalive is not used. |
Logging
| false | When true, various pieces of information is output to any configured TraceListeners. See , "Using the MariaDB Connector/Net Trace Source Object" for further details. |
Old Guids , OldGuids
| false | This option was introduced in Connector/Net 6.1.1. The backend representation of a GUID type was changed from BINARY(16) to CHAR(36) . This was done to allow developers to use the server function UUID() to populate a GUID table - UUID() generates a 36-character string. Developers of older applications can add 'Old Guids=true' to the connection string to use a GUID of data type BINARY(16) .
|
Old Syntax , OldSyntax , Use Old Syntax , UseOldSyntax
| false | This option was deprecated in Connector/Net 5.2.2. All code should now be written using the '@' symbol as the parameter marker. |
Password , pwd
| The password for the MariaDB account being used. | |
Persist Security Info , PersistSecurityInfo
| false | When set to false or no (strongly recommended), security-sensitive information, such as the password, is not returned as part of the connection if the connection is open or has ever been in an open state. Resetting the connection string resets all connection string values, including the password. Recognized values are true , false , yes , and no .
|
Pipe Name , Pipe , PipeName
| mysql | When set to the name of a named pipe, the MySqlConnection will attempt to connect to MariaDB on that named pipe. This setting only applies to the Windows platform.
|
Port
| 3306 | The port MariaDB is using to listen for connections. This value is ignored if Unix socket is used. |
Procedure Cache Size , ProcedureCacheSize , procedure cache , procedurecache
| 25 | Sets the size of the stored procedure cache. By default, Connector/Net stores the metadata (input/output data types) about the last 25 stored procedures used. To disable the stored procedure cache, set the value to zero (0). This option was added in Connector/Net 5.0.2 and Connector/Net 1.0.9. |
Protocol , Connection Protocol , ConnectionProtocol
| socket | Specifies the type of connection to make to the server. Values can be: socket or tcp for a socket connection, pipe for a named pipe connection, unix for a Unix socket connection, memory to use MariaDB shared memory.
|
Replication
| false | Indicates if this connection is to use replicated servers. |
Respect Binary Flags , RespectBinaryFlags
| true | Setting this option to false means that Connector/Net ignores a column's binary flags as set by the server. This option was added in Connector/Net version 5.1.3.
|
Shared Memory Name , SharedMemoryName
| MYSQL | The name of the shared memory object to use for communication if the connection protocol is set to memory .
|
Sql Server Mode , sqlservermode
| false | Allow SQL Server syntax. When set to true , enables Connector/Net to support square brackets around symbols instead of backticks. This enables Visual Studio wizards that bracket symbols with [] to work with Connector/Net. This option incurs a performance hit, so should only be used if necessary. This option was added in version 6.3.1.
|
SSL Mode , SslMode
| None | This option has the following values:
This option was introduced in MariaDB Connector/Net 6.2.1. |
Table Cache , tablecache , tablecaching
| false | Enables or disables caching of TableDirect commands. A value of true enables the cache while false disables it. For usage information about table caching, see , "Using Connector/Net with Table Caching". This option was added in Connector/Net 6.4.
|
Treat BLOBs as UTF8 , TreatBlobsAsUTF8
| false | |
Treat Tiny As Boolean , TreatTinyAsBoolean
| true | Setting this value to false indicates that TINYINT(1) will be treated as an INT . See , "Numeric Type Overview" for a further explanation of the TINYINT and BOOL data types.
|
Use Affected Rows , UseAffectedRows
| false | When true the connection will report changed rows instead of found rows. This option was added in Connector/Net version 5.2.6.
|
Use Procedure Bodies , UseProcedureBodies , procedure bodies
| true | When set to true , the default value, MariaDB Connector/Net expects the body of the procedure to be viewable. This enables it to determine the parameter types and order. Set the option to false when the user connecting to the database does not have the SELECT privileges for the mysql.proc (stored procedures) table, or cannot view INFORMATION_SCHEMA.ROUTINES . In this case, MariaDB Connector/Net cannot determine the types and order of the parameters, and must be alerted to this fact by setting this option to false . When set to false , MariaDB Connector/Net does not rely on this information being available when the procedure is called. Because MariaDB Connector/Net will not be able to determine this information, explicitly set the types of all the parameters before the call and add the parameters to the command in the same order as they appear in the procedure definition. This option was added in MariaDB Connector/Net 5.0.4 and MariaDB Connector/Net 1.0.10.
|
User Id , UserID , Username , Uid , User name , User
| The MariaDB login account being used. | |
Compress , Use Compression , UseCompression
| false | Setting this option to true enables compression of packets exchanged between the client and the server. This exchange is defined by the MariaDB client/server protocol.
Compression is used if both client and server support ZLIB compression, and the client has requested compression using this option. A compressed packet header is: packet length (3 bytes), packet number (1 byte), and Uncompressed Packet Length (3 bytes). The Uncompressed Packet Length is the number of bytes in the original, uncompressed packet. If this is zero, the data in this packet has not been compressed. When the compression protocol is in use, either the client or the server may compress packets. However, compression will not occur if the compressed length is greater than the original length. Thus, some packets will contain compressed data while other packets will not. |
Use Usage Advisor , Usage Advisor , UseUsageAdvisor
| false | Logs inefficient database operations. |
Use Performance Monitor , UsePerformanceMonitor , userperfmon , perfmon
| false | Indicates that performance counters should be updated during execution. |
Connection Pooling Options
The following table lists the valid names for options related to connection pooling within the ConnectionString
. For more information about connection pooling, see , "Using Connector/Net with Connection Pooling".
Name | Default | Description |
---|---|---|
Cache Server Properties , CacheServerProperties
| false | Specifies whether server variable settings are updated by a SHOW VARIABLES command each time a pooled connection is returned. Enabling this setting speeds up connections in a connection pool environment. Your application will not be informed of any changes to configuration variables made by other connections. This option was added in Connector/Net 6.3.
|
Connection Lifetime , ConnectionLifeTime
| 0 | When a connection is returned to the pool, its creation time is compared with the current time, and the connection is destroyed if that time span (in seconds) exceeds the value specified by Connection Lifetime . This is useful in clustered configurations to force load balancing between a running server and a server just brought online. A value of zero (0) causes pooled connections to have the maximum connection timeout.
|
Connection Reset , ConnectionReset
| false | If true, the connection state will be reset when it is retrieved from the pool. The default value of false avoids making an additional server round trip when obtaining a connection, but the connection state is not reset. |
Maximum Pool Size , Max Pool Size , maximumpoolsize
| 100 | The maximum number of connections allowed in the pool. |
Minimum Pool Size , Min Pool Size , MinimumPoolSize
| 0 | The minimum number of connections allowed in the pool. |
Pooling
| true | When true , the MySqlConnection object is drawn from the appropriate pool, or if necessary, is created and added to the appropriate pool. Recognized values are true , false , yes , and no . |
Connector/Net API Reference
This section of the manual contains a complete reference to the Connector/Net ADO.NET component, automatically generated from the embedded documentation.
MySql.Data.MySqlClient
MySql.Data.MySqlClientHierarchy
BaseCommandInterceptor
BaseExceptionInterceptor
MySqlCommand
ClassMySqlCommandBuilder
ClassMySqlException
ClassMySqlHelper
ClassMySqlErrorCode
Enumeration
Classes
Class | Description |
---|---|
BaseCommandInterceptor | Provides a means of enhancing or replacing SQL commands through the connection string rather than recompiling. |
BaseExceptionInterceptor | Provides a means of enabling and disabling exception handling through the connection string rather than recompiling. |
MySqlClientPermission | Derived from the .NET DBDataPermission class. For usage information, see , "Working with Partial Trust". |
MySqlCommand | |
MySqlCommandBuilder | |
MySqlConnection | |
MySqlDataAdapter | |
MySqlDataReader | Provides a means of reading a forward-only stream of rows from a MariaDB database. This class cannot be inherited. |
MySqlError | Collection of error codes that can be returned by the server |
MySqlException | The exception that is thrown when MariaDB returns an error. This class cannot be inherited. |
MySqlHelper | Helper class that makes it easier to work with the provider. |
MySqlInfoMessageEventArgs | Provides data for the InfoMessage event. This class cannot be inherited. |
MySqlParameter | Represents a parameter to a MySqlCommand, and optionally, its mapping to DataSetcolumns. This class cannot be inherited. |
MySqlParameterCollection | Represents a collection of parameters relevant to a MySqlCommand as well as their respective mappings to columns in a DataSet. This class cannot be inherited. |
MySqlRowUpdatedEventArgs | Provides data for the RowUpdated event. This class cannot be inherited. |
MySqlRowUpdatingEventArgs | Provides data for the RowUpdating event. This class cannot be inherited. |
MySqlTransaction |
Delegates
Delegate | Description |
---|---|
MySqlInfoMessageEventHandler | Represents the method that will handle the InfoMessage event of a MySqlConnection. |
MySqlRowUpdatedEventHandler | Represents the method that will handle the RowUpdatedevent of a MySqlDataAdapter. |
MySqlRowUpdatingEventHandler | Represents the method that will handle the RowUpdatingevent of a MySqlDataAdapter. |
Enumerations
Enumeration | Description |
---|---|
MySqlDbType | Specifies MySQL-specific data type of a field, property, for use in a MySqlParameter. |
MySqlErrorCode |
MySql.Data.MySqlClientHierarchy
See Also
MySql.Data.MySqlClient Namespace
BaseCommandInterceptor
The BaseCommandInterceptor
class has these methods that you can override:
public virtual bool ExecuteScalar(string sql, ref object returnValue); public virtual bool ExecuteNonQuery(string sql, ref int returnValue); public virtual bool ExecuteReader(string sql, CommandBehavior behavior, ref MySqlDataReader returnValue); public virtual void Init(MySqlConnection connection);
If your interceptor overrides one of the Execute...
methods, set the returnValue
output parameter and return true
if you handled the event, or false
if you did not handle the event. The SQL command is processed normally only when all command interceptors return false
.
The connection passed to the Init
method is the connection that is attached to this interceptor.
For full usage and examples, see , "Using the Connector/Net Interceptor Classes".
BaseExceptionInterceptor
You develop an exception interceptor first by creating a subclass of the BaseExceptionInterceptor
class. You must override the InterceptException()
method. You can also override the Init()
method to do some one-time initialization.
Each exception interceptor has 2 methods:
public abstract Exception InterceptException(Exception exception, MySqlConnection connection); public virtual void Init(MySqlConnection connection);
The connection passed to Init()
is the connection that is attached to this interceptor.
Each interceptor is required to override InterceptException
and return an exception. It can return the exception it is given, or it can wrap it in a new exception. We currently do not offer the ability to suppress the exception.
For full usage and examples, see , "Using the Connector/Net Interceptor Classes".
MySqlCommand
Class
For a list of all members of this type, see MySqlCommand Members.
Syntax: Visual Basic
NotInheritable Public Class MySqlCommand_ Inherits Component_ Implements IDbCommand, ICloneable
Syntax: C#
public sealed class MySqlCommand : Component, IDbCommand, ICloneable
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlCommand Members, MySql.Data.MySqlClient Namespace
MySqlCommand
Members
MySqlCommand
Constructor- CommandText Property
- CommandTimeout Property
- CommandType Property
- Connection Property
- IsPrepared Property
- Parameters Property
- Transaction Property
- UpdatedRowSource Property
MySqlCommand.Cancel
MethodMySqlCommand.CreateParameter
MethodMySqlCommand.ExecuteNonQuery
Method- ExecuteReader Method
MySqlCommand.ExecuteScalar
MethodMySqlCommand.Prepare
Method- CommandText Property
Public Instance Constructors
MySqlCommand | Overloaded. Initializes a new instance of the MySqlCommand class. |
Public Instance Properties
CommandText | |
CommandTimeout | |
CommandType | |
Connection | |
Container (inherited from Component) | Gets the IContainer that contains the Component. |
IsPrepared | |
Parameters | |
Site (inherited from Component) | Gets or sets the ISite of the Component. |
Transaction | |
UpdatedRowSource |
Public Instance Methods
Cancel | Attempts to cancel the execution of a MySqlCommand. This operation is not supported. |
CreateObjRef (inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. |
CreateParameter | Creates a new instance of a MySqlParameter object. |
Dispose (inherited from Component) | Releases all resources used by the Component. |
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
ExecuteNonQuery | |
ExecuteReader | Overloaded. |
ExecuteScalar | |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetLifetimeService (inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance. |
GetType (inherited from Object) | Gets the Type of the current instance. |
InitializeLifetimeService (inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance. |
Prepare | |
ToString (inherited from Component) | Returns a String containing the name of the Component, if any. This method should not be overridden. |
Public Instance Events
Disposed (inherited from Component) | Adds an event handler to listen to the Disposed event on the component. |
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
MySqlCommand
Constructor
MySqlCommand
Constructor ()MySqlCommand
Constructor (String)MySqlCommand
ConstructorMySqlCommand
Constructor
Initializes a new instance of the MySqlCommand class.
Overload List
Initializes a new instance of the MySqlCommand class.
- public MySqlCommand();
- public MySqlCommand(string);
- public MySqlCommand(string,MySqlConnection);
- public MySqlCommand(string,MySqlConnection,MySqlTransaction);
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
MySqlCommand
Constructor ()
Initializes a new instance of the MySqlCommand class.
Syntax: Visual Basic
Overloads Public Sub New()
Syntax: C#
public MySqlCommand();
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace, MySqlCommand Constructor Overload List
MySqlCommand
Constructor (String)
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal cmdText As String _ )
Syntax: C#
public MySqlCommand( stringcmdText );
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace, MySqlCommand Constructor Overload List
MySqlCommand
Constructor
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal cmdText As String, _ ByVal connection As MySqlConnection _ )
Syntax: C#
public MySqlCommand( stringcmdText, MySqlConnectionconnection );
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace, MySqlCommand Constructor Overload List
MySqlConnection
Class
For a list of all members of this type, see MySqlConnection Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlConnection_ Inherits Component_ Implements IDbConnection, ICloneable
Syntax: C#
public sealed class MySqlConnection : Component, IDbConnection, ICloneable
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlConnection Members, MySql.Data.MySqlClient Namespace
MySqlConnection
Members
Public Instance Constructors
MySqlConnection | Overloaded. Initializes a new instance of the MySqlConnection class. |
Public Instance Properties
ConnectionString | |
ConnectionTimeout | |
Container (inherited from Component) | Gets the IContainer that contains the Component. |
Database | |
DataSource | Gets the name of the MariaDB server to which to connect. |
ServerThread | Returns the ID of the server thread this connection is executing on. |
ServerVersion | |
Site (inherited from Component) | Gets or sets the ISite of the Component. |
State | |
UseCompression | Indicates if this connection should use compression when communicating with the server. |
Public Instance Methods
BeginTransaction | Overloaded. |
ChangeDatabase | |
Close | |
CreateCommand | |
CreateObjRef (inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. |
Dispose (inherited from Component) | Releases all resources used by the Component. |
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetLifetimeService (inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance. |
GetType (inherited from Object) | Gets the Type of the current instance. |
InitializeLifetimeService (inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance. |
Open | |
Ping | Ping |
ToString (inherited from Component) | Returns a String containing the name of the Component, if any. This method should not be overridden. |
Public Instance Events
Disposed (inherited from Component) | Adds an event handler to listen to the Disposed event on the component. |
InfoMessage | |
StateChange |
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
MySqlConnection
Constructor
Initializes a new instance of the MySqlConnection class.
Overload List
Initializes a new instance of the MySqlConnection class.
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
MySqlConnection
Constructor
Initializes a new instance of the MySqlConnection class.
Syntax: Visual Basic
Overloads Public Sub New()
Syntax: C#
public MySqlConnection();
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace, MySqlConnection Constructor Overload List
MySqlConnection
Constructor
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal connectionString As String _ )
Syntax: C#
public MySqlConnection( stringconnectionString );
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace, MySqlConnection Constructor Overload List
ConnectionString Property
Syntax: Visual Basic
NotOverridable Public Property ConnectionString As String _ _ Implements IDbConnection.ConnectionString
Syntax: C#
public string ConnectionString {get; set;}
Implements
IDbConnection.ConnectionString
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
ConnectionTimeout Property
Syntax: Visual Basic
NotOverridable Public ReadOnly Property ConnectionTimeout As Integer _ _ Implements IDbConnection.ConnectionTimeout
Syntax: C#
public int ConnectionTimeout {get;}
Implements
IDbConnection.ConnectionTimeout
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
Database Property
Syntax: Visual Basic
NotOverridable Public ReadOnly Property Database As String _ _ Implements IDbConnection.Database
Syntax: C#
public string Database {get;}
Implements
IDbConnection.Database
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
DataSource Property
Gets the name of the MariaDB server to which to connect.
Syntax: Visual Basic
Public ReadOnly Property DataSource As String
Syntax: C#
public string DataSource {get;}
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
ServerThread Property
Returns the ID of the server thread this connection is executing on
Syntax: Visual Basic
Public ReadOnly Property ServerThread As Integer
Syntax: C#
public int ServerThread {get;}
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
ServerVersion Property
Syntax: Visual Basic
Public ReadOnly Property ServerVersion As String
Syntax: C#
public string ServerVersion {get;}
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
State Property
Syntax: Visual Basic
NotOverridable Public ReadOnly Property State As ConnectionState _ _ Implements IDbConnection.State
Syntax: C#
public System.Data.ConnectionState State {get;}
Implements
IDbConnection.State
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
UseCompression Property
Indicates if this connection should use compression when communicating with the server.
Syntax: Visual Basic
Public ReadOnly Property UseCompression As Boolean
Syntax: C#
public bool UseCompression {get;}
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
BeginTransaction Method
Overload List
- public MySqlTransaction BeginTransaction();
- public MySqlTransaction BeginTransaction(IsolationLevel);
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
MySqlConnection.BeginTransaction
Method
Syntax: Visual Basic
Overloads Public Function BeginTransaction() As MySqlTransaction
Syntax: C#
public MySqlTransaction BeginTransaction();
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace, MySqlConnection.BeginTransaction Overload List
MySqlTransaction
Class
For a list of all members of this type, see MySqlTransaction Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlTransaction_ Implements IDbTransaction, IDisposable
Syntax: C#
public sealed class MySqlTransaction : IDbTransaction, IDisposable
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlTransaction Members, MySql.Data.MySqlClient Namespace
MySqlTransaction
Members
Public Instance Properties
Connection | Gets the MySqlConnection object associated with the transaction, or a null reference (Nothing in Visual Basic) if the transaction is no longer valid. |
IsolationLevel | Specifies the IsolationLevel for this transaction. |
Public Instance Methods
Commit | |
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetType (inherited from Object) | Gets the Type of the current instance. |
Rollback | |
ToString (inherited from Object) | Returns a String that represents the current Object. |
See Also
MySqlTransaction Class, MySql.Data.MySqlClient Namespace
Connection Property
Gets the MySqlConnection object associated with the transaction, or a null reference (Nothing in Visual Basic) if the transaction is no longer valid.
Syntax: Visual Basic
Public ReadOnly Property Connection As MySqlConnection
Syntax: C#
public MySqlConnection Connection {get;}
Property Value
The MySqlConnection object associated with this transaction.
Remarks
A single application may have multiple database connections, each with zero or more transactions. This property enables you to determine the connection object associated with a particular transaction created by BeginTransaction.
See Also
MySqlTransaction Class, MySql.Data.MySqlClient Namespace
IsolationLevel Property
Specifies the IsolationLevel for this transaction.
Syntax: Visual Basic
NotOverridable Public ReadOnly Property IsolationLevel As IsolationLevel _ _ Implements IDbTransaction.IsolationLevel
Syntax: C#
public System.Data.IsolationLevel IsolationLevel {get;}
Property Value
The IsolationLevel for this transaction. The default is ReadCommitted.
Implements
IDbTransaction.IsolationLevel
Remarks
Parallel transactions are not supported. Therefore, the IsolationLevel applies to the entire transaction.
See Also
MySqlTransaction Class, MySql.Data.MySqlClient Namespace
MySqlTransaction.Commit
Method
Syntax: Visual Basic
NotOverridable Public Sub Commit() _ _ Implements IDbTransaction.Commit
Syntax: C#
public void Commit();
Implements
IDbTransaction.Commit
See Also
MySqlTransaction Class, MySql.Data.MySqlClient Namespace
MySqlTransaction.Rollback
Method
Syntax: Visual Basic
NotOverridable Public Sub Rollback() _ _ Implements IDbTransaction.Rollback
Syntax: C#
public void Rollback();
Implements
IDbTransaction.Rollback
See Also
MySqlTransaction Class, MySql.Data.MySqlClient Namespace
MySqlConnection.BeginTransaction
Method
Syntax: Visual Basic
Overloads Public Function BeginTransaction( _ ByVal iso As IsolationLevel _ ) As MySqlTransaction
Syntax: C#
public MySqlTransaction BeginTransaction( IsolationLeveliso );
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace, MySqlConnection.BeginTransaction Overload List
MySqlConnection.ChangeDatabase
Method
Syntax: Visual Basic
NotOverridable Public Sub ChangeDatabase( _ ByVal databaseName As String _ ) _ _ Implements IDbConnection.ChangeDatabase
Syntax: C#
public void ChangeDatabase( stringdatabaseName );
Implements
IDbConnection.ChangeDatabase
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
MySqlConnection.Close
Method
Syntax: Visual Basic
NotOverridable Public Sub Close() _ _ Implements IDbConnection.Close
Syntax: C#
public void Close();
Implements
IDbConnection.Close
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
MySqlConnection.CreateCommand
Method
Syntax: Visual Basic
Public Function CreateCommand() As MySqlCommand
Syntax: C#
public MySqlCommand CreateCommand();
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
MySqlConnection.Open
Method
Syntax: Visual Basic
NotOverridable Public Sub Open() _ _ Implements IDbConnection.Open
Syntax: C#
public void Open();
Implements
IDbConnection.Open
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
MySqlConnection.Ping
Method
Ping
Syntax: Visual Basic
Public Function Ping() As Boolean
Syntax: C#
public bool Ping();
Return Value
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
MySqlConnection.InfoMessage
Event
Syntax: Visual Basic
Public Event InfoMessage As MySqlInfoMessageEventHandler
Syntax: C#
public event MySqlInfoMessageEventHandler InfoMessage;
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
MySqlInfoMessageEventHandler
Delegate
Represents the method that will handle the InfoMessage event of a MySqlConnection.
Syntax: Visual Basic
Public Delegate Sub MySqlInfoMessageEventHandler( _ ByVal sender As Object, _ ByVal args As MySqlInfoMessageEventArgs _ )
Syntax: C#
public delegate void MySqlInfoMessageEventHandler( objectsender, MySqlInfoMessageEventArgsargs );
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySql.Data.MySqlClient Namespace
MySqlInfoMessageEventArgs
Class
Provides data for the InfoMessage event. This class cannot be inherited.
For a list of all members of this type, see MySqlInfoMessageEventArgs Members .
Syntax: Visual Basic
Public Class MySqlInfoMessageEventArgs_ Inherits EventArgs
Syntax: C#
public class MySqlInfoMessageEventArgs : EventArgs
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlInfoMessageEventArgs Members, MySql.Data.MySqlClient Namespace
MySqlInfoMessageEventArgs
Members
MySqlInfoMessageEventArgs overview
Public Instance Constructors
MySqlInfoMessageEventArgs Constructor | Initializes a new instance of the MySqlInfoMessageEventArgs class. |
Public Instance Fields
errors |
Public Instance Methods
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetType (inherited from Object) | Gets the Type of the current instance. |
ToString (inherited from Object) | Returns a String that represents the current Object. |
Protected Instance Methods
Finalize (inherited from Object) | Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. |
MemberwiseClone (inherited from Object) | Creates a shallow copy of the current Object. |
See Also
MySqlInfoMessageEventArgs Class, MySql.Data.MySqlClient Namespace
MySqlInfoMessageEventArgs
Constructor
Initializes a new instance of the MySqlInfoMessageEventArgs class.
Syntax: Visual Basic
Public Sub New()
Syntax: C#
public MySqlInfoMessageEventArgs();
See Also
MySqlInfoMessageEventArgs Class, MySql.Data.MySqlClient Namespace
MySqlInfoMessageEventArgs.errors
Field
Syntax: Visual Basic
Public errors As MySqlError()
Syntax: C#
public MySqlError[] errors;
See Also
MySqlInfoMessageEventArgs Class, MySql.Data.MySqlClient Namespace
MySqlError
Class
Collection of error codes that can be returned by the server
For a list of all members of this type, see MySqlError Members .
Syntax: Visual Basic
Public Class MySqlError
Syntax: C#
public class MySqlError
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlError Members, MySql.Data.MySqlClient Namespace
MySqlError
Members
Public Instance Constructors
MySqlError Constructor |
Public Instance Properties
Code | Error code |
Level | Error level |
Message | Error message |
Public Instance Methods
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetType (inherited from Object) | Gets the Type of the current instance. |
ToString (inherited from Object) | Returns a String that represents the current Object. |
Protected Instance Methods
Finalize (inherited from Object) | Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. |
MemberwiseClone (inherited from Object) | Creates a shallow copy of the current Object. |
See Also
MySqlError Class, MySql.Data.MySqlClient Namespace
MySqlError
Constructor
Syntax: Visual Basic
Public Sub New( _ ByVal level As String, _ ByVal code As Integer, _ ByVal message As String _ )
Syntax: C#
public MySqlError( stringlevel, intcode, stringmessage );
Parameters
level
:code
:message
:
See Also
MySqlError Class, MySql.Data.MySqlClient Namespace
Code Property
Error code
Syntax: Visual Basic
Public ReadOnly Property Code As Integer
Syntax: C#
public int Code {get;}
See Also
MySqlError Class, MySql.Data.MySqlClient Namespace
Level Property
Error level
Syntax: Visual Basic
Public ReadOnly Property Level As String
Syntax: C#
public string Level {get;}
See Also
MySqlError Class, MySql.Data.MySqlClient Namespace
Message Property
Error message
Syntax: Visual Basic
Public ReadOnly Property Message As String
Syntax: C#
public string Message {get;}
See Also
MySqlError Class, MySql.Data.MySqlClient Namespace
MySqlConnection.StateChange
Event
Syntax: Visual Basic
Public Event StateChange As StateChangeEventHandler
Syntax: C#
public event StateChangeEventHandler StateChange;
See Also
MySqlConnection Class, MySql.Data.MySqlClient Namespace
MySqlCommand
Constructor
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal cmdText As String, _ ByVal connection As MySqlConnection, _ ByVal transaction As MySqlTransaction _ )
Syntax: C#
public MySqlCommand( stringcmdText, MySqlConnectionconnection, MySqlTransactiontransaction );
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace, MySqlCommand Constructor Overload List
CommandText Property
Syntax: Visual Basic
NotOverridable Public Property CommandText As String _ _ Implements IDbCommand.CommandText
Syntax: C#
public string CommandText {get; set;}
Implements
IDbCommand.CommandText
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
CommandTimeout Property
Syntax: Visual Basic
NotOverridable Public Property CommandTimeout As Integer _ _ Implements IDbCommand.CommandTimeout
Syntax: C#
public int CommandTimeout {get; set;}
Implements
IDbCommand.CommandTimeout
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
CommandType Property
Syntax: Visual Basic
NotOverridable Public Property CommandType As CommandType _ _ Implements IDbCommand.CommandType
Syntax: C#
public System.Data.CommandType CommandType {get; set;}
Implements
IDbCommand.CommandType
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
Connection Property
Syntax: Visual Basic
Public Property Connection As MySqlConnection
Syntax: C#
public MySqlConnection Connection {get; set;}
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
IsPrepared Property
Syntax: Visual Basic
Public ReadOnly Property IsPrepared As Boolean
Syntax: C#
public bool IsPrepared {get;}
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
Parameters Property
Syntax: Visual Basic
Public ReadOnly Property Parameters As MySqlParameterCollection
Syntax: C#
public MySqlParameterCollection Parameters {get;}
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
MySqlParameterCollection
Class
Represents a collection of parameters relevant to a MySqlCommand as well as their respective mappings to columns in a DataSet. This class cannot be inherited.
For a list of all members of this type, see MySqlParameterCollection Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlParameterCollection_ Inherits MarshalByRefObject_ Implements IDataParameterCollection, IList, ICollection, IEnumerable
Syntax: C#
public sealed class MySqlParameterCollection : MarshalByRefObject, IDataParameterCollection, IList, ICollection, IEnumerable
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlParameterCollection Members, MySql.Data.MySqlClient Namespace
MySqlParameterCollection
Members
MySqlParameterCollection
Constructor- Count Property
- Item Property
- Add Method
MySqlParameterCollection.Clear
Method- Contains Method
MySqlParameterCollection.CopyTo
Method- IndexOf Method
MySqlParameterCollection.Insert
MethodMySqlParameterCollection.Remove
Method- RemoveAt Method
- Count Property
MySqlParameterCollection overview
Public Instance Constructors
MySqlParameterCollection Constructor | Initializes a new instance of the MySqlParameterCollection class. |
Public Instance Properties
Count | Gets the number of MySqlParameter objects in the collection. |
Item | Overloaded. Gets the MySqlParameter with a specified attribute. In C#, this property is the indexer for the MySqlParameterCollection class. |
Public Instance Methods
Add | Overloaded. Adds the specified MySqlParameter object to the MySqlParameterCollection. |
Clear | Removes all items from the collection. |
Contains | Overloaded. Gets a value indicating whether a MySqlParameter exists in the collection. |
CopyTo | Copies MySqlParameter objects from the MySqlParameterCollection to the specified array. |
CreateObjRef (inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. |
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetLifetimeService (inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance. |
GetType (inherited from Object) | Gets the Type of the current instance. |
IndexOf | Overloaded. Gets the location of a MySqlParameter in the collection. |
InitializeLifetimeService (inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance. |
Insert | Inserts a MySqlParameter into the collection at the specified index. |
Remove | Removes the specified MySqlParameter from the collection. |
RemoveAt | Overloaded. Removes the specified MySqlParameter from the collection. |
ToString (inherited from Object) | Returns a String that represents the current Object. |
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
MySqlParameterCollection
Constructor
Initializes a new instance of the MySqlParameterCollection class.
Syntax: Visual Basic
Public Sub New()
Syntax: C#
public MySqlParameterCollection();
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
Count Property
Gets the number of MySqlParameter objects in the collection.
Syntax: Visual Basic
NotOverridable Public ReadOnly Property Count As Integer _ _ Implements ICollection.Count
Syntax: C#
public int Count {get;}
Implements
ICollection.Count
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
Item Property
Gets the MySqlParameter with a specified attribute. In C#, this property is the indexer for the MySqlParameterCollection class.
Overload List
Gets the MySqlParameter at the specified index.
Gets the MySqlParameter with the specified name.
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
MySqlParameter
Class
Represents a parameter to a MySqlCommand, and optionally, its mapping to DataSetcolumns. This class cannot be inherited.
For a list of all members of this type, see MySqlParameter Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlParameter_ Inherits MarshalByRefObject_ Implements IDataParameter, IDbDataParameter, ICloneable
Syntax: C#
public sealed class MySqlParameter : MarshalByRefObject, IDataParameter, IDbDataParameter, ICloneable
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlParameter Members, MySql.Data.MySqlClient Namespace
MySqlParameter
Members
Public Instance Constructors
MySqlParameter | Overloaded. Initializes a new instance of the MySqlParameter class. |
Public Instance Properties
DbType | Gets or sets the DbType of the parameter. |
Direction | Gets or sets a value indicating whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter. As of MariaDB version 4.1 and earlier, input-only is the only valid choice. |
IsNullable | Gets or sets a value indicating whether the parameter accepts null values. |
IsUnsigned | |
MySqlDbType | Gets or sets the MySqlDbType of the parameter. |
ParameterName | Gets or sets the name of the MySqlParameter. |
Precision | Gets or sets the maximum number of digits used to represent the Value property. |
Scale | Gets or sets the number of decimal places to which Value is resolved. |
Size | Gets or sets the maximum size, in bytes, of the data within the column. |
SourceColumn | Gets or sets the name of the source column that is mapped to the DataSetand used for loading or returning the Value. |
SourceVersion | Gets or sets the DataRowVersion to use when loading Value. |
Value | Gets or sets the value of the parameter. |
Public Instance Methods
CreateObjRef (inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. |
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetLifetimeService (inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance. |
GetType (inherited from Object) | Gets the Type of the current instance. |
InitializeLifetimeService (inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance. |
ToString | Overridden. Gets a string containing the ParameterName. |
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
MySqlParameter
Constructor
Initializes a new instance of the MySqlParameter class.
Overload List
Initializes a new instance of the MySqlParameter class.
Initializes a new instance of the MySqlParameter class with the parameter name and the data type.
Initializes a new instance of the MySqlParameter class with the parameter name, the MySqlDbType, and the size.
Initializes a new instance of the MySqlParameter class with the parameter name, the type of the parameter, the size of the parameter, a ParameterDirection, the precision of the parameter, the scale of the parameter, the source column, a DataRowVersion to use, and the value of the parameter.
Initializes a new instance of the MySqlParameter class with the parameter name, the MySqlDbType, the size, and the source column name.
Initializes a new instance of the MySqlParameter class with the parameter name and a value of the new MySqlParameter.
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
MySqlParameter
Constructor ()
Initializes a new instance of the MySqlParameter class.
Syntax: Visual Basic
Overloads Public Sub New()
Syntax: C#
public MySqlParameter();
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace, MySqlParameter Constructor Overload List
MySqlParameter
Constructor
Initializes a new instance of the MySqlParameter class with the parameter name and the data type.
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType _ )
Syntax: C#
public MySqlParameter( stringparameterName, MySqlDbTypedbType );
Parameters
parameterName
: The name of the parameter to map.dbType
: One of the MySqlDbType values.
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace, MySqlParameter Constructor Overload List
MySqlDbType
Enumeration
Specifies MySQL-specific data type of a field, property, for use in a MySqlParameter.
Syntax: Visual Basic
Public Enum MySqlDbType
Syntax: C#
public enum MySqlDbType
Members
Member Name | Description |
Newdate | Obsolete. Use Datetime or Date type. |
Timestamp | A timestamp. The range is '1970-01-01 00:00:01.000000' to '2038-01-19 03:14:07.999999'. (Fractional seconds can only be stored with a MariaDB 5.6.4 or higher database server.) |
Time | The range is '-838:59:59.000000' to '838:59:59.000000'. (Fractional seconds can only be stored with a MariaDB 5.6.4 or higher database server.) |
Date | The supported range is '1000-01-01' to '9999-12-31'. |
Datetime | The supported range is '1000-01-01 00:00:00.000000' to '9999-12-31 23:59:59.999999'. (Fractional seconds can only be stored with a MariaDB 5.6.4 or higher database server.) |
Year | A year in 2- or 4-digit format (default is 4-digit). The allowable values are 1901 to 2155, 0000 in the 4-digit year format, and 1970-2069 if you use the 2-digit format (70-69). |
TinyBlob | A BLOB column with a maximum length of 255 (2^8 - 1) characters. |
Blob | A BLOB column with a maximum length of 65535 (2^16 - 1) characters. |
MediumBlob | A BLOB column with a maximum length of 16777215 (2^24 - 1) characters. |
LongBlob | A BLOB column with a maximum length of 4294967295 or 4G (2^32 - 1) characters. |
Int16 | A 16-bit signed integer. The signed range is -32768 to 32767. The unsigned range is 0 to 65535. |
Int24 | Specifies a 24 (3 byte) signed or unsigned value. |
Int32 | A 32-bit signed integer. |
Int64 | A 64-bit signed integer. |
Byte | The signed range is -128 to 127. The unsigned range is 0 to 255. |
Float | A small (single-precision) floating-point number. Allowable values are -3.402823466E+38 to -1.175494351E-38, 0, and 1.175494351E-38 to 3.402823466E+38. |
Double | A normal-size (double-precision) floating-point number. Allowable values are -1.7976931348623157E+308 to -2.2250738585072014E-308, 0, and 2.2250738585072014E-308 to 1.7976931348623157E+308. |
UByte | An 8-bit unsigned value. |
UInt16 | A 16-bit unsigned value. |
UInt24 | A 24-bit unsigned value. |
UInt32 | A 32-bit unsigned value. |
UInt64 | A 64-bit unsigned value. |
Decimal | A fixed precision and scale numeric value between -10^38-1 and 10^38-1. |
NewDecimal | New Decimal |
Set | A set. A string object that can have zero or more values, each of which must be chosen from the list of values 'value1', 'value2', ... A SET can have a maximum of 64 members. |
String | Obsolete. Use VarChar type. |
VarChar | A variable-length string containing 0 to 255 characters. |
VarString | A variable-length string containing 0 to 65535 characters. |
Enum | An enumeration. A string object that can have only one value, chosen from the list of values 'value1', 'value2', ..., NULL or the special '' error value. An ENUM can have a maximum of 65535 distinct values. |
Geometry | |
Bit | Bit-field data type. |
TinyText | A nonbinary string column supporting a maximum length of 255 (2^8 - 1) characters. |
Text | A nonbinary string column supporting a maximum length of 65535 (2^16 - 1) characters. |
MediumText | A nonbinary string column supporting a maximum length of 16777215 (2^24 - 1) characters. |
LongText | A nonbinary string column supporting a maximum length of 4294967295 (2^32 - 1) characters. |
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySql.Data.MySqlClient Namespace
MySqlParameter
Constructor (String, MySqlDbType, Int32)
Initializes a new instance of the MySqlParameter class with the parameter name, the MySqlDbType, and the size.
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType, _ ByVal size As Integer _ )
Syntax: C#
public MySqlParameter( stringparameterName, MySqlDbTypedbType, intsize );
Parameters
parameterName
: The name of the parameter to map.dbType
: One of the MySqlDbType values.size
: The length of the parameter.
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace, MySqlParameter Constructor Overload List
MySqlParameter
Constructor
Initializes a new instance of the MySqlParameter class with the parameter name, the type of the parameter, the size of the parameter, a ParameterDirection, the precision of the parameter, the scale of the parameter, the source column, a DataRowVersion to use, and the value of the parameter.
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType, _ ByVal size As Integer, _ ByVal direction As ParameterDirection, _ ByVal isNullable As Boolean, _ ByVal precision As Byte, _ ByVal scale As Byte, _ ByVal sourceColumn As String, _ ByVal sourceVersion As DataRowVersion, _ ByVal value As Object _ )
Syntax: C#
public MySqlParameter( stringparameterName, MySqlDbTypedbType, intsize, ParameterDirectiondirection, boolisNullable, byteprecision, bytescale, stringsourceColumn, DataRowVersionsourceVersion, objectvalue );
Parameters
parameterName
: The name of the parameter to map.dbType
: One of the MySqlDbType values.size
: The length of the parameter.direction
: One of the ParameterDirectionvalues.isNullable
: true if the value of the field can be null, otherwise false.precision
: The total number of digits to the left and right of the decimal point to which Value is resolved.scale
: The total number of decimal places to which Value is resolved.sourceColumn
: The name of the source column.sourceVersion
: One of the DataRowVersionvalues.value
: An Object that is the value of the MySqlParameter.
Exceptions
Exception Type | Condition |
ArgumentException |
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace, MySqlParameter Constructor Overload List
Value Property
Gets or sets the value of the parameter.
Syntax: Visual Basic
NotOverridable Public Property Value As Object _ _ Implements IDataParameter.Value
Syntax: C#
public object Value {get; set;}
Implements
IDataParameter.Value
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
MySqlParameter
Constructor
Initializes a new instance of the MySqlParameter class with the parameter name, the MySqlDbType, the size, and the source column name.
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType, _ ByVal size As Integer, _ ByVal sourceColumn As String _ )
Syntax: C#
public MySqlParameter( stringparameterName, MySqlDbTypedbType, intsize, stringsourceColumn );
Parameters
parameterName
: The name of the parameter to map.dbType
: One of the MySqlDbType values.size
: The length of the parameter.sourceColumn
: The name of the source column.
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace, MySqlParameter Constructor Overload List
MySqlParameter
Constructor
Initializes a new instance of the MySqlParameter class with the parameter name and a value of the new MySqlParameter.
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal parameterName As String, _ ByVal value As Object _ )
Syntax: C#
public MySqlParameter( stringparameterName, objectvalue );
Parameters
parameterName
: The name of the parameter to map.value
: An Object that is the value of the MySqlParameter.
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace, MySqlParameter Constructor Overload List
DbType Property
Gets or sets the DbType of the parameter.
Syntax: Visual Basic
NotOverridable Public Property DbType As DbType _ _ Implements IDataParameter.DbType
Syntax: C#
public System.Data.DbType DbType {get; set;}
Implements
IDataParameter.DbType
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
Direction Property
Gets or sets a value indicating whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter. As of MariaDB version 4.1 and earlier, input-only is the only valid choice.
Syntax: Visual Basic
NotOverridable Public Property Direction As ParameterDirection _ _ Implements IDataParameter.Direction
Syntax: C#
public System.Data.ParameterDirection Direction {get; set;}
Implements
IDataParameter.Direction
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
IsNullable Property
Gets or sets a value indicating whether the parameter accepts null values.
Syntax: Visual Basic
NotOverridable Public Property IsNullable As Boolean _ _ Implements IDataParameter.IsNullable
Syntax: C#
public bool IsNullable {get; set;}
Implements
IDataParameter.IsNullable
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
IsUnsigned Property
Syntax: Visual Basic
Public Property IsUnsigned As Boolean
Syntax: C#
public bool IsUnsigned {get; set;}
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
MySqlDbType
Property
Gets or sets the MySqlDbType of the parameter.
Syntax: Visual Basic
Public Property MySqlDbType As MySqlDbType
Syntax: C#
public MySqlDbType MySqlDbType {get; set;}
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
ParameterName Property
Gets or sets the name of the MySqlParameter.
Syntax: Visual Basic
NotOverridable Public Property ParameterName As String _ _ Implements IDataParameter.ParameterName
Syntax: C#
public string ParameterName {get; set;}
Implements
IDataParameter.ParameterName
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
Precision Property
Gets or sets the maximum number of digits used to represent the Value property.
Syntax: Visual Basic
NotOverridable Public Property Precision As Byte _ _ Implements IDbDataParameter.Precision
Syntax: C#
public byte Precision {get; set;}
Implements
IDbDataParameter.Precision
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
Scale Property
Gets or sets the number of decimal places to which Value is resolved.
Syntax: Visual Basic
NotOverridable Public Property Scale As Byte _ _ Implements IDbDataParameter.Scale
Syntax: C#
public byte Scale {get; set;}
Implements
IDbDataParameter.Scale
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
Size Property
Gets or sets the maximum size, in bytes, of the data within the column.
Syntax: Visual Basic
NotOverridable Public Property Size As Integer _ _ Implements IDbDataParameter.Size
Syntax: C#
public int Size {get; set;}
Implements
IDbDataParameter.Size
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
SourceColumn Property
Gets or sets the name of the source column that is mapped to the DataSetand used for loading or returning the Value.
Syntax: Visual Basic
NotOverridable Public Property SourceColumn As String _ _ Implements IDataParameter.SourceColumn
Syntax: C#
public string SourceColumn {get; set;}
Implements
IDataParameter.SourceColumn
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
SourceVersion Property
Gets or sets the DataRowVersion to use when loading Value.
Syntax: Visual Basic
NotOverridable Public Property SourceVersion As DataRowVersion _ _ Implements IDataParameter.SourceVersion
Syntax: C#
public System.Data.DataRowVersion SourceVersion {get; set;}
Implements
IDataParameter.SourceVersion
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
MySqlParameter.ToString
Method
Overridden. Gets a string containing the ParameterName.
Syntax: Visual Basic
Overrides Public Function ToString() As String
Syntax: C#
public override string ToString();
Return Value
See Also
MySqlParameter Class, MySql.Data.MySqlClient Namespace
Item Property (Int32)
Gets the MySqlParameter at the specified index.
Syntax: Visual Basic
Overloads Public Default Property Item( _ ByVal index As Integer _ ) As MySqlParameter
Syntax: C#
public MySqlParameter this[ intindex ] {get; set;}
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.Item Overload List
Item Property (String)
Gets the MySqlParameter with the specified name.
Syntax: Visual Basic
Overloads Public Default Property Item( _ ByVal name As String _ ) As MySqlParameter
Syntax: C#
public MySqlParameter this[ stringname ] {get; set;}
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.Item Overload List
Add Method
Adds the specified MySqlParameter object to the MySqlParameterCollection.
Overload List
Adds the specified MySqlParameter object to the MySqlParameterCollection.
Adds the specified MySqlParameter object to the MySqlParameterCollection.
Adds a MySqlParameter to the MySqlParameterCollection given the parameter name and the data type.
Adds a MySqlParameter to the MySqlParameterCollection with the parameter name, the data type, and the column length.
Adds a MySqlParameter to the MySqlParameterCollection with the parameter name, the data type, the column length, and the source column name.
Adds a MySqlParameter to the MySqlParameterCollection given the specified parameter name and value.
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
MySqlParameterCollection.Add
Method
Adds the specified MySqlParameter object to the MySqlParameterCollection.
Syntax: Visual Basic
Overloads Public Function Add( _ ByVal value As MySqlParameter _ ) As MySqlParameter
Syntax: C#
public MySqlParameter Add( MySqlParametervalue );
Parameters
value
: The MySqlParameter to add to the collection.
Return Value
The newly added MySqlParameter object.
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.Add Overload List
MySqlParameterCollection.Add
Method
Adds the specified MySqlParameter object to the MySqlParameterCollection.
Syntax: Visual Basic
NotOverridable Overloads Public Function Add( _ ByVal value As Object _ ) As Integer _ _ Implements IList.Add
Syntax: C#
public int Add( objectvalue );
Parameters
value
: The MySqlParameter to add to the collection.
Return Value
The index of the new MySqlParameter object.
Implements
IList.Add
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.Add Overload List
MySqlParameterCollection.Add
Method
Adds a MySqlParameter to the MySqlParameterCollection given the parameter name and the data type.
Syntax: Visual Basic
Overloads Public Function Add( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType _ ) As MySqlParameter
Syntax: C#
public MySqlParameter Add( stringparameterName, MySqlDbTypedbType );
Parameters
parameterName
: The name of the parameter.dbType
: One of the MySqlDbType values.
Return Value
The newly added MySqlParameter object.
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.Add Overload List
MySqlParameterCollection.Add
Method
Adds a MySqlParameter to the MySqlParameterCollection with the parameter name, the data type, and the column length.
Syntax: Visual Basic
Overloads Public Function Add( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType, _ ByVal size As Integer _ ) As MySqlParameter
Syntax: C#
public MySqlParameter Add( stringparameterName, MySqlDbTypedbType, intsize );
Parameters
parameterName
: The name of the parameter.dbType
: One of the MySqlDbType values.size
: The length of the column.
Return Value
The newly added MySqlParameter object.
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.Add Overload List
MySqlParameterCollection.Add
Method
Adds a MySqlParameter to the MySqlParameterCollection with the parameter name, the data type, the column length, and the source column name.
Syntax: Visual Basic
Overloads Public Function Add( _ ByVal parameterName As String, _ ByVal dbType As MySqlDbType, _ ByVal size As Integer, _ ByVal sourceColumn As String _ ) As MySqlParameter
Syntax: C#
public MySqlParameter Add( stringparameterName, MySqlDbTypedbType, intsize, stringsourceColumn );
Parameters
parameterName
: The name of the parameter.dbType
: One of the MySqlDbType values.size
: The length of the column.sourceColumn
: The name of the source column.
Return Value
The newly added MySqlParameter object.
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.Add Overload List
MySqlParameterCollection.Add
Method
Adds a MySqlParameter to the MySqlParameterCollection given the specified parameter name and value.
Syntax: Visual Basic
Overloads Public Function Add( _ ByVal parameterName As String, _ ByVal value As Object _ ) As MySqlParameter
Syntax: C#
public MySqlParameter Add( stringparameterName, objectvalue );
Parameters
parameterName
: The name of the parameter.value
: The Value of the MySqlParameter to add to the collection.
Return Value
The newly added MySqlParameter object.
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.Add Overload List
MySqlParameterCollection.Clear
Method
Removes all items from the collection.
Syntax: Visual Basic
NotOverridable Public Sub Clear() _ _ Implements IList.Clear
Syntax: C#
public void Clear();
Implements
IList.Clear
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
Contains Method
Gets a value indicating whether a MySqlParameter exists in the collection.
Overload List
Gets a value indicating whether a MySqlParameter exists in the collection.
Gets a value indicating whether a MySqlParameter with the specified parameter name exists in the collection.
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
MySqlParameterCollection.Contains
Method
Gets a value indicating whether a MySqlParameter exists in the collection.
Syntax: Visual Basic
NotOverridable Overloads Public Function Contains( _ ByVal value As Object _ ) As Boolean _ _ Implements IList.Contains
Syntax: C#
public bool Contains( objectvalue );
Parameters
value
: The value of the MySqlParameter object to find.
Return Value
true if the collection contains the MySqlParameter object; otherwise, false.
Implements
IList.Contains
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.Contains Overload List
MySqlParameterCollection.Contains
Method
Gets a value indicating whether a MySqlParameter with the specified parameter name exists in the collection.
Syntax: Visual Basic
NotOverridable Overloads Public Function Contains( _ ByVal name As String _ ) As Boolean _ _ Implements IDataParameterCollection.Contains
Syntax: C#
public bool Contains( stringname );
Parameters
name
: The name of the MySqlParameter object to find.
Return Value
true if the collection contains the parameter; otherwise, false.
Implements
IDataParameterCollection.Contains
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.Contains Overload List
MySqlParameterCollection.CopyTo
Method
Copies MySqlParameter objects from the MySqlParameterCollection to the specified array.
Syntax: Visual Basic
NotOverridable Public Sub CopyTo( _ ByVal array As Array, _ ByVal index As Integer _ ) _ _ Implements ICollection.CopyTo
Syntax: C#
public void CopyTo( Arrayarray, intindex );
Parameters
array
:index
:
Implements
ICollection.CopyTo
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
IndexOf Method
Gets the location of a MySqlParameter in the collection.
Overload List
Gets the location of a MySqlParameter in the collection.
Gets the location of the MySqlParameter in the collection with a specific parameter name.
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
MySqlParameterCollection.IndexOf
Method
Gets the location of a MySqlParameter in the collection.
Syntax: Visual Basic
NotOverridable Overloads Public Function IndexOf( _ ByVal value As Object _ ) As Integer _ _ Implements IList.IndexOf
Syntax: C#
public int IndexOf( objectvalue );
Parameters
value
: The MySqlParameter object to locate.
Return Value
The zero-based location of the MySqlParameter in the collection.
Implements
IList.IndexOf
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.IndexOf Overload List
MySqlParameterCollection.IndexOf
Method
Gets the location of the MySqlParameter in the collection with a specific parameter name.
Syntax: Visual Basic
NotOverridable Overloads Public Function IndexOf( _ ByVal parameterName As String _ ) As Integer _ _ Implements IDataParameterCollection.IndexOf
Syntax: C#
public int IndexOf( stringparameterName );
Parameters
parameterName
: The name of the MySqlParameter object to retrieve.
Return Value
The zero-based location of the MySqlParameter in the collection.
Implements
IDataParameterCollection.IndexOf
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.IndexOf Overload List
MySqlParameterCollection.Insert
Method
Inserts a MySqlParameter into the collection at the specified index.
Syntax: Visual Basic
NotOverridable Public Sub Insert( _ ByVal index As Integer, _ ByVal value As Object _ ) _ _ Implements IList.Insert
Syntax: C#
public void Insert( intindex, objectvalue );
Parameters
index
:value
:
Implements
IList.Insert
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
MySqlParameterCollection.Remove
Method
Removes the specified MySqlParameter from the collection.
Syntax: Visual Basic
NotOverridable Public Sub Remove( _ ByVal value As Object _ ) _ _ Implements IList.Remove
Syntax: C#
public void Remove( objectvalue );
Parameters
value
:
Implements
IList.Remove
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
RemoveAt Method
Removes the specified MySqlParameter from the collection.
Overload List
Removes the specified MySqlParameter from the collection using a specific index.
Removes the specified MySqlParameter from the collection using the parameter name.
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace
MySqlParameterCollection.RemoveAt
Method
Removes the specified MySqlParameter from the collection using a specific index.
Syntax: Visual Basic
NotOverridable Overloads Public Sub RemoveAt( _ ByVal index As Integer _ ) _ _ Implements IList.RemoveAt
Syntax: C#
public void RemoveAt( intindex );
Parameters
index
: The zero-based index of the parameter.
Implements
IList.RemoveAt
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.RemoveAt Overload List
MySqlParameterCollection.RemoveAt
Method
Removes the specified MySqlParameter from the collection using the parameter name.
Syntax: Visual Basic
NotOverridable Overloads Public Sub RemoveAt( _ ByVal name As String _ ) _ _ Implements IDataParameterCollection.RemoveAt
Syntax: C#
public void RemoveAt( stringname );
Parameters
name
: The name of the MySqlParameter object to retrieve.
Implements
IDataParameterCollection.RemoveAt
See Also
MySqlParameterCollection Class, MySql.Data.MySqlClient Namespace, MySqlParameterCollection.RemoveAt Overload List
Transaction Property
Syntax: Visual Basic
Public Property Transaction As MySqlTransaction
Syntax: C#
public MySqlTransaction Transaction {get; set;}
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
UpdatedRowSource Property
Syntax: Visual Basic
NotOverridable Public Property UpdatedRowSource As UpdateRowSource _ _ Implements IDbCommand.UpdatedRowSource
Syntax: C#
public System.Data.UpdateRowSource UpdatedRowSource {get; set;}
Implements
IDbCommand.UpdatedRowSource
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
MySqlCommand.Cancel
Method
Attempts to cancel the execution of a MySqlCommand. This operation is not supported.
Syntax: Visual Basic
NotOverridable Public Sub Cancel() _ _ Implements IDbCommand.Cancel
Syntax: C#
public void Cancel();
Implements
IDbCommand.Cancel
Remarks
Cancelling an executing command is currently not supported on any version of MySQL.
Exceptions
Exception Type | Condition |
NotSupportedException | This operation is not supported. |
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
MySqlCommand.CreateParameter
Method
Creates a new instance of a MySqlParameter object.
Syntax: Visual Basic
Public Function CreateParameter() As MySqlParameter
Syntax: C#
public MySqlParameter CreateParameter();
Return Value
A MySqlParameter object.
Remarks
This method is a strongly-typed version of CreateParameter.
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
MySqlCommand.ExecuteNonQuery
Method
Syntax: Visual Basic
NotOverridable Public Function ExecuteNonQuery() As Integer _ _ Implements IDbCommand.ExecuteNonQuery
Syntax: C#
public int ExecuteNonQuery();
Implements
IDbCommand.ExecuteNonQuery
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
ExecuteReader Method
Overload List
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
MySqlCommand.ExecuteReader
Method
Syntax: Visual Basic
Overloads Public Function ExecuteReader() As MySqlDataReader
Syntax: C#
public MySqlDataReader ExecuteReader();
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace, MySqlCommand.ExecuteReader Overload List
MySqlDataReader
Class
Provides a means of reading a forward-only stream of rows from a MariaDB database. This class cannot be inherited.
For a list of all members of this type, see MySqlDataReader Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlDataReader_ Inherits MarshalByRefObject_ Implements IEnumerable, IDataReader, IDisposable, IDataRecord
Syntax: C#
public sealed class MySqlDataReader : MarshalByRefObject, IEnumerable, IDataReader, IDisposable, IDataRecord
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlDataReader Members, MySql.Data.MySqlClient Namespace
MySqlDataReader
Members
Public Instance Properties
Depth | Gets a value indicating the depth of nesting for the current row. This method is not supported currently and always returns 0. |
FieldCount | Gets the number of columns in the current row. |
HasRows | Gets a value indicating whether the MySqlDataReader contains one or more rows. |
IsClosed | Gets a value indicating whether the data reader is closed. |
Item | Overloaded. Overloaded. Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class. |
RecordsAffected | Gets the number of rows changed, inserted, or deleted by execution of the SQL statement. |
Public Instance Methods
Close | Closes the MySqlDataReader object. |
CreateObjRef (inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. |
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetBoolean | Gets the value of the specified column as a Boolean. |
GetByte | Gets the value of the specified column as a byte. |
GetBytes | Reads a stream of bytes from the specified column offset into the buffer an array starting at the given buffer offset. |
GetChar | Gets the value of the specified column as a single character. |
GetChars | Reads a stream of characters from the specified column offset into the buffer as an array starting at the given buffer offset. |
GetDataTypeName | Gets the name of the source data type. |
GetDateTime | |
GetDecimal | |
GetDouble | |
GetFieldType | Gets the Type that is the data type of the object. |
GetFloat | |
GetGuid | |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetInt16 | |
GetInt32 | |
GetInt64 | |
GetLifetimeService (inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance. |
GetMySqlDateTime | |
GetName | Gets the name of the specified column. |
GetOrdinal | Gets the column ordinal, given the name of the column. |
GetSchemaTable | Returns a DataTable that describes the column metadata of the MySqlDataReader. |
GetString | |
GetTimeSpan | |
GetType (inherited from Object) | Gets the Type of the current instance. |
GetUInt16 | |
GetUInt32 | |
GetUInt64 | |
GetValue | Gets the value of the specified column in its native format. |
GetValues | Gets all attribute columns in the collection for the current row. |
InitializeLifetimeService (inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance. |
IsDBNull | Gets a value indicating whether the column contains non-existent or missing values. |
NextResult | Advances the data reader to the next result, when reading the results of batch SQL statements. |
Read | Advances the MySqlDataReader to the next record. |
ToString (inherited from Object) | Returns a String that represents the current Object. |
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
Depth Property
Gets a value indicating the depth of nesting for the current row. This method is not supported currently and always returns 0.
Syntax: Visual Basic
NotOverridable Public ReadOnly Property Depth As Integer _ _ Implements IDataReader.Depth
Syntax: C#
public int Depth {get;}
Implements
IDataReader.Depth
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
FieldCount Property
Gets the number of columns in the current row.
Syntax: Visual Basic
NotOverridable Public ReadOnly Property FieldCount As Integer _ _ Implements IDataRecord.FieldCount
Syntax: C#
public int FieldCount {get;}
Implements
IDataRecord.FieldCount
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
HasRows Property
Gets a value indicating whether the MySqlDataReader contains one or more rows.
Syntax: Visual Basic
Public ReadOnly Property HasRows As Boolean
Syntax: C#
public bool HasRows {get;}
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
IsClosed Property
Gets a value indicating whether the data reader is closed.
Syntax: Visual Basic
NotOverridable Public ReadOnly Property IsClosed As Boolean _ _ Implements IDataReader.IsClosed
Syntax: C#
public bool IsClosed {get;}
Implements
IDataReader.IsClosed
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
Item Property
Overloaded. Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class.
Overload List
Overloaded. Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class.
Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class.
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
Item Property (Int32)
Overloaded. Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class.
Syntax: Visual Basic
NotOverridable Overloads Public Default ReadOnly Property Item( _ ByVal i As Integer _ ) _ _ Implements IDataRecord.Item As Object _ _ Implements IDataRecord.Item
Syntax: C#
public object this[ inti ] {get;}
Implements
IDataRecord.Item
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace, MySqlDataReader.Item Overload List
Item Property (String)
Gets the value of a column in its native format. In C#, this property is the indexer for the MySqlDataReader class.
Syntax: Visual Basic
NotOverridable Overloads Public Default ReadOnly Property Item( _ ByVal name As String _ ) _ _ Implements IDataRecord.Item As Object _ _ Implements IDataRecord.Item
Syntax: C#
public object this[ stringname ] {get;}
Implements
IDataRecord.Item
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace, MySqlDataReader.Item Overload List
RecordsAffected Property
Gets the number of rows changed, inserted, or deleted by execution of the SQL statement.
Syntax: Visual Basic
NotOverridable Public ReadOnly Property RecordsAffected As Integer _ _ Implements IDataReader.RecordsAffected
Syntax: C#
public int RecordsAffected {get;}
Implements
IDataReader.RecordsAffected
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.Close
Method
Closes the MySqlDataReader object.
Syntax: Visual Basic
NotOverridable Public Sub Close() _ _ Implements IDataReader.Close
Syntax: C#
public void Close();
Implements
IDataReader.Close
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetBoolean
Method
Gets the value of the specified column as a Boolean.
Syntax: Visual Basic
NotOverridable Public Function GetBoolean( _ ByVal i As Integer _ ) As Boolean _ _ Implements IDataRecord.GetBoolean
Syntax: C#
public bool GetBoolean( inti );
Parameters
i
:
Return Value
Implements
IDataRecord.GetBoolean
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetByte
Method
Gets the value of the specified column as a byte.
Syntax: Visual Basic
NotOverridable Public Function GetByte( _ ByVal i As Integer _ ) As Byte _ _ Implements IDataRecord.GetByte
Syntax: C#
public byte GetByte( inti );
Parameters
i
:
Return Value
Implements
IDataRecord.GetByte
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetBytes
Method
Reads a stream of bytes from the specified column offset into the buffer an array starting at the given buffer offset.
Syntax: Visual Basic
NotOverridable Public Function GetBytes( _ ByVal i As Integer, _ ByVal dataIndex As Long, _ ByVal buffer As Byte(), _ ByVal bufferIndex As Integer, _ ByVal length As Integer _ ) As Long _ _ Implements IDataRecord.GetBytes
Syntax: C#
public long GetBytes( inti, longdataIndex, byte[]buffer, intbufferIndex, intlength );
Parameters
i
: The zero-based column ordinal.dataIndex
: The index within the field from which to begin the read operation.buffer
: The buffer into which to read the stream of bytes.bufferIndex
: The index for buffer to begin the read operation.length
: The maximum length to copy into the buffer.
Return Value
The actual number of bytes read.
Implements
IDataRecord.GetBytes
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetChar
Method
Gets the value of the specified column as a single character.
Syntax: Visual Basic
NotOverridable Public Function GetChar( _ ByVal i As Integer _ ) As Char _ _ Implements IDataRecord.GetChar
Syntax: C#
public char GetChar( inti );
Parameters
i
:
Return Value
Implements
IDataRecord.GetChar
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetChars
Method
Reads a stream of characters from the specified column offset into the buffer as an array starting at the given buffer offset.
Syntax: Visual Basic
NotOverridable Public Function GetChars( _ ByVal i As Integer, _ ByVal fieldOffset As Long, _ ByVal buffer As Char(), _ ByVal bufferoffset As Integer, _ ByVal length As Integer _ ) As Long _ _ Implements IDataRecord.GetChars
Syntax: C#
public long GetChars( inti, longfieldOffset, char[]buffer, intbufferoffset, intlength );
Parameters
i
:fieldOffset
:buffer
:bufferoffset
:length
:
Return Value
Implements
IDataRecord.GetChars
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetDataTypeName
Method
Gets the name of the source data type.
Syntax: Visual Basic
NotOverridable Public Function GetDataTypeName( _ ByVal i As Integer _ ) As String _ _ Implements IDataRecord.GetDataTypeName
Syntax: C#
public string GetDataTypeName( inti );
Parameters
i
:
Return Value
Implements
IDataRecord.GetDataTypeName
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetDateTime
Method
Syntax: Visual Basic
NotOverridable Public Function GetDateTime( _ ByVal index As Integer _ ) As Date _ _ Implements IDataRecord.GetDateTime
Syntax: C#
public DateTime GetDateTime( intindex );
Implements
IDataRecord.GetDateTime
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetDecimal
Method
Syntax: Visual Basic
NotOverridable Public Function GetDecimal( _ ByVal index As Integer _ ) As Decimal _ _ Implements IDataRecord.GetDecimal
Syntax: C#
public decimal GetDecimal( intindex );
Implements
IDataRecord.GetDecimal
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetDouble
Method
Syntax: Visual Basic
NotOverridable Public Function GetDouble( _ ByVal index As Integer _ ) As Double _ _ Implements IDataRecord.GetDouble
Syntax: C#
public double GetDouble( intindex );
Implements
IDataRecord.GetDouble
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetFieldType
Method
Gets the Type that is the data type of the object.
Syntax: Visual Basic
NotOverridable Public Function GetFieldType( _ ByVal i As Integer _ ) As Type _ _ Implements IDataRecord.GetFieldType
Syntax: C#
public Type GetFieldType( inti );
Parameters
i
:
Return Value
Implements
IDataRecord.GetFieldType
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetFloat
Method
Syntax: Visual Basic
NotOverridable Public Function GetFloat( _ ByVal index As Integer _ ) As Single _ _ Implements IDataRecord.GetFloat
Syntax: C#
public float GetFloat( intindex );
Implements
IDataRecord.GetFloat
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetGuid
Method
Syntax: Visual Basic
NotOverridable Public Function GetGuid( _ ByVal index As Integer _ ) As Guid _ _ Implements IDataRecord.GetGuid
Syntax: C#
public Guid GetGuid( intindex );
Implements
IDataRecord.GetGuid
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetInt16
Method
Syntax: Visual Basic
NotOverridable Public Function GetInt16( _ ByVal index As Integer _ ) As Short _ _ Implements IDataRecord.GetInt16
Syntax: C#
public short GetInt16( intindex );
Implements
IDataRecord.GetInt16
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetInt32
Method
Syntax: Visual Basic
NotOverridable Public Function GetInt32( _ ByVal index As Integer _ ) As Integer _ _ Implements IDataRecord.GetInt32
Syntax: C#
public int GetInt32( intindex );
Implements
IDataRecord.GetInt32
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetInt64
Method
Syntax: Visual Basic
NotOverridable Public Function GetInt64( _ ByVal index As Integer _ ) As Long _ _ Implements IDataRecord.GetInt64
Syntax: C#
public long GetInt64( intindex );
Implements
IDataRecord.GetInt64
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetMySqlDateTime
Method
Syntax: Visual Basic
Public Function GetMySqlDateTime( _ ByVal index As Integer _ ) As MySqlDateTime
Syntax: C#
public MySqlDateTime GetMySqlDateTime( intindex );
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetName
Method
Gets the name of the specified column.
Syntax: Visual Basic
NotOverridable Public Function GetName( _ ByVal i As Integer _ ) As String _ _ Implements IDataRecord.GetName
Syntax: C#
public string GetName( inti );
Parameters
i
:
Return Value
Implements
IDataRecord.GetName
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetOrdinal
Method
Gets the column ordinal, given the name of the column.
Syntax: Visual Basic
NotOverridable Public Function GetOrdinal( _ ByVal name As String _ ) As Integer _ _ Implements IDataRecord.GetOrdinal
Syntax: C#
public int GetOrdinal( stringname );
Parameters
name
:
Return Value
Implements
IDataRecord.GetOrdinal
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetSchemaTable
Method
Returns a DataTable that describes the column metadata of the MySqlDataReader.
Syntax: Visual Basic
NotOverridable Public Function GetSchemaTable() As DataTable _ _ Implements IDataReader.GetSchemaTable
Syntax: C#
public DataTable GetSchemaTable();
Return Value
Implements
IDataReader.GetSchemaTable
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetString
Method
Syntax: Visual Basic
NotOverridable Public Function GetString( _ ByVal index As Integer _ ) As String _ _ Implements IDataRecord.GetString
Syntax: C#
public string GetString( intindex );
Implements
IDataRecord.GetString
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetTimeSpan
Method
Syntax: Visual Basic
Public Function GetTimeSpan( _ ByVal index As Integer _ ) As TimeSpan
Syntax: C#
public TimeSpan GetTimeSpan( intindex );
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetUInt16
Method
Syntax: Visual Basic
Public Function GetUInt16( _ ByVal index As Integer _ ) As UInt16
Syntax: C#
public ushort GetUInt16( intindex );
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetUInt32
Method
Syntax: Visual Basic
Public Function GetUInt32( _ ByVal index As Integer _ ) As UInt32
Syntax: C#
public uint GetUInt32( intindex );
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetUInt64
Method
Syntax: Visual Basic
Public Function GetUInt64( _ ByVal index As Integer _ ) As UInt64
Syntax: C#
public ulong GetUInt64( intindex );
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetValue
Method
Gets the value of the specified column in its native format.
Syntax: Visual Basic
NotOverridable Public Function GetValue( _ ByVal i As Integer _ ) As Object _ _ Implements IDataRecord.GetValue
Syntax: C#
public object GetValue( inti );
Parameters
i
:
Return Value
Implements
IDataRecord.GetValue
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.GetValues
Method
Gets all attribute columns in the collection for the current row.
Syntax: Visual Basic
NotOverridable Public Function GetValues( _ ByVal values As Object() _ ) As Integer _ _ Implements IDataRecord.GetValues
Syntax: C#
public int GetValues( object[]values );
Parameters
values
:
Return Value
Implements
IDataRecord.GetValues
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.IsDBNull
Method
Gets a value indicating whether the column contains non-existent or missing values.
Syntax: Visual Basic
NotOverridable Public Function IsDBNull( _ ByVal i As Integer _ ) As Boolean _ _ Implements IDataRecord.IsDBNull
Syntax: C#
public bool IsDBNull( inti );
Parameters
i
:
Return Value
Implements
IDataRecord.IsDBNull
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.NextResult
Method
Advances the data reader to the next result, when reading the results of batch SQL statements.
Syntax: Visual Basic
NotOverridable Public Function NextResult() As Boolean _ _ Implements IDataReader.NextResult
Syntax: C#
public bool NextResult();
Return Value
Implements
IDataReader.NextResult
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlDataReader.Read
Method
Advances the MySqlDataReader to the next record.
Syntax: Visual Basic
NotOverridable Public Function Read() As Boolean _ _ Implements IDataReader.Read
Syntax: C#
public bool Read();
Return Value
Implements
IDataReader.Read
See Also
MySqlDataReader Class, MySql.Data.MySqlClient Namespace
MySqlCommand.ExecuteReader
Method
Syntax: Visual Basic
Overloads Public Function ExecuteReader( _ ByVal behavior As CommandBehavior _ ) As MySqlDataReader
Syntax: C#
public MySqlDataReader ExecuteReader( CommandBehaviorbehavior );
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace, MySqlCommand.ExecuteReader Overload List
MySqlCommand.ExecuteScalar
Method
Syntax: Visual Basic
NotOverridable Public Function ExecuteScalar() As Object _ _ Implements IDbCommand.ExecuteScalar
Syntax: C#
public object ExecuteScalar();
Implements
IDbCommand.ExecuteScalar
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
MySqlCommand.Prepare
Method
Syntax: Visual Basic
NotOverridable Public Sub Prepare() _ _ Implements IDbCommand.Prepare
Syntax: C#
public void Prepare();
Implements
IDbCommand.Prepare
See Also
MySqlCommand Class, MySql.Data.MySqlClient Namespace
MySqlCommandBuilder
Class
For a list of all members of this type, see MySqlCommandBuilder Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlCommandBuilder_ Inherits Component
Syntax: C#
public sealed class MySqlCommandBuilder : Component
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlCommandBuilder Members, MySql.Data.MySqlClient Namespace
MySqlCommandBuilder
Members
- DeriveParameters Method
MySqlCommandBuilder
Constructor- DataAdapter Property
- QuotePrefix Property
- QuoteSuffix Property
MySqlCommandBuilder.GetDeleteCommand
MethodMySqlCommandBuilder.GetInsertCommand
MethodMySqlCommandBuilder.GetUpdateCommand
MethodMySqlCommandBuilder.RefreshSchema
Method
Public Static (Shared) Methods
DeriveParameters | Overloaded. Retrieves parameter information from the stored procedure specified in the MySqlCommand and populates the Parameters collection of the specified MySqlCommand object. This method is not currently supported since stored procedures are not available in MySql. |
Public Instance Constructors
MySqlCommandBuilder | Overloaded. Initializes a new instance of the MySqlCommandBuilder class. |
Public Instance Properties
Container (inherited from Component) | Gets the IContainer that contains the Component. |
DataAdapter | |
QuotePrefix | |
QuoteSuffix | |
Site (inherited from Component) | Gets or sets the ISite of the Component. |
Public Instance Methods
CreateObjRef (inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. |
Dispose (inherited from Component) | Releases all resources used by the Component. |
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetDeleteCommand | |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetInsertCommand | |
GetLifetimeService (inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance. |
GetType (inherited from Object) | Gets the Type of the current instance. |
GetUpdateCommand | |
InitializeLifetimeService (inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance. |
RefreshSchema | |
ToString (inherited from Component) | Returns a String containing the name of the Component, if any. This method should not be overridden. |
Public Instance Events
Disposed (inherited from Component) | Adds an event handler to listen to the Disposed event on the component. |
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace
DeriveParameters Method
Retrieves parameter information from the stored procedure specified in the MySqlCommand and populates the Parameters collection of the specified MySqlCommand object. This method is not currently supported since stored procedures are not available in MySql.
Overload List
Retrieves parameter information from the stored procedure specified in the MySqlCommand and populates the Parameters collection of the specified MySqlCommand object. This method is not currently supported since stored procedures are not available in MySql.
- public static void DeriveParameters(MySqlCommand);
- public static void DeriveParameters(MySqlCommand,bool);
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace
MySqlCommandBuilder.DeriveParameters
Method
Retrieves parameter information from the stored procedure specified in the MySqlCommand and populates the Parameters collection of the specified MySqlCommand object. This method is not currently supported since stored procedures are not available in MySql.
Syntax: Visual Basic
Overloads Public Shared Sub DeriveParameters( _ ByVal command As MySqlCommand _ )
Syntax: C#
public static void DeriveParameters( MySqlCommandcommand );
Parameters
command
: The MySqlCommand referencing the stored procedure from which the parameter information is to be derived. The derived parameters are added to the Parameters collection of the MySqlCommand.
Exceptions
Exception Type | Condition |
InvalidOperationException | The command text is not a valid stored procedure name. |
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace, MySqlCommandBuilder.DeriveParameters Overload List
MySqlCommandBuilder.DeriveParameters
Method
Syntax: Visual Basic
Overloads Public Shared Sub DeriveParameters( _ ByVal command As MySqlCommand, _ ByVal useProc As Boolean _ )
Syntax: C#
public static void DeriveParameters( MySqlCommandcommand, booluseProc );
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace, MySqlCommandBuilder.DeriveParameters Overload List
MySqlCommandBuilder
Constructor
MySqlCommandBuilder
ConstructorMySqlCommandBuilder
ConstructorMySqlCommandBuilder
ConstructorMySqlCommandBuilder
Constructor
Initializes a new instance of the MySqlCommandBuilder class.
Overload List
Initializes a new instance of the MySqlCommandBuilder class.
- public MySqlCommandBuilder();
- public MySqlCommandBuilder(MySqlDataAdapter);
- public MySqlCommandBuilder(MySqlDataAdapter,bool);
- public MySqlCommandBuilder(bool);
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace
MySqlCommandBuilder
Constructor
Initializes a new instance of the MySqlCommandBuilder class.
Syntax: Visual Basic
Overloads Public Sub New()
Syntax: C#
public MySqlCommandBuilder();
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace, MySqlCommandBuilder Constructor Overload List
MySqlCommandBuilder
Constructor
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal adapter As MySqlDataAdapter _ )
Syntax: C#
public MySqlCommandBuilder( MySqlDataAdapteradapter );
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace, MySqlCommandBuilder Constructor Overload List
MySqlDataAdapter
Class
For a list of all members of this type, see MySqlDataAdapter Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlDataAdapter_ Inherits DbDataAdapter
Syntax: C#
public sealed class MySqlDataAdapter : DbDataAdapter
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlDataAdapter Members, MySql.Data.MySqlClient Namespace
MySqlDataAdapter
Members
Public Instance Constructors
MySqlDataAdapter | Overloaded. Initializes a new instance of the MySqlDataAdapter class. |
Public Instance Properties
AcceptChangesDuringFill (inherited from DataAdapter) | Gets or sets a value indicating whether AcceptChangesis called on a DataRowafter it is added to the DataTableduring any of the Fill operations. |
AcceptChangesDuringUpdate (inherited from DataAdapter) | Gets or sets whether AcceptChangesis called during a Update. |
Container (inherited from Component) | Gets the IContainer that contains the Component. |
ContinueUpdateOnError (inherited from DataAdapter) | Gets or sets a value that specifies whether to generate an exception when an error is encountered during a row update. |
DeleteCommand | Overloaded. |
FillLoadOption (inherited from DataAdapter) | Gets or sets the LoadOption that determines how the adapter fills the DataTablefrom the DbDataReader. |
InsertCommand | Overloaded. |
MissingMappingAction (inherited from DataAdapter) | Determines the action to take when incoming data does not have a matching table or column. |
MissingSchemaAction (inherited from DataAdapter) | Determines the action to take when existing DataSetschema does not match incoming data. |
ReturnProviderSpecificTypes (inherited from DataAdapter) | Gets or sets whether the Fillmethod should return provider-specific values or common CLS-compliant values. |
SelectCommand | Overloaded. |
Site (inherited from Component) | Gets or sets the ISite of the Component. |
TableMappings (inherited from DataAdapter) | Gets a collection that provides the master mapping between a source table and a DataTable. |
UpdateBatchSize (inherited from DbDataAdapter) | Gets or sets a value that enables or disables batch processing support, and specifies the number of commands that can be executed in a batch. |
UpdateCommand | Overloaded. |
Public Instance Methods
CreateObjRef (inherited from MarshalByRefObject) | Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. |
Dispose (inherited from Component) | Releases all resources used by the Component. |
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
Fill (inherited from DbDataAdapter) | Overloaded. Adds or refreshes rows in the DataSetto match those in the data source using the DataSetname, and creates a DataTablenamed 'Table.' |
FillSchema (inherited from DbDataAdapter) | Overloaded. Configures the schema of the specified DataTablebased on the specified SchemaType. |
GetFillParameters (inherited from DbDataAdapter) | Gets the parameters set by the user when executing an SQL SELECT statement.
|
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetLifetimeService (inherited from MarshalByRefObject) | Retrieves the current lifetime service object that controls the lifetime policy for this instance. |
GetType (inherited from Object) | Gets the Type of the current instance. |
InitializeLifetimeService (inherited from MarshalByRefObject) | Obtains a lifetime service object to control the lifetime policy for this instance. |
ResetFillLoadOption (inherited from DataAdapter) | Resets FillLoadOptionto its default state and causes Fillto honor AcceptChangesDuringFill. |
ShouldSerializeAcceptChangesDuringFill (inherited from DataAdapter) | Determines whether the AcceptChangesDuringFillproperty should be persisted. |
ShouldSerializeFillLoadOption (inherited from DataAdapter) | Determines whether the FillLoadOptionproperty should be persisted. |
ToString (inherited from Component) | Returns a String containing the name of the Component, if any. This method should not be overridden. |
Update (inherited from DbDataAdapter) | Overloaded. Calls the respective INSERT, UPDATE, or DELETE statements for each inserted, updated, or deleted row in the specified DataSet. |
Public Instance Events
Disposed (inherited from Component) | Adds an event handler to listen to the Disposed event on the component. |
FillError (inherited from DataAdapter) | Returned when an error occurs during a fill operation. |
RowUpdated | Occurs during Update after a command is executed against the data source. The attempt to update is made, so the event fires. |
RowUpdating | Occurs during Update before a command is executed against the data source. The attempt to update is made, so the event fires. |
Protected Internal Instance Properties
FillCommandBehavior (inherited from DbDataAdapter) | Gets or sets the behavior of the command used to fill the data adapter. |
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace
MySqlDataAdapter
Constructor
Initializes a new instance of the MySqlDataAdapter class.
Overload List
Initializes a new instance of the MySqlDataAdapter class.
- public MySqlDataAdapter();
- public MySqlDataAdapter(MySqlCommand);
- public MySqlDataAdapter(string,MySqlConnection);
- public MySqlDataAdapter(string,string);
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace
MySqlDataAdapter
Constructor
Initializes a new instance of the MySqlDataAdapter class.
Syntax: Visual Basic
Overloads Public Sub New()
Syntax: C#
public MySqlDataAdapter();
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace, MySqlDataAdapter Constructor Overload List
MySqlDataAdapter
Constructor
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal selectCommand As MySqlCommand _ )
Syntax: C#
public MySqlDataAdapter( MySqlCommandselectCommand );
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace, MySqlDataAdapter Constructor Overload List
MySqlDataAdapter
Constructor
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal selectCommandText As String, _ ByVal connection As MySqlConnection _ )
Syntax: C#
public MySqlDataAdapter( stringselectCommandText, MySqlConnectionconnection );
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace, MySqlDataAdapter Constructor Overload List
MySqlDataAdapter
Constructor
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal selectCommandText As String, _ ByVal selectConnString As String _ )
Syntax: C#
public MySqlDataAdapter( stringselectCommandText, stringselectConnString );
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace, MySqlDataAdapter Constructor Overload List
DeleteCommand Property
Syntax: Visual Basic
Overloads Public Property DeleteCommand As MySqlCommand
Syntax: C#
new public MySqlCommand DeleteCommand {get; set;}
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace
InsertCommand Property
Syntax: Visual Basic
Overloads Public Property InsertCommand As MySqlCommand
Syntax: C#
new public MySqlCommand InsertCommand {get; set;}
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace
SelectCommand Property
Syntax: Visual Basic
Overloads Public Property SelectCommand As MySqlCommand
Syntax: C#
new public MySqlCommand SelectCommand {get; set;}
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace
UpdateCommand Property
Syntax: Visual Basic
Overloads Public Property UpdateCommand As MySqlCommand
Syntax: C#
new public MySqlCommand UpdateCommand {get; set;}
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace
MySqlDataAdapter.RowUpdated
Event
Occurs during Update after a command is executed against the data source. The attempt to update is made, so the event fires.
Syntax: Visual Basic
Public Event RowUpdated As MySqlRowUpdatedEventHandler
Syntax: C#
public event MySqlRowUpdatedEventHandler RowUpdated;
Event Data
The event handler receives an argument of type MySqlRowUpdatedEventArgs containing data related to this event. The following MySqlRowUpdatedEventArgsproperties provide information specific to this event.
Property | Description |
Command | Gets or sets the MySqlCommand executed when Update is called. |
Errors | Gets any errors generated by the .NET Framework data provider when the Commandwas executed. |
RecordsAffected | Gets the number of rows changed, inserted, or deleted by execution of the SQL statement. |
Row | Gets the DataRowsent through an Update. |
RowCount | Gets the number of rows processed in a batch of updated records. |
StatementType | Gets the type of SQL statement executed. |
Status | Gets the UpdateStatus of the Commandproperty. |
TableMapping | Gets the DataTableMappingsent through an Update. |
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace
MySqlRowUpdatedEventHandler
Delegate
Represents the method that will handle the RowUpdatedevent of a MySqlDataAdapter.
Syntax: Visual Basic
Public Delegate Sub MySqlRowUpdatedEventHandler( _ ByVal sender As Object, _ ByVal e As MySqlRowUpdatedEventArgs _ )
Syntax: C#
public delegate void MySqlRowUpdatedEventHandler( objectsender, MySqlRowUpdatedEventArgs );
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySql.Data.MySqlClient Namespace
MySqlRowUpdatedEventArgs
Class
Provides data for the RowUpdated event. This class cannot be inherited.
For a list of all members of this type, see MySqlRowUpdatedEventArgs Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlRowUpdatedEventArgs_ Inherits RowUpdatedEventArgs
Syntax: C#
public sealed class MySqlRowUpdatedEventArgs : RowUpdatedEventArgs
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlRowUpdatedEventArgs Members, MySql.Data.MySqlClient Namespace
MySqlRowUpdatedEventArgs
Members
MySqlRowUpdatedEventArgs overview
Public Instance Constructors
MySqlRowUpdatedEventArgs Constructor | Initializes a new instance of the MySqlRowUpdatedEventArgs class. |
Public Instance Properties
Command | Overloaded. Gets or sets the MySqlCommand executed when Update is called. |
Errors (inherited from RowUpdatedEventArgs) | Gets any errors generated by the .NET Framework data provider when the Commandwas executed. |
RecordsAffected (inherited from RowUpdatedEventArgs) | Gets the number of rows changed, inserted, or deleted by execution of the SQL statement. |
Row (inherited from RowUpdatedEventArgs) | Gets the DataRowsent through an Update. |
RowCount (inherited from RowUpdatedEventArgs) | Gets the number of rows processed in a batch of updated records. |
StatementType (inherited from RowUpdatedEventArgs) | Gets the type of SQL statement executed. |
Status (inherited from RowUpdatedEventArgs) | Gets the UpdateStatus of the Commandproperty. |
TableMapping (inherited from RowUpdatedEventArgs) | Gets the DataTableMappingsent through an Update. |
Public Instance Methods
CopyToRows (inherited from RowUpdatedEventArgs) | Overloaded. Copies references to the modified rows into the provided array. |
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetType (inherited from Object) | Gets the Type of the current instance. |
ToString (inherited from Object) | Returns a String that represents the current Object. |
See Also
MySqlRowUpdatedEventArgs Class, MySql.Data.MySqlClient Namespace
MySqlRowUpdatedEventArgs
Constructor
Initializes a new instance of the MySqlRowUpdatedEventArgs class.
Syntax: Visual Basic
Public Sub New( _ ByVal row As DataRow, _ ByVal command As IDbCommand, _ ByVal statementType As StatementType, _ ByVal tableMapping As DataTableMapping _ )
Syntax: C#
public MySqlRowUpdatedEventArgs( DataRowrow, IDbCommandcommand, StatementTypestatementType, DataTableMappingtableMapping );
Parameters
row
: The DataRowsent through an Update.command
: The IDbCommand executed when Update is called.statementType
: One of the StatementTypevalues that specifies the type of query executed.tableMapping
: The DataTableMapping sent through an Update.
See Also
MySqlRowUpdatedEventArgs Class, MySql.Data.MySqlClient Namespace
Command Property
Gets or sets the MySqlCommand executed when Update is called.
Syntax: Visual Basic
Overloads Public ReadOnly Property Command As MySqlCommand
Syntax: C#
new public MySqlCommand Command {get;}
See Also
MySqlRowUpdatedEventArgs Class, MySql.Data.MySqlClient Namespace
MySqlDataAdapter.RowUpdating
Event
Occurs during Update before a command is executed against the data source. The attempt to update is made, so the event fires.
Syntax: Visual Basic
Public Event RowUpdating As MySqlRowUpdatingEventHandler
Syntax: C#
public event MySqlRowUpdatingEventHandler RowUpdating;
Event Data
The event handler receives an argument of type MySqlRowUpdatingEventArgs containing data related to this event. The following MySqlRowUpdatingEventArgsproperties provide information specific to this event.
Property | Description |
Command | Gets or sets the MySqlCommand to execute when performing the Update. |
Errors | Gets any errors generated by the .NET Framework data provider when the Command executes. |
Row | Gets the DataRow that will be sent to the server as part of an insert, update, or delete operation. |
StatementType | Gets the type of SQL statement to execute. |
Status | Gets or sets the UpdateStatus of the Commandproperty. |
TableMapping | Gets the DataTableMapping to send through the Update. |
See Also
MySqlDataAdapter Class, MySql.Data.MySqlClient Namespace
MySqlRowUpdatingEventHandler
Delegate
Represents the method that will handle the RowUpdatingevent of a MySqlDataAdapter.
Syntax: Visual Basic
Public Delegate Sub MySqlRowUpdatingEventHandler( _ ByVal sender As Object, _ ByVal e As MySqlRowUpdatingEventArgs _ )
Syntax: C#
public delegate void MySqlRowUpdatingEventHandler( objectsender, MySqlRowUpdatingEventArgs );
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySql.Data.MySqlClient Namespace
MySqlRowUpdatingEventArgs
Class
Provides data for the RowUpdating event. This class cannot be inherited.
For a list of all members of this type, see MySqlRowUpdatingEventArgs Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlRowUpdatingEventArgs_ Inherits RowUpdatingEventArgs
Syntax: C#
public sealed class MySqlRowUpdatingEventArgs : RowUpdatingEventArgs
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlRowUpdatingEventArgs Members, MySql.Data.MySqlClient Namespace
MySqlRowUpdatingEventArgs
Members
MySqlRowUpdatingEventArgs overview
Public Instance Constructors
MySqlRowUpdatingEventArgs Constructor | Initializes a new instance of the MySqlRowUpdatingEventArgs class. |
Public Instance Properties
Command | Overloaded. Gets or sets the MySqlCommand to execute when performing the Update. |
Errors (inherited from RowUpdatingEventArgs) | Gets any errors generated by the .NET Framework data provider when the Command executes. |
Row (inherited from RowUpdatingEventArgs) | Gets the DataRow that will be sent to the server as part of an insert, update, or delete operation. |
StatementType (inherited from RowUpdatingEventArgs) | Gets the type of SQL statement to execute. |
Status (inherited from RowUpdatingEventArgs) | Gets or sets the UpdateStatus of the Commandproperty. |
TableMapping (inherited from RowUpdatingEventArgs) | Gets the DataTableMapping to send through the Update. |
Public Instance Methods
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetType (inherited from Object) | Gets the Type of the current instance. |
ToString (inherited from Object) | Returns a String that represents the current Object. |
See Also
MySqlRowUpdatingEventArgs Class, MySql.Data.MySqlClient Namespace
MySqlRowUpdatingEventArgs
Constructor
Initializes a new instance of the MySqlRowUpdatingEventArgs class.
Syntax: Visual Basic
Public Sub New( _ ByVal row As DataRow, _ ByVal command As IDbCommand, _ ByVal statementType As StatementType, _ ByVal tableMapping As DataTableMapping _ )
Syntax: C#
public MySqlRowUpdatingEventArgs( DataRowrow, IDbCommandcommand, StatementTypestatementType, DataTableMappingtableMapping );
Parameters
row
: The DataRowto Update.command
: The IDbCommandto execute during Update.statementType
: One of the StatementTypevalues that specifies the type of query executed.tableMapping
: The DataTableMappingsent through an Update.
See Also
MySqlRowUpdatingEventArgs Class, MySql.Data.MySqlClient Namespace
Command Property
Gets or sets the MySqlCommand to execute when performing the Update.
Syntax: Visual Basic
Overloads Public Property Command As MySqlCommand
Syntax: C#
new public MySqlCommand Command {get; set;}
See Also
MySqlRowUpdatingEventArgs Class, MySql.Data.MySqlClient Namespace
MySqlCommandBuilder
Constructor
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal adapter As MySqlDataAdapter, _ ByVal lastOneWins As Boolean _ )
Syntax: C#
public MySqlCommandBuilder( MySqlDataAdapteradapter, boollastOneWins );
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace, MySqlCommandBuilder Constructor Overload List
MySqlCommandBuilder
Constructor
Syntax: Visual Basic
Overloads Public Sub New( _ ByVal lastOneWins As Boolean _ )
Syntax: C#
public MySqlCommandBuilder( boollastOneWins );
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace, MySqlCommandBuilder Constructor Overload List
DataAdapter Property
Syntax: Visual Basic
Public Property DataAdapter As MySqlDataAdapter
Syntax: C#
public MySqlDataAdapter DataAdapter {get; set;}
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace
QuotePrefix Property
Syntax: Visual Basic
Public Property QuotePrefix As String
Syntax: C#
public string QuotePrefix {get; set;}
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace
QuoteSuffix Property
Syntax: Visual Basic
Public Property QuoteSuffix As String
Syntax: C#
public string QuoteSuffix {get; set;}
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace
MySqlCommandBuilder.GetDeleteCommand
Method
Syntax: Visual Basic
Public Function GetDeleteCommand() As MySqlCommand
Syntax: C#
public MySqlCommand GetDeleteCommand();
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace
MySqlCommandBuilder.GetInsertCommand
Method
Syntax: Visual Basic
Public Function GetInsertCommand() As MySqlCommand
Syntax: C#
public MySqlCommand GetInsertCommand();
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace
MySqlCommandBuilder.GetUpdateCommand
Method
Syntax: Visual Basic
Public Function GetUpdateCommand() As MySqlCommand
Syntax: C#
public MySqlCommand GetUpdateCommand();
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace
MySqlCommandBuilder.RefreshSchema
Method
Syntax: Visual Basic
Public Sub RefreshSchema()
Syntax: C#
public void RefreshSchema();
See Also
MySqlCommandBuilder Class, MySql.Data.MySqlClient Namespace
MySqlException
Class
The exception that is thrown when MariaDB returns an error. This class cannot be inherited.
For a list of all members of this type, see MySqlException Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlException_ Inherits SystemException
Syntax: C#
public sealed class MySqlException : SystemException
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlException Members, MySql.Data.MySqlClient Namespace
MySqlException
Members
Public Instance Properties
Data (inherited from Exception) | Gets a collection of key/value pairs that provide additional, user-defined information about the exception. |
HelpLink (inherited from Exception) | Gets or sets a link to the help file associated with this exception. |
InnerException (inherited from Exception) | Gets the Exceptioninstance that caused the current exception.
|
Message (inherited from Exception) | Gets a message that describes the current exception. |
Number | Gets a number that identifies the type of error. This number corresponds to the error numbers given in "Server Error Codes and Messages". |
Source (inherited from Exception) | Gets or sets the name of the application or the object that causes the error. |
StackTrace (inherited from Exception) | Gets a string representation of the frames on the call stack at the time the current exception was thrown. |
TargetSite (inherited from Exception) | Gets the method that throws the current exception. |
Public Instance Methods
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetBaseException (inherited from Exception) | When overridden in a derived class, returns the Exception that is the root cause of one or more subsequent exceptions. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetObjectData (inherited from Exception) | When overridden in a derived class, sets the SerializationInfo with information about the exception. |
GetType (inherited from Exception) | Gets the runtime type of the current instance. |
ToString (inherited from Exception) | Creates and returns a string representation of the current exception. |
See Also
MySqlException Class, MySql.Data.MySqlClient Namespace
Number Property
Gets a number that identifies the type of error.
Syntax: Visual Basic
Public ReadOnly Property Number As Integer
Syntax: C#
public int Number {get;}
See Also
MySqlException Class, MySql.Data.MySqlClient Namespace
MySqlHelper
Class
Helper class that makes it easier to work with the provider.
For a list of all members of this type, see MySqlHelper Members .
Syntax: Visual Basic
NotInheritable Public Class MySqlHelper
Syntax: C#
public sealed class MySqlHelper
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlHelper Members, MySql.Data.MySqlClient Namespace
MySqlHelper
Members
MySqlHelper.ExecuteDataRow
Method- ExecuteDataset Method
- ExecuteNonQuery Method
- ExecuteReader Method
- ExecuteScalar Method
MySqlHelper.UpdateDataSet
Method- ExecuteDataset Method
Public Static (Shared) Methods
ExecuteDataRow | Executes a single SQL statement and returns the first row of the resultset. A new MySqlConnection object is created, opened, and closed during this method. |
ExecuteDataset | Overloaded. Executes a single SQL statement and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method. |
ExecuteNonQuery | Overloaded. Executes a single command against a MariaDB database. The MySqlConnection is assumed to be open when the method is called and remains open after the method completes. |
ExecuteReader | Overloaded. Executes a single command against a MariaDB database. |
ExecuteScalar | Overloaded. Execute a single command against a MariaDB database. |
UpdateDataSet | Updates the given table with data from the given DataSet |
Public Instance Methods
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetType (inherited from Object) | Gets the Type of the current instance. |
ToString (inherited from Object) | Returns a String that represents the current Object. |
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace
MySqlHelper.ExecuteDataRow
Method
Executes a single SQL statement and returns the first row of the resultset. A new MySqlConnection object is created, opened, and closed during this method.
Syntax: Visual Basic
Public Shared Function ExecuteDataRow( _ ByVal connectionString As String, _ ByVal commandText As String, _ ParamArray parms As MySqlParameter() _ ) As DataRow
Syntax: C#
public static DataRow ExecuteDataRow( stringconnectionString, stringcommandText, params MySqlParameter[]parms );
Parameters
connectionString
: Settings to be used for the connectioncommandText
: Command to executeparms
: Parameters to use for the command
Return Value
DataRow containing the first row of the resultset
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace
ExecuteDataset Method
MySqlHelper.ExecuteDataset
MethodMySqlHelper.ExecuteDataset
MethodMySqlHelper.ExecuteDataset
MethodMySqlHelper.ExecuteDataset
Method
Executes a single SQL statement and returns the resultset in a DataSet. The state of the MySqlConnection object remains unchanged after execution of this method.
Overload List
Executes a single SQL statement and returns the resultset in a DataSet. The state of the MySqlConnection object remains unchanged after execution of this method.
Executes a single SQL statement and returns the resultset in a DataSet. The state of the MySqlConnection object remains unchanged after execution of this method.
Executes a single SQL statement and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method.
Executes a single SQL statement and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method.
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace
MySqlHelper.ExecuteDataset
Method
Executes a single SQL statement and returns the resultset in a DataSet. The state of the MySqlConnection object remains unchanged after execution of this method.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteDataset( _ ByVal connection As MySqlConnection, _ ByVal commandText As String _ ) As DataSet
Syntax: C#
public static DataSet ExecuteDataset( MySqlConnectionconnection, stringcommandText );
Parameters
connection
: MySqlConnection object to usecommandText
: Command to execute
Return Value
DataSetcontaining the resultset
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteDataset Overload List
MySqlHelper.ExecuteDataset
Method
Executes a single SQL statement and returns the resultset in a DataSet. The state of the MySqlConnection object remains unchanged after execution of this method.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteDataset( _ ByVal connection As MySqlConnection, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As DataSet
Syntax: C#
public static DataSet ExecuteDataset( MySqlConnectionconnection, stringcommandText, params MySqlParameter[]commandParameters );
Parameters
connection
: MySqlConnection object to usecommandText
: Command to executecommandParameters
: Parameters to use for the command
Return Value
DataSetcontaining the resultset
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteDataset Overload List
MySqlHelper.ExecuteDataset
Method
Executes a single SQL statement and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteDataset( _ ByVal connectionString As String, _ ByVal commandText As String _ ) As DataSet
Syntax: C#
public static DataSet ExecuteDataset( stringconnectionString, stringcommandText );
Parameters
connectionString
: Settings to be used for the connectioncommandText
: Command to execute
Return Value
DataSetcontaining the resultset
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteDataset Overload List
MySqlHelper.ExecuteDataset
Method
Executes a single SQL statement and returns the resultset in a DataSet. A new MySqlConnection object is created, opened, and closed during this method.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteDataset( _ ByVal connectionString As String, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As DataSet
Syntax: C#
public static DataSet ExecuteDataset( stringconnectionString, stringcommandText, params MySqlParameter[]commandParameters );
Parameters
connectionString
: Settings to be used for the connectioncommandText
: Command to executecommandParameters
: Parameters to use for the command
Return Value
DataSetcontaining the resultset
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteDataset Overload List
ExecuteNonQuery Method
Executes a single command against a MariaDB database. The MySqlConnection is assumed to be open when the method is called and remains open after the method completes.
Overload List
Executes a single command against a MariaDB database. The MySqlConnection is assumed to be open when the method is called and remains open after the method completes.
Executes a single command against a MariaDB database. A new MySqlConnection is created using the ConnectionString given.
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace
MySqlHelper.ExecuteNonQuery
Method
Executes a single command against a MariaDB database. The MySqlConnection is assumed to be open when the method is called and remains open after the method completes.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteNonQuery( _ ByVal connection As MySqlConnection, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As Integer
Syntax: C#
public static int ExecuteNonQuery( MySqlConnectionconnection, stringcommandText, params MySqlParameter[]commandParameters );
Parameters
connection
: MySqlConnection object to usecommandText
: SQL statement to be executedcommandParameters
: Array of MySqlParameter objects to use with the command.
Return Value
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteNonQuery Overload List
MySqlHelper.ExecuteNonQuery
Method
Executes a single command against a MariaDB database. A new MySqlConnection is created using the ConnectionString given.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteNonQuery( _ ByVal connectionString As String, _ ByVal commandText As String, _ ParamArray parms As MySqlParameter() _ ) As Integer
Syntax: C#
public static int ExecuteNonQuery( stringconnectionString, stringcommandText, params MySqlParameter[]parms );
Parameters
connectionString
: ConnectionString to usecommandText
: SQL statement to be executedparms
: Array of MySqlParameter objects to use with the command.
Return Value
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteNonQuery Overload List
ExecuteReader Method
Executes a single command against a MariaDB database.
Overload List
Executes a single command against a MariaDB database.
Executes a single command against a MariaDB database.
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace
MySqlHelper.ExecuteReader
Method
Executes a single command against a MariaDB database.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteReader( _ ByVal connectionString As String, _ ByVal commandText As String _ ) As MySqlDataReader
Syntax: C#
public static MySqlDataReader ExecuteReader( stringconnectionString, stringcommandText );
Parameters
connectionString
: Settings to use for this commandcommandText
: Command text to use
Return Value
MySqlDataReader object ready to read the results of the command
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteReader Overload List
MySqlHelper.ExecuteReader
Method
Executes a single command against a MariaDB database.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteReader( _ ByVal connectionString As String, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As MySqlDataReader
Syntax: C#
public static MySqlDataReader ExecuteReader( stringconnectionString, stringcommandText, params MySqlParameter[]commandParameters );
Parameters
connectionString
: Settings to use for this commandcommandText
: Command text to usecommandParameters
: Array of MySqlParameter objects to use with the command
Return Value
MySqlDataReader object ready to read the results of the command
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteReader Overload List
ExecuteScalar Method
MySqlHelper.ExecuteScalar
MethodMySqlHelper.ExecuteScalar
MethodMySqlHelper.ExecuteScalar
MethodMySqlHelper.ExecuteScalar
Method
Execute a single command against a MariaDB database.
Overload List
Execute a single command against a MariaDB database.
Execute a single command against a MariaDB database.
Execute a single command against a MariaDB database.
Execute a single command against a MariaDB database.
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace
MySqlHelper.ExecuteScalar
Method
Execute a single command against a MariaDB database.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteScalar( _ ByVal connection As MySqlConnection, _ ByVal commandText As String _ ) As Object
Syntax: C#
public static object ExecuteScalar( MySqlConnectionconnection, stringcommandText );
Parameters
connection
: MySqlConnection object to usecommandText
: Command text to use for the command
Return Value
The first column of the first row in the result set, or a null reference if the result set is empty.
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteScalar Overload List
MySqlHelper.ExecuteScalar
Method
Execute a single command against a MariaDB database.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteScalar( _ ByVal connection As MySqlConnection, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As Object
Syntax: C#
public static object ExecuteScalar( MySqlConnectionconnection, stringcommandText, params MySqlParameter[]commandParameters );
Parameters
connection
: MySqlConnection object to usecommandText
: Command text to use for the commandcommandParameters
: Parameters to use for the command
Return Value
The first column of the first row in the result set, or a null reference if the result set is empty.
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteScalar Overload List
MySqlHelper.ExecuteScalar
Method
Execute a single command against a MariaDB database.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteScalar( _ ByVal connectionString As String, _ ByVal commandText As String _ ) As Object
Syntax: C#
public static object ExecuteScalar( stringconnectionString, stringcommandText );
Parameters
connectionString
: Settings to use for the updatecommandText
: Command text to use for the update
Return Value
The first column of the first row in the result set, or a null reference if the result set is empty.
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteScalar Overload List
MySqlHelper.ExecuteScalar
Method
Execute a single command against a MariaDB database.
Syntax: Visual Basic
Overloads Public Shared Function ExecuteScalar( _ ByVal connectionString As String, _ ByVal commandText As String, _ ParamArray commandParameters As MySqlParameter() _ ) As Object
Syntax: C#
public static object ExecuteScalar( stringconnectionString, stringcommandText, params MySqlParameter[]commandParameters );
Parameters
connectionString
: Settings to use for the commandcommandText
: Command text to use for the commandcommandParameters
: Parameters to use for the command
Return Value
The first column of the first row in the result set, or a null reference if the result set is empty.
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace, MySqlHelper.ExecuteScalar Overload List
MySqlHelper.UpdateDataSet
Method
Updates the given table with data from the given DataSet
Syntax: Visual Basic
Public Shared Sub UpdateDataSet( _ ByVal connectionString As String, _ ByVal commandText As String, _ ByVal ds As DataSet, _ ByVal tablename As String _ )
Syntax: C#
public static void UpdateDataSet( stringconnectionString, stringcommandText, DataSetds, stringtablename );
Parameters
connectionString
: Settings to use for the updatecommandText
: Command text to use for the updateds
: DataSetcontaining the new data to use in the updatetablename
: Tablename in the data set to update
See Also
MySqlHelper Class, MySql.Data.MySqlClient Namespace
MySqlErrorCode
Enumeration
Syntax: Visual Basic
Public Enum MySqlErrorCode
Syntax: C#
public enum MySqlErrorCode
Members
Member Name | Description |
PacketTooLarge | |
PasswordNotAllowed | |
DuplicateKeyEntry | |
HostNotPrivileged | |
PasswordNoMatch | |
AnonymousUser | |
DuplicateKey | |
KeyNotFound | |
DuplicateKeyName |
Requirements
Namespace: MySql.Data.MySqlClient
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySql.Data.MySqlClient Namespace
MySql.Data.Types
Classes
Class | Description |
MySqlConversionException | Summary description for MySqlConversionException. |
MySqlDateTime | Summary description for MySqlDateTime. |
MySqlValue |
MySql.Data.TypesHierarchy
See Also
MySqlConversionException
Class
Summary description for MySqlConversionException.
For a list of all members of this type, see MySqlConversionException Members .
Syntax: Visual Basic
Public Class MySqlConversionException_ Inherits ApplicationException
Syntax: C#
public class MySqlConversionException : ApplicationException
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.Types
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlConversionException Members, MySql.Data.Types Namespace
MySqlConversionException
Members
MySqlConversionException overview
Public Instance Constructors
MySqlConversionException Constructor | Ctor |
Public Instance Properties
Data (inherited from Exception) | Gets a collection of key/value pairs that provide additional, user-defined information about the exception. |
HelpLink (inherited from Exception) | Gets or sets a link to the help file associated with this exception. |
InnerException (inherited from Exception) | Gets the Exceptioninstance that caused the current exception.
|
Message (inherited from Exception) | Gets a message that describes the current exception. |
Source (inherited from Exception) | Gets or sets the name of the application or the object that causes the error. |
StackTrace (inherited from Exception) | Gets a string representation of the frames on the call stack at the time the current exception was thrown. |
TargetSite (inherited from Exception) | Gets the method that throws the current exception. |
Public Instance Methods
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetBaseException (inherited from Exception) | When overridden in a derived class, returns the Exception that is the root cause of one or more subsequent exceptions. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetObjectData (inherited from Exception) | When overridden in a derived class, sets the SerializationInfo with information about the exception. |
GetType (inherited from Exception) | Gets the runtime type of the current instance. |
ToString (inherited from Exception) | Creates and returns a string representation of the current exception. |
Protected Instance Properties
HResult (inherited from Exception) | Gets or sets HRESULT , a coded numeric value that is assigned to a specific exception. |
Protected Instance Methods
Finalize (inherited from Object) | Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. |
MemberwiseClone (inherited from Object) | Creates a shallow copy of the current Object. |
See Also
MySqlConversionException Class, MySql.Data.Types Namespace
MySqlConversionException
Constructor
Syntax: Visual Basic
Public Sub New( _ ByVal msg As String _ )
Syntax: C#
public MySqlConversionException( stringmsg );
See Also
MySqlConversionException Class, MySql.Data.Types Namespace
MySqlDateTime
Class
Summary description for MySqlDateTime.
For a list of all members of this type, see MySqlDateTime Members .
Syntax: Visual Basic
Public Class MySqlDateTime_ Inherits MySqlValue_ Implements IConvertible, IComparable
Syntax: C#
public class MySqlDateTime : MySqlValue, IConvertible, IComparable
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.Types
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlDateTime Members, MySql.Data.Types Namespace
MySqlDateTime
Members
MySqlDateTime
ExplicitMySqlDateTime
toDateTime
Conversion- Day Property
- Hour Property
- IsNull Property
- IsValidDateTime Property
- Millisecond Property
- Minute Property
- Month Property
- Second Property
- Year Property
MySqlDateTime.GetDateTime
MethodMySqlDateTime.ToString
Method- Day Property
Public Static (Shared) Type Conversions
Explicit MySqlDateTime to DateTime Conversion |
Public Instance Properties
Day | Returns the day portion of this datetime |
Hour | Returns the hour portion of this datetime |
IsNull (inherited from MySqlValue) | |
IsValidDateTime | Indicates if this object contains a value that can be represented as a DateTime |
Minute | Returns the minute portion of this datetime |
Month | Returns the month portion of this datetime |
Second | Returns the second portion of this datetime |
Millisecond | Returns the millisecond portion of this datetime |
ValueAsObject (inherited from MySqlValue) | Returns the value of this field as an object |
Year | Returns the year portion of this datetime |
Public Instance Methods
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetDateTime | Returns this value as a DateTime |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetType (inherited from Object) | Gets the Type of the current instance. |
ToString | Returns a MySQL-specific string representation of this value |
Protected Instance Fields
classType (inherited from MySqlValue) | The system type represented by this value |
dbType (inherited from MySqlValue) | The generic dbtype of this value |
isNull (inherited from MySqlValue) | Is this value null |
mySqlDbType (inherited from MySqlValue) | The specific MariaDB db type |
mySqlTypeName (inherited from MySqlValue) | The MySQL-specific typename of this value |
objectValue (inherited from MySqlValue) |
Protected Instance Methods
Finalize (inherited from Object) | Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. |
MemberwiseClone (inherited from Object) | Creates a shallow copy of the current Object. |
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
MySqlDateTime
Explicit MySqlDateTime
to DateTime
Conversion
Syntax: Visual Basic
MySqlDateTime.op_Explicit(val)
Syntax: C#
public static explicit operator DateTime( MySqlDateTimeval );
Parameters
val
:
Return Value
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
Day Property
Returns the day portion of this datetime
Syntax: Visual Basic
Public Property Day As Integer
Syntax: C#
public int Day {get; set;}
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
Hour Property
Returns the hour portion of this datetime
Syntax: Visual Basic
Public Property Hour As Integer
Syntax: C#
public int Hour {get; set;}
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
IsNull Property
Syntax: Visual Basic
Public Property IsNull As Boolean
Syntax: C#
public bool IsNull {get; set;}
See Also
MySqlValue Class, MySql.Data.Types Namespace
MySqlValue
Class
For a list of all members of this type, see MySqlValue Members .
Syntax: Visual Basic
MustInherit Public Class MySqlValue
Syntax: C#
public abstract class MySqlValue
Thread Safety
Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.
Requirements
Namespace: MySql.Data.Types
Assembly: MySql.Data (in MySql.Data.dll)
See Also
MySqlValue Members, MySql.Data.Types Namespace
MySqlValue
Members
MySqlValue.numberFormat
FieldMySqlValue
Constructor- ValueAsObject Property
MySqlValue.ToString
MethodMySqlValue.classType
FieldMySqlValue.dbType
FieldMySqlValue.mySqlDbType
FieldMySqlValue.mySqlTypeName
FieldMySqlValue.objectValue
Field
Protected Static (Shared) Fields
numberFormat |
Public Instance Constructors
MySqlValue Constructor | Initializes a new instance of the MySqlValue class. |
Public Instance Properties
IsNull | |
ValueAsObject | Returns the value of this field as an object |
Public Instance Methods
Equals (inherited from Object) | Determines whether the specified Object is equal to the current Object. |
GetHashCode (inherited from Object) | Serves as a hash function for a particular type. GetHashCode is suitable for use in hashing algorithms and data structures like a hash table. |
GetType (inherited from Object) | Gets the Type of the current instance. |
ToString | Returns a string representation of this value |
Protected Instance Fields
classType | The system type represented by this value |
dbType | The generic dbtype of this value |
isNull | Is this value null |
mySqlDbType | The specific MariaDB db type |
mySqlTypeName | The MySQL-specific typename of this value |
objectValue |
Protected Instance Methods
Finalize (inherited from Object) | Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. |
MemberwiseClone (inherited from Object) | Creates a shallow copy of the current Object. |
See Also
MySqlValue Class, MySql.Data.Types Namespace
MySqlValue.numberFormat
Field
Syntax: Visual Basic
Protected Shared numberFormat As NumberFormatInfo
Syntax: C#
protected static NumberFormatInfo numberFormat;
See Also
MySqlValue Class, MySql.Data.Types Namespace
MySqlValue
Constructor
Initializes a new instance of the MySqlValue class.
Syntax: Visual Basic
Public Sub New()
Syntax: C#
public MySqlValue();
See Also
MySqlValue Class, MySql.Data.Types Namespace
ValueAsObject Property
Returns the value of this field as an object
Syntax: Visual Basic
Public ReadOnly Property ValueAsObject As Object
Syntax: C#
public object ValueAsObject {get;}
See Also
MySqlValue Class, MySql.Data.Types Namespace
MySqlValue.ToString
Method
Returns a string representation of this value
Syntax: Visual Basic
Overrides Public Function ToString() As String
Syntax: C#
public override string ToString();
See Also
MySqlValue Class, MySql.Data.Types Namespace
MySqlValue.classType
Field
The system type represented by this value
Syntax: Visual Basic
Protected classType As Type
Syntax: C#
protected Type classType;
See Also
MySqlValue Class, MySql.Data.Types Namespace
MySqlValue.dbType
Field
The generic dbtype of this value
Syntax: Visual Basic
Protected dbType As DbType
Syntax: C#
protected DbType dbType;
See Also
MySqlValue Class, MySql.Data.Types Namespace
MySqlValue.mySqlDbType
Field
The specific MariaDB db type
Syntax: Visual Basic
Protected mySqlDbType As MySqlDbType
Syntax: C#
protected MySqlDbType mySqlDbType;
See Also
MySqlValue Class, MySql.Data.Types Namespace
MySqlValue.mySqlTypeName
Field
The MySQL-specific typename of this value
Syntax: Visual Basic
Protected mySqlTypeName As String
Syntax: C#
protected string mySqlTypeName;
See Also
MySqlValue Class, MySql.Data.Types Namespace
MySqlValue.objectValue
Field
Syntax: Visual Basic
Protected objectValue As Object
Syntax: C#
protected object objectValue;
See Also
MySqlValue Class, MySql.Data.Types Namespace
IsValidDateTime Property
Indicates if this object contains a value that can be represented as a DateTime
Syntax: Visual Basic
Public ReadOnly Property IsValidDateTime As Boolean
Syntax: C#
public bool IsValidDateTime {get;}
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
Millisecond Property
Returns the millisecond portion of this datetime
Syntax: Visual Basic
Public Property Millisecond As Integer
Syntax: C#
public int Millisecond {get; set;}
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
Minute Property
Returns the minute portion of this datetime
Syntax: Visual Basic
Public Property Minute As Integer
Syntax: C#
public int Minute {get; set;}
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
Month Property
Returns the month portion of this datetime
Syntax: Visual Basic
Public Property Month As Integer
Syntax: C#
public int Month {get; set;}
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
Second Property
Returns the second portion of this datetime
Syntax: Visual Basic
Public Property Second As Integer
Syntax: C#
public int Second {get; set;}
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
Year Property
Returns the year portion of this datetime
Syntax: Visual Basic
Public Property Year As Integer
Syntax: C#
public int Year {get; set;}
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
MySqlDateTime.GetDateTime
Method
Returns this value as a DateTime
Syntax: Visual Basic
Public Function GetDateTime() As Date
Syntax: C#
public DateTime GetDateTime();
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
MySqlDateTime.ToString
Method
Returns a MySQL-specific string representation of this value
Syntax: Visual Basic
Overrides Public Function ToString() As String
Syntax: C#
public override string ToString();
See Also
MySqlDateTime Class, MySql.Data.Types Namespace
Connector/Net Support
- Connector/Net Community Support
- How to Report Connector/Net Problems or Bugs
- Connector/Net Change History
- How to Report Connector/Net Problems or Bugs
The developers of Connector/Net greatly value the input of our users in the software development process. If you find Connector/Net lacking some feature important to you, or if you discover a bug and need to file a bug report, please use the instructions in , "How to Report Bugs or Problems".
Connector/Net Community Support
- Community support for Connector/Net can be found through the forums at http://forums.mysql.com.
- Community support for Connector/Net can also be found through the mailing lists at http://lists.mysql.com.
- Paid support is available from Oracle. Additional information is available at http://dev.mysql.com/support/.
How to Report Connector/Net Problems or Bugs
If you encounter difficulties or problems with Connector/Net, contact the Connector/Net community, as explained in , "Connector/Net Community Support".
First try to execute the same SQL statements and commands from the mysql client program or from admndemo
. This helps you determine whether the error is in Connector/Net or MySQL.
If reporting a problem, ideally include the following information with the email:
- Operating system and version.
- Connector/Net version.
- MySQL server version.
- Copies of error messages or other unexpected output.
- Simple reproducible sample.
Remember that the more information you can supply to us, the more likely it is that we can fix the problem.
If you believe the problem to be a bug, then you must report the bug through https://jira.mariadb.org/.
Connector/Net Change History
The Connector/Net Change History (Changelog) is located with the main Changelog for MySQL. See "MySQL Connector/Net Change History".
Connector/Net FAQ
Questions
- : How do I obtain the value of an auto-incremented column?
Questions and Answers
21.2.9.1: How do I obtain the value of an auto-incremented column?
When using CommandBuilder
, setting ReturnGeneratedIdentifiers
property to true
no longer works, as CommandBuilder
does not add last_insert_id()
by default.
CommandBuilder hooks up to the DataAdapter.RowUpdating
event handler, which means it will get called for every row. It examines the command object and, if it is the same referenced object, it essentially rebuilds the object, thereby destroying your command text changes.
One approach to solving this problem is to clone the command object so you have a different actual reference:
dataAdapter.InsertCommand = cb.GetInsertCommand().Clone()
This will work, but since the CommandBuilder is still connected to the DataAdapter, the RowUpdating event will still fire and performance will be hit. To stop that, once all your commands have been added you need to disconnect the CommandBuilder from the DataAdapter:
cb.DataAdapter = null;
The last requirement is to make sure the id
that is returned by last_insert_id()
has the correct name. For example:
SELECT last_insert_id() AS id
A complete working example is shown here:
using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using MySql.Data; using MySql.Data.MySqlClient; namespace GetAutoIncId { class Program { static void Main(string[] args) { string connStr = 'server=localhost;user=root;database=TestDB;port=3306;password=******;'; MySqlConnection conn = new MySqlConnection(connStr); try { Console.WriteLine('Connecting to MariaDB...'); conn.Open(); string sql = 'SELECT * FROM TestTable'; MySqlDataAdapter da = new MySqlDataAdapter(sql, conn); MySqlCommandBuilder cb = new MySqlCommandBuilder(da); MySqlCommand cmd = new MySqlCommand(); cmd.Connection = conn; cmd.CommandText = sql; // use Cloned object to avoid .NET rebuilding the object, and // thereby throwing away our command text additions. MySqlCommand insertCmd = cb.GetInsertCommand().Clone(); insertCmd.CommandText = insertCmd.CommandText + ';SELECT last_insert_id() AS id'; insertCmd.UpdatedRowSource = UpdateRowSource.FirstReturnedRecord; da.InsertCommand = insertCmd; cb.DataAdapter = null; // Unhook RowUpdating event handler DataTable dt = new DataTable(); da.Fill(dt); DataRow row = dt.NewRow(); row['name'] = 'Joe Smith'; dt.Rows.Add(row); da.Update(dt); System.Console.WriteLine('ID after update: ' + row['id']); } catch (Exception ex) { Console.WriteLine(ex.ToString()); } conn.Close(); Console.WriteLine('Done.'); } } }
MySQL Connector/J
- Overview of MariaDB Connector/J
- Connector/J Versions
- Connector/J Installation
- Connector/J Examples
- Connector/J (JDBC) Reference
- JDBC Concepts
- J2EE Concepts
- Using Connector/J with Tomcat
- Using Connector/J with JBoss
- Using Connector/J with Spring
- Using Connector/J with GlassFish
- Troubleshooting Connector/J
- Connector/J Support
- Connector/J Versions
Overview of MariaDB Connector/J
MySQL provides connectivity for client applications developed in the Java programming language through a JDBC driver, which is called MariaDB Connector/J.
MySQL Connector/J is a JDBC Type 4 driver. Different versions are available that are compatible with the JDBC 3.0 and JDBC 4.0 specifications. The Type 4 designation means that the driver is pure-Java implementation of the MariaDB protocol and does not rely on the MariaDB client libraries.
For large-scale programs that use common design patterns of data access, consider using one of the popular persistence frameworks such as Hibernate, Spring's JDBC templates or Ibatis SQL Maps to reduce the amount of JDBC code for you to debug, tune, secure, and maintain.
This section is not designed to be a complete JDBC tutorial. If you need more information about using JDBC you might be interested in the following online tutorials that are more in-depth than the information presented here:
- JDBC Basics: A tutorial from Sun covering beginner topics in JDBC
- JDBC Short Course: A more in-depth tutorial from Sun and JGuru
Key Topics
- For help with connection strings, connection options, and setting up your connection through JDBC, see , "Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J".
Connector/J Versions
There are currently four versions of MariaDB Connector/J available:
- Connector/J 5.1 is the Type 4 pure Java JDBC driver, which conforms to the JDBC 3.0 and JDBC 4.0 specifications. It provides compatibility with all the functionality of MySQL, including 4.1, 5.0, 5.1, 5.4 and 5.5. Connector/J 5.1 provides ease of development features, including auto-registration with the Driver Manager, standardized validity checks, categorized SQLExceptions, support for the JDBC-4.0 XML processing, per connection client information,
NCHAR
,NVARCHAR
andNCLOB
types. This release also includes all bug fixes up to and including Connector/J 5.0.6. - Connector/J 5.0 provides support for all the functionality offered by Connector/J 3.1 and includes distributed transaction (XA) support.
- Connector/J 3.1 was designed for connectivity to MariaDB and MariaDB 5.0 servers and provides support for all the functionality in MariaDB 5.0 except distributed transaction (XA) support.
- Connector/J 3.0 provides core functionality and was designed with connectivity to MariaDB 3.x or MariaDB servers, although it will provide basic compatibility with later versions of MySQL. Connector/J 3.0 does not support server-side prepared statements, and does not support any of the features in versions of MariaDB later than 4.1.
The following table summarizes the Connector/J versions available:
Connector/J version | Driver Type | JDBC version | MySQL Server version | Status |
---|---|---|---|---|
5.1 | 4 | 3.0, 4.0 | 4.1, 5.0, 5.1, 5.4, 5.5 | Recommended version |
5.0 | 4 | 3.0 | 4.1, 5.0 | Released version |
3.1 | 4 | 3.0 | 4.1, 5.0 | Obsolete |
3.0 | 4 | 3.0 | 3.x, 4.1 | Obsolete |
The current recommended version for Connector/J is 5.1. This guide covers all four connector versions, with specific notes given where a setting applies to a specific option.
Java Versions Supported
The following table summarizes Connector/J Java dependencies:
Connector/J version | Java RTE required | JDK required (to build source code) |
---|---|---|
5.1 | 1.5.x, 1.6.x | 1.6.x and 1.5.x |
5.0 | 1.3.x, 1.4.x, 1.5.x, 1.6.x | 1.4.2, 1.5.x, 1.6.x |
3.1 | 1.2.x, 1.3.x, 1.4.x, 1.5.x, 1.6.x | 1.4.2, 1.5.x, 1.6.x |
3.0 | 1.2.x, 1.3.x, 1.4.x, 1.5.x, 1.6.x | 1.4.2, 1.5.x, 1.6.x |
MySQL Connector/J does not support JDK-1.1.x or JDK-1.0.x.
Because of the implementation of java.sql.Savepoint
, Connector/J 3.1.0 and newer will not run on a Java runtime older than 1.4 unless the class verifier is turned off (by setting the -Xverify:none
option to the Java runtime). This is because the class verifier will try to load the class definition for java.sql.Savepoint
even though it is not accessed by the driver unless you actually use savepoint functionality.
Caching functionality provided by Connector/J 3.1.0 or newer is also not available on JVMs older than 1.4.x, as it relies on java.util.LinkedHashMap
which was first available in JDK-1.4.0.
If you are building Connector/J from source code using the source distribution (see , "Installing from the Development Source Tree"), you must use JDK 1.4.2 or newer to compile the Connector package. For Connector/J 5.1, you must have both JDK-1.6.x and JDK-1.5.x installed to be able to build the source code.
Connector/J Installation
- Installing Connector/J from a Binary Distribution
- Installing the Driver and Configuring the
CLASSPATH
- Upgrading from an Older Version
- Installing from the Development Source Tree
- Installing the Driver and Configuring the
You can install the Connector/J package using either the binary or source distribution. The binary distribution provides the easiest method for installation; the source distribution lets you customize your installation further. With either solution, you manually add the Connector/J location to your Java CLASSPATH
.
If you are upgrading from a previous version, read the upgrade information in , "Upgrading from an Older Version" before continuing.
Connector/J is also available as part of the Maven project. For more information, and to download the Connector/J JAR files, see the Maven repository.
Installing Connector/J from a Binary Distribution
For the easiest method of installation, use the binary distribution of the Connector/J package. The binary distribution is available either as a tar/gzip or zip file. Extract it to a suitable location, then optionally make the information about the package available by changing your CLASSPATH
(see , "Installing the Driver and Configuring the CLASSPATH
").
MySQL Connector/J is distributed as a .zip
or .tar.gz
archive containing the sources, the class files, and the JAR archive named mysql-connector-java-
.
[version]
-bin.jar
Starting with Connector/J 3.1.9, the .class
files that constitute the JAR files are only included as part of the driver JAR file.
Starting with Connector/J 3.1.8, the archive also includes a debug build of the driver in a file named mysql-connector-java-
. Do not use the debug build of the driver unless instructed to do so when reporting a problem or a bug, as it is not designed to be run in production environments, and will have adverse performance impact when used. The debug binary also depends on the Aspect/J runtime library, which is located in the [version]
-bin-g.jarsrc/lib/aspectjrt.jar
file that comes with the Connector/J distribution.
Use the appropriate graphical or command-line utility to extract the distribution (for example, WinZip for the .zip archive, and tar for the .tar.gz archive). Because there are potentially long file names in the distribution, we use the GNU tar archive format. Use GNU tar (or an application that understands the GNU tar archive format) to unpack the .tar.gz variant of the distribution.
Installing the Driver and Configuring the CLASSPATH
Once you have extracted the distribution archive, you can install the driver by placing mysql-connector-java-[version]-bin.jar
in your classpath, either by adding the full path to it to your CLASSPATH
environment variable, or by directly specifying it with the command line switch -cp
when starting the JVM.
To use the driver with the JDBC DriverManager, use com.mysql.jdbc.Driver
as the class that implements java.sql.Driver
.
You can set the CLASSPATH
environment variable under UNIX, Linux or Mac OS X either locally for a user within their .profile
, .login
or other login file. You can also set it globally by editing the global /etc/profile
file.
For example, add the Connector/J driver to your CLASSPATH
using one of the following forms, depending on your command shell:
# Bourne-compatible shell (sh, ksh, bash, zsh): shell> export CLASSPATH=/path/mysql-connector-java-[ver]-bin.jar:$CLASSPATH # C shell (csh, tcsh): shell> setenv CLASSPATH /path/mysql-connector-java-[ver]-bin.jar:$CLASSPATH
Within Windows 2000, Windows XP, Windows Server 2003 and Windows Vista, you set the environment variable through the System Control Panel.
To use MariaDB Connector/J with an application server such as GlassFish, Tomcat or JBoss, read your vendor's documentation for more information on how to configure third-party class libraries, as most application servers ignore the CLASSPATH
environment variable. For configuration examples for some J2EE application servers, see , "J2EE Concepts". However, the authoritative source for JDBC connection pool configuration information for your particular application server is the documentation for that application server.
If you are developing servlets or JSPs, and your application server is J2EE-compliant, you can put the driver's .jar
file in the WEB-INF/lib
subdirectory of your webapp, as this is a standard location for third party class libraries in J2EE web applications.
You can also use the MysqlDataSource
or MysqlConnectionPoolDataSource
classes in the com.mysql.jdbc.jdbc2.optional
package, if your J2EE application server supports or requires them. Starting with Connector/J 5.0.0, the javax.sql.XADataSource
interface is implemented using the com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
class, which supports XA distributed transactions when used in combination with MariaDB server version 5.0.
The various MysqlDataSource
classes support the following parameters (through standard set mutators):
user
password
serverName
(see the previous section about fail-over hosts)databaseName
port
Upgrading from an Older Version
- Upgrading from MariaDB Connector/J 3.0 to 3.1
- Upgrading to MariaDB Connector/J 5.1.x
- JDBC-Specific Issues When Upgrading to MariaDB Server 4.1 or Newer
- Upgrading to MariaDB Connector/J 5.1.x
This section has information for users who are upgrading from one version of Connector/J to another, or to a new version of the MariaDB server that supports a more recent level of JDBC. A newer version of Connector/J might include changes to support new features, improve existing functionality, or comply with new standards.
Upgrading from MariaDB Connector/J 3.0 to 3.1
Connector/J 3.1 is designed to be backward-compatible with Connector/J 3.0 as much as possible. Major changes are isolated to new functionality exposed in MySQL-4.1 and newer, which includes Unicode character sets, server-side prepared statements, SQLState
codes returned in error messages by the server and various performance enhancements that can be enabled or disabled using configuration properties.
- Unicode Character Sets: See the next section, as well as , "Character Set Support", for information on this MariaDB feature. If you have something misconfigured, it will usually show up as an error with a message similar to
Illegal mix of collations
. - Server-side Prepared Statements: Connector/J 3.1 will automatically detect and use server-side prepared statements when they are available (MySQL server version 4.1.0 and newer).
Starting with version 3.1.7, the driver scans SQL you are preparing using all variants of
Connection.prepareStatement()
to determine if it is a supported type of statement to prepare on the server side, and if it is not supported by the server, it instead prepares it as a client-side emulated prepared statement. You can disable this feature by passing emulateUnsupportedPstmts=false in your JDBC URL.If your application encounters issues with server-side prepared statements, you can revert to the older client-side emulated prepared statement code that is still presently used for MariaDB servers older than 4.1.0 with the connection property useServerPrepStmts=false.
- Datetimes with all-zero components (
0000-00-00 ...
): These values cannot be represented reliably in Java. Connector/J 3.0.x always converted them toNULL
when being read from a ResultSet.Connector/J 3.1 throws an exception by default when these values are encountered, as this is the most correct behavior according to the JDBC and SQL standards. This behavior can be modified using the zeroDateTimeBehavior configuration property. The permissible values are:
exception
(the default), which throws an SQLException with an SQLState ofS1009
.convertToNull
, which returnsNULL
instead of the date.round
, which rounds the date to the nearest closest value which is0001-01-01
.
Starting with Connector/J 3.1.7,
ResultSet.getString()
can be decoupled from this behavior using noDatetimeStringSync=true (the default value isfalse
) so that you can retrieve the unaltered all-zero value as a String. Note that this also precludes using any time zone conversions, therefore the driver will not allow you to enable noDatetimeStringSync and useTimezone at the same time. - New SQLState Codes: Connector/J 3.1 uses SQL:1999 SQLState codes returned by the MariaDB server (if supported), which are different from the legacy X/Open state codes that Connector/J 3.0 uses. If connected to a MariaDB server older than MySQL-4.1.0 (the oldest version to return SQLStates as part of the error code), the driver will use a built-in mapping. You can revert to the old mapping by using the configuration property useSqlStateCodes=false.
ResultSet.getString()
: CallingResultSet.getString()
on aBLOB
column will now return the address of thebyte[]
array that represents it, instead of aString
representation of theBLOB
.BLOB
values have no character set, so they cannot be converted tojava.lang.String
s without data loss or corruption.To store strings in MariaDB with LOB behavior, use one of the
TEXT
types, which the driver will treat as ajava.sql.Clob
.- Debug builds: Starting with Connector/J 3.1.8 a debug build of the driver in a file named
mysql-connector-java-
is shipped alongside the normal binary jar file that is named[version]
-bin-g.jarmysql-connector-java-
.[version]
-bin.jarStarting with Connector/J 3.1.9, we do not ship the
.class
files unbundled, they are only available in the JAR archives that ship with the driver.Do not use the debug build of the driver unless instructed to do so when reporting a problem or bug, as it is not designed to be run in production environments, and will have adverse performance impact when used. The debug binary also depends on the Aspect/J runtime library, which is located in the
src/lib/aspectjrt.jar
file that comes with the Connector/J distribution.
Upgrading to MariaDB Connector/J 5.1.x
- In Connector/J 5.0.x and earlier, the alias for a table in a
SELECT
statement is returned when accessing the result set metadata usingResultSetMetaData.getColumnName()
. This behavior however is not JDBC compliant, and in Connector/J 5.1 this behavior was changed so that the original table name, rather than the alias, is returned.
The JDBC-compliant behavior is designed to let API users reconstruct the DML statement based on the metadata within
ResultSet
andResultSetMetaData
.You can get the alias for a column in a result set by calling
ResultSetMetaData.getColumnLabel()
. To use the old noncompliant behavior withResultSetMetaData.getColumnName()
, use theuseOldAliasMetadataBehavior
option and set the value totrue
.In Connector/J 5.0.x the default value of
useOldAliasMetadataBehavior
wastrue
, but in Connector/J 5.1 this was changed to a default value offalse
.
JDBC-Specific Issues When Upgrading to MariaDB Server 4.1 or Newer
- Using the UTF-8 Character Encoding - Prior to MariaDB server version 4.1, the UTF-8 character encoding was not supported by the server, however the JDBC driver could use it, allowing storage of multiple character sets in
latin1
tables on the server.
Starting with MySQL-4.1, this functionality is deprecated. If you have applications that rely on this functionality, and can not upgrade them to use the official Unicode character support in MariaDB server version 4.1 or newer, add the following property to your connection URL:
useOldUTF8Behavior=true
- Server-side Prepared Statements - Connector/J 3.1 will automatically detect and use server-side prepared statements when they are available (MySQL server version 4.1.0 and newer). If your application encounters issues with server-side prepared statements, you can revert to the older client-side emulated prepared statement code that is still presently used for MariaDB servers older than 4.1.0 with the following connection property:
useServerPrepStmts=false
Installing from the Development Source Tree
CautionRead this section only if you are interested in helping us test our new code. To just get MariaDB Connector/J up and running on your system, use a standard binary release distribution.
To install MariaDB Connector/J from the development source tree, make sure that you have the following prerequisites:
- A Bazaar client, to check out the sources from our Launchpad repository (available from http://bazaar-vcs.org/).
- Apache Ant version 1.7 or newer (available from http://ant.apache.org/).
- JDK 1.4.2 or later. Although MariaDB Connector/J can be be used with older JDKs, compiling it from source requires at least JDK 1.4.2. To build Connector/J 5.1 requires JDK 1.6.x and an older JDK such as JDK 1.5.x; point your
JAVA_HOME
environment variable at the older installation.
To check out and compile a specific branch of MariaDB Connector/J, follow these steps:
- Check out the latest code from the branch that you want with one of the following commands.
The source code repository for MariaDB Connector/J is located on Launchpad at https://code.launchpad.net/connectorj. To check out the latest development branch, use:
shell>
bzr branch lp:connectorj
iThis creates a
connectorj
subdirectory in the current directory that contains the latest sources for the requested branch.To check out the latest 5.1 code, use:
shell>
bzr branch lp:connectorj/5.1
This creates a
5.1
subdirectory in the current directory containing the latest 5.1 code. - To build Connector/J 5.1, make sure that you have both JDK 1.6.x installed and an older JDK such as JDK 1.5.x. This is because Connector/J supports both JDBC 3.0 (which was prior to JDK 1.6.x) and JDBC 4.0. Set your
JAVA_HOME
environment variable to the path of the older JDK installation. - Change your current working directory to either the
connectorj
or5.1
directory, depending on which branch you intend to build. - To build Connector/J 5.1, edit the
build.xml
to reflect the location of your JDK 1.6.x installation. The lines to change are:<property name="com.mysql.jdbc.java6.javac" value="C:\jvms\jdk1.6.0\bin\javac.exe" /> <property name="com.mysql.jdbc.java6.rtjar" value="C:\jvms\jdk1.6.0\jre\lib\rt.jar" />
Alternatively, you can set the value of these property names through the Ant
-D
option. - Issue the following command to compile the driver and create a
.jar
file suitable for installation:shell>
ant dist
This creates a
build
directory in the current directory, where all build output will go. A directory is created in thebuild
directory that includes the version number of the sources you are building from. This directory contains the sources, compiled.class
files, and a.jar
file suitable for deployment. For other possible targets, including ones that will create a fully packaged distribution, issue the following command:shell>
ant -projecthelp
- A newly created
.jar
file containing the JDBC driver will be placed in the directorybuild/mysql-connector-java-
.[version]
Install the newly created JDBC driver as you would a binary
.jar
file that you download from MySQL, by following the instructions in , "Installing the Driver and Configuring theCLASSPATH
".
A package containing both the binary and source code for Connector/J 5.1 can also be found at the following location: Connector/J 5.1 Download
Connector/J Examples
Examples of using Connector/J are located throughout this document. This section provides a summary and links to these examples.
- Example 20.1, "Connector/J: Obtaining a connection from the
DriverManager
" - Example 20.2, "Connector/J: Using java.sql.Statement to execute a
SELECT
query" - Example 20.3, "Connector/J: Calling Stored Procedures"
- Example 20.4, "Connector/J: Using
Connection.prepareCall()
" - Example 20.5, "Connector/J: Registering output parameters"
- Example 20.6, "Connector/J: Setting
CallableStatement
input parameters" - Example 20.7, "Connector/J: Retrieving results and output parameter values"
- Example 20.8, "Connector/J: Retrieving
AUTO_INCREMENT
column values usingStatement.getGeneratedKeys()
" - Example 20.9, "Connector/J: Retrieving
AUTO_INCREMENT
column values usingSELECT LAST_INSERT_ID()
" - Example 20.10, "Connector/J: Retrieving
AUTO_INCREMENT
column values inUpdatable ResultSets
" - Example 20.11, "Connector/J: Using a connection pool with a J2EE application server"
- Example 20.12, "Connector/J: Example of transaction with retry logic"
Connector/J (JDBC) Reference
- Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J
- JDBC API Implementation Notes
- Java, JDBC and MariaDB Types
- Using Character Sets and Unicode
- Connecting Securely Using SSL
- Using Master/Slave Replication with ReplicationConnection
- Mapping MariaDB Error Numbers to SQLStates
- JDBC API Implementation Notes
This section of the manual contains reference material for MariaDB Connector/J, some of which is automatically generated during the Connector/J build process.
Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J
The name of the class that implements java.sql.Driver in MariaDB Connector/J is com.mysql.jdbc.Driver
. The org.gjt.mm.mysql.Driver
class name is also usable to remain backward-compatible with MM.MySQL. Use this class name when registering the driver, or when otherwise configuring software to use MariaDB Connector/J.
The JDBC URL format for MariaDB Connector/J is as follows, with items in square brackets ([, ]) being optional:
jdbc:mysql://[host][,failoverhost...][:port]/[database] » [?propertyName1][=propertyValue1][&propertyName2][=propertyValue2]...
If the host name is not specified, it defaults to 127.0.0.1
. If the port is not specified, it defaults to 3306
, the default port number for MariaDB servers.
jdbc:mysql://[host:port],[host:port].../[database] » [?propertyName1][=propertyValue1][&propertyName2][=propertyValue2]...
Here is a sample connection URL:
jdbc:mysql://localhost:3306/sakila?profileSQL=true
If the database is not specified, the connection is made with no default database. In this case, either call the setCatalog()
method on the Connection instance, or fully specify table names using the database name (that is, SELECT dbname.tablename.colname FROM dbname.tablename...
) in your SQL. Not specifying the database to use upon connection is generally only useful when building tools that work with multiple databases, such as GUI database managers.Note
Always use the Connection.setCatalog()
method to specify the desired database in JDBC applications, rather than the USE
statement.
database
MySQL Connector/J has fail-over support. This enables the driver to fail-over to any number of slave hosts and still perform read-only queries. Fail-over only happens when the connection is in an autoCommit(true)
state, because fail-over can not happen reliably when a transaction is in progress. Most application servers and connection pools set autoCommit
to true
at the end of every transaction/connection use.
The fail-over functionality has the following behavior:
- If the URL property autoReconnect is false: Failover only happens at connection initialization, and failback occurs when the driver determines that the first host has become available again.
- If the URL property autoReconnect is true: Failover happens when the driver determines that the connection has failed (before every query), and falls back to the first host when it determines that the host has become available again (after
queriesBeforeRetryMaster
queries have been issued).
In either case, whenever you are connected to a 'failed-over' server, the connection will be set to read-only state, so queries that would modify data will have exceptions thrown (the query will never be processed by the MariaDB server).
Configuration properties define how Connector/J will make a connection to a MariaDB server. Unless otherwise noted, properties can be set for a DataSource
object or for a Connection
object.
Configuration properties can be set in one of the following ways:
- Using the
set*()
methods on MariaDB implementations ofjava.sql.DataSource
(which is the preferred method when using implementations ofjava.sql.DataSource
):
com.mysql.jdbc.jdbc2.optional.MysqlDataSource
com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource
- As a key/value pair in the java.util.Properties instance passed to
DriverManager.getConnection()
orDriver.connect()
- As a JDBC URL parameter in the URL given to
java.sql.DriverManager.getConnection()
,java.sql.Driver.connect()
or the MariaDB implementations of thejavax.sql.DataSource
setURL()
method.NoteIf the mechanism you use to configure a JDBC URL is XML-based, use the XML character literal & to separate configuration parameters, as the ampersand is a reserved character for XML.
The properties are listed in the following tables.
Connection/Authentication.
Property Name | Definition | Default Value | Since Version |
user | The user to connect as | all versions | |
password | The password to use when connecting | all versions | |
socketFactory | The name of the class that the driver should use for creating socket connections to the server. This class must implement the interface 'com.mysql.jdbc.SocketFactory' and have public no-args constructor. | com.mysql.jdbc.StandardSocketFactory | 3.0.3 |
connectTimeout | Timeout for socket connect (in milliseconds), with 0 being no timeout. Only works on JDK-1.4 or newer. Defaults to '0'. | 0 | 3.0.1 |
socketTimeout | Timeout on network socket operations (0, the default means no timeout). | 0 | 3.0.1 |
connectionLifecycleInterceptors | A comma-delimited list of classes that implement 'com.mysql.jdbc.ConnectionLifecycleInterceptor' that should notified of connection lifecycle events (creation, destruction, commit, rollback, setCatalog and setAutoCommit) and potentially alter the execution of these commands. ConnectionLifecycleInterceptors are 'stackable', more than one interceptor may be specified via the configuration property as a comma-delimited list, with the interceptors executed in order from left to right. | 5.1.4 | |
useConfigs | Load the comma-delimited list of configuration properties before parsing the URL or applying user-specified properties. These configurations are explained in the 'Configurations' of the documentation. | 3.1.5 | |
authenticationPlugins | Comma-delimited list of classes that implement com.mysql.jdbc.AuthenticationPlugin and which will be used for authentication unless disabled by 'disabledAuthenticationPlugins' property. | 5.1.19 | |
defaultAuthenticationPlugin | Name of a class implementing com.mysql.jdbc.AuthenticationPlugin which will be used as the default authentication plugin (see below). It is an error to use a class which is not listed in 'authenticationPlugins' nor it is one of the built-in plugins. It is an error to set as default a plugin which was disabled with 'disabledAuthenticationPlugins' property. It is an error to set this value to null or the empty string (i.e. there must be at least a valid default authentication plugin specified for the connection, meeting all constraints listed above). | com.mysql.jdbc.authentication.MysqlNativePasswordPlugin | 5.1.19 |
disabledAuthenticationPlugins | Comma-delimited list of classes implementing com.mysql.jdbc.AuthenticationPlugin or mechanisms, i.e. 'mysql_native_password'. The authentication plugins or mechanisms listed will not be used for authentication which will fail if it requires one of them. It is an error to disable the default authentication plugin (either the one named by 'defaultAuthenticationPlugin' property or the hard-coded one if 'defaultAuthenticationPlugin' propery is not set). | 5.1.19 | |
interactiveClient | Set the CLIENT_INTERACTIVE flag, which tells MariaDB to timeout connections based on INTERACTIVE_TIMEOUT instead of WAIT_TIMEOUT | false | 3.1.0 |
localSocketAddress | Hostname or IP address given to explicitly configure the interface that the driver will bind the client side of the TCP/IP connection to when connecting. | 5.0.5 | |
propertiesTransform | An implementation of com.mysql.jdbc.ConnectionPropertiesTransform that the driver will use to modify URL properties passed to the driver before attempting a connection | 3.1.4 | |
useCompression | Use zlib compression when communicating with the server (true/false)? Defaults to 'false'. | false | 3.0.17 |
Networking.
Property Name | Definition | Default Value | Since Version |
maxAllowedPacket | Maximum allowed packet size to send to server. If not set, the value of system variable 'max_allowed_packet' will be used to initialize this upon connecting. This value will not take effect if set larger than the value of 'max_allowed_packet'. | -1 | 5.1.8 |
tcpKeepAlive | If connecting using TCP/IP, should the driver set SO_KEEPALIVE? | true | 5.0.7 |
tcpNoDelay | If connecting using TCP/IP, should the driver set SO_TCP_NODELAY (disabling the Nagle Algorithm)? | true | 5.0.7 |
tcpRcvBuf | If connecting using TCP/IP, should the driver set SO_RCV_BUF to the given value? The default value of '0', means use the platform default value for this property) | 0 | 5.0.7 |
tcpSndBuf | If connecting using TCP/IP, should the driver set SO_SND_BUF to the given value? The default value of '0', means use the platform default value for this property) | 0 | 5.0.7 |
tcpTrafficClass | If connecting using TCP/IP, should the driver set traffic class or type-of-service fields ?See the documentation for java.net.Socket.setTrafficClass() for more information. | 0 | 5.0.7 |
High Availability and Clustering.
Property Name | Definition | Default Value | Since Version |
autoReconnect | Should the driver try to re-establish stale and/or dead connections? If enabled the driver will throw an exception for a queries issued on a stale or dead connection, which belong to the current transaction, but will attempt reconnect before the next query issued on the connection in a new transaction. The use of this feature is not recommended, because it has side effects related to session state and data consistency when applications don't handle SQLExceptions properly, and is only designed to be used when you are unable to configure your application to handle SQLExceptions resulting from dead and stale connections properly. Alternatively, as a last option, investigate setting the MariaDB server variable 'wait_timeout' to a high value, rather than the default of 8 hours. | false | 1.1 |
autoReconnectForPools | Use a reconnection strategy appropriate for connection pools (defaults to 'false') | false | 3.1.3 |
failOverReadOnly | When failing over in autoReconnect mode, should the connection be set to 'read-only'? | true | 3.0.12 |
maxReconnects | Maximum number of reconnects to attempt if autoReconnect is true, default is '3'. | 3 | 1.1 |
reconnectAtTxEnd | If autoReconnect is set to true, should the driver attempt reconnections at the end of every transaction? | false | 3.0.10 |
retriesAllDown | When using loadbalancing, the number of times the driver should cycle through available hosts, attempting to connect. Between cycles, the driver will pause for 250ms if no servers are available. | 120 | 5.1.6 |
initialTimeout | If autoReconnect is enabled, the initial time to wait between re-connect attempts (in seconds, defaults to '2'). | 2 | 1.1 |
roundRobinLoadBalance | When autoReconnect is enabled, and failoverReadonly is false, should we pick hosts to connect to on a round-robin basis? | false | 3.1.2 |
queriesBeforeRetryMaster | Number of queries to issue before falling back to master when failed over (when using multi-host failover). Whichever condition is met first, 'queriesBeforeRetryMaster' or 'secondsBeforeRetryMaster' will cause an attempt to be made to reconnect to the master. Defaults to 50. | 50 | 3.0.2 |
secondsBeforeRetryMaster | How long should the driver wait, when failed over, before attempting | 30 | 3.0.2 |
selfDestructOnPingMaxOperations | =If set to a non-zero value, the driver will report close the connection and report failure when Connection.ping() or Connection.isValid(int) is called if the connnection's count of commands sent to the server exceeds this value. | 0 | 5.1.6 |
selfDestructOnPingSecondsLifetime | If set to a non-zero value, the driver will report close the connection and report failure when Connection.ping() or Connection.isValid(int) is called if the connnection's lifetime exceeds this value. | 0 | 5.1.6 |
resourceId | A globally unique name that identifies the resource that this datasource or connection is connected to, used for XAResource.isSameRM() when the driver can't determine this value based on hostnames used in the URL | 5.0.1 |
Security.
Property Name | Definition | Default Value | Since Version |
allowMultiQueries | Allow the use of ';' to delimit multiple queries during one statement (true/false), defaults to 'false', and does not affect the addBatch() and executeBatch() methods, which instead rely on rewriteBatchStatements. | false | 3.1.1 |
useSSL | Use SSL when communicating with the server (true/false), defaults to 'false' | false | 3.0.2 |
requireSSL | Require SSL connection if useSSL=true? (defaults to 'false'). | false | 3.1.0 |
verifyServerCertificate | If 'useSSL' is set to 'true', should the driver verify the server's certificate? When using this feature, the keystore parameters should be specified by the 'clientCertificateKeyStore*' properties, rather than system properties. | true | 5.1.6 |
clientCertificateKeyStoreUrl | URL to the client certificate KeyStore (if not specified, use defaults) | 5.1.0 | |
clientCertificateKeyStoreType | KeyStore type for client certificates (NULL or empty means use the default, which is 'JKS'. Standard keystore types supported by the JVM are 'JKS' and 'PKCS12', your environment may have more available depending on what security products are installed and available to the JVM. | JKS | 5.1.0 |
clientCertificateKeyStorePassword | Password for the client certificates KeyStore | 5.1.0 | |
trustCertificateKeyStoreUrl | URL to the trusted root certificate KeyStore (if not specified, use defaults) | 5.1.0 | |
trustCertificateKeyStoreType | KeyStore type for trusted root certificates (NULL or empty means use the default, which is 'JKS'. Standard keystore types supported by the JVM are 'JKS' and 'PKCS12', your environment may have more available depending on what security products are installed and available to the JVM. | JKS | 5.1.0 |
trustCertificateKeyStorePassword | Password for the trusted root certificates KeyStore | 5.1.0 | |
allowLoadLocalInfile | Should the driver allow use of 'LOAD DATA LOCAL INFILE...' (defaults to 'true'). | true | 3.0.3 |
allowUrlInLocalInfile | Should the driver allow URLs in 'LOAD DATA LOCAL INFILE' statements? | false | 3.1.4 |
paranoid | Take measures to prevent exposure sensitive information in error messages and clear data structures holding sensitive data when possible? (defaults to 'false') | false | 3.0.1 |
passwordCharacterEncoding | What character encoding is used for passwords? Leaving this set to the default value (null), uses the platform character set, which works for ISO8859_1 (i.e. 'latin1') passwords. For passwords in other character encodings, the encoding will have to be specified with this property, as it's not possible for the driver to auto-detect this. | 5.1.7 |
Performance Extensions.
Property Name | Definition | Default Value | Since Version |
callableStmtCacheSize | If 'cacheCallableStmts' is enabled, how many callable statements should be cached? | 100 | 3.1.2 |
metadataCacheSize | The number of queries to cache ResultSetMetadata for if cacheResultSetMetaData is set to 'true' (default 50) | 50 | 3.1.1 |
useLocalSessionState | Should the driver refer to the internal values of autocommit and transaction isolation that are set by Connection.setAutoCommit() and Connection.setTransactionIsolation() and transaction state as maintained by the protocol, rather than querying the database or blindly sending commands to the database for commit() or rollback() method calls? | false | 3.1.7 |
useLocalTransactionState | Should the driver use the in-transaction state provided by the MariaDB protocol to determine if a commit() or rollback() should actually be sent to the database? | false | 5.1.7 |
prepStmtCacheSize | If prepared statement caching is enabled, how many prepared statements should be cached? | 25 | 3.0.10 |
prepStmtCacheSqlLimit | If prepared statement caching is enabled, what's the largest SQL the driver will cache the parsing for? | 256 | 3.0.10 |
alwaysSendSetIsolation | Should the driver always communicate with the database when Connection.setTransactionIsolation() is called? If set to false, the driver will only communicate with the database when the requested transaction isolation is different than the whichever is newer, the last value that was set via Connection.setTransactionIsolation(), or the value that was read from the server when the connection was established. Note that useLocalSessionState=true will force the same behavior as alwaysSendSetIsolation=false, regardless of how alwaysSendSetIsolation is set. | true | 3.1.7 |
maintainTimeStats | Should the driver maintain various internal timers to enable idle time calculations as well as more verbose error messages when the connection to the server fails? Setting this property to false removes at least two calls to System.getCurrentTimeMillis() per query. | true | 3.1.9 |
useCursorFetch | If connected to MariaDB > 5.0.2, and setFetchSize() > 0 on a statement, should that statement use cursor-based fetching to retrieve rows? | false | 5.0.0 |
blobSendChunkSize | Chunk to use when sending BLOB/CLOBs via ServerPreparedStatements | 1048576 | 3.1.9 |
cacheCallableStmts | Should the driver cache the parsing stage of CallableStatements | false | 3.1.2 |
cachePrepStmts | Should the driver cache the parsing stage of PreparedStatements of client-side prepared statements, the 'check' for suitability of server-side prepared and server-side prepared statements themselves? | false | 3.0.10 |
cacheResultSetMetadata | Should the driver cache ResultSetMetaData for Statements and PreparedStatements? (Req. JDK-1.4+, true/false, default 'false') | false | 3.1.1 |
cacheServerConfiguration | Should the driver cache the results of 'SHOW VARIABLES' and 'SHOW COLLATION' on a per-URL basis? | false | 3.1.5 |
defaultFetchSize | The driver will call setFetchSize(n) with this value on all newly-created Statements | 0 | 3.1.9 |
dontTrackOpenResources | The JDBC specification requires the driver to automatically track and close resources, however if your application doesn't do a good job of explicitly calling close() on statements or result sets, this can cause memory leakage. Setting this property to true relaxes this constraint, and can be more memory efficient for some applications. | false | 3.1.7 |
dynamicCalendars | Should the driver retrieve the default calendar when required, or cache it per connection/session? | false | 3.1.5 |
elideSetAutoCommits | If using MySQL-4.1 or newer, should the driver only issue 'set autocommit=n' queries when the server's state doesn't match the requested state by Connection.setAutoCommit(boolean)? | false | 3.1.3 |
enableQueryTimeouts | When enabled, query timeouts set via Statement.setQueryTimeout() use a shared java.util.Timer instance for scheduling. Even if the timeout doesn't expire before the query is processed, there will be memory used by the TimerTask for the given timeout which won't be reclaimed until the time the timeout would have expired if it hadn't been cancelled by the driver. High-load environments might want to consider disabling this functionality. | true | 5.0.6 |
holdResultsOpenOverStatementClose | Should the driver close result sets on Statement.close() as required by the JDBC specification? | false | 3.1.7 |
largeRowSizeThreshold | What size result set row should the JDBC driver consider 'large', and thus use a more memory-efficient way of representing the row internally? | 2048 | 5.1.1 |
loadBalanceStrategy | If using a load-balanced connection to connect to SQL nodes in a MariaDB Cluster/NDB configuration (by using the URL prefix 'jdbc:mysql:loadbalance://'), which load balancing algorithm should the driver use: (1) 'random' - the driver will pick a random host for each request. This tends to work better than round-robin, as the randomness will somewhat account for spreading loads where requests vary in response time, while round-robin can sometimes lead to overloaded nodes if there are variations in response times across the workload. (2) 'bestResponseTime' - the driver will route the request to the host that had the best response time for the previous transaction. | random | 5.0.6 |
locatorFetchBufferSize | If 'emulateLocators' is configured to 'true', what size buffer should be used when fetching BLOB data for getBinaryInputStream? | 1048576 | 3.2.1 |
rewriteBatchedStatements | Should the driver use multiqueries (irregardless of the setting of 'allowMultiQueries') as well as rewriting of prepared statements for INSERT into multi-value inserts when executeBatch() is called? Notice that this has the potential for SQL injection if using plain java.sql.Statements and your code doesn't sanitize input correctly. Notice that for prepared statements, server-side prepared statements can not currently take advantage of this rewrite option, and that if you don't specify stream lengths when using PreparedStatement.set*Stream(), the driver won't be able to determine the optimum number of parameters per batch and you might receive an error from the driver that the resultant packet is too large. Statement.getGeneratedKeys() for these rewritten statements only works when the entire batch includes INSERT statements. | false | 3.1.13 |
useDirectRowUnpack | Use newer result set row unpacking code that skips a copy from network buffers to a MariaDB packet instance and instead reads directly into the result set row data buffers. | true | 5.1.1 |
useDynamicCharsetInfo | Should the driver use a per-connection cache of character set information queried from the server when necessary, or use a built-in static mapping that is more efficient, but isn't aware of custom character sets or character sets implemented after the release of the JDBC driver? | true | 5.0.6 |
useFastDateParsing | Use internal String->Date/Time/Timestamp conversion routines to avoid excessive object creation? | true | 5.0.5 |
useFastIntParsing | Use internal String->Integer conversion routines to avoid excessive object creation? | true | 3.1.4 |
useJvmCharsetConverters | Always use the character encoding routines built into the JVM, rather than using lookup tables for single-byte character sets? | false | 5.0.1 |
useReadAheadInput | Use newer, optimized non-blocking, buffered input stream when reading from the server? | true | 3.1.5 |
Debugging/Profiling.
Property Name | Definition | Default Value | Since Version |
logger | The name of a class that implements 'com.mysql.jdbc.log.Log' that will be used to log messages to. (default is 'com.mysql.jdbc.log.StandardLogger', which logs to STDERR) | com.mysql.jdbc.log.StandardLogger | 3.1.1 |
gatherPerfMetrics | Should the driver gather performance metrics, and report them via the configured logger every 'reportMetricsIntervalMillis' milliseconds? | false | 3.1.2 |
profileSQL | Trace queries and their execution/fetch times to the configured logger (true/false) defaults to 'false' | false | 3.1.0 |
profileSql | Deprecated, use 'profileSQL' instead. Trace queries and their execution/fetch times on STDERR (true/false) defaults to 'false' | 2.0.14 | |
reportMetricsIntervalMillis | If 'gatherPerfMetrics' is enabled, how often should they be logged (in ms)? | 30000 | 3.1.2 |
maxQuerySizeToLog | Controls the maximum length/size of a query that will get logged when profiling or tracing | 2048 | 3.1.3 |
packetDebugBufferSize | The maximum number of packets to retain when 'enablePacketDebug' is true | 20 | 3.1.3 |
slowQueryThresholdMillis | If 'logSlowQueries' is enabled, how long should a query (in ms) before it is logged as 'slow'? | 2000 | 3.1.2 |
slowQueryThresholdNanos | If 'useNanosForElapsedTime' is set to true, and this property is set to a non-zero value, the driver will use this threshold (in nanosecond units) to determine if a query was slow. | 0 | 5.0.7 |
useUsageAdvisor | Should the driver issue 'usage' warnings advising proper and efficient usage of JDBC and MariaDB Connector/J to the log (true/false, defaults to 'false')? | false | 3.1.1 |
autoGenerateTestcaseScript | Should the driver dump the SQL it is executing, including server-side prepared statements to STDERR? | false | 3.1.9 |
autoSlowLog | Instead of using slowQueryThreshold* to determine if a query is slow enough to be logged, maintain statistics that allow the driver to determine queries that are outside the 99th percentile? | true | 5.1.4 |
clientInfoProvider | The name of a class that implements the com.mysql.jdbc.JDBC4ClientInfoProvider interface in order to support JDBC-4.0's Connection.get/setClientInfo() methods | com.mysql.jdbc.JDBC4CommentClientInfoProvider | 5.1.0 |
dumpMetadataOnColumnNotFound | Should the driver dump the field-level metadata of a result set into the exception message when ResultSet.findColumn() fails? | false | 3.1.13 |
dumpQueriesOnException | Should the driver dump the contents of the query sent to the server in the message for SQLExceptions? | false | 3.1.3 |
enablePacketDebug | When enabled, a ring-buffer of 'packetDebugBufferSize' packets will be kept, and dumped when exceptions are thrown in key areas in the driver's code | false | 3.1.3 |
explainSlowQueries | If 'logSlowQueries' is enabled, should the driver automatically issue an 'EXPLAIN' on the server and send the results to the configured log at a WARN level? | false | 3.1.2 |
includeInnodbStatusInDeadlockExceptions | Include the output of 'SHOW ENGINE INNODB STATUS' in exception messages when deadlock exceptions are detected? | false | 5.0.7 |
includeThreadDumpInDeadlockExceptions | Include a current Java thread dump in exception messages when deadlock exceptions are detected? | false | 5.1.15 |
includeThreadNamesAsStatementComment | Include the name of the current thread as a comment visible in 'SHOW PROCESSLIST', or in Innodb deadlock dumps, useful in correlation with 'includeInnodbStatusInDeadlockExceptions=true' and 'includeThreadDumpInDeadlockExceptions=true'. | false | 5.1.15 |
logSlowQueries | Should queries that take longer than 'slowQueryThresholdMillis' be logged? | false | 3.1.2 |
logXaCommands | Should the driver log XA commands sent by MysqlXaConnection to the server, at the DEBUG level of logging? | false | 5.0.5 |
profilerEventHandler | Name of a class that implements the interface com.mysql.jdbc.profiler.ProfilerEventHandler that will be used to handle profiling/tracing events. | com.mysql.jdbc.profiler.LoggingProfilerEventHandler | 5.1.6 |
resultSetSizeThreshold | If the usage advisor is enabled, how many rows should a result set contain before the driver warns that it is suspiciously large? | 100 | 5.0.5 |
traceProtocol | Should trace-level network protocol be logged? | false | 3.1.2 |
useNanosForElapsedTime | For profiling/debugging functionality that measures elapsed time, should the driver try to use nanoseconds resolution if available (JDK >= 1.5)? | false | 5.0.7 |
Miscellaneous.
Property Name | Definition | Default Value | Since Version |
useUnicode | Should the driver use Unicode character encodings when handling strings? Should only be used when the driver can't determine the character set mapping, or you are trying to 'force' the driver to use a character set that MariaDB either doesn't natively support (such as UTF-8), true/false, defaults to 'true' | true | 1.1g |
characterEncoding | If 'useUnicode' is set to true, what character encoding should the driver use when dealing with strings? (defaults is to 'autodetect') | 1.1g | |
characterSetResults | Character set to tell the server to return results as. | 3.0.13 | |
connectionCollation | If set, tells the server to use this collation via 'set collation_connection' | 3.0.13 | |
useBlobToStoreUTF8OutsideBMP | Tells the driver to treat [MEDIUM/LONG]BLOB columns as [LONG]VARCHAR columns holding text encoded in UTF-8 that has characters outside the BMP (4-byte encodings), which MariaDB server can't handle natively. | false | 5.1.3 |
utf8OutsideBmpExcludedColumnNamePattern | When 'useBlobToStoreUTF8OutsideBMP' is set to 'true', column names matching the given regex will still be treated as BLOBs unless they match the regex specified for 'utf8OutsideBmpIncludedColumnNamePattern'. The regex must follow the patterns used for the java.util.regex package. | 5.1.3 | |
utf8OutsideBmpIncludedColumnNamePattern | Used to specify exclusion rules to 'utf8OutsideBmpExcludedColumnNamePattern'. The regex must follow the patterns used for the java.util.regex package. | 5.1.3 | |
loadBalanceEnableJMX | Enables JMX-based management of load-balanced connection groups, including live addition/removal of hosts from load-balancing pool. | false | 5.1.13 |
sessionVariables | A comma-separated list of name/value pairs to be sent as SET SESSION ... to the server when the driver connects. | 3.1.8 | |
useColumnNamesInFindColumn | Prior to JDBC-4.0, the JDBC specification had a bug related to what could be given as a 'column name' to ResultSet methods like findColumn(), or getters that took a String property. JDBC-4.0 clarified 'column name' to mean the label, as given in an 'AS' clause and returned by ResultSetMetaData.getColumnLabel(), and if no AS clause, the column name. Setting this property to 'true' will give behavior that is congruent to JDBC-3.0 and earlier versions of the JDBC specification, but which because of the specification bug could give unexpected results. This property is preferred over 'useOldAliasMetadataBehavior' unless you need the specific behavior that it provides with respect to ResultSetMetadata. | false | 5.1.7 |
allowNanAndInf | Should the driver allow NaN or +/- INF values in PreparedStatement.setDouble()? | false | 3.1.5 |
autoClosePStmtStreams | Should the driver automatically call .close() on streams/readers passed as arguments via set*() methods? | false | 3.1.12 |
autoDeserialize | Should the driver automatically detect and de-serialize objects stored in BLOB fields? | false | 3.1.5 |
blobsAreStrings | Should the driver always treat BLOBs as Strings - specifically to work around dubious metadata returned by the server for GROUP BY clauses? | false | 5.0.8 |
capitalizeTypeNames | Capitalize type names in DatabaseMetaData? (usually only useful when using WebObjects, true/false, defaults to 'false') | true | 2.0.7 |
clobCharacterEncoding | The character encoding to use for sending and retrieving TEXT, MEDIUMTEXT and LONGTEXT values instead of the configured connection characterEncoding | 5.0.0 | |
clobberStreamingResults | This will cause a 'streaming' ResultSet to be automatically closed, and any outstanding data still streaming from the server to be discarded if another query is executed before all the data has been read from the server. | false | 3.0.9 |
compensateOnDuplicateKeyUpdateCounts | Should the driver compensate for the update counts of 'ON DUPLICATE KEY' INSERT statements (2 = 1, 0 = 1) when using prepared statements? | false | 5.1.7 |
continueBatchOnError | Should the driver continue processing batch commands if one statement fails. The JDBC spec allows either way (defaults to 'true'). | true | 3.0.3 |
createDatabaseIfNotExist | Creates the database given in the URL if it doesn't yet exist. Assumes the configured user has permissions to create databases. | false | 3.1.9 |
emptyStringsConvertToZero | Should the driver allow conversions from empty string fields to numeric values of '0'? | true | 3.1.8 |
emulateLocators | Should the driver emulate java.sql.Blobs with locators? With this feature enabled, the driver will delay loading the actual Blob data until the one of the retrieval methods (getInputStream(), getBytes(), and so forth) on the blob data stream has been accessed. For this to work, you must use a column alias with the value of the column to the actual name of the Blob. The feature also has the following restrictions: The SELECT that created the result set must reference only one table, the table must have a primary key; the SELECT must alias the original blob column name, specified as a string, to an alternate name; the SELECT must cover all columns that make up the primary key. | false | 3.1.0 |
emulateUnsupportedPstmts | Should the driver detect prepared statements that are not supported by the server, and replace them with client-side emulated versions? | true | 3.1.7 |
exceptionInterceptors | Comma-delimited list of classes that implement com.mysql.jdbc.ExceptionInterceptor. These classes will be instantiated one per Connection instance, and all SQLExceptions thrown by the driver will be allowed to be intercepted by these interceptors, in a chained fashion, with the first class listed as the head of the chain. | 5.1.8 | |
functionsNeverReturnBlobs | Should the driver always treat data from functions returning BLOBs as Strings - specifically to work around dubious metadata returned by the server for GROUP BY clauses? | false | 5.0.8 |
generateSimpleParameterMetadata | Should the driver generate simplified parameter metadata for PreparedStatements when no metadata is available either because the server couldn't support preparing the statement, or server-side prepared statements are disabled? | false | 5.0.5 |
ignoreNonTxTables | Ignore non-transactional table warning for rollback? (defaults to 'false'). | false | 3.0.9 |
jdbcCompliantTruncation | Should the driver throw java.sql.DataTruncation exceptions when data is truncated as is required by the JDBC specification when connected to a server that supports warnings (MySQL 4.1.0 and newer)? This property has no effect if the server sql-mode includes STRICT_TRANS_TABLES. | true | 3.1.2 |
loadBalanceAutoCommitStatementRegex | When load-balancing is enabled for auto-commit statements (via loadBalanceAutoCommitStatementThreshold), the statement counter will only increment when the SQL matches the regular expression. By default, every statement issued matches. | 5.1.15 | |
loadBalanceAutoCommitStatementThreshold | When auto-commit is enabled, the number of statements which should be executed before triggering load-balancing to rebalance. Default value of 0 causes load-balanced connections to only rebalance when exceptions are encountered, or auto-commit is disabled and transactions are explicitly committed or rolled back. | 0 | 5.1.15 |
loadBalanceBlacklistTimeout | Time in milliseconds between checks of servers which are unavailable, by controlling how long a server lives in the global blacklist. | 0 | 5.1.0 |
loadBalanceConnectionGroup | Logical group of load-balanced connections within a classloader, used to manage different groups independently. If not specified, live management of load-balanced connections is disabled. | 5.1.13 | |
loadBalanceExceptionChecker | Fully-qualified class name of custom exception checker. The class must implement com.mysql.jdbc.LoadBalanceExceptionChecker interface, and is used to inspect SQLExceptions and determine whether they should trigger fail-over to another host in a load-balanced deployment. | com.mysql.jdbc.StandardLoadBalanceExceptionChecker | 5.1.13 |
loadBalancePingTimeout | Time in milliseconds to wait for ping response from each of load-balanced physical connections when using load-balanced Connection. | 0 | 5.1.13 |
loadBalanceSQLExceptionSubclassFailover | Comma-delimited list of classes/interfaces used by default load-balanced exception checker to determine whether a given SQLException should trigger failover. The comparison is done using Class.isInstance(SQLException) using the thrown SQLException. | 5.1.13 | |
loadBalanceSQLStateFailover | Comma-delimited list of SQLState codes used by default load-balanced exception checker to determine whether a given SQLException should trigger failover. The SQLState of a given SQLException is evaluated to determine whether it begins with any value in the comma-delimited list. | 5.1.13 | |
loadBalanceValidateConnectionOnSwapServer | Should the load-balanced Connection explicitly check whether the connection is live when swapping to a new physical connection at commit/rollback? | false | 5.1.13 |
maxRows | The maximum number of rows to return (0, the default means return all rows). | -1 | all versions |
netTimeoutForStreamingResults | What value should the driver automatically set the server setting 'net_write_timeout' to when the streaming result sets feature is in use? (value has unit of seconds, the value '0' means the driver will not try and adjust this value) | 600 | 5.1.0 |
noAccessToProcedureBodies | When determining procedure parameter types for CallableStatements, and the connected user can't access procedure bodies through 'SHOW CREATE PROCEDURE' or select on mysql.proc should the driver instead create basic metadata (all parameters reported as IN VARCHARs, but allowing registerOutParameter() to be called on them anyway) instead of throwing an exception? | false | 5.0.3 |
noDatetimeStringSync | Don't ensure that ResultSet.getDatetimeType().toString().equals(ResultSet.getString()) | false | 3.1.7 |
noTimezoneConversionForTimeType | Don't convert TIME values using the server timezone if 'useTimezone'='true' | false | 5.0.0 |
nullCatalogMeansCurrent | When DatabaseMetadataMethods ask for a 'catalog' parameter, does the value null mean use the current catalog? (this is not JDBC-compliant, but follows legacy behavior from earlier versions of the driver) | true | 3.1.8 |
nullNamePatternMatchesAll | Should DatabaseMetaData methods that accept *pattern parameters treat null the same as '%' (this is not JDBC-compliant, however older versions of the driver accepted this departure from the specification) | true | 3.1.8 |
overrideSupportsIntegrityEnhancementFacility | Should the driver return 'true' for DatabaseMetaData.supportsIntegrityEnhancementFacility() even if the database doesn't support it to workaround applications that require this method to return 'true' to signal support of foreign keys, even though the SQL specification states that this facility contains much more than just foreign key support (one such application being OpenOffice)? | false | 3.1.12 |
padCharsWithSpace | If a result set column has the CHAR type and the value does not fill the amount of characters specified in the DDL for the column, should the driver pad the remaining characters with space (for ANSI compliance)? | false | 5.0.6 |
pedantic | Follow the JDBC spec to the letter. | false | 3.0.0 |
pinGlobalTxToPhysicalConnection | When using XAConnections, should the driver ensure that operations on a given XID are always routed to the same physical connection? This allows the XAConnection to support 'XA START ... JOIN' after 'XA END' has been called | false | 5.0.1 |
populateInsertRowWithDefaultValues | When using ResultSets that are CONCUR_UPDATABLE, should the driver pre-populate the 'insert' row with default values from the DDL for the table used in the query so those values are immediately available for ResultSet accessors? This functionality requires a call to the database for metadata each time a result set of this type is created. If disabled (the default), the default values will be populated by the an internal call to refreshRow() which pulls back default values and/or values changed by triggers. | false | 5.0.5 |
processEscapeCodesForPrepStmts | Should the driver process escape codes in queries that are prepared? | true | 3.1.12 |
queryTimeoutKillsConnection | If the timeout given in Statement.setQueryTimeout() expires, should the driver forcibly abort the Connection instead of attempting to abort the query? | false | 5.1.9 |
relaxAutoCommit | If the version of MariaDB the driver connects to does not support transactions, still allow calls to commit(), rollback() and setAutoCommit() (true/false, defaults to 'false')? | false | 2.0.13 |
retainStatementAfterResultSetClose | Should the driver retain the Statement reference in a ResultSet after ResultSet.close() has been called. This is not JDBC-compliant after JDBC-4.0. | false | 3.1.11 |
rollbackOnPooledClose | Should the driver issue a rollback() when the logical connection in a pool is closed? | true | 3.0.15 |
runningCTS13 | Enables workarounds for bugs in Sun's JDBC compliance testsuite version 1.3 | false | 3.1.7 |
serverTimezone | Override detection/mapping of timezone. Used when timezone from server doesn't map to Java timezone | 3.0.2 | |
statementInterceptors | A comma-delimited list of classes that implement 'com.mysql.jdbc.StatementInterceptor' that should be placed 'in between' query execution to influence the results. StatementInterceptors are 'chainable', the results returned by the 'current' interceptor will be passed on to the next in in the chain, from left-to-right order, as specified in this property. | 5.1.1 | |
strictFloatingPoint | Used only in older versions of compliance test | false | 3.0.0 |
strictUpdates | Should the driver do strict checking (all primary keys selected) of updatable result sets (true, false, defaults to 'true')? | true | 3.0.4 |
tinyInt1isBit | Should the driver treat the datatype TINYINT(1) as the BIT type (because the server silently converts BIT -> TINYINT(1) when creating tables)? | true | 3.0.16 |
transformedBitIsBoolean | If the driver converts TINYINT(1) to a different type, should it use BOOLEAN instead of BIT for future compatibility with MySQL-5.0, as MySQL-5.0 has a BIT type? | false | 3.1.9 |
treatUtilDateAsTimestamp | Should the driver treat java.util.Date as a TIMESTAMP for the purposes of PreparedStatement.setObject()? | true | 5.0.5 |
ultraDevHack | Create PreparedStatements for prepareCall() when required, because UltraDev is broken and issues a prepareCall() for _all_ statements? (true/false, defaults to 'false') | false | 2.0.3 |
useAffectedRows | Don't set the CLIENT_FOUND_ROWS flag when connecting to the server (not JDBC-compliant, will break most applications that rely on 'found' rows vs. 'affected rows' for DML statements), but does cause 'correct' update counts from 'INSERT ... ON DUPLICATE KEY UPDATE' statements to be returned by the server. | false | 5.1.7 |
useGmtMillisForDatetimes | Convert between session timezone and GMT before creating Date and Timestamp instances (value of 'false' is legacy behavior, 'true' leads to more JDBC-compliant behavior. | false | 3.1.12 |
useHostsInPrivileges | Add '@hostname' to users in DatabaseMetaData.getColumn/TablePrivileges() (true/false), defaults to 'true'. | true | 3.0.2 |
useInformationSchema | When connected to MySQL-5.0.7 or newer, should the driver use the INFORMATION_SCHEMA to derive information used by DatabaseMetaData? | false | 5.0.0 |
useJDBCCompliantTimezoneShift | Should the driver use JDBC-compliant rules when converting TIME/TIMESTAMP/DATETIME values' timezone information for those JDBC arguments which take a java.util.Calendar argument? (Notice that this option is exclusive of the 'useTimezone=true' configuration option.) | false | 5.0.0 |
useLegacyDatetimeCode | Use code for DATE/TIME/DATETIME/TIMESTAMP handling in result sets and statements that consistently handles timezone conversions from client to server and back again, or use the legacy code for these datatypes that has been in the driver for backwards-compatibility? | true | 5.1.6 |
useOldAliasMetadataBehavior | Should the driver use the legacy behavior for 'AS' clauses on columns and tables, and only return aliases (if any) for ResultSetMetaData.getColumnName() or ResultSetMetaData.getTableName() rather than the original column/table name? In 5.0.x, the default value was true. | false | 5.0.4 |
useOldUTF8Behavior | Use the UTF-8 behavior the driver did when communicating with 4.0 and older servers | false | 3.1.6 |
useOnlyServerErrorMessages | Don't prepend 'standard' SQLState error messages to error messages returned by the server. | true | 3.0.15 |
useSSPSCompatibleTimezoneShift | If migrating from an environment that was using server-side prepared statements, and the configuration property 'useJDBCCompliantTimeZoneShift' set to 'true', use compatible behavior when not using server-side prepared statements when sending TIMESTAMP values to the MariaDB server. | false | 5.0.5 |
useServerPrepStmts | Use server-side prepared statements if the server supports them? | false | 3.1.0 |
useSqlStateCodes | Use SQL Standard state codes instead of 'legacy' X/Open/SQL state codes (true/false), default is 'true' | true | 3.1.3 |
useStreamLengthsInPrepStmts | Honor stream length parameter in PreparedStatement/ResultSet.setXXXStream() method calls (true/false, defaults to 'true')? | true | 3.0.2 |
useTimezone | Convert time/date types between client and server timezones (true/false, defaults to 'false')? | false | 3.0.2 |
useUnbufferedInput | Don't use BufferedInputStream for reading data from the server | true | 3.0.11 |
yearIsDateType | Should the JDBC driver treat the MariaDB type 'YEAR' as a java.sql.Date, or as a SHORT? | true | 3.1.9 |
zeroDateTimeBehavior | What should happen when the driver encounters DATETIME values that are composed entirely of zeros (used by MariaDB to represent invalid dates)? Valid values are 'exception', 'round' and 'convertToNull'. | exception | 3.1.4 |
Connector/J also supports access to MariaDB using named pipes on Windows NT/2000/XP using the NamedPipeSocketFactory as a plugin-socket factory using the socketFactory property. If you do not use a namedPipePath property, the default of '\\.\pipe\MySQL'
is used. If you use the NamedPipeSocketFactory
, the host name and port number values in the JDBC url are ignored. To enable this feature, use:
socketFactory=com.mysql.jdbc.NamedPipeSocketFactory
Named pipes only work when connecting to a MariaDB server on the same physical machine as the one the JDBC driver is being used on. In simple performance tests, it appears that named pipe access is between 30%-50% faster than the standard TCP/IP access. However, this varies per system, and named pipes are slower than TCP/IP in many Windows configurations.
To create your own socket factories, follow the example code in com.mysql.jdbc.NamedPipeSocketFactory
, or com.mysql.jdbc.StandardSocketFactory
.
JDBC API Implementation Notes
MySQL Connector/J passes all of the tests in the publicly available version of Sun's JDBC compliance test suite. this section gives details on a interface-by-interface level about implementation decisions that might affect how you code applications with MariaDB Connector/J. The JDBC specification is vague about how certain functionality should be implemented, or the specification enables leeway in implementation.
- BLOB
Starting with Connector/J version 3.1.0, you can emulate BLOBs with locators by adding the property
emulateLocators=true
to your JDBC URL. Using this method, the driver will delay loading the actual BLOB data until you retrieve the other data and then use retrieval methods (getInputStream()
,getBytes()
, and so forth) on the blob data stream.You must use a column alias with the value of the column to the actual name of the BLOB, for example:
SELECT id, 'data' as blob_data from blobtable
You must also follow these rules:
- The
SELECT
must reference only one table. The table must have a primary key. - The
SELECT
must alias the original blob column name, specified as a string, to an alternate name. - The
SELECT
must cover all columns that make up the primary key.
The BLOB implementation does not allow in-place modification (they are copies, as reported by the
DatabaseMetaData.locatorsUpdateCopies()
method). Because of this, use the correspondingPreparedStatement.setBlob()
orResultSet.updateBlob()
(in the case of updatable result sets) methods to save changes back to the database. - The
- CallableStatement
Starting with Connector/J 3.1.1, stored procedures are supported when connecting to MariaDB version 5.0 or newer using the
CallableStatement
interface. Currently, thegetParameterMetaData()
method ofCallableStatement
is not supported. - Clob
The CLOB implementation does not allow in-place modification (they are copies, as reported by the
DatabaseMetaData.locatorsUpdateCopies()
method). Because of this, use thePreparedStatement.setClob()
method to save changes back to the database. The JDBC API does not have aResultSet.updateClob()
method. - Connection
Unlike older versions of MM.MySQL, the
isClosed()
method does not ping the server to determine if it is available. In accordance with the JDBC specification, it only returns true ifclosed()
has been called on the connection. If you need to determine if the connection is still valid, issue a simple query, such asSELECT 1
. The driver will throw an exception if the connection is no longer valid. - DatabaseMetaData
Foreign key information (
getImportedKeys()
/getExportedKeys()
andgetCrossReference()
) is only available from InnoDB tables. The driver usesSHOW CREATE TABLE
to retrieve this information, so if any other storage engines add support for foreign keys, the driver would transparently support them as well. - PreparedStatement
PreparedStatements are implemented by the driver, as MariaDB does not have a prepared statement feature. Because of this, the driver does not implement
getParameterMetaData()
orgetMetaData()
as it would require the driver to have a complete SQL parser in the client.Starting with version 3.1.0 MariaDB Connector/J, server-side prepared statements and binary-encoded result sets are used when the server supports them.
Take care when using a server-side prepared statement with large parameters that are set using
setBinaryStream()
,setAsciiStream()
,setUnicodeStream()
,setBlob()
, orsetClob()
. To re-execute the statement with any large parameter changed to a nonlarge parameter, callclearParameters()
and set all parameters again. The reason for this is as follows:- During both server-side prepared statements and client-side emulation, large data is exchanged only when
PreparedStatement.execute()
is called.
- Once that has been done, the stream used to read the data on the client side is closed (as per the JDBC spec), and cannot be read from again.
- If a parameter changes from large to nonlarge, the driver must reset the server-side state of the prepared statement to allow the parameter that is being changed to take the place of the prior large value. This removes all of the large data that has already been sent to the server, thus requiring the data to be re-sent, using the
setBinaryStream()
,setAsciiStream()
,setUnicodeStream()
,setBlob()
orsetClob()
method.
Consequently, to change the type of a parameter to a nonlarge one, you must call
clearParameters()
and set all parameters of the prepared statement again before it can be re-executed. - During both server-side prepared statements and client-side emulation, large data is exchanged only when
- ResultSet
By default, ResultSets are completely retrieved and stored in memory. In most cases this is the most efficient way to operate, and due to the design of the MariaDB network protocol is easier to implement. If you are working with ResultSets that have a large number of rows or large values, and cannot allocate heap space in your JVM for the memory required, you can tell the driver to stream the results back one row at a time.
To enable this functionality, create a
Statement
instance in the following manner:stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY, java.sql.ResultSet.CONCUR_READ_ONLY); stmt.setFetchSize(Integer.MIN_VALUE);
The combination of a forward-only, read-only result set, with a fetch size of
Integer.MIN_VALUE
serves as a signal to the driver to stream result sets row-by-row. After this, any result sets created with the statement will be retrieved row-by-row.There are some caveats with this approach. You must read all of the rows in the result set (or close it) before you can issue any other queries on the connection, or an exception will be thrown.
The earliest the locks these statements hold can be released (whether they be
MyISAM
table-level locks or row-level locks in some other storage engine such asInnoDB
) is when the statement completes.If the statement is within scope of a transaction, then locks are released when the transaction completes (which implies that the statement needs to complete first). As with most other databases, statements are not complete until all the results pending on the statement are read or the active result set for the statement is closed.
Therefore, if using streaming results, process them as quickly as possible if you want to maintain concurrent access to the tables referenced by the statement producing the result set.
- ResultSetMetaData
The
isAutoIncrement()
method only works when using MariaDB servers 4.0 and newer. - Statement
When using versions of the JDBC driver earlier than 3.2.1, and connected to server versions earlier than 5.0.3, the
setFetchSize()
method has no effect, other than to toggle result set streaming as described above.Connector/J 5.0.0 and later include support for both
Statement.cancel()
andStatement.setQueryTimeout()
. Both require MariaDB 5.0.0 or newer server, and require a separate connection to issue theKILL QUERY
statement. In the case ofsetQueryTimeout()
, the implementation creates an additional thread to handle the timeout functionality.NoteFailures to cancel the statement for
setQueryTimeout()
may manifest themselves asRuntimeException
rather than failing silently, as there is currently no way to unblock the thread that is executing the query being cancelled due to timeout expiration and have it throw the exception instead.NoteThe MariaDB statement
KILL QUERY
(which is what the driver uses to implementStatement.cancel()
) is non-deterministic; thus, avoid the use ofStatement.cancel()
if possible. If no query is in process, the next query issued will be killed by the server. This race condition is guarded against as of Connector/J 5.1.18.MySQL does not support SQL cursors, and the JDBC driver doesn't emulate them, so
setCursorName()
has no effect.Connector/J 5.1.3 and later include two additional methods:
setLocalInfileInputStream()
sets anInputStream
instance that will be used to send data to the MariaDB server for aLOAD DATA LOCAL INFILE
statement rather than aFileInputStream
orURLInputStream
that represents the path given as an argument to the statement.
This stream will be read to completion upon execution of a
LOAD DATA LOCAL INFILE
statement, and will automatically be closed by the driver, so it needs to be reset before each call toexecute*()
that would cause the MariaDB server to request data to fulfill the request forLOAD DATA LOCAL INFILE
.If this value is set to
NULL
, the driver will revert to using aFileInputStream
orURLInputStream
as required.getLocalInfileInputStream()
returns theInputStream
instance that will be used to send data in response to aLOAD DATA LOCAL INFILE
statement.This method returns
NULL
if no such stream has been set usingsetLocalInfileInputStream()
.
Java, JDBC and MariaDB Types
MySQL Connector/J is flexible in the way it handles conversions between MariaDB data types and Java data types.
In general, any MariaDB data type can be converted to a java.lang.String, and any numeric type can be converted to any of the Java numeric types, although round-off, overflow, or loss of precision may occur.Note
All TEXT
types return Types.LONGVARCHAR
with different getPrecision()
values (65535, 255, 16777215, and 2147483647 respectively) with getColumnType()
returning -1
. This behavior is intentional even though TINYTEXT does not fall, regarding to its size, within the LONGVARCHAR
category. This is to avoid different handling inside the same base type. And getColumnType()
returns -1
because the internal server handling is of type TEXT
, which is similar to BLOB
.
Also note that getColumnTypeName()
will return VARCHAR
even though getColumnType()
returns Types.LONGVARCHAR
, because VARCHAR
is the designated column database-specific name for this type.
Starting with Connector/J 3.1.0, the JDBC driver issues warnings or throws DataTruncation
exceptions as is required by the JDBC specification unless the connection was configured not to do so by using the property jdbcCompliantTruncation and setting it to false
.
The conversions that are always guaranteed to work are listed in the following table:
Connection Properties - Miscellaneous.
These MariaDB Data Types | Can always be converted to these Java types |
---|---|
CHAR, VARCHAR, BLOB, TEXT, ENUM, and SET
| java.lang.String, java.io.InputStream, java.io.Reader, java.sql.Blob, java.sql.Clob
|
FLOAT, REAL, DOUBLE PRECISION, NUMERIC, DECIMAL, TINYINT, SMALLINT, MEDIUMINT, INTEGER, BIGINT
| java.lang.String, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Double, java.math.BigDecimal
|
DATE, TIME, DATETIME, TIMESTAMP
| java.lang.String, java.sql.Date, java.sql.Timestamp |
Round-off, overflow or loss of precision may occur if you choose a Java numeric data type that has less precision or capacity than the MariaDB data type you are converting to/from.
The ResultSet.getObject()
method uses the type conversions between MariaDB and Java types, following the JDBC specification where appropriate. The value returned by ResultSetMetaData.GetColumnClassName()
is also shown below. For more information on the java.sql.Types
classes see Java 2 Platform Types.
MySQL Types to Java Types for ResultSet.getObject().
MySQL Type Name | Return value of GetColumnClassName
| Returned as Java Class |
---|---|---|
BIT(1) (new in MySQL-5.0) | BIT | java.lang.Boolean
|
BIT( > 1) (new in MySQL-5.0) | BIT | byte[]
|
TINYINT | TINYINT | java.lang.Boolean if the configuration property tinyInt1isBit is set to true (the default) and the storage size is 1, or java.lang.Integer if not.
|
BOOL, BOOLEAN | TINYINT | See TINYINT, above as these are aliases for TINYINT(1), currently. |
SMALLINT[(M)] [UNSIGNED] | SMALLINT [UNSIGNED] | java.lang.Integer (regardless if UNSIGNED or not)
|
MEDIUMINT[(M)] [UNSIGNED] | MEDIUMINT [UNSIGNED] | java.lang.Integer, if UNSIGNED java.lang.Long (C/J 3.1 and earlier), or java.lang.Integer for C/J 5.0 and later
|
INT,INTEGER[(M)] [UNSIGNED] | INTEGER [UNSIGNED] | java.lang.Integer , if UNSIGNED java.lang.Long
|
BIGINT[(M)] [UNSIGNED] | BIGINT [UNSIGNED] | java.lang.Long , if UNSIGNED java.math.BigInteger
|
FLOAT[(M,D)] | FLOAT | java.lang.Float
|
DOUBLE[(M,B)] | DOUBLE | java.lang.Double
|
DECIMAL[(M[,D])] | DECIMAL | java.math.BigDecimal
|
DATE | DATE | java.sql.Date
|
DATETIME | DATETIME | java.sql.Timestamp
|
TIMESTAMP[(M)] | TIMESTAMP | java.sql.Timestamp
|
TIME | TIME | java.sql.Time
|
YEAR[(2|4)] | YEAR | If yearIsDateType configuration property is set to false , then the returned object type is java.sql.Short . If set to true (the default), then the returned object is of type java.sql.Date with the date set to January 1st, at midnight.
|
CHAR(M) | CHAR | java.lang.String (unless the character set for the column is BINARY, then byte[] is returned.
|
VARCHAR(M) [BINARY] | VARCHAR | java.lang.String (unless the character set for the column is BINARY, then byte[] is returned.
|
BINARY(M) | BINARY | byte[]
|
VARBINARY(M) | VARBINARY | byte[]
|
TINYBLOB | TINYBLOB | byte[]
|
TINYTEXT | VARCHAR | java.lang.String
|
BLOB | BLOB | byte[]
|
TEXT | VARCHAR | java.lang.String
|
MEDIUMBLOB | MEDIUMBLOB | byte[]
|
MEDIUMTEXT | VARCHAR | java.lang.String
|
LONGBLOB | LONGBLOB | byte[]
|
LONGTEXT | VARCHAR | java.lang.String
|
ENUM('value1','value2',...) | CHAR | java.lang.String
|
SET('value1','value2',...) | CHAR | java.lang.String |
Using Character Sets and Unicode
All strings sent from the JDBC driver to the server are converted automatically from native Java Unicode form to the client character encoding, including all queries sent using Statement.execute()
, Statement.executeUpdate()
, Statement.executeQuery()
as well as all PreparedStatement
and CallableStatement
parameters with the exclusion of parameters set using setBytes()
, setBinaryStream()
, setAsciiStream()
, setUnicodeStream()
and setBlob()
.
Prior to MariaDB Server 4.1, Connector/J supported a single character encoding per connection, which could either be automatically detected from the server configuration, or could be configured by the user through the useUnicode
and characterEncoding
properties.
Starting with MariaDB Server 4.1, Connector/J supports a single character encoding between client and server, and any number of character encodings for data returned by the server to the client in ResultSets
.
The character encoding between client and server is automatically detected upon connection. The encoding used by the driver is specified on the server using the character_set
system variable for server versions older than 4.1.0 and character-set-server
for server versions 4.1.0 and newer. For more information, see , "Server Character Set and Collation".
To override the automatically detected encoding on the client side, use the characterEncoding
property in the URL used to connect to the server.
When specifying character encodings on the client side, use Java-style names. The following table lists Java-style names for MariaDB character sets:
MySQL to Java Encoding Name Translations.
MySQL Character Set Name | Java-Style Character Encoding Name |
---|---|
ascii | US-ASCII |
big5 | Big5 |
gbk | GBK |
sjis | SJIS (or Cp932 or MS932 for MariaDB Server < 4.1.11) |
cp932 | Cp932 or MS932 (MySQL Server > 4.1.11) |
gb2312 | EUC_CN |
ujis | EUC_JP |
euckr | EUC_KR |
latin1 | Cp1252 |
latin2 | ISO8859_2 |
greek | ISO8859_7 |
hebrew | ISO8859_8 |
cp866 | Cp866 |
tis620 | TIS620 |
cp1250 | Cp1250 |
cp1251 | Cp1251 |
cp1257 | Cp1257 |
macroman | MacRoman |
macce | MacCentralEurope |
utf8 | UTF-8 |
ucs2 | UnicodeBig |
Do not issue the query 'set names' with Connector/J, as the driver will not detect that the character set has changed, and will continue to use the character set detected during the initial connection setup.
To allow multiple character sets to be sent from the client, use the UTF-8 encoding, either by configuring utf8
as the default server character set, or by configuring the JDBC driver to use UTF-8 through the characterEncoding
property.
Connecting Securely Using SSL
SSL in MariaDB Connector/J encrypts all data (other than the initial handshake) between the JDBC driver and the server. The performance penalty for enabling SSL is an increase in query processing time between 35% and 50%, depending on the size of the query, and the amount of data it returns.
For SSL Support to work, you must have the following:
- A JDK that includes JSSE (Java Secure Sockets Extension), like JDK-1.4.1 or newer. SSL does not currently work with a JDK that you can add JSSE to, like JDK-1.2.x or JDK-1.3.x due to the following JSSE bug: http://developer.java.sun.com/developer/bugParade/bugs/4273544.html
- A MariaDB server that supports SSL and has been compiled and configured to do so, which is MySQL-4.0.4 or later, see , "Using SSL for Secure Connections", for more information.
- A client certificate (covered later in this section)
The system works through two Java truststore files, one file contains the certificate information for the server (truststore
in the examples below). The other file contains the certificate for the client (keystore
in the examples below). All Java truststore files are password protected by supplying a suitable password to the keytool when you create the files. You need the file names and associated passwords to create an SSL connection.
You will first need to import the MariaDB server CA Certificate into a Java truststore. A sample MariaDB server CA Certificate is located in the SSL
subdirectory of the MariaDB source distribution. This is what SSL will use to determine if you are communicating with a secure MariaDB server. Alternatively, use the CA Certificate that you have generated or been provided with by your SSL provider.
To use Java's keytool to create a truststore in the current directory , and import the server's CA certificate (cacert.pem
), you can do the following (assuming that keytool is in your path. The keytool is typically located in the bin
subdirectory of your JDK or JRE):
shell> keytool -import -alias mysqlServerCACert \ -file cacert.pem -keystore truststore
Enter the password when prompted for the keystore file. Interaction with keytool looks like this:
Enter keystore password: ********* Owner: EMAILADDRESS=walrus@example.com, CN=Walrus, O=MariaDB Foundation, L=Orenburg, ST=Some-State, C=RU Issuer: EMAILADDRESS=walrus@example.com, CN=Walrus, O=MariaDB Foundation, L=Orenburg, ST=Some-State, C=RU Serial number: 0 Valid from: Fri Aug 02 16:55:53 CDT 2002 until: Sat Aug 02 16:55:53 CDT 2003 Certificate fingerprints: MD5: 61:91:A0:F2:03:07:61:7A:81:38:66:DA:19:C4:8D:AB SHA1: 25:77:41:05:D5:AD:99:8C:14:8C:CA:68:9C:2F:B8:89:C3:34:4D:6C Trust this certificate? [no]: yes Certificate was added to keystore
You then have two options: either import the client certificate that matches the CA certificate you just imported, or create a new client certificate.
Importing an existing certificate requires the certificate to be in DER format. You can use openssl to convert an existing certificate into the new format. For example:
shell> openssl x509 -outform DER -in client-cert.pem -out client.cert
Now import the converted certificate into your keystore using keytool:
shell> keytool -import -file client.cert -keystore keystore -alias mysqlClientCertificate
To generate your own client certificate, use keytool to create a suitable certificate and add it to the keystore
file:
shell> keytool -genkey -keyalg rsa \ -alias mysqlClientCertificate -keystore keystore
Keytool will prompt you for the following information, and create a keystore named keystore
in the current directory.
Respond with information that is appropriate for your situation:
Enter keystore password: ********* What is your first and last name? [Unknown]: Matthews What is the name of your organizational unit? [Unknown]: Software Development What is the name of your organization? [Unknown]: MariaDB Foundation What is the name of your City or Locality? [Unknown]: Flossmoor What is the name of your State or Province? [Unknown]: IL What is the two-letter country code for this unit? [Unknown]: US Is <CN=Matthews, OU=Software Development, O=MariaDB Foundation, L=Flossmoor, ST=IL, C=US> correct? [no]: y Enter key password for <mysqlClientCertificate> (RETURN if same as keystore password):
Finally, to get JSSE to use the keystore and truststore that you have generated, you need to set the following system properties when you start your JVM, replacing path_to_keystore_file with the full path to the keystore file you created, path_to_truststore_file with the path to the truststore file you created, and using the appropriate password values for each property. You can do this either on the command line:
-Djavax.net.ssl.keyStore=path_to_keystore_file -Djavax.net.ssl.keyStorePassword=password -Djavax.net.ssl.trustStore=path_to_truststore_file -Djavax.net.ssl.trustStorePassword=password
Or you can set the values directly within the application:
System.setProperty('javax.net.ssl.keyStore','path_to_keystore_file'); System.setProperty('javax.net.ssl.keyStorePassword','password'); System.setProperty('javax.net.ssl.trustStore','path_to_truststore_file'); System.setProperty('javax.net.ssl.trustStorePassword','password');
You will also need to set useSSL to true
in your connection parameters for MariaDB Connector/J, either by adding useSSL=true
to your URL, or by setting the property useSSL to true
in the java.util.Properties
instance you pass to DriverManager.getConnection()
.
You can test that SSL is working by turning on JSSE debugging (as detailed below), and look for the following key events:
... *** ClientHello, v3.1 RandomCookie: GMT: 1018531834 bytes = { 199, 148, 180, 215, 74, 12, » 54, 244, 0, 168, 55, 103, 215, 64, 16, 138, 225, 190, 132, 153, 2, » 217, 219, 239, 202, 19, 121, 78 } Session ID: {} Cipher Suites: { 0, 5, 0, 4, 0, 9, 0, 10, 0, 18, 0, 19, 0, 3, 0, 17 } Compression Methods: { 0 } *** [write] MD5 and SHA1 hashes: len = 59 0000: 01 00 00 37 03 01 3D B6 90 FA C7 94 B4 D7 4A 0C ...7..=.......J. 0010: 36 F4 00 A8 37 67 D7 40 10 8A E1 BE 84 99 02 D9 6...7g.@........ 0020: DB EF CA 13 79 4E 00 00 10 00 05 00 04 00 09 00 ....yN.......... 0030: 0A 00 12 00 13 00 03 00 11 01 00 ........... main, WRITE: SSL v3.1 Handshake, length = 59 main, READ: SSL v3.1 Handshake, length = 74 *** ServerHello, v3.1 RandomCookie: GMT: 1018577560 bytes = { 116, 50, 4, 103, 25, 100, 58, » 202, 79, 185, 178, 100, 215, 66, 254, 21, 83, 187, 190, 42, 170, 3, » 132, 110, 82, 148, 160, 92 } Session ID: {163, 227, 84, 53, 81, 127, 252, 254, 178, 179, 68, 63, » 182, 158, 30, 11, 150, 79, 170, 76, 255, 92, 15, 226, 24, 17, 177, » 219, 158, 177, 187, 143} Cipher Suite: { 0, 5 } Compression Method: 0 *** %% Created: [Session-1, SSL_RSA_WITH_RC4_128_SHA] ** SSL_RSA_WITH_RC4_128_SHA [read] MD5 and SHA1 hashes: len = 74 0000: 02 00 00 46 03 01 3D B6 43 98 74 32 04 67 19 64 ...F..=.C.t2.g.d 0010: 3A CA 4F B9 B2 64 D7 42 FE 15 53 BB BE 2A AA 03 :.O..d.B..S..*.. 0020: 84 6E 52 94 A0 5C 20 A3 E3 54 35 51 7F FC FE B2 .nR..\ ..T5Q.... 0030: B3 44 3F B6 9E 1E 0B 96 4F AA 4C FF 5C 0F E2 18 .D?.....O.L.\... 0040: 11 B1 DB 9E B1 BB 8F 00 05 00 .......... main, READ: SSL v3.1 Handshake, length = 1712 ...
JSSE provides debugging (to STDOUT) when you set the following system property: -Djavax.net.debug=all
This will tell you what keystores and truststores are being used, as well as what is going on during the SSL handshake and certificate exchange. It will be helpful when trying to determine what is not working when trying to get an SSL connection to happen.
Using Master/Slave Replication with ReplicationConnection
Starting with Connector/J 3.1.7, we've made available a variant of the driver that will automatically send queries to a read/write master, or a failover or round-robin loadbalanced set of slaves based on the state of Connection.getReadOnly()
.
An application signals that it wants a transaction to be read-only by calling Connection.setReadOnly(true)
, this replication-aware connection will use one of the slave connections, which are load-balanced per-vm using a round-robin scheme (a given connection is sticky to a slave unless that slave is removed from service). If you have a write transaction, or if you have a read that is time-sensitive (remember, replication in MariaDB is asynchronous), set the connection to be not read-only, by calling Connection.setReadOnly(false)
and the driver will ensure that further calls are sent to the master MariaDB server. The driver takes care of propagating the current state of autocommit, isolation level, and catalog between all of the connections that it uses to accomplish this load balancing functionality.
To enable this functionality, use the ' com.mysql.jdbc.ReplicationDriver
' class when configuring your application server's connection pool or when creating an instance of a JDBC driver for your standalone application. Because it accepts the same URL format as the standard MariaDB JDBC driver, ReplicationDriver
does not currently work with java.sql.DriverManager
-based connection creation unless it is the only MariaDB JDBC driver registered with the DriverManager
.
Here is a short, simple example of how ReplicationDriver might be used in a standalone application.
import java.sql.Connection; import java.sql.ResultSet; import java.util.Properties; import com.mysql.jdbc.ReplicationDriver; public class ReplicationDriverDemo { public static void main(String[] args) throws Exception { ReplicationDriver driver = new ReplicationDriver(); Properties props = new Properties(); // We want this for failover on the slaves props.put('autoReconnect', 'true'); // We want to load balance between the slaves props.put('roundRobinLoadBalance', 'true'); props.put('user', 'foo'); props.put('password', 'bar'); // // Looks like a normal MariaDB JDBC url, with a // comma-separated list of hosts, the first // being the 'master', the rest being any number // of slaves that the driver will load balance against // Connection conn = driver.connect('jdbc:mysql:replication://master,slave1,slave2,slave3/test', props); // // Perform read/write work on the master // by setting the read-only flag to 'false' // conn.setReadOnly(false); conn.setAutoCommit(false); conn.createStatement().executeUpdate('UPDATE some_table ....'); conn.commit(); // // Now, do a query from a slave, the driver automatically picks one // from the list // conn.setReadOnly(true); ResultSet rs = conn.createStatement().executeQuery('SELECT a,b FROM alt_table'); ....... } }
Consider investigating the Load Balancing JDBC Pool (lbpol) tool, which provides a wrapper around the standard JDBC driver and enables you to use DB connection pools that includes checks for system failures and uneven load distribution. For more information, see Load Balancing JDBC Pool (lbpool).
Mapping MariaDB Error Numbers to SQLStates
The table below provides a mapping of the MariaDB Error Numbers to SQL States
Table 20.6. Mapping of MariaDB Error Numbers to SQLStates
MySQL Error Number | MySQL Error Name | Legacy (X/Open) SQLState | SQL Standard SQLState |
---|---|---|---|
1022 | ER_DUP_KEY | S1000 | 23000 |
1037 | ER_OUTOFMEMORY | S1001 | HY001 |
1038 | ER_OUT_OF_SORTMEMORY | S1001 | HY001 |
1040 | ER_CON_COUNT_ERROR | 08004 | 08004 |
1042 | ER_BAD_HOST_ERROR | 08004 | 08S01 |
1043 | ER_HANDSHAKE_ERROR | 08004 | 08S01 |
1044 | ER_DBACCESS_DENIED_ERROR | S1000 | 42000 |
1045 | ER_ACCESS_DENIED_ERROR | 28000 | 28000 |
1047 | ER_UNKNOWN_COM_ERROR | 08S01 | HY000 |
1050 | ER_TABLE_EXISTS_ERROR | S1000 | 42S01 |
1051 | ER_BAD_TABLE_ERROR | 42S02 | 42S02 |
1052 | ER_NON_UNIQ_ERROR | S1000 | 23000 |
1053 | ER_SERVER_SHUTDOWN | S1000 | 08S01 |
1054 | ER_BAD_FIELD_ERROR | S0022 | 42S22 |
1055 | ER_WRONG_FIELD_WITH_GROUP | S1009 | 42000 |
1056 | ER_WRONG_GROUP_FIELD | S1009 | 42000 |
1057 | ER_WRONG_SUM_SELECT | S1009 | 42000 |
1058 | ER_WRONG_VALUE_COUNT | 21S01 | 21S01 |
1059 | ER_TOO_LONG_IDENT | S1009 | 42000 |
1060 | ER_DUP_FIELDNAME | S1009 | 42S21 |
1061 | ER_DUP_KEYNAME | S1009 | 42000 |
1062 | ER_DUP_ENTRY | S1009 | 23000 |
1063 | ER_WRONG_FIELD_SPEC | S1009 | 42000 |
1064 | ER_PARSE_ERROR | 42000 | 42000 |
1065 | ER_EMPTY_QUERY | 42000 | 42000 |
1066 | ER_NONUNIQ_TABLE | S1009 | 42000 |
1067 | ER_INVALID_DEFAULT | S1009 | 42000 |
1068 | ER_MULTIPLE_PRI_KEY | S1009 | 42000 |
1069 | ER_TOO_MANY_KEYS | S1009 | 42000 |
1070 | ER_TOO_MANY_KEY_PARTS | S1009 | 42000 |
1071 | ER_TOO_LONG_KEY | S1009 | 42000 |
1072 | ER_KEY_COLUMN_DOES_NOT_EXITS | S1009 | 42000 |
1073 | ER_BLOB_USED_AS_KEY | S1009 | 42000 |
1074 | ER_TOO_BIG_FIELDLENGTH | S1009 | 42000 |
1075 | ER_WRONG_AUTO_KEY | S1009 | 42000 |
1080 | ER_FORCING_CLOSE | S1000 | 08S01 |
1081 | ER_IPSOCK_ERROR | 08S01 | 08S01 |
1082 | ER_NO_SUCH_INDEX | S1009 | 42S12 |
1083 | ER_WRONG_FIELD_TERMINATORS | S1009 | 42000 |
1084 | ER_BLOBS_AND_NO_TERMINATED | S1009 | 42000 |
1090 | ER_CANT_REMOVE_ALL_FIELDS | S1000 | 42000 |
1091 | ER_CANT_DROP_FIELD_OR_KEY | S1000 | 42000 |
1101 | ER_BLOB_CANT_HAVE_DEFAULT | S1000 | 42000 |
1102 | ER_WRONG_DB_NAME | S1000 | 42000 |
1103 | ER_WRONG_TABLE_NAME | S1000 | 42000 |
1104 | ER_TOO_BIG_SELECT | S1000 | 42000 |
1106 | ER_UNKNOWN_PROCEDURE | S1000 | 42000 |
1107 | ER_WRONG_PARAMCOUNT_TO_PROCEDURE | S1000 | 42000 |
1109 | ER_UNKNOWN_TABLE | S1000 | 42S02 |
1110 | ER_FIELD_SPECIFIED_TWICE | S1000 | 42000 |
1112 | ER_UNSUPPORTED_EXTENSION | S1000 | 42000 |
1113 | ER_TABLE_MUST_HAVE_COLUMNS | S1000 | 42000 |
1115 | ER_UNKNOWN_CHARACTER_SET | S1000 | 42000 |
1118 | ER_TOO_BIG_ROWSIZE | S1000 | 42000 |
1120 | ER_WRONG_OUTER_JOIN | S1000 | 42000 |
1121 | ER_NULL_COLUMN_IN_INDEX | S1000 | 42000 |
1129 | ER_HOST_IS_BLOCKED | 08004 | HY000 |
1130 | ER_HOST_NOT_PRIVILEGED | 08004 | HY000 |
1131 | ER_PASSWORD_ANONYMOUS_USER | S1000 | 42000 |
1132 | ER_PASSWORD_NOT_ALLOWED | S1000 | 42000 |
1133 | ER_PASSWORD_NO_MATCH | S1000 | 42000 |
1136 | ER_WRONG_VALUE_COUNT_ON_ROW | S1000 | 21S01 |
1138 | ER_INVALID_USE_OF_NULL | S1000 | 42000 |
1139 | ER_REGEXP_ERROR | S1000 | 42000 |
1140 | ER_MIX_OF_GROUP_FUNC_AND_FIELDS | S1000 | 42000 |
1141 | ER_NONEXISTING_GRANT | S1000 | 42000 |
1142 | ER_TABLEACCESS_DENIED_ERROR | S1000 | 42000 |
1143 | ER_COLUMNACCESS_DENIED_ERROR | S1000 | 42000 |
1144 | ER_ILLEGAL_GRANT_FOR_TABLE | S1000 | 42000 |
1145 | ER_GRANT_WRONG_HOST_OR_USER | S1000 | 42000 |
1146 | ER_NO_SUCH_TABLE | S1000 | 42S02 |
1147 | ER_NONEXISTING_TABLE_GRANT | S1000 | 42000 |
1148 | ER_NOT_ALLOWED_COMMAND | S1000 | 42000 |
1149 | ER_SYNTAX_ERROR | S1000 | 42000 |
1152 | ER_ABORTING_CONNECTION | S1000 | 08S01 |
1153 | ER_NET_PACKET_TOO_LARGE | S1000 | 08S01 |
1154 | ER_NET_READ_ERROR_FROM_PIPE | S1000 | 08S01 |
1155 | ER_NET_FCNTL_ERROR | S1000 | 08S01 |
1156 | ER_NET_PACKETS_OUT_OF_ORDER | S1000 | 08S01 |
1157 | ER_NET_UNCOMPRESS_ERROR | S1000 | 08S01 |
1158 | ER_NET_READ_ERROR | S1000 | 08S01 |
1159 | ER_NET_READ_INTERRUPTED | S1000 | 08S01 |
1160 | ER_NET_ERROR_ON_WRITE | S1000 | 08S01 |
1161 | ER_NET_WRITE_INTERRUPTED | S1000 | 08S01 |
1162 | ER_TOO_LONG_STRING | S1000 | 42000 |
1163 | ER_TABLE_CANT_HANDLE_BLOB | S1000 | 42000 |
1164 | ER_TABLE_CANT_HANDLE_AUTO_INCREMENT | S1000 | 42000 |
1166 | ER_WRONG_COLUMN_NAME | S1000 | 42000 |
1167 | ER_WRONG_KEY_COLUMN | S1000 | 42000 |
1169 | ER_DUP_UNIQUE | S1000 | 23000 |
1170 | ER_BLOB_KEY_WITHOUT_LENGTH | S1000 | 42000 |
1171 | ER_PRIMARY_CANT_HAVE_NULL | S1000 | 42000 |
1172 | ER_TOO_MANY_ROWS | S1000 | 42000 |
1173 | ER_REQUIRES_PRIMARY_KEY | S1000 | 42000 |
1177 | ER_CHECK_NO_SUCH_TABLE | S1000 | 42000 |
1178 | ER_CHECK_NOT_IMPLEMENTED | S1000 | 42000 |
1179 | ER_CANT_DO_THIS_DURING_AN_TRANSACTION | S1000 | 25000 |
1184 | ER_NEW_ABORTING_CONNECTION | S1000 | 08S01 |
1189 | ER_MASTER_NET_READ | S1000 | 08S01 |
1190 | ER_MASTER_NET_WRITE | S1000 | 08S01 |
1203 | ER_TOO_MANY_USER_CONNECTIONS | S1000 | 42000 |
1205 | ER_LOCK_WAIT_TIMEOUT | 41000 | 41000 |
1207 | ER_READ_ONLY_TRANSACTION | S1000 | 25000 |
1211 | ER_NO_PERMISSION_TO_CREATE_USER | S1000 | 42000 |
1213 | ER_LOCK_DEADLOCK | 41000 | 40001 |
1216 | ER_NO_REFERENCED_ROW | S1000 | 23000 |
1217 | ER_ROW_IS_REFERENCED | S1000 | 23000 |
1218 | ER_CONNECT_TO_MASTER | S1000 | 08S01 |
1222 | ER_WRONG_NUMBER_OF_COLUMNS_IN_SELECT | S1000 | 21000 |
1226 | ER_USER_LIMIT_REACHED | S1000 | 42000 |
1230 | ER_NO_DEFAULT | S1000 | 42000 |
1231 | ER_WRONG_VALUE_FOR_VAR | S1000 | 42000 |
1232 | ER_WRONG_TYPE_FOR_VAR | S1000 | 42000 |
1234 | ER_CANT_USE_OPTION_HERE | S1000 | 42000 |
1235 | ER_NOT_SUPPORTED_YET | S1000 | 42000 |
1239 | ER_WRONG_FK_DEF | S1000 | 42000 |
1241 | ER_OPERAND_COLUMNS | S1000 | 21000 |
1242 | ER_SUBQUERY_NO_1_ROW | S1000 | 21000 |
1247 | ER_ILLEGAL_REFERENCE | S1000 | 42S22 |
1248 | ER_DERIVED_MUST_HAVE_ALIAS | S1000 | 42000 |
1249 | ER_SELECT_REDUCED | S1000 | 01000 |
1250 | ER_TABLENAME_NOT_ALLOWED_HERE | S1000 | 42000 |
1251 | ER_NOT_SUPPORTED_AUTH_MODE | S1000 | 08004 |
1252 | ER_SPATIAL_CANT_HAVE_NULL | S1000 | 42000 |
1253 | ER_COLLATION_CHARSET_MISMATCH | S1000 | 42000 |
1261 | ER_WARN_TOO_FEW_RECORDS | S1000 | 01000 |
1262 | ER_WARN_TOO_MANY_RECORDS | S1000 | 01000 |
1263 | ER_WARN_NULL_TO_NOTNULL | S1000 | 01000 |
1264 | ER_WARN_DATA_OUT_OF_RANGE | S1000 | 01000 |
1265 | ER_WARN_DATA_TRUNCATED | S1000 | 01000 |
1280 | ER_WRONG_NAME_FOR_INDEX | S1000 | 42000 |
1281 | ER_WRONG_NAME_FOR_CATALOG | S1000 | 42000 |
1286 | ER_UNKNOWN_STORAGE_ENGINE | S1000 | 42000 |
JDBC Concepts
- Connecting to MariaDB Using the
DriverManager
Interface- Using Statements to Execute SQL
- Using
CallableStatements
to Execute Stored Procedures- Retrieving
AUTO_INCREMENT
Column Values - Using Statements to Execute SQL
This section provides some general JDBC background.
Connecting to MariaDB Using the DriverManager
Interface
When you are using JDBC outside of an application server, the DriverManager
class manages the establishment of Connections.
Specify to the DriverManager
which JDBC drivers to try to make Connections with. The easiest way to do this is to use Class.forName()
on the class that implements the java.sql.Driver
interface. With MariaDB Connector/J, the name of this class is com.mysql.jdbc.Driver
. With this method, you could use an external configuration file to supply the driver class name and driver parameters to use when connecting to a database.
The following section of Java code shows how you might register MariaDB Connector/J from the main()
method of your application. If testing this code, first read the installation section at , "Connector/J Installation", to make sure you have connector installed correctly and the CLASSPATH
set up. Also, ensure that MariaDB is configured to accept external TCP/IP connections.
import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; // Notice, do not import com.mysql.jdbc.* // or you will have problems! public class LoadDriver { public static void main(String[] args) { try { // The newInstance() call is a work around for some // broken Java implementations Class.forName('com.mysql.jdbc.Driver').newInstance(); } catch (Exception ex) { // handle the error } } }
After the driver has been registered with the DriverManager
, you can obtain a Connection
instance that is connected to a particular database by calling DriverManager.getConnection()
:
Example 20.1. Connector/J: Obtaining a connection from the DriverManager
If you have not already done so, please review the section , "Connecting to MariaDB Using the DriverManager
Interface" before working with these examples.
This example shows how you can obtain a Connection
instance from the DriverManager
. There are a few different signatures for the getConnection()
method. Consult the API documentation that comes with your JDK for more specific information on how to use them.
import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; Connection conn = null; ... try { conn = DriverManager.getConnection('jdbc:mysql://localhost/test?' + 'user=monty&password=greatsqldb'); // Do something with the Connection ... } catch (SQLException ex) { // handle any errors System.out.println('SQLException: ' + ex.getMessage()); System.out.println('SQLState: ' + ex.getSQLState()); System.out.println('VendorError: ' + ex.getErrorCode()); }
Once a Connection
is established, it can be used to create Statement
and PreparedStatement
objects, as well as retrieve metadata about the database. This is explained in the following sections.
Using Statements to Execute SQL
Statement
objects allow you to execute basic SQL queries and retrieve the results through the ResultSet
class which is described later.
To create a Statement
instance, you call the createStatement()
method on the Connection
object you have retrieved using one of the DriverManager.getConnection()
or DataSource.getConnection()
methods described earlier.
Once you have a Statement
instance, you can execute a SELECT
query by calling the executeQuery(String)
method with the SQL you want to use.
To update data in the database, use the executeUpdate(String SQL)
method. This method returns the number of rows matched by the update statement, not the number of rows that were modified.
If you do not know ahead of time whether the SQL statement will be a SELECT
or an UPDATE
/INSERT
, then you can use the execute(String SQL)
method. This method will return true if the SQL query was a SELECT
, or false if it was an UPDATE
, INSERT
, or DELETE
statement. If the statement was a SELECT
query, you can retrieve the results by calling the getResultSet()
method. If the statement was an UPDATE
, INSERT
, or DELETE
statement, you can retrieve the affected rows count by calling getUpdateCount()
on the Statement
instance.
Example 20.2. Connector/J: Using java.sql.Statement to execute a SELECT
query
import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; import java.sql.Statement; import java.sql.ResultSet; // assume that conn is an already created JDBC connection (see previous examples) Statement stmt = null; ResultSet rs = null; try { stmt = conn.createStatement(); rs = stmt.executeQuery('SELECT foo FROM bar'); // or alternatively, if you don't know ahead of time that // the query will be a SELECT... if (stmt.execute('SELECT foo FROM bar')) { rs = stmt.getResultSet(); } // Now do something with the ResultSet .... } catch (SQLException ex){ // handle any errors System.out.println('SQLException: ' + ex.getMessage()); System.out.println('SQLState: ' + ex.getSQLState()); System.out.println('VendorError: ' + ex.getErrorCode()); } finally { // it is a good idea to release // resources in a finally{} block // in reverse-order of their creation // if they are no-longer needed if (rs != null) { try { rs.close(); } catch (SQLException sqlEx) { } // ignore rs = null; } if (stmt != null) { try { stmt.close(); } catch (SQLException sqlEx) { } // ignore stmt = null; } }
Using CallableStatements
to Execute Stored Procedures
Starting with MariaDB server version 5.0 when used with Connector/J 3.1.1 or newer, the java.sql.CallableStatement
interface is fully implemented with the exception of the getParameterMetaData()
method.
For more information on MariaDB stored procedures, please refer to http://dev.mysql.com/doc/mysql/en/stored-routines.html.
Connector/J exposes stored procedure functionality through JDBC's CallableStatement
interface.Note
Current versions of MariaDB server do not return enough information for the JDBC driver to provide result set metadata for callable statements. This means that when using CallableStatement
, ResultSetMetaData
may return NULL
.
The following example shows a stored procedure that returns the value of inOutParam
incremented by 1, and the string passed in using inputParam
as a ResultSet
:
Example 20.3. Connector/J: Calling Stored Procedures
CREATE PROCEDURE demoSp(IN inputParam VARCHAR(255), \ INOUT inOutParam INT) BEGIN DECLARE z INT; SET z = inOutParam + 1; SET inOutParam = z; SELECT inputParam; SELECT CONCAT('zyxw', inputParam); END
To use the demoSp
procedure with Connector/J, follow these steps:
- Prepare the callable statement by using
Connection.prepareCall()
.
Notice that you have to use JDBC escape syntax, and that the parentheses surrounding the parameter placeholders are not optional:
Example 20.4. Connector/J: Using
Connection.prepareCall()
import java.sql.CallableStatement; ... // // Prepare a call to the stored procedure 'demoSp' // with two parameters // // Notice the use of JDBC-escape syntax ({call ...}) // CallableStatement cStmt = conn.prepareCall('{call demoSp(?, ?)}'); cStmt.setString(1, 'abcdefg');
NoteConnection.prepareCall()
is an expensive method, due to the metadata retrieval that the driver performs to support output parameters. For performance reasons, minimize unnecessary calls toConnection.prepareCall()
by reusingCallableStatement
instances in your code. - Register the output parameters (if any exist)
To retrieve the values of output parameters (parameters specified as
OUT
orINOUT
when you created the stored procedure), JDBC requires that they be specified before statement execution using the variousregisterOutputParameter()
methods in theCallableStatement
interface:Example 20.5. Connector/J: Registering output parameters
import java.sql.Types; ... // // Connector/J supports both named and indexed // output parameters. You can register output // parameters using either method, as well // as retrieve output parameters using either // method, regardless of what method was // used to register them. // // The following examples show how to use // the various methods of registering // output parameters (you should of course // use only one registration per parameter). // // // Registers the second parameter as output, and // uses the type 'INTEGER' for values returned from // getObject() // cStmt.registerOutParameter(2, Types.INTEGER); // // Registers the named parameter 'inOutParam', and // uses the type 'INTEGER' for values returned from // getObject() // cStmt.registerOutParameter('inOutParam', Types.INTEGER); ...
- Set the input parameters (if any exist)
Input and in/out parameters are set as for
PreparedStatement
objects. However,CallableStatement
also supports setting parameters by name:Example 20.6. Connector/J: Setting
CallableStatement
input parameters... // // Set a parameter by index // cStmt.setString(1, 'abcdefg'); // // Alternatively, set a parameter using // the parameter name // cStmt.setString('inputParameter', 'abcdefg'); // // Set the 'in/out' parameter using an index // cStmt.setInt(2, 1); // // Alternatively, set the 'in/out' parameter // by name // cStmt.setInt('inOutParam', 1); ...
- Execute the
CallableStatement
, and retrieve any result sets or output parameters.Although
CallableStatement
supports calling any of theStatement
execute methods (executeUpdate()
,executeQuery()
orexecute()
), the most flexible method to call isexecute()
, as you do not need to know ahead of time if the stored procedure returns result sets:Example 20.7. Connector/J: Retrieving results and output parameter values
... boolean hadResults = cStmt.execute(); // // Process all returned result sets // while (hadResults) { ResultSet rs = cStmt.getResultSet(); // process result set ... hadResults = cStmt.getMoreResults(); } // // Retrieve output parameters // // Connector/J supports both index-based and // name-based retrieval // int outputValue = cStmt.getInt(2); // index-based outputValue = cStmt.getInt('inOutParam'); // name-based ...
Retrieving AUTO_INCREMENT
Column Values
Before version 3.0 of the JDBC API, there was no standard way of retrieving key values from databases that supported auto increment or identity columns. With older JDBC drivers for MySQL, you could always use a MySQL-specific method on the Statement
interface, or issue the query SELECT LAST_INSERT_ID()
after issuing an INSERT
to a table that had an AUTO_INCREMENT
key. Using the MySQL-specific method call isn't portable, and issuing a SELECT
to get the AUTO_INCREMENT
key's value requires another round-trip to the database, which isn't as efficient as possible. The following code snippets demonstrate the three different ways to retrieve AUTO_INCREMENT
values. First, we demonstrate the use of the new JDBC-3.0 method getGeneratedKeys()
which is now the preferred method to use if you need to retrieve AUTO_INCREMENT
keys and have access to JDBC-3.0. The second example shows how you can retrieve the same value using a standard SELECT LAST_INSERT_ID()
query. The final example shows how updatable result sets can retrieve the AUTO_INCREMENT
value when using the insertRow()
method.
Example 20.8. Connector/J: Retrieving AUTO_INCREMENT
column values using Statement.getGeneratedKeys()
Statement stmt = null; ResultSet rs = null; try { // // Create a Statement instance that we can use for // 'normal' result sets assuming you have a // Connection 'conn' to a MariaDB database already // available stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY, java.sql.ResultSet.CONCUR_UPDATABLE); // // Issue the DDL queries for the table for this example // stmt.executeUpdate('DROP TABLE IF EXISTS autoIncTutorial'); stmt.executeUpdate( 'CREATE TABLE autoIncTutorial (' + 'priKey INT NOT NULL AUTO_INCREMENT, ' + 'dataField VARCHAR(64), PRIMARY KEY (priKey))'); // // Insert one row that will generate an AUTO INCREMENT // key in the 'priKey' field // stmt.executeUpdate( 'INSERT INTO autoIncTutorial (dataField) ' + 'values ('Can I Get the Auto Increment Field?')', Statement.RETURN_GENERATED_KEYS); // // Example of using Statement.getGeneratedKeys() // to retrieve the value of an auto-increment // value // int autoIncKeyFromApi = -1; rs = stmt.getGeneratedKeys(); if (rs.next()) { autoIncKeyFromApi = rs.getInt(1); } else { // throw an exception from here } rs.close(); rs = null; System.out.println('Key returned from getGeneratedKeys():' + autoIncKeyFromApi); } finally { if (rs != null) { try { rs.close(); } catch (SQLException ex) { // ignore } } if (stmt != null) { try { stmt.close(); } catch (SQLException ex) { // ignore } } }
Example 20.9. Connector/J: Retrieving AUTO_INCREMENT
column values using SELECT LAST_INSERT_ID()
Statement stmt = null; ResultSet rs = null; try { // // Create a Statement instance that we can use for // 'normal' result sets. stmt = conn.createStatement(); // // Issue the DDL queries for the table for this example // stmt.executeUpdate('DROP TABLE IF EXISTS autoIncTutorial'); stmt.executeUpdate( 'CREATE TABLE autoIncTutorial (' + 'priKey INT NOT NULL AUTO_INCREMENT, ' + 'dataField VARCHAR(64), PRIMARY KEY (priKey))'); // // Insert one row that will generate an AUTO INCREMENT // key in the 'priKey' field // stmt.executeUpdate( 'INSERT INTO autoIncTutorial (dataField) ' + 'values ('Can I Get the Auto Increment Field?')'); // // Use the MariaDB LAST_INSERT_ID() // function to do the same thing as getGeneratedKeys() // int autoIncKeyFromFunc = -1; rs = stmt.executeQuery('SELECT LAST_INSERT_ID()'); if (rs.next()) { autoIncKeyFromFunc = rs.getInt(1); } else { // throw an exception from here } rs.close(); System.out.println('Key returned from ' + ''SELECT LAST_INSERT_ID()': ' + autoIncKeyFromFunc); } finally { if (rs != null) { try { rs.close(); } catch (SQLException ex) { // ignore } } if (stmt != null) { try { stmt.close(); } catch (SQLException ex) { // ignore } } }
Example 20.10. Connector/J: Retrieving AUTO_INCREMENT
column values in Updatable ResultSets
Statement stmt = null; ResultSet rs = null; try { // // Create a Statement instance that we can use for // 'normal' result sets as well as an 'updatable' // one, assuming you have a Connection 'conn' to // a MariaDB database already available // stmt = conn.createStatement(java.sql.ResultSet.TYPE_FORWARD_ONLY, java.sql.ResultSet.CONCUR_UPDATABLE); // // Issue the DDL queries for the table for this example // stmt.executeUpdate('DROP TABLE IF EXISTS autoIncTutorial'); stmt.executeUpdate( 'CREATE TABLE autoIncTutorial (' + 'priKey INT NOT NULL AUTO_INCREMENT, ' + 'dataField VARCHAR(64), PRIMARY KEY (priKey))'); // // Example of retrieving an AUTO INCREMENT key // from an updatable result set // rs = stmt.executeQuery('SELECT priKey, dataField ' + 'FROM autoIncTutorial'); rs.moveToInsertRow(); rs.updateString('dataField', 'AUTO INCREMENT here?'); rs.insertRow(); // // the driver adds rows at the end // rs.last(); // // We should now be on the row we just inserted // int autoIncKeyFromRS = rs.getInt('priKey'); rs.close(); rs = null; System.out.println('Key returned for inserted row: ' + autoIncKeyFromRS); } finally { if (rs != null) { try { rs.close(); } catch (SQLException ex) { // ignore } } if (stmt != null) { try { stmt.close(); } catch (SQLException ex) { // ignore } } }
Running the preceding example code should produce the following output:
Key returned from getGeneratedKeys(): 1 Key returned from SELECT LAST_INSERT_ID(): 1 Key returned for inserted row: 2
At times, it can be tricky to use the SELECT LAST_INSERT_ID()
query, as that function's value is scoped to a connection. So, if some other query happens on the same connection, the value is overwritten. On the other hand, the getGeneratedKeys()
method is scoped by the Statement
instance, so it can be used even if other queries happen on the same connection, but not on the same Statement
instance.
J2EE Concepts
- Understanding Connection Pooling
- Managing Load Balanced Connections
- Load Balancing Failover Policies
- Managing Load Balanced Connections
This section provides general background on J2EE concepts that pertain to use of Connector/J.
Understanding Connection Pooling
Connection pooling is a technique of creating and managing a pool of connections that are ready for use by any thread that needs them. Connection pooling can greatly increase the performance of your Java application, while reducing overall resource usage.
How Connection Pooling Works
Most applications only need a thread to have access to a JDBC connection when they are actively processing a transaction, which often takes only milliseconds to complete. When not processing a transaction, the connection sits idle. Connection pooling enables the idle connection to be used by some other thread to do useful work.
In practice, when a thread needs to do work against a MariaDB or other database with JDBC, it requests a connection from the pool. When the thread is finished using the connection, it returns it to the pool, so that it can be used by any other threads.
When the connection is loaned out from the pool, it is used exclusively by the thread that requested it. From a programming point of view, it is the same as if your thread called DriverManager.getConnection()
every time it needed a JDBC connection. With connection pooling, your thread may end up using either a new connection or an already-existing connection.
Benefits of Connection Pooling
The main benefits to connection pooling are:
- Reduced connection creation time.
Although this is not usually an issue with the quick connection setup that MariaDB offers compared to other databases, creating new JDBC connections still incurs networking and JDBC driver overhead that will be avoided if connections are recycled.
- Simplified programming model.
When using connection pooling, each individual thread can act as though it has created its own JDBC connection, allowing you to use straightforward JDBC programming techniques.
- Controlled resource usage.
If you create a new connection every time a thread needs one, rather than using connection pooling, your application's resource usage can be wasteful and lead to unpredictable behavior under load.
Using Connection Pooling with Connector/J
Sun has standardized the concept of connection pooling in JDBC through the JDBC-2.0 Optional interfaces, and all major application servers have implementations of these APIs that work with MariaDB Connector/J.
Generally, you configure a connection pool in your application server configuration files, and access it through the Java Naming and Directory Interface (JNDI). The following code shows how you might use a connection pool from an application deployed in a J2EE application server:
Example 20.11. Connector/J: Using a connection pool with a J2EE application server
import java.sql.Connection; import java.sql.SQLException; import java.sql.Statement; import javax.naming.InitialContext; import javax.sql.DataSource; public class MyServletJspOrEjb { public void doSomething() throws Exception { /* * Create a JNDI Initial context to be able to * lookup the DataSource * * In production-level code, this should be cached as * an instance or static variable, as it can * be quite expensive to create a JNDI context. * * Note: This code only works when you are using servlets * or EJBs in a J2EE application server. If you are * using connection pooling in standalone Java code, you * will have to create/configure datasources using whatever * mechanisms your particular connection pooling library * provides. */ InitialContext ctx = new InitialContext(); /* * Lookup the DataSource, which will be backed by a pool * that the application server provides. DataSource instances * are also a good candidate for caching as an instance * variable, as JNDI lookups can be expensive as well. */ DataSource ds = (DataSource)ctx.lookup('java:comp/env/jdbc/MySQLDB'); /* * The following code is what would actually be in your * Servlet, JSP or EJB 'service' method...where you need * to work with a JDBC connection. */ Connection conn = null; Statement stmt = null; try { conn = ds.getConnection(); /* * Now, use normal JDBC programming to work with * MySQL, making sure to close each resource when you're * finished with it, which permits the connection pool * resources to be recovered as quickly as possible */ stmt = conn.createStatement(); stmt.execute('SOME SQL QUERY'); stmt.close(); stmt = null; conn.close(); conn = null; } finally { /* * close any jdbc instances here that weren't * explicitly closed during normal code path, so * that we don't 'leak' resources... */ if (stmt != null) { try { stmt.close(); } catch (sqlexception sqlex) { // ignore -- as we can't do anything about it here } stmt = null; } if (conn != null) { try { conn.close(); } catch (sqlexception sqlex) { // ignore -- as we can't do anything about it here } conn = null; } } } }
As shown in the example above, after obtaining the JNDI InitialContext
, and looking up the DataSource
, the rest of the code follows familiar JDBC conventions.
When using connection pooling, always make sure that connections, and anything created by them (such as statements or result sets) are closed. This rule applies no matter what happens in your code (exceptions, flow-of-control, and so forth). When these objects are closed, they can be re-used; otherwise, they will be stranded, which means that the MariaDB server resources they represent (such as buffers, locks, or sockets) are tied up for some time, or in the worst case can be tied up forever.
Sizing the Connection Pool
Each connection to MariaDB has overhead (memory, CPU, context switches, and so forth) on both the client and server side. Every connection limits how many resources there are available to your application as well as the MariaDB server. Many of these resources will be used whether or not the connection is actually doing any useful work! Connection pools can be tuned to maximize performance, while keeping resource utilization below the point where your application will start to fail rather than just run slower.
The optimal size for the connection pool depends on anticipated load and average database transaction time. In practice, the optimal connection pool size can be smaller than you might expect. If you take Sun's Java Petstore blueprint application for example, a connection pool of 15-20 connections can serve a relatively moderate load (600 concurrent users) using MariaDB and Tomcat with acceptable response times.
To correctly size a connection pool for your application, create load test scripts with tools such as Apache JMeter or The Grinder, and load test your application.
An easy way to determine a starting point is to configure your connection pool's maximum number of connections to be unbounded, run a load test, and measure the largest amount of concurrently used connections. You can then work backward from there to determine what values of minimum and maximum pooled connections give the best performance for your particular application.
Validating Connections
MySQL Connector/J can validate the connection by executing a lightweight ping against a server. In the case of load-balanced connections, this is performed against all active pooled internal connections that are retained. This is beneficial to Java applications using connection pools, as the pool can use this feature to validate connections. Depending on your connection pool and configuration, this validation can be carried out at different times:
- Before the pool returns a connection to the application.
- When the application returns a connection to the pool.
- During periodic checks of idle connections.
To use this feature, specify a validation query in your connection pool that starts with /* ping */
. Note that the syntax must be exactly as specified. This will cause the driver send a ping to the server and return a dummy lightweight result set. When using a ReplicationConnection
or LoadBalancedConnection
, the ping will be sent across all active connections.
It is critical that the syntax be specified correctly. The syntax needs to be exact for reasons of efficiency, as this test is done for every statement that is executed:
protected static final String PING_MARKER = '/* ping */'; ... if (sql.charAt(0) == '/') { if (sql.startsWith(PING_MARKER)) { doPingInstead(); ...
None of the following snippets will work, because the ping syntax is sensitive to whitespace, capitalization, and placement:
sql = '/* PING */ SELECT 1'; sql = 'SELECT 1 /* ping*/'; sql = '/*ping*/ SELECT 1'; sql = ' /* ping */ SELECT 1'; sql = '/*to ping or not to ping*/ SELECT 1';
All of the previous statements will issue a normal SELECT
statement and will not be transformed into the lightweight ping. Further, for load-balanced connections, the statement will be executed against one connection in the internal pool, rather than validating each underlying physical connection. This results in the non-active physical connections assuming a stale state, and they may die. If Connector/J then re-balances, it might select a dead connection, resulting in an exception being passed to the application. To help prevent this, you can use loadBalanceValidateConnectionOnSwapServer
to validate the connection before use.
If your Connector/J deployment uses a connection pool that allows you to specify a validation query, take advantage of it, but ensure that the query starts exactly with /* ping */
. This is particularly important if you are using the load-balancing or replication-aware features of Connector/J, as it will help keep alive connections which otherwise will go stale and die, causing problems later.
Managing Load Balanced Connections
Connector/J has long provided an effective means to distribute read/write load across multiple MariaDB server instances for Cluster or master-master replication deployments. Starting with Connector/J 5.1.3, you can now dynamically configure load-balanced connections, with no service outage. In-process transactions are not lost, and no application exceptions are generated if any application is trying to use that particular server instance.
There are two connection string options associated with this functionality:
loadBalanceConnectionGroup
- This provides the ability to group connections from different sources. This allows you to manage these JDBC sources within a single class-loader in any combination you choose. If they use the same configuration, and you want to manage them as a logical single group, give them the same name. This is the key property for management: if you do not define a name (string) forloadBalanceConnectionGroup
, you cannot manage the connections. All load-balanced connections sharing the sameloadBalanceConnectionGroup
value, regardless of how the application creates them, will be managed together.loadBalanceEnableJMX
- The ability to manage the connections is exposed when you define aloadBalanceConnectionGroup
, but if you want to manage this externally, enable JMX by setting this property totrue
. This enables a JMX implementation, which exposes the management and monitoring operations of a connection group. Further, start your application with the-Dcom.sun.management.jmxremote
JVM flag. You can then perform connect and perform operations using a JMX client such asjconsole
.
Once a connection has been made using the correct connection string options, a number of monitoring properties are available:
- Current active host count.
- Current active physical connection count.
- Current active logical connection count.
- Total logical connections created.
- Total transaction count.
The following management operations can also be performed:
- Add host.
- Remove host.
The JMX interface, com.mysql.jdbc.jmx.LoadBalanceConnectionGroupManagerMBean
, has the following methods:
int getActiveHostCount(String group);
int getTotalHostCount(String group);
long getTotalLogicalConnectionCount(String group);
long getActiveLogicalConnectionCount(String group);
long getActivePhysicalConnectionCount(String group);
long getTotalPhysicalConnectionCount(String group);
long getTotalTransactionCount(String group);
void removeHost(String group, String host) throws SQLException;
void stopNewConnectionsToHost(String group, String host) throws SQLException;
void addHost(String group, String host, boolean forExisting);
String getActiveHostsList(String group);
String getRegisteredConnectionGroups();
The getRegisteredConnectionGroups()
method returns the names of all connection groups defined in that class-loader.
You can test this setup with the following code:
public class Test { private static String URL = 'jdbc:mysql:loadbalance://' + 'localhost:3306,localhost:3310/test?' + 'loadBalanceConnectionGroup=first&loadBalanceEnableJMX=true'; public static void main(String[] args) throws Exception { new Thread(new Repeater()).start(); new Thread(new Repeater()).start(); new Thread(new Repeater()).start(); } static Connection getNewConnection() throws SQLException, ClassNotFoundException { Class.forName('com.mysql.jdbc.Driver'); return DriverManager.getConnection(URL, 'root', ''); } static void executeSimpleTransaction(Connection c, int conn, int trans){ try { c.setAutoCommit(false); Statement s = c.createStatement(); s.executeQuery('SELECT SLEEP(1) /* Connection: ' + conn + ', transaction: ' + trans + ' */'); c.commit(); } catch (SQLException e) { e.printStackTrace(); } } public static class Repeater implements Runnable { public void run() { for(int i=0; i < 100; i++){ try { Connection c = getNewConnection(); for(int j=0; j < 10; j++){ executeSimpleTransaction(c, i, j); Thread.sleep(Math.round(100 * Math.random())); } c.close(); Thread.sleep(100); } catch (Exception e) { e.printStackTrace(); } } } } }
After compiling, the application can be started with the -Dcom.sun.management.jmxremote
flag, to enable remote management. jconsole
can then be started. The Test
main class will be listed by jconsole
. Select this and click Connect. You can then navigate to the com.mysql.jdbc.jmx.LoadBalanceConnectionGroupManager
bean. At this point, you can click on various operations and examine the returned result.
If you now had an additional instance of MariaDB running on port 3309, you could ensure that Connector/J starts using it by using the addHost()
, which is exposed in jconsole
. Note that these operations can be performed dynamically without having to stop the application running.
Load Balancing Failover Policies
Connector/J provides a useful load-balancing implementation for Cluster or multi-master deployments. As of Connector/J 5.1.12, this same implementation is used for balancing load between read-only slaves with ReplicationDriver
. When trying to balance workload between multiple servers, the driver has to determine when it is safe to swap servers, doing so in the middle of a transaction, for example, could cause problems. It is important not to lose state information. For this reason, Connector/J will only try to pick a new server when one of the following happens:
- At transaction boundaries (transactions are explicitly committed or rolled back).
- A communication exception (SQL State starting with '08') is encountered.
- When a
SQLException
matches conditions defined by user, using the extension points defined by theloadBalanceSQLStateFailover
,loadBalanceSQLExceptionSubclassFailover
orloadBalanceExceptionChecker
properties.
The third condition revolves around three new properties introduced with Connector/J 5.1.13. It allows you to control which SQLException
s trigger failover.
loadBalanceExceptionChecker
- TheloadBalanceExceptionChecker
property is really the key. This takes a fully-qualified class name which implements the newcom.mysql.jdbc.LoadBalanceExceptionChecker
interface. This interface is very simple, and you only need to implement the following method:
public boolean shouldExceptionTriggerFailover(SQLException ex)
A
SQLException
is passed in, and a boolean returned.True
triggers a failover,false
does not.You can use this to implement your own custom logic. An example where this might be useful is when dealing with transient errors when using MariaDB Cluster, where certain buffers may become overloaded. The following code snippet illustrates this:
public class NdbLoadBalanceExceptionChecker extends StandardLoadBalanceExceptionChecker { public boolean shouldExceptionTriggerFailover(SQLException ex) { return super.shouldExceptionTriggerFailover(ex) || checkNdbException(ex); } private boolean checkNdbException(SQLException ex){ // Have to parse the message since most NDB errors // are mapped to the same DEMC. return (ex.getMessage().startsWith('Lock wait timeout exceeded') || (ex.getMessage().startsWith('Got temporary error') && ex.getMessage().endsWith('from NDB'))); } }
The code above extends
com.mysql.jdbc.StandardLoadBalanceExceptionChecker
, which is the default implementation. There are a few convenient shortcuts built into this, for those who want to have some level of control using properties, without writing Java code. This default implementation uses the two remaining properties:loadBalanceSQLStateFailover
andloadBalanceSQLExceptionSubclassFailover
.loadBalanceSQLStateFailover
- allows you to define a comma-delimited list ofSQLState
code prefixes, against which aSQLException
is compared. If the prefix matches, failover is triggered. So, for example, the following would trigger a failover if a givenSQLException
starts with '00', or is '12345':loadBalanceSQLStateFailover=00,12345
loadBalanceSQLExceptionSubclassFailover
- can be used in conjunction withloadBalanceSQLStateFailover
or on its own. If you want certain subclasses ofSQLException
to trigger failover, simply provide a comma-delimited list of fully-qualified class or interface names to check against. For example, if you want allSQLTransientConnectionExceptions
to trigger failover, you would specify:loadBalanceSQLExceptionSubclassFailover=java.sql.SQLTransientConnectionException
While the three fail-over conditions enumerated earlier suit most situations, if auto-commit
is enabled, Connector/J never re-balances, and continues using the same physical connection. This can be problematic, particularly when load-balancing is being used to distribute read-only load across multiple slaves. However, Connector/J can be configured to re-balance after a certain number of statements are executed, when auto-commit
is enabled. This functionality is dependent upon the following properties:
loadBalanceAutoCommitStatementThreshold
- defines the number of matching statements which will trigger the driver to potentially swap physical server connections. The default value, 0, retains the behavior that connections withauto-commit
enabled are never balanced.loadBalanceAutoCommitStatementRegex
- the regular expression against which statements must match. The default value, blank, matches all statements. So, for example, using the following properties will cause Connector/J to re-balance after every third statement that contains the string "test":loadBalanceAutoCommitStatementThreshold=3 loadBalanceAutoCommitStatementRegex=.*test.*
loadBalanceAutoCommitStatementRegex
can prove useful in a number of situations. Your application may use temporary tables, server-side session state variables, or connection state, where letting the driver arbitrarily swap physical connections before processing is complete could cause data loss or other problems. This allows you to identify a trigger statement that is only executed when it is safe to swap physical connections.
Using Connector/J with Tomcat
The following instructions are based on the instructions for Tomcat-5.x, available at http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html which is current at the time this document was written.
First, install the .jar file that comes with Connector/J in $CATALINA_HOME/common/lib
so that it is available to all applications installed in the container.
Next, Configure the JNDI DataSource by adding a declaration resource to $CATALINA_HOME/conf/server.xml
in the context that defines your web application:
<Context ....> ... <Resource name="jdbc/MySQLDB" auth="Container" type="javax.sql.DataSource"/> <!-- The name you used above, must match _exactly_ here! The connection pool will be bound into JNDI with the name 'java:/comp/env/jdbc/MySQLDB' --> <ResourceParams name="jdbc/MySQLDB"> <parameter> <name>factory</name> <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> </parameter> <!-- Don't set this any higher than max_connections on your MariaDB server, usually this should be a 10 or a few 10's of connections, not hundreds or thousands --> <parameter> <name>maxActive</name> <value>10</value> </parameter> <!-- You don't want to many idle connections hanging around if you can avoid it, only enough to soak up a spike in the load --> <parameter> <name>maxIdle</name> <value>5</value> </parameter> <!-- Don't use autoReconnect=true, it's going away eventually and it's a crutch for older connection pools that couldn't test connections. You need to decide whether your application is supposed to deal with SQLExceptions (hint, it should), and how much of a performance penalty you're willing to pay to ensure 'freshness' of the connection --> <parameter> <name>validationQuery</name> <value>SELECT 1</value> <-- See discussion below for update to this option --> </parameter> <!-- The most conservative approach is to test connections before they're given to your application. For most applications this is okay, the query used above is very small and takes no real server resources to process, other than the time used to traverse the network. If you have a high-load application you'll need to rely on something else. --> <parameter> <name>testOnBorrow</name> <value>true</value> </parameter> <!-- Otherwise, or in addition to testOnBorrow, you can test while connections are sitting idle --> <parameter> <name>testWhileIdle</name> <value>true</value> </parameter> <!-- You have to set this value, otherwise even though you've asked connections to be tested while idle, the idle evicter thread will never run --> <parameter> <name>timeBetweenEvictionRunsMillis</name> <value>10000</value> </parameter> <!-- Don't allow connections to hang out idle too long, never longer than what wait_timeout is set to on the server...A few minutes or even fraction of a minute is sometimes okay here, it depends on your application and how much spikey load it will see --> <parameter> <name>minEvictableIdleTimeMillis</name> <value>60000</value> </parameter> <!-- Username and password used when connecting to MariaDB --> <parameter> <name>username</name> <value>someuser</value> </parameter> <parameter> <name>password</name> <value>somepass</value> </parameter> <!-- Class name for the Connector/J driver --> <parameter> <name>driverClassName</name> <value>com.mysql.jdbc.Driver</value> </parameter> <!-- The JDBC connection url for connecting to MySQL, notice that if you want to pass any other MySQL-specific parameters you should pass them here in the URL, setting them using the parameter tags above will have no effect, you will also need to use & to separate parameter values as the ampersand is a reserved character in XML --> <parameter> <name>url</name> <value>jdbc:mysql://localhost:3306/test</value> </parameter> </ResourceParams> </Context>
Note that Connector/J 5.1.3 introduced a facility whereby, rather than use a validationQuery
value of SELECT 1
, it is possible to use validationQuery
with a value set to /* ping */
. This sends a ping to the server which then returns a fake result set. This is a lighter weight solution. It also has the advantage that if using ReplicationConnection
or LoadBalancedConnection
type connections, the ping will be sent across all active connections. The following XML snippet illustrates how to select this option:
<parameter> <name>validationQuery</name> <value>/* ping */</value> </parameter>
Note that /* ping */
has to be specified exactly.
In general, follow the installation instructions that come with your version of Tomcat, as the way you configure datasources in Tomcat changes from time-to-time, and if you use the wrong syntax in your XML file, you will most likely end up with an exception similar to the following:
Error: java.sql.SQLException: Cannot load JDBC driver class 'null ' SQL state: null
Note that the auto-loading of drivers having the META-INF/service/java.sql.Driver
class in JDBC 4.0 causes an improper undeployment of the Connector/J driver in Tomcat on Windows. Namely, the Connector/J jar remains locked. This is an initialization problem that is not related to the driver. The possible workarounds, if viable, are as follows: use 'antiResourceLocking=true
' as a Tomcat Context attribute, or remove the META-INF/
directory.
Using Connector/J with JBoss
These instructions cover JBoss-4.x. To make the JDBC driver classes available to the application server, copy the .jar file that comes with Connector/J to the lib
directory for your server configuration (which is usually called default
). Then, in the same configuration directory, in the subdirectory named deploy, create a datasource configuration file that ends with '-ds.xml', which tells JBoss to deploy this file as a JDBC Datasource. The file should have the following contents:
<datasources> <local-tx-datasource> <!-- This connection pool will be bound into JNDI with the name 'java:/MySQLDB' --> <jndi-name>MySQLDB</jndi-name> <connection-url>jdbc:mysql://localhost:3306/dbname</connection-url> <driver-class>com.mysql.jdbc.Driver</driver-class> <user-name>user</user-name> <password>pass</password> <min-pool-size>5</min-pool-size> <!-- Don't set this any higher than max_connections on your MariaDB server, usually this should be a 10 or a few 10's of connections, not hundreds or thousands --> <max-pool-size>20</max-pool-size> <!-- Don't allow connections to hang out idle too long, never longer than what wait_timeout is set to on the server...A few minutes is usually okay here, it depends on your application and how much spikey load it will see --> <idle-timeout-minutes>5</idle-timeout-minutes> <!-- If you're using Connector/J 3.1.8 or newer, you can use our implementation of these to increase the robustness of the connection pool. --> <exception-sorter-class-name> com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter </exception-sorter-class-name> <valid-connection-checker-class-name> com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker </valid-connection-checker-class-name> </local-tx-datasource> </datasources>
Using Connector/J with Spring
The Spring Framework is a Java-based application framework designed for assisting in application design by providing a way to configure components. The technique used by Spring is a well known design pattern called Dependency Injection (see Inversion of Control Containers and the Dependency Injection pattern). This article will focus on Java-oriented access to MariaDB databases with Spring 2.0. For those wondering, there is a .NET port of Spring appropriately named Spring.NET.
Spring is not only a system for configuring components, but also includes support for aspect oriented programming (AOP). This is one of the main benefits and the foundation for Spring's resource and transaction management. Spring also provides utilities for integrating resource management with JDBC and Hibernate.
For the examples in this section the MariaDB world sample database will be used. The first task is to set up a MariaDB data source through Spring. Components within Spring use the 'bean' terminology. For example, to configure a connection to a MariaDB server supporting the world sample database you might use:
<util:map id="dbProps"> <entry key="db.driver" value="com.mysql.jdbc.Driver"/> <entry key="db.jdbcurl" value="jdbc:mysql://localhost/world"/> <entry key="db.username" value="myuser"/> <entry key="db.password" value="mypass"/> </util:map>
In the above example we are assigning values to properties that will be used in the configuration. For the datasource configuration:
<bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource"> <property name="driverClassName" value="${db.driver}"/> <property name="url" value="${db.jdbcurl}"/> <property name="username" value="${db.username}"/> <property name="password" value="${db.password}"/> </bean>
The placeholders are used to provide values for properties of this bean. This means that you can specify all the properties of the configuration in one place instead of entering the values for each property on each bean. We do, however, need one more bean to pull this all together. The last bean is responsible for actually replacing the placeholders with the property values.
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"> <property name="properties" ref="dbProps"/> </bean>
Now that we have our MariaDB data source configured and ready to go, we write some Java code to access it. The example below will retrieve three random cities and their corresponding country using the data source we configured with Spring.
// Create a new application context. this processes the Spring config ApplicationContext ctx = new ClassPathXmlApplicationContext('ex1appContext.xml'); // Retrieve the data source from the application context DataSource ds = (DataSource) ctx.getBean('dataSource'); // Open a database connection using Spring's DataSourceUtils Connection c = DataSourceUtils.getConnection(ds); try { // retrieve a list of three random cities PreparedStatement ps = c.prepareStatement( 'select City.Name as 'City', Country.Name as 'Country' ' + 'from City inner join Country on City.CountryCode = Country.Code ' + 'order by rand() limit 3'); ResultSet rs = ps.executeQuery(); while(rs.next()) { String city = rs.getString('City'); String country = rs.getString('Country'); System.out.printf('The city %s is in %s%n', city, country); } } catch (SQLException ex) { // something has failed and we print a stack trace to analyse the error ex.printStackTrace(); // ignore failure closing connection try { c.close(); } catch (SQLException e) { } } finally { // properly release our connection DataSourceUtils.releaseConnection(c, ds); }
This is very similar to normal JDBC access to MariaDB with the main difference being that we are using DataSourceUtils instead of the DriverManager to create the connection.
While it may seem like a small difference, the implications are somewhat far reaching. Spring manages this resource in a way similar to a container managed data source in a J2EE application server. When a connection is opened, it can be subsequently accessed in other parts of the code if it is synchronized with a transaction. This makes it possible to treat different parts of your application as transactional instead of passing around a database connection.
Using JdbcTemplate
Spring makes extensive use of the Template method design pattern (see Template Method Pattern). Our immediate focus will be on the JdbcTemplate
and related classes, specifically NamedParameterJdbcTemplate
. The template classes handle obtaining and releasing a connection for data access when one is needed.
The next example shows how to use NamedParameterJdbcTemplate
inside of a DAO (Data Access Object) class to retrieve a random city given a country code.
public class Ex2JdbcDao { /** * Data source reference which will be provided by Spring. */ private DataSource dataSource; /** * Our query to find a random city given a country code. Notice * the ':country' parameter toward the end. This is called a * named parameter. */ private String queryString = 'select Name from City ' + 'where CountryCode = :country order by rand() limit 1'; /** * Retrieve a random city using Spring JDBC access classes. */ public String getRandomCityByCountryCode(String cntryCode) { // A template that permits using queries with named parameters NamedParameterJdbcTemplate template = new NamedParameterJdbcTemplate(dataSource); // A java.util.Map is used to provide values for the parameters Map params = new HashMap(); params.put('country', cntryCode); // We query for an Object and specify what class we are expecting return (String)template.queryForObject(queryString, params, String.class); } /** * A JavaBean setter-style method to allow Spring to inject the data source. * @param dataSource */ public void setDataSource(DataSource dataSource) { this.dataSource = dataSource; } }
The focus in the above code is on the getRandomCityByCountryCode()
method. We pass a country code and use the NamedParameterJdbcTemplate
to query for a city. The country code is placed in a Map with the key 'country', which is the parameter is named in the SQL query.
To access this code, you need to configure it with Spring by providing a reference to the data source.
<bean id="dao" class="code.Ex2JdbcDao"> <property name="dataSource" ref="dataSource"/> </bean>
At this point, we can just grab a reference to the DAO from Spring and call getRandomCityByCountryCode()
.
// Create the application context ApplicationContext ctx = new ClassPathXmlApplicationContext('ex2appContext.xml'); // Obtain a reference to our DAO Ex2JdbcDao dao = (Ex2JdbcDao) ctx.getBean('dao'); String countryCode = 'USA'; // Find a few random cities in the US for(int i = 0; i < 4; ++i) System.out.printf('A random city in %s is %s%n', countryCode, dao.getRandomCityByCountryCode(countryCode));
This example shows how to use Spring's JDBC classes to completely abstract away the use of traditional JDBC classes including Connection
and PreparedStatement
.
Transactional JDBC Access
You might be wondering how we can add transactions into our code if we do not deal directly with the JDBC classes. Spring provides a transaction management package that not only replaces JDBC transaction management, but also enables declarative transaction management (configuration instead of code).
To use transactional database access, we will need to change the storage engine of the tables in the world database. The downloaded script explicitly creates MyISAM tables which do not support transactional semantics. The InnoDB storage engine does support transactions and this is what we will be using. We can change the storage engine with the following statements.
ALTER TABLE City ENGINE=InnoDB; ALTER TABLE Country ENGINE=InnoDB; ALTER TABLE CountryLanguage ENGINE=InnoDB;
A good programming practice emphasized by Spring is separating interfaces and implementations. What this means is that we can create a Java interface and only use the operations on this interface without any internal knowledge of what the actual implementation is. We will let Spring manage the implementation and with this it will manage the transactions for our implementation.
First you create a simple interface:
public interface Ex3Dao { Integer createCity(String name, String countryCode, String district, Integer population); }
This interface contains one method that will create a new city record in the database and return the id of the new record. Next you need to create an implementation of this interface.
public class Ex3DaoImpl implements Ex3Dao { protected DataSource dataSource; protected SqlUpdate updateQuery; protected SqlFunction idQuery; public Integer createCity(String name, String countryCode, String district, Integer population) { updateQuery.update(new Object[] { name, countryCode, district, population }); return getLastId(); } protected Integer getLastId() { return idQuery.run(); } }
You can see that we only operate on abstract query objects here and do not deal directly with the JDBC API. Also, this is the complete implementation. All of our transaction management will be dealt with in the configuration. To get the configuration started, we need to create the DAO.
<bean id="dao" class="code.Ex3DaoImpl"> <property name="dataSource" ref="dataSource"/> <property name="updateQuery">...</property> <property name="idQuery">...</property> </bean>
Now you need to set up the transaction configuration. The first thing you must do is create transaction manager to manage the data source and a specification of what transaction properties are required for the dao
methods.
<bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager"> <property name="dataSource" ref="dataSource"/> </bean> <tx:advice id="txAdvice" transaction-manager='transactionManager'> <tx:attributes> <tx:method name="*"/> </tx:attributes> </tx:advice>
The preceding code creates a transaction manager that handles transactions for the data source provided to it. The txAdvice
uses this transaction manager and the attributes specify to create a transaction for all methods. Finally you need to apply this advice with an AOP pointcut.
<aop:config> <aop:pointcut id="daoMethods" expression="execution(* code.Ex3Dao.*(..))"/> <aop:advisor advice-ref='txAdvice' pointcut-ref='daoMethods'/> </aop:config>
This basically says that all methods called on the Ex3Dao
interface will be wrapped in a transaction. To make use of this, you only have to retrieve the dao
from the application context and call a method on the dao
instance.
Ex3Dao dao = (Ex3Dao) ctx.getBean('dao'); Integer id = dao.createCity(name, countryCode, district, pop);
We can verify from this that there is no transaction management happening in our Java code and it is all configured with Spring. This is a very powerful notion and regarded as one of the most beneficial features of Spring.
Connection Pooling with Spring
In many situations, such as web applications, there will be a large number of small database transactions. When this is the case, it usually makes sense to create a pool of database connections available for web requests as needed. Although MariaDB does not spawn an extra process when a connection is made, there is still a small amount of overhead to create and set up the connection. Pooling of connections also alleviates problems such as collecting large amounts of sockets in the TIME_WAIT
state.
Setting up pooling of MariaDB connections with Spring is as simple as changing the data source configuration in the application context. There are a number of configurations that we can use. The first example is based on the Jakarta Commons DBCP library. The example below replaces the source configuration that was based on DriverManagerDataSource
with DBCP's BasicDataSource.
<bean id="dataSource" destroy-method='close' class="org.apache.commons.dbcp.BasicDataSource"> <property name="driverClassName" value="${db.driver}"/> <property name="url" value="${db.jdbcurl}"/> <property name="username" value="${db.username}"/> <property name="password" value="${db.password}"/> <property name="initialSize" value="3"/> </bean>
The configuration of the two solutions is very similar. The difference is that DBCP will pool connections to the database instead of creating a new connection every time one is requested. We have also set a parameter here called initialSize
. This tells DBCP that we want three connections in the pool when it is created.
Another way to configure connection pooling is to configure a data source in our J2EE application server. Using JBoss as an example, you can set up the MariaDB connection pool by creating a file called mysql-local-ds.xml
and placing it in the server/default/deploy directory in JBoss. Once we have this setup, we can use JNDI to look it up. With Spring, this lookup is very simple. The data source configuration looks like this.
<jee:jndi-lookup id="dataSource" jndi-name='java:MySQL_DS'/>
Using Connector/J with GlassFish
- A Simple JSP Application with Glassfish, Connector/J and MySQL
- A Simple Servlet with Glassfish, Connector/J and MySQL
This section explains how to use MariaDB Connector/J with Glassfish Server Open Source Edition 3.0.1. Glassfish can be downloaded from the Glassfish website.
Once Glassfish is installed you will need to make sure it can access MariaDB Connector/J. To do this copy the MariaDB Connector/J JAR file to the directory
. For example, copy GLASSFISH_INSTALL
/glassfish/libmysql-connector-java-5.1.12-bin.jar
to C:\glassfishv3\glassfish\lib
. Restart the Glassfish Application Server.
You are now ready to create JDBC Connection Pools and JDBC Resources.
Creating a Connection Pool
- In the Glassfish Administration Console, using the navigation tree navigate to Resources, JDBC, Connection Pools.
- In the JDBC Connection Pools frame click New. You will enter a two step wizard.
- In the Name field under General Settings enter the name for the connection pool, for example enter
MySQLConnPool
. - In the Resource Type field, select
javax.sql.DataSource
from the drop-down listbox. - In the Database Vendor field, select
MariaDB
from the drop-down listbox. Click Next to go to the next page of the wizard. - You can accept the default settings for General Settings, Pool Settings and Transactions for this example. Scroll down to Additional Properties.
- In Additional Properties you will need to ensure the following properties are set:
- ServerName - The server to connect to. For local testing this will be
localhost
. - User - The user name with which to connect to MariaDB.
- Password - The corresponding password for the user.
- DatabaseName - The database to connect to, for example the sample MariaDB database
World
.
- ServerName - The server to connect to. For local testing this will be
- Click Finish to exit the wizard. You will be taken to the JDBC Connection Pools page where all current connection pools, including the one you just created, will be displayed.
- In the JDBC Connection Pools frame click on the connection pool you just created. Here you can review and edit information about the connection pool.
- To test your connection pool click the Ping button at the top of the frame. A message will be displayed confirming correct operation or otherwise. If an error message is received recheck the previous steps, and ensure that MariaDB Connector/J has been correctly copied into the previously specified location.
Now that you have created a connection pool you will also need to create a JDBC Resource (data source) for use by your application.
Creating a JDBC Resource
Your Java application will usually reference a data source object to establish a connection with the database. This needs to be created first using the following procedure.
- Using the navigation tree in the Glassfish Administration Console, navigate to Resources, JDBC, JDBC Resources. A list of resources will be displayed in the JDBC Resources frame.
- Click New. The New JDBC Resource frame will be displayed.
- In the JNDI Name field, enter the JNDI name that will be used to access this resource, for example enter
jdbc/MySQLDataSource
. - In the Pool Name field, select a connection pool you want this resource to use from the drop-down listbox.
- Optionally, you can enter a description into the Description field.
- Additional properties can be added if required.
- Click OK to create the new JDBC resource. The JDBC Resources frame will list all available JDBC Resources.
A Simple JSP Application with Glassfish, Connector/J and MariaDB
This section shows how to deploy a simple JSP application on Glassfish, that connects to a MariaDB database.
This example assumes you have already set up a suitable Connection Pool and JDBC Resource, as explained in the preceding sections. It is also assumed you have a sample database installed, such as world
.
The main application code, index.jsp
is presented here:
<%@ page import="java.sql.*, javax.sql.*, java.io.*, javax.naming.*" %> <html> <head><title>Hello world from JSP</title></head> <body> <% InitialContext ctx; DataSource ds; Connection conn; Statement stmt; ResultSet rs; try { ctx = new InitialContext(); ds = (DataSource) ctx.lookup('java:comp/env/jdbc/MySQLDataSource'); //ds = (DataSource) ctx.lookup('jdbc/MySQLDataSource'); conn = ds.getConnection(); stmt = conn.createStatement(); rs = stmt.executeQuery('SELECT * FROM Country'); while(rs.next()) { %> <h3>Name: <%= rs.getString('Name') %></h3> <h3>Population: <%= rs.getString('Population') %></h3> <% } } catch (SQLException se) { %> <%= se.getMessage() %> <% } catch (NamingException ne) { %> <%= ne.getMessage() %> <% } %> </body> </html>
In addition two XML files are required: web.xml
, and sun-web.xml
. There may be other files present, such as classes and images. These files are organized into the directory structure as follows:
index.jsp WEB-INF | - web.xml - sun-web.xml
The code for web.xml
is:
<?xml version="1.0" encoding="UTF-8"?> <web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd'> <display-name>HelloWebApp</display-name> <distributable/> <resource-ref> <res-ref-name>jdbc/MySQLDataSource</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope> </resource-ref> </web-app>
The code for sun-web.xml
is:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE sun-web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Application Server 8.1 Servlet 2.4//EN' 'http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd'> <sun-web-app> <context-root>HelloWebApp</context-root> <resource-ref> <res-ref-name>jdbc/MySQLDataSource</res-ref-name> <jndi-name>jdbc/MySQLDataSource</jndi-name> </resource-ref> </sun-web-app>
These XML files illustrate a very important aspect of running JDBC applications on Glassfish. On Glassfish it is important to map the string specified for a JDBC resource to its JNDI name, as set up in the Glassfish administration console. In this example, the JNDI name for the JDBC resource, as specified in the Glassfish Administration console when creating the JDBC Resource, was jdbc/MySQLDataSource
. This must be mapped to the name given in the application. In this example the name specified in the application, jdbc/MySQLDataSource
, and the JNDI name, happen to be the same, but this does not necessarily have to be the case. Note that the XML element <res-ref-name> is used to specify the name as used in the application source code, and this is mapped to the JNDI name specified using the <jndi-name> element, in the file sun-web.xml
. The resource also has to be created in the web.xml
file, although the mapping of the resource to a JNDI name takes place in the sun-web.xml
file.
If you do not have this mapping set up correctly in the XML files you will not be able to lookup the data source using a JNDI lookup string such as:
ds = (DataSource) ctx.lookup('java:comp/env/jdbc/MySQLDataSource');
You will still be able to access the data source directly using:
ds = (DataSource) ctx.lookup('jdbc/MySQLDataSource');
With the source files in place, in the correct directory structure, you are ready to deploy the application:
- In the navigation tree, navigate to Applications - the Applications frame will be displayed. Click Deploy.
- You can now deploy an application packaged into a single WAR file from a remote client, or you can choose a packaged file or directory that is locally accessible to the server. If you are simply testing an application locally you can simply point Glassfish at the directory that contains your application, without needing to package the application into a WAR file.
- Now select the application type from the Type drop-down listbox, which in this example is
Web application
. - Click OK.
Now, when you navigate to the Applications frame, you will have the option to Launch, Redeploy, or Restart your application. You can test your application by clicking Launch. The application will connection to the MariaDB database and display the Name and Population of countries in the Country
table.
A Simple Servlet with Glassfish, Connector/J and MariaDB
This section describes a simple servlet that can be used in the Glassfish environment to access a MariaDB database. As with the previous section, this example assumes the sample database world
is installed.
The project is set up with the following directory structure:
index.html WEB-INF | - web.xml - sun-web.xml - classes | - HelloWebServlet.java - HelloWebServlet.class
The code for the servlet, located in HelloWebServlet.java
, is as follows:
import javax.servlet.http.*; import javax.servlet.*; import java.io.*; import java.sql.*; import javax.sql.*; import javax.naming.*; public class HelloWebServlet extends HttpServlet { InitialContext ctx = null; DataSource ds = null; Connection conn = null; PreparedStatement ps = null; ResultSet rs = null; String sql = 'SELECT Name, Population FROM Country WHERE Name=?'; public void init () throws ServletException { try { ctx = new InitialContext(); ds = (DataSource) ctx.lookup('java:comp/env/jdbc/MySQLDataSource'); conn = ds.getConnection(); ps = conn.prepareStatement(sql); } catch (SQLException se) { System.out.println('SQLException: '+se.getMessage()); } catch (NamingException ne) { System.out.println('NamingException: '+ne.getMessage()); } } public void destroy () { try { if (rs != null) rs.close(); if (ps != null) ps.close(); if (conn != null) conn.close(); if (ctx != null) ctx.close(); } catch (SQLException se) { System.out.println('SQLException: '+se.getMessage()); } catch (NamingException ne) { System.out.println('NamingException: '+ne.getMessage()); } } public void doPost(HttpServletRequest req, HttpServletResponse resp){ try { String country_name = req.getParameter('country_name'); resp.setContentType('text/html'); PrintWriter writer = resp.getWriter(); writer.println('<html><body>'); writer.println('<p>Country: '+country_name+'</p>'); ps.setString(1, country_name); rs = ps.executeQuery(); if (!rs.next()){ writer.println('<p>Country does not exist!</p>'); } else { rs.beforeFirst(); while(rs.next()) { writer.println('<p>Name: '+rs.getString('Name')+'</p>'); writer.println('<p>Population: '+rs.getString('Population')+'</p>'); } } writer.println('</body></html>'); writer.close(); } catch (Exception e) { e.printStackTrace(); } } public void doGet(HttpServletRequest req, HttpServletResponse resp){ try { resp.setContentType('text/html'); PrintWriter writer = resp.getWriter(); writer.println('<html><body>'); writer.println('<p>Hello from servlet doGet()</p>'); writer.println('</body></html>'); writer.close(); } catch (Exception e) { e.printStackTrace(); } } }
In the preceding code a basic doGet()
method is implemented, but is not used in the example. The code to establish the connection with the database is as shown in the previous example, , "A Simple JSP Application with Glassfish, Connector/J and MySQL", and is most conveniently located in the servlet init()
method. The corresponding freeing of resources is located in the destroy method. The main functionality of the servlet is located in the doPost()
method. If the user enters nto the input form a country name that can be located in the database, the population of the country is returned. The code is invoked using a POST action associated with the input form. The form is defined in the file index.html
:
<html> <head><title>HelloWebServlet</title></head> <body> <h1>HelloWebServlet</h1> <p>Please enter country name:</p> <form action="HelloWebServlet" method="POST"> <input type="text" name="country_name" length="50" /> <input type="submit" value="Submit" /> </form> </body> </html>
The XML files web.xml
and sun-web.xml
are as for the example in the preceding section, , "A Simple JSP Application with Glassfish, Connector/J and MySQL", no additional changes are required.
Whe compiling the Java source code, you will need to specify the path to the file javaee.jar
. On Windows, this can be done as follows:
shell> javac -classpath c:\glassfishv3\glassfish\lib\javaee.jar HelloWebServlet.java
Once the code is correctly located within its directory structure, and compiled, the application can be deployed in Glassfish. This is done in exactly the same way as described in the preceding section, , "A Simple JSP Application with Glassfish, Connector/J and MySQL".
Once deployed the application can be launched from within the Glassfish Administration Console. Enter a country name such as "England", and the application will return "Country does not exist!". Enter "France", and the application will return a population of 59225700.
Troubleshooting Connector/J
There are a few issues that seem to be commonly encountered often by users of MariaDB Connector/J. This section deals with their symptoms, and their resolutions.
Questions
- : When I try to connect to the database with MariaDB Connector/J, I get the following exception:
SQLException: Server configuration denies access to data source SQLState: 08001 VendorError: 0
What is going on? I can connect just fine with the MariaDB command-line client.
- : My application throws an SQLException 'No Suitable Driver'. Why is this happening?
- : I'm trying to use MariaDB Connector/J in an applet or application and I get an exception similar to:
SQLException: Cannot connect to MariaDB server on host:3306. Is there a MariaDB server running on the machine/port you are trying to connect to? (java.security.AccessControlException) SQLState: 08S01 VendorError: 0
- : I have a servlet/application that works fine for a day, and then stops working overnight
- : I'm trying to use JDBC-2.0 updatable result sets, and I get an exception saying my result set is not updatable.
- : I cannot connect to the MariaDB server using Connector/J, and I'm sure the connection parameters are correct.
- : I am trying to connect to my MariaDB server within my application, but I get the following error and stack trace:
java.net.SocketException MESSAGE: Software caused connection abort: recv failed STACKTRACE: java.net.SocketException: Software caused connection abort: recv failed at java.net.SocketInputStream.socketRead0(Native Method) at java.net.SocketInputStream.read(Unknown Source) at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1392) at com.mysql.jdbc.MysqlIO.readPacket(MysqlIO.java:1414) at com.mysql.jdbc.MysqlIO.doHandshake(MysqlIO.java:625) at com.mysql.jdbc.Connection.createNewIO(Connection.java:1926) at com.mysql.jdbc.Connection.<init>(Connection.java:452) at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:411)
- : My application is deployed through JBoss and I am using transactions to handle the statements on the MariaDB database. Under heavy loads I am getting a error and stack trace, but these only occur after a fixed period of heavy activity.
- : When using gcj an
java.io.CharConversionException
is raised when working with certain character sequences. - : Updating a table that contains a primary key that is either
FLOAT
or compound primary key that usesFLOAT
fails to update the table and raises an exception. - : You get an
ER_NET_PACKET_TOO_LARGE
exception, even though the binary blob size you want to insert using JDBC is safely below themax_allowed_packet
size. - : What should you do if you receive error messages similar to the following: "Communications link failure - Last packet sent to the server was X ms ago"?
- : Why does Connector/J not reconnect to MariaDB and re-issue the statement after a communication failure, instead of throwing an Exception, even though I use the
autoReconnect
connection string option? - : How can I use 3-byte UTF8 with Connector/J?
- : How can I use 4-byte UTF8,
utf8mb4
with Connector/J? - : Using
useServerPrepStmts=false
and certain character encodings can lead to corruption when inserting BLOBs. How can this be avoided?
Questions and Answers
21.3.12.1: When I try to connect to the database with MariaDB Connector/J, I get the following exception:
SQLException: Server configuration denies access to data source SQLState: 08001 VendorError: 0
What is going on? I can connect just fine with the MariaDB command-line client.
MySQL Connector/J must use TCP/IP sockets to connect to MySQL, as Java does not support Unix Domain Sockets. Therefore, when MariaDB Connector/J connects to MySQL, the security manager in MariaDB server will use its grant tables to determine whether the connection is permitted.
You must add the necessary security credentials to the MariaDB server for this to happen, using the GRANT
statement to your MariaDB Server. See , "GRANT
Syntax", for more information.Note
Testing your connectivity with the mysql command-line client will not work unless you add the --host
flag, and use something other than localhost
for the host. The mysql command-line client will use Unix domain sockets if you use the special host name localhost
. If you are testing connectivity to localhost
, use 127.0.0.1
as the host name instead.Warning
Changing privileges and permissions improperly in MariaDB can potentially cause your server installation to not have optimal security properties.
21.3.12.2: My application throws an SQLException 'No Suitable Driver'. Why is this happening?
There are three possible causes for this error:
- The Connector/J driver is not in your
CLASSPATH
, see , "Connector/J Installation". - The format of your connection URL is incorrect, or you are referencing the wrong JDBC driver.
- When using DriverManager, the
jdbc.drivers
system property has not been populated with the location of the Connector/J driver.
21.3.12.3: I'm trying to use MariaDB Connector/J in an applet or application and I get an exception similar to:
SQLException: Cannot connect to MariaDB server on host:3306. Is there a MariaDB server running on the machine/port you are trying to connect to? (java.security.AccessControlException) SQLState: 08S01 VendorError: 0
Either you're running an Applet, your MariaDB server has been installed with the '--skip-networking' option set, or your MariaDB server has a firewall sitting in front of it.
Applets can only make network connections back to the machine that runs the web server that served the .class files for the applet. This means that MariaDB must run on the same machine (or you must have some sort of port re-direction) for this to work. This also means that you will not be able to test applets from your local file system, you must always deploy them to a web server.
MySQL Connector/J can only communicate with MariaDB using TCP/IP, as Java does not support Unix domain sockets. TCP/IP communication with MariaDB might be affected if MariaDB was started with the '--skip-networking' flag, or if it is firewalled.
If MariaDB has been started with the '--skip-networking' option set (the Debian Linux package of MariaDB server does this for example), you need to comment it out in the file /etc/mysql/my.cnf or /etc/my.cnf. Of course your my.cnf file might also exist in the data
directory of your MariaDB server, or anywhere else (depending on how MariaDB was compiled for your system). Binaries created by us always look in /etc/my.cnf and [datadir]/my.cnf. If your MariaDB server has been firewalled, you will need to have the firewall configured to allow TCP/IP connections from the host where your Java code is running to the MariaDB server on the port that MariaDB is listening to (by default, 3306).
21.3.12.4: I have a servlet/application that works fine for a day, and then stops working overnight
MySQL closes connections after 8 hours of inactivity. You either need to use a connection pool that handles stale connections or use the 'autoReconnect' parameter (see , "Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J").
Also, catch SQLExceptions in your application and deal with them, rather than propagating them all the way until your application exits. This is just good programming practice. MariaDB Connector/J will set the SQLState (see java.sql.SQLException.getSQLState()
in your API docs) to '08S01' when it encounters network-connectivity issues during the processing of a query. Attempt to reconnect to MariaDB at this point.
The following (simplistic) example shows what code that can handle these exceptions might look like:
Example 20.12. Connector/J: Example of transaction with retry logic
public void doBusinessOp() throws SQLException { Connection conn = null; Statement stmt = null; ResultSet rs = null; // // How many times do you want to retry the transaction // (or at least _getting_ a connection)? // int retryCount = 5; boolean transactionCompleted = false; do { try { conn = getConnection(); // assume getting this from a // javax.sql.DataSource, or the // java.sql.DriverManager conn.setAutoCommit(false); // // Okay, at this point, the 'retry-ability' of the // transaction really depends on your application logic, // whether or not you're using autocommit (in this case // not), and whether you're using transactional storage // engines // // For this example, we'll assume that it's _not_ safe // to retry the entire transaction, so we set retry // count to 0 at this point // // If you were using exclusively transaction-safe tables, // or your application could recover from a connection going // bad in the middle of an operation, then you would not // touch 'retryCount' here, and just let the loop repeat // until retryCount == 0. // retryCount = 0; stmt = conn.createStatement(); String query = 'SELECT foo FROM bar ORDER BY baz'; rs = stmt.executeQuery(query); while (rs.next()) { } rs.close(); rs = null; stmt.close(); stmt = null; conn.commit(); conn.close(); conn = null; transactionCompleted = true; } catch (SQLException sqlEx) { // // The two SQL states that are 'retry-able' are 08S01 // for a communications error, and 40001 for deadlock. // // Only retry if the error was due to a stale connection, // communications problem or deadlock // String sqlState = sqlEx.getSQLState(); if ('08S01'.equals(sqlState) || '40001'.equals(sqlState)) { retryCount--; } else { retryCount = 0; } } finally { if (rs != null) { try { rs.close(); } catch (SQLException sqlEx) { // You'd probably want to log this . . . } } if (stmt != null) { try { stmt.close(); } catch (SQLException sqlEx) { // You'd probably want to log this as well . . . } } if (conn != null) { try { // // If we got here, and conn is not null, the // transaction should be rolled back, as not // all work has been done try { conn.rollback(); } finally { conn.close(); } } catch (SQLException sqlEx) { // // If we got an exception here, something // pretty serious is going on, so we better // pass it up the stack, rather than just // logging it. . . throw sqlEx; } } } } while (!transactionCompleted && (retryCount > 0)); }Note
Use of the autoReconnect
option is not recommended because there is no safe method of reconnecting to the MariaDB server without risking some corruption of the connection state or database state information. Instead, use a connection pool, which will enable your application to connect to the MariaDB server using an available connection from the pool. The autoReconnect
facility is deprecated, and may be removed in a future release.
21.3.12.5: I'm trying to use JDBC-2.0 updatable result sets, and I get an exception saying my result set is not updatable.
Because MariaDB does not have row identifiers, MariaDB Connector/J can only update result sets that have come from queries on tables that have at least one primary key, the query must select every primary key and the query can only span one table (that is, no joins). This is outlined in the JDBC specification.
Note that this issue only occurs when using updatable result sets, and is caused because Connector/J is unable to guarantee that it can identify the correct rows within the result set to be updated without having a unique reference to each row. There is no requirement to have a unique field on a table if you are using UPDATE
or DELETE
statements on a table where you can individually specify the criteria to be matched using a WHERE
clause.
21.3.12.6: I cannot connect to the MariaDB server using Connector/J, and I'm sure the connection parameters are correct.
Make sure that the skip-networking
option has not been enabled on your server. Connector/J must be able to communicate with your server over TCP/IP, named sockets are not supported. Also ensure that you are not filtering connections through a Firewall or other network security system. For more information, see "Can't connect to [local] MariaDB server
".
21.3.12.7: I am trying to connect to my MariaDB server within my application, but I get the following error and stack trace:
java.net.SocketException MESSAGE: Software caused connection abort: recv failed STACKTRACE: java.net.SocketException: Software caused connection abort: recv failed at java.net.SocketInputStream.socketRead0(Native Method) at java.net.SocketInputStream.read(Unknown Source) at com.mysql.jdbc.MysqlIO.readFully(MysqlIO.java:1392) at com.mysql.jdbc.MysqlIO.readPacket(MysqlIO.java:1414) at com.mysql.jdbc.MysqlIO.doHandshake(MysqlIO.java:625) at com.mysql.jdbc.Connection.createNewIO(Connection.java:1926) at com.mysql.jdbc.Connection.<init>(Connection.java:452) at com.mysql.jdbc.NonRegisteringDriver.connect(NonRegisteringDriver.java:411)
The error probably indicates that you are using a older version of the Connector/J JDBC driver (2.0.14 or 3.0.x) and you are trying to connect to a MariaDB server with version 4.1x or newer. The older drivers are not compatible with 4.1 or newer of MariaDB as they do not support the newer authentication mechanisms.
It is likely that the older version of the Connector/J driver exists within your application directory or your CLASSPATH
includes the older Connector/J package.
21.3.12.8: My application is deployed through JBoss and I am using transactions to handle the statements on the MariaDB database. Under heavy loads I am getting a error and stack trace, but these only occur after a fixed period of heavy activity.
This is a JBoss, not Connector/J, issue and is connected to the use of transactions. Under heavy loads the time taken for transactions to complete can increase, and the error is caused because you have exceeded the predefined timeout.
You can increase the timeout value by setting the TransactionTimeout
attribute to the TransactionManagerService
within the /conf/jboss-service.xml
file (pre-4.0.3) or /deploy/jta-service.xml
for JBoss 4.0.3 or later. See TransactionTimeoute within the JBoss wiki for more information.
21.3.12.9: When using gcj an java.io.CharConversionException
is raised when working with certain character sequences.
This is a known issue with gcj which raises an exception when it reaches an unknown character or one it cannot convert. Add useJvmCharsetConverters=true
to your connection string to force character conversion outside of the gcj libraries, or try a different JDK.
21.3.12.10: Updating a table that contains a primary key that is either FLOAT
or compound primary key that uses FLOAT
fails to update the table and raises an exception.
Connector/J adds conditions to the WHERE
clause during an UPDATE
to check the old values of the primary key. If there is no match then Connector/J considers this a failure condition and raises an exception.
The problem is that rounding differences between supplied values and the values stored in the database may mean that the values never match, and hence the update fails. The issue will affect all queries, not just those from Connector/J.
To prevent this issue, use a primary key that does not use FLOAT
. If you have to use a floating point column in your primary key use DOUBLE
or DECIMAL
types in place of FLOAT
.
21.3.12.11: You get an ER_NET_PACKET_TOO_LARGE
exception, even though the binary blob size you want to insert using JDBC is safely below the max_allowed_packet
size.
This is because the hexEscapeBlock()
method in com.mysql.jdbc.PreparedStatement.streamToBytes()
may almost double the size of your data.
21.3.12.12: What should you do if you receive error messages similar to the following: "Communications link failure - Last packet sent to the server was X ms ago"?
Generally speaking, this error suggests that the network connection has been closed. There can be several root causes:
- Firewalls or routers may clamp down on idle connections (the MariaDB client/server protocol does not ping).
- The MariaDB Server may be closing idle connections which exceed the
wait_timeout
orinteractive_timeout
threshold.
To help troubleshoot these issues, the following tips can be used. If a recent (5.1.13+) version of Connector/J is used, you will see an improved level of information compared to earlier versions. Older versions simply display the last time a packet was sent to the server, which is frequently 0 ms ago. This is of limited use, as it may be that a packet was just sent, while a packet from the server has not been received for several hours. Knowing the period of time since Connector/J last received a packet from the server is useful information, so if this is not displayed in your exception message, it is recommended that you update Connector/J.
Further, if the time a packet was last sent/received exceeds the wait_timeout
or interactive_timeout
threshold, this is noted in the exception message.
Although network connections can be volatile, the following can be helpful in avoiding problems:
- Ensure connections are valid when used from the connection pool. Use a query that starts with
/* ping */
to execute a lightweight ping instead of full query. Note, the syntax of the ping needs to be exactly as specified here. - Minimize the duration a connection object is left idle while other application logic is executed.
- Explicitly validate the connection before using it if the connection has been left idle for an extended period of time.
- Ensure that
wait_timeout
andinteractive_timeout
are set sufficiently high. - Ensure that
tcpKeepalive
is enabled. - Ensure that any configurable firewall or router timeout settings allow for the maximum expected connection idle time.
Do not expect to be able to reuse a connection without problems, if it has being lying idle for a period. If a connection is to be reused after being idle for any length of time, ensure that you explicitly test it before reusing it.
21.3.12.13: Why does Connector/J not reconnect to MariaDB and re-issue the statement after a communication failure, instead of throwing an Exception, even though I use the autoReconnect
connection string option?
There are several reasons for this. The first is transactional integrity. The MariaDB Reference Manual states that "there is no safe method of reconnecting to the MariaDB server without risking some corruption of the connection state or database state information". Consider the following series of statements for example:
conn.createStatement().execute( 'UPDATE checking_account SET balance = balance - 1000.00 WHERE customer="Smith"'); conn.createStatement().execute( 'UPDATE savings_account SET balance = balance + 1000.00 WHERE customer="Smith"'); conn.commit();
Consider the case where the connection to the server fails after the UPDATE
to checking_account
. If no exception is thrown, and the application never learns about the problem, it will continue executing. However, the server did not commit the first transaction in this case, so that will get rolled back. But execution continues with the next transaction, and increases the savings_account
balance by 1000. The application did not receive an exception, so it continued regardless, eventually committing the second transaction, as the commit only applies to the changes made in the new connection. Rather than a transfer taking place, a deposit was made in this example.
Note that running with auto-commit
enabled does not solve this problem. When Connector/J encounters a communication problem, there is no means to determine whether the server processed the currently executing statement or not. The following theoretical states are equally possible:
- The server never received the statement, and therefore no related processing occurred on the server.
- The server received the statement, executed it in full, but the response was not received by the client.
If you are running with auto-commit
enabled, it is not possible to guarantee the state of data on the server when a communication exception is encountered. The statement may have reached the server, or it may not. All you know is that communication failed at some point, before the client received confirmation (or data) from the server. This does not only affect auto-commit
statements though. If the communication problem occurred during Connection.commit()
, the question arises of whether the transaction was committed on the server before the communication failed, or whether the server received the commit request at all.
The second reason for the generation of exceptions is that transaction-scoped contextual data may be vulnerable, for example:
- Temporary tables.
- User-defined variables.
- Server-side prepared statements.
These items are lost when a connection fails, and if the connection silently reconnects without generating an exception, this could be detrimental to the correct execution of your application.
In summary, communication errors generate conditions that may well be unsafe for Connector/J to simply ignore by silently reconnecting. It is necessary for the application to be notified. It is then for the application developer to decide how to proceed in the event of connection errors and failures.
21.3.12.14: How can I use 3-byte UTF8 with Connector/J?
To use 3-byte UTF8 with Connector/J set characterEncoding=utf8
and set useUnicode=true
in the connection string.
21.3.12.15: How can I use 4-byte UTF8, utf8mb4
with Connector/J?
To use 4-byte UTF8 with Connector/J configure the MariaDB server with character_set_server=utf8mb4
. Connector/J will then use that setting as long as characterEncoding
has not been set in the connection string. This is equivalent to autodetection of the character set.
21.3.12.16: Using useServerPrepStmts=false
and certain character encodings can lead to corruption when inserting BLOBs. How can this be avoided?
When using certain character encodings, such as SJIS, CP932, and BIG5, it is possible that BLOB data contains characters that can be interpreted as control characters, for example, backslash, '\'. This can lead to corrupted data when inserting BLOBs into the database. There are two things that need to be done to avoid this:
- Set the connection string option
useServerPrepStmts
totrue
. - Set
SQL_MODE
toNO_BACKSLASH_ESCAPES
.
Connector/J Support
Connector/J Community Support
Oracle provides assistance to the user community by means of its mailing lists. For Connector/J related issues, you can get help from experienced users by using the MariaDB and Java mailing list. Archives and subscription information is available online at http://lists.mysql.com/java.
For information about subscribing to MariaDB mailing lists or to browse list archives, visit http://lists.mysql.com/. See , "MySQL Mailing Lists".
Community support from experienced users is also available through the JDBC Forum. You may also find help from other users in the other MariaDB Forums, located at http://forums.mysql.com. See , "MySQL Community Support at the MariaDB Forums".
How to Report Connector/J Bugs or Problems
The normal place to report bugs is https://jira.mariadb.org/, which is the address for our bugs database. This database is public, and can be browsed and searched by anyone. If you log in to the system, you will also be able to enter new reports.
If you have found a sensitive security bug in MySQL, you can send email to <security@mysql.com>
.
Writing a good bug report takes patience, but doing it right the first time saves time both for us and for yourself. A good bug report, containing a full test case for the bug, makes it very likely that we will fix the bug in the next release.
This section will help you write your report correctly so that you do not waste your time doing things that may not help us much or at all.
If you have a repeatable bug report, please report it to the bugs database at https://jira.mariadb.org/. Any bug that we are able to repeat has a high chance of being fixed in the next MariaDB release.
To report other problems, you can use one of the MariaDB mailing lists.
Remember that it is possible for us to respond to a message containing too much information, but not to one containing too little. People often omit facts because they think they know the cause of a problem and assume that some details do not matter.
A good principle is this: If you are in doubt about stating something, state it. It is faster and less troublesome to write a couple more lines in your report than to wait longer for the answer if we must ask you to provide information that was missing from the initial report.
The most common errors made in bug reports are (a) not including the version number of Connector/J or MariaDB used, and (b) not fully describing the platform on which Connector/J is installed (including the JVM version, and the platform type and version number that MariaDB itself is installed on).
This is highly relevant information, and in 99 cases out of 100, the bug report is useless without it. Very often we get questions like, "Why doesn't this work for me?" Then we find that the feature requested wasn't implemented in that MariaDB version, or that a bug described in a report has already been fixed in newer MariaDB versions.
Sometimes the error is platform-dependent; in such cases, it is next to impossible for us to fix anything without knowing the operating system and the version number of the platform.
If at all possible, create a repeatable, standalone testcase that doesn't involve any third-party classes.
To streamline this process, we ship a base class for testcases with Connector/J, named 'com.mysql.jdbc.util.BaseBugReport
'. To create a testcase for Connector/J using this class, create your own class that inherits from com.mysql.jdbc.util.BaseBugReport
and override the methods setUp()
, tearDown()
and runTest()
.
In the setUp()
method, create code that creates your tables, and populates them with any data needed to demonstrate the bug.
In the runTest()
method, create code that demonstrates the bug using the tables and data you created in the setUp
method.
In the tearDown()
method, drop any tables you created in the setUp()
method.
In any of the above three methods, use one of the variants of the getConnection()
method to create a JDBC connection to MySQL:
getConnection()
- Provides a connection to the JDBC URL specified ingetUrl()
. If a connection already exists, that connection is returned, otherwise a new connection is created.getNewConnection()
- Use this if you need to get a new connection for your bug report (that is, there is more than one connection involved).getConnection(String url)
- Returns a connection using the given URL.getConnection(String url, Properties props)
- Returns a connection using the given URL and properties.
If you need to use a JDBC URL that is different from 'jdbc:mysql:///test', override the method getUrl()
as well.
Use the assertTrue(boolean expression)
and assertTrue(String failureMessage, boolean expression)
methods to create conditions that must be met in your testcase demonstrating the behavior you are expecting (vs. the behavior you are observing, which is why you are most likely filing a bug report).
Finally, create a main()
method that creates a new instance of your testcase, and calls the run
method:
public static void main(String[] args) throws Exception { new MyBugReport().run(); }
Once you have finished your testcase, and have verified that it demonstrates the bug you are reporting, upload it with your bug report to https://jira.mariadb.org/.
Connector/J Change History
The Connector/J Change History (Changelog) is located with the main Changelog for MySQL. See "MySQL Connector/J Change History".
MySQL Connector/MXJ
- Overview of Connector/MXJ
- Connector/MXJ Versions
- Connector/MXJ Installation
- Connector/MXJ Configuration
- Connector/MXJ Reference
- Connector/MXJ Notes and Tips
- Connector/MXJ Samples
- Connector/MXJ Support
- Connector/MXJ Versions
MySQL Connector/MXJ is a Java Utility package for deploying and managing a MariaDB database. Deploying and using MariaDB can be as easy as adding another parameter to the JDBC connection URL, which will result in the database being started when the first connection is made. This makes it easy for Java developers to deploy applications which require a database by reducing installation barriers for their end-users.
MySQL Connector/MXJ makes the MariaDB database appear to be a Java-based component. It does this by determining what platform the system is running on, selecting the appropriate binary, and launching the executable. It will also optionally deploy an initial database, with any specified parameters.
Included are instructions for use with a JDBC driver and deploying as a JMX MBean to JBoss.
You can download sources and binaries from: http://dev.mysql.com/downloads/connector/mxj/
This a beta release and feedback is welcome and encouraged.
Please send questions or comments to the MySQL and Java mailing list.
Overview of Connector/MXJ
Connector/MXJ consists of a Java class, a copy of the mysqld
binary for a specific list of platforms, and associated files and support utilities. The Java class controls the initialization of an instance of the embedded mysqld
binary, and the ongoing management of the mysqld
process. The entire sequence and management can be controlled entirely from within Java using the Connector/MXJ Java classes. You can see an overview of the contents of the Connector/MXJ package in the figure below.
It is important to note that Connector/MXJ is not an embedded version of MySQL, or a version of MariaDB written as part of a Java class. Connector/MXJ works through the use of an embedded, compiled binary of mysqld
as would normally be used when deploying a standard MariaDB installation.
It is the Connector/MXJ wrapper, support classes and tools, that enable Connector/MXJ to appear as a MariaDB instance.
When Connector/MXJ is initialized, the corresponding mysqld
binary for the current platform is extracted, along with a pre-configured data directed. Both are contained within the Connector/MXJ JAR file. The mysqld
instance is then started, with any additional options as specified during the initialization, and the MariaDB database becomes accessible.
Because Connector/MXJ works in combination with Connector/J, you can access and integrate with the MariaDB instance through a JDBC connection. When you have finished with the server, the instance is terminated, and, by default, any data created during the session is retained within the temporary directory created when the instance was started.
Connector/MXJ and the embedded mysqld
instance can be deployed in a number of environments where relying on an existing database, or installing a MariaDB instance would be impossible, including CD-ROM embedded database applications and temporary database requirements within a Java-based application environment.
Connector/MXJ Versions
Connector/MXJ 5.x, currently in beta status, includes mysqld
version 5.x and includes binaries for Linux x86, Mac OS X PPC, Windows XP/NT/2000 x86 and Solaris SPARC. Connector/MXJ 5.x requires the Connector/J 5.x package.
A summary of the different MariaDB versions supplied with each Connector/MXJ release are shown in the table.
Connector/MXJ Version | MySQL Version(s) |
---|---|
5.0.11 | 5.1.40 |
5.0.9 | 5.0.51a (CS), 5.0.54 (ES) |
5.0.8 | (CS), 5.0.46 (ES) |
5.0.7 | (CS), 5.0.42 (ES) |
5.0.6 | (CS), 5.0.40 (ES) |
5.0.5 | (CS), 5.0.36 (ES) |
5.0.4 | (CS), 5.0.32 (ES) |
5.0.3 | 5.0.22 |
5.0.2 | 5.0.19 |
This guide provides information on the Connector/MXJ 5.x release. For information on using the older releases, please see the documentation included with the appropriate distribution.
Connector/MXJ Installation
- Supported Platforms
- Connector/MXJ Base Installation
- Connector/MXJ Quick Start Guide
- Deploying Connector/MXJ using Driver Launch
- Deploying Connector/MXJ within JBoss
- Verifying Installation using JUnit
- Connector/MXJ Base Installation
Connector/MXJ does not have a installation application or process, but there are some steps you can follow to make the installation and deployment of Connector/MXJ easier.
Before you start, there are some baseline requirements for
- Java Runtime Environment (v1.4.0 or newer) if you are only going to deploy the package.
- Java Development Kit (v1.4.0 or newer) if you intend to build Connector/MXJ from source.
- Connector/J 5.0 or newer.
Depending on your target installation/deployment environment you may also require:
- JBoss - 4.0rc1 or newer
- Apache Tomcat - 5.0 or newer
- Sun's JMX reference implementation version 1.2.1 (from http://java.sun.com/products/JavaManagement/)
Supported Platforms
Connector/MXJ is compatible with any platform supporting Java and MySQL. By default, Connector/MXJ incorporates the mysqld
binary for a select number of platforms which differs by version. The following platforms have been tested and working as deployment platforms. Support for all the platforms listed below is not included by default.
- Linux (i386)
- FreeBSD (i386)
- Windows NT (x86), Windows 2000 (x86), Windows XP (x86), Windows Vista (x86)
- Solaris 8, SPARC 32-bit (compatible with Solaris 8, Solaris 9 and Solaris 10 on SPARC 32-bit and 64-bit platforms)
- Mac OS X (PowerPC and Intel)
The Connector/MXJ 5.0.8 release includes mysqld binaries for the following platforms:
- Linux (i386)
- Windows (x86), compatible with Windows NT, Windows 2000, Windows XP , Windows Vista
- Solaris 8, SPARC 32-bit (compatible with Solaris 8, Solaris 9 and Solaris 10 on SPARC 32-bit and 64-bit platforms)
- Mac OS X (PowerPC and Intel)
For more information on packaging your own Connector/MXJ with the platforms you require, see , "Creating your own Connector/MXJ Package"
Connector/MXJ Base Installation
Because there is no formal installation process, the method, installation directory, and access methods you use for Connector/MXJ are entirely up to your individual requirements.
To perform a basic installation, choose a target directory for the files included in the Connector/MXJ package. On Unix/Linux systems, you might use a directory such as /usr/local/connector-mxj
. On Windows, you might install the files in the base directory, C:\Connector-MXJ
, or within the Program Files
directory.
To install the files, for a Connector/MXJ 5.0.4 installation:
- Download the Connector/MXJ package, either in Tar/Gzip format (ideal for Unix/Linux systems) or Zip format (Windows).
- Extract the files from the package. This will create a directory
mysql-connector-mxj-gpl-[ver]
. Copy and optionally rename this directory to your desired location. - For best results, update your global
CLASSPATH
variable with the location of the requiredjar
files.Within Unix/Linux you can do this globally by editing the global shell profile, or on a user by user basis by editing their individual shell profile.
On Windows 2000, Windows NT and Windows XP, you can edit the global
CLASSPATH
by editing theEnvironment Variables
configured through theSystem
control panel.
For Connector/MXJ 5.0.6 and later you need the following JAR files in your CLASSPATH
:
mysql-connector-mxj-gpl-[ver].jar
: contains the main Connector/MXJ classes.mysql-connector-mxj-gpl-[ver]-db-files.jar
: contains the embeddedmysqld
and database files.aspectjrt.jar
: the AspectJ runtime library, located inlib/aspectjrt.jar
in the Connector/MXJ package.mysql-connector-java-[ver]-bin.jar
: Connector/J, see , "MySQL Connector/J".
For Connector/MXJ 5.0.4 and later you need the following JAR files in your CLASSPATH
:
connector-mxj.jar
: contains the main Connector/MXJ classes.connector-mxj-db-files.jar
: contains the embeddedmysqld
and database files.aspectjrt.jar
: the AspectJ runtime library, located inlib/aspectjrt.jar
in the Connector/MXJ package.mysql-connector-mxj-gpl-[ver].jar
: Connector/J, see , "MySQL Connector/J".
For Connector/MXJ 5.0.3 and earlier, you need the following JAR files:
connector-mxj.jar
aspectjrt.jar
: the AspectJ runtime library, located inlib/aspectjrt.jar
in the Connector/MXJ package.mysql-connector-mxj-gpl-[ver].jar
: Connector/J, see , "MySQL Connector/J".
Connector/MXJ Quick Start Guide
Once you have extracted the Connector/MXJ and Connector/J components you can run one of the sample applications that initiates a MariaDB instance. You can test the installation by running the ConnectorMXJUrlTestExample
:
shell> java ConnectorMXJUrlTestExample jdbc:mysql:mxj://localhost:3336/our_test_app?server.basedir» =/var/tmp/test-mxj&createDatabaseIfNotExist=true&server.initialize-user=true [/var/tmp/test-mxj/bin/mysqld][--no-defaults][--port=3336][--socket=mysql.sock]» [--basedir=/var/tmp/test-mxj][--datadir=/var/tmp/test-mxj/data]» [--pid-file=/var/tmp/test-mxj/data/MysqldResource.pid] [MysqldResource] launching mysqld (driver_launched_mysqld_1) InnoDB: The first specified data file ./ibdata1 did not exist: InnoDB: a new database to be created! 080220 9:40:20 InnoDB: Setting file ./ibdata1 size to 10 MB InnoDB: Database physically writes the file full: wait... 080220 9:40:20 InnoDB: Log file ./ib_logfile0 did not exist: new to be created InnoDB: Setting log file ./ib_logfile0 size to 5 MB InnoDB: Database physically writes the file full: wait... 080220 9:40:20 InnoDB: Log file ./ib_logfile1 did not exist: new to be created InnoDB: Setting log file ./ib_logfile1 size to 5 MB InnoDB: Database physically writes the file full: wait... InnoDB: Doublewrite buffer not found: creating new InnoDB: Doublewrite buffer created InnoDB: Creating foreign key constraint system tables InnoDB: Foreign key constraint system tables created 080220 9:40:21 InnoDB: Started; log sequence number 0 0 080220 9:40:21 [Note] /var/tmp/test-mxj/bin/mysqld: ready for connections. Version: '5.0.51a' socket: 'mysql.sock' port: 3336 MariaDB Community Server (GPL) [MysqldResource] mysqld running as process: 2238 ------------------------ SELECT VERSION() ------------------------ 5.0.51a ------------------------ [MysqldResource] stopping mysqld (process: 2238) 080220 9:40:27 [Note] /var/tmp/test-mxj/bin/mysqld: Normal shutdown 080220 9:40:27 InnoDB: Starting shutdown... 080220 9:40:29 InnoDB: Shutdown completed; log sequence number 0 43655 080220 9:40:29 [Note] /var/tmp/test-mxj/bin/mysqld: Shutdown complete [MysqldResource] shutdown complete
The above output shows an instance of MariaDB starting, the necessary files being created (log files, InnoDB data files) and the MariaDB database entering the running state. The instance is then shutdown by Connector/MXJ before the example terminates.Warning
Avoid running your Connector/MXJ application as the root
user, because this will cause the mysqld to also be executed with root privileges. For more information, see , "How to Run MariaDB as a Normal User".
Deploying Connector/MXJ using Driver Launch
Connector/MXJ and Connector/J work together to enable you to launch an instance of the mysqld
server through the use of a keyword in the JDBC connection string. Deploying Connector/MXJ within a Java application can be automated through this method, making the deployment of Connector/MXJ a simple process:
- Download and unzip Connector/MXJ. Add
mysql-connector-mxj-gpl-[ver].jar
to theCLASSPATH
.
If you are using Connector/MXJ v5.0.4 or later, also add the
mysql-connector-mxj-gpl-[ver]-db-files.jar
file to yourCLASSPATH
. - To the JDBC connection string, embed the
mxj
keyword, for example:jdbc:mysql:mxj://localhost:
.PORT
/DBNAME
For more details, see , "Connector/MXJ Configuration".
Deploying Connector/MXJ within JBoss
For deployment of Connector/MXJ within a JBoss environment, you must configure the JBoss environment to use the Connector/MXJ component within the JDBC parameters:
- Download Connector/MXJ and copy the
mysql-connector-mxj-gpl-[ver].jar
file to the$JBOSS_HOME/server/default/lib
directory.
If you are using Connector/MXJ v5.0.4 or later, also copy the
mysql-connector-mxj-gpl-[ver]-db-files.jar
file to$JBOSS_HOME/server/default/lib
. - Download Connector/J and copy the
mysql-connector-java-
file to the5.1.5
-bin.jar$JBOSS_HOME/server/default/lib
directory. - Create an MBean service xml file in the
$JBOSS_HOME/server/default/deploy
directory with any attributes set, for instance thedatadir
andautostart
. - Set the JDBC parameters of your web application to use:
String driver = 'com.mysql.jdbc.Driver'; String url = 'jdbc:mysql:///test?propertiesTransform='+ 'com.mysql.management.jmx.ConnectorMXJPropertiesTransform'; String user = 'root'; String password = ''; Class.forName(driver); Connection conn = DriverManager.getConnection(url, user, password);
You might create a separate users and database table spaces for each application, rather than using 'root and test'.
We highly suggest having a routine backup procedure for backing up the database files in the datadir
.
Verifying Installation using JUnit
The best way to ensure that your platform is supported is to run the JUnit tests. These will test the Connector/MXJ classes and the associated components.
JUnit Test Requirements
The first thing to do is make sure that the components will work on the platform. The MysqldResource
class is really a wrapper for a native version of MySQL, so not all platforms are supported. At the time of this writing, Linux on the i386 architecture has been tested and seems to work quite well, as does OS X v10.3. There has been limited testing on Windows and Solaris.
Requirements:
- JDK-1.4 or newer (or the JRE if you aren't going to be compiling the source or JSPs).
- MySQL Connector/J version 5.0 or newer (from http://dev.mysql.com/downloads/connector/j/) installed and available using your CLASSPATH.
- The
javax.management
classes for JMX version 1.2.1, these are present in the following application servers:- JBoss - 4.0rc1 or newer.
- Apache Tomcat - 5.0 or newer.
- Sun's JMX reference implementation version 1.2.1 (from http://java.sun.com/products/JavaManagement/).
- JUnit 3.8.1 (from http://www.junit.org/).
If building from source, All of the requirements from above, plus:
- Ant version 1.5 or newer (download from http://ant.apache.org/).
Running the JUnit Tests
- The tests attempt to launch MariaDB on the port 3336. That MariaDB instance is unlikely to conflict with another MariaDB server on the same machine, because the default port for MariaDB is 3306. If you do encounter a port conflict, either set the
c-mxj_test_port
Java property to a port of your choosing, or shut down any instances of MariaDB you have running on the target machine.
The tests suppress output to the console by default. For verbose output, you may set the
c-mxj_test_silent
Java property tofalse
. - To run the JUnit test suite, the
$CLASSPATH
must include the following:- JUnit
- JMX
- Connector/J
- MySQL Connector/MXJ
- If
connector-mxj.jar
is not present in your download, unzip MariaDB Connector/MXJ source archive.cd mysqldjmx ant dist
Then add
$TEMP/cmxj/stage/connector-mxj/connector-mxj.jar
to theCLASSPATH
. - If you have
junit
, execute the unit tests. From the command line, type:java com.mysql.management.AllTestsSuite
The output should look something like this:
......................................... ......................................... .......... Time: 259.438 OK (101 tests)
Note that the tests are a bit slow near the end, so please be patient.
Connector/MXJ Configuration
Running as part of the JDBC Driver
A feature of the MariaDB Connector/J JDBC driver is the ability to specify a connection to an embedded Connector/MXJ instance through the use of the mxj keyword in the JDBC connection string.
In the following example, we have a program which creates a connection, executes a query, and prints the result to the System.out. The MariaDB database will be deployed and started as part of the connection process, and shutdown as part of the finally block.
You can find this file in the Connector/MXJ package as src/ConnectorMXJUrlTestExample.java
.
import java.io.File; import java.sql.Connection; import java.sql.DriverManager; import com.mysql.management.driverlaunched.ServerLauncherSocketFactory; import com.mysql.management.util.QueryUtil; public class ConnectorMXJUrlTestExample { public static String DRIVER = 'com.mysql.jdbc.Driver'; public static String JAVA_IO_TMPDIR = 'java.io.tmpdir'; public static void main(String[] args) throws Exception { File ourAppDir = new File(System.getProperty(JAVA_IO_TMPDIR)); File databaseDir = new File(ourAppDir, 'test-mxj'); int port = Integer.parseInt(System.getProperty('c-mxj_test_port', '3336')); String dbName = 'our_test_app'; String url = 'jdbc:mysql:mxj://localhost:' + port + '/' + dbName // + '?' + 'server.basedir=' + databaseDir // + '&' + 'createDatabaseIfNotExist=true'// + '&' + 'server.initialize-user=true' // ; System.out.println(url); String userName = 'alice'; String password = 'q93uti0opwhkd'; Class.forName(DRIVER); Connection conn = null; try { conn = DriverManager.getConnection(url, userName, password); String sql = 'SELECT VERSION()'; String queryForString = new QueryUtil(conn).queryForString(sql); System.out.println('------------------------'); System.out.println(sql); System.out.println('------------------------'); System.out.println(queryForString); System.out.println('------------------------'); System.out.flush(); Thread.sleep(100); // wait for System.out to finish flush } finally { try { if (conn != null) conn.close(); } catch (Exception e) { e.printStackTrace(); } ServerLauncherSocketFactory.shutdown(databaseDir, null); } } }
To run the above program, be sure to have connector-mxj.jar
and Connector/J in the CLASSPATH. Then type:
java ConnectorMXJUrlTestExample
Running within a Java Object
To "embed" a MariaDB database within a Java application, use the com.mysql.management.MysqldResource
class directly. This class may be instantiated with the default (no argument) constructor, or by passing in a java.io.File
object representing the directory into which to unzip the server. It may also be instantiated with printstreams for stdout
and stderr
for logging.
Once instantiated, a java.util.Map
, the object will be able to provide a java.util.Map
of server options appropriate for the platform and version of MariaDB which you will be using.
The MysqldResource
enables you to 'start' MariaDB with a java.util.Map
of server options which you provide, as well as 'shutdown' the database. The following example shows a simplistic way to embed MariaDB in an application using plain java objects.
You can find this file in the Connector/MXJ package as src/ConnectorMXJObjectTestExample.java
.
import java.io.File; import java.sql.Connection; import java.sql.DriverManager; import java.util.HashMap; import java.util.Map; import com.mysql.management.MysqldResource; import com.mysql.management.MysqldResourceI; import com.mysql.management.util.QueryUtil; public class ConnectorMXJObjectTestExample { public static final String DRIVER = 'com.mysql.jdbc.Driver'; public static final String JAVA_IO_TMPDIR = 'java.io.tmpdir'; public static void main(String[] args) throws Exception { File ourAppDir = new File(System.getProperty(JAVA_IO_TMPDIR)); File databaseDir = new File(ourAppDir, 'mysql-mxj'); int port = Integer.parseInt(System.getProperty('c-mxj_test_port', '3336')); String userName = 'alice'; String password = 'q93uti0opwhkd'; MysqldResource mysqldResource = startDatabase(databaseDir, port, userName, password); Class.forName(DRIVER); Connection conn = null; try { String dbName = 'our_test_app'; String url = 'jdbc:mysql://localhost:' + port + '/' + dbName // + '?' + 'createDatabaseIfNotExist=true'// ; conn = DriverManager.getConnection(url, userName, password); String sql = 'SELECT VERSION()'; String queryForString = new QueryUtil(conn).queryForString(sql); System.out.println('------------------------'); System.out.println(sql); System.out.println('------------------------'); System.out.println(queryForString); System.out.println('------------------------'); System.out.flush(); Thread.sleep(100); // wait for System.out to finish flush } finally { try { if (conn != null) { conn.close(); } } catch (Exception e) { e.printStackTrace(); } try { mysqldResource.shutdown(); } catch (Exception e) { e.printStackTrace(); } } } public static MysqldResource startDatabase(File databaseDir, int port, String userName, String password) { MysqldResource mysqldResource = new MysqldResource(databaseDir); Map database_options = new HashMap(); database_options.put(MysqldResourceI.PORT, Integer.toString(port)); database_options.put(MysqldResourceI.INITIALIZE_USER, 'true'); database_options.put(MysqldResourceI.INITIALIZE_USER_NAME, userName); database_options.put(MysqldResourceI.INITIALIZE_PASSWORD, password); mysqldResource.start('test-mysqld-thread', database_options); if (!mysqldResource.isRunning()) { throw new RuntimeException('MySQL did not start.'); } System.out.println('MySQL is running.'); return mysqldResource; } }
Setting server options
There are many options you might set for a MariaDB database. These options may be specified as part of the JDBC connection string simply by prefixing each server option with server.
. The following example sets two driver parameters and two server parameters:
String url = 'jdbc:mysql://' + hostColonPort + '/' + '?' + 'cacheServerConfiguration=true' + '&' + 'useLocalSessionState=true' + '&' + 'server.basedir=/opt/myapp/db' + '&' + 'server.datadir=/mnt/bigdisk/myapp/data';
Starting with Connector/MXJ 5.0.6, you can use the initialize-user
property to a connection string. If set to true, the default anonymous and root users will be removed and the user/password combination from the connection URL will be used to create a new user. For example:
String url = 'jdbc:mysql:mxj://localhost:' + port + '/alice_db' + '?server.datadir=' + dataDir.getPath() + '&server.initialize-user=true' + '&createDatabaseIfNotExist=true' ;
Connector/MXJ Reference
The following sections include detailed information on the different API interfaces to Connector/MXJ.
MysqldResource Constructors
The MysqldResource
class supports three different constructor forms:
public MysqldResource(File baseDir, File dataDir, String mysqlVersionString, PrintStream out, PrintStream err)
Enables you to set the base directory, data directory, select a server by its version string, standard out and standard error.
public MysqldResource(File baseDir, File dataDir, String mysqlVersionString)
Enables you to set the base directory, data directory and select a server by its version string. Output for standard out and standard err are directed to System.out and System.err.
public MysqldResource(File baseDir, File dataDir)
Enables you to set the base directory and data directory. The default MariaDB version is selected, and output for standard out and standard err are directed to System.out and System.err.
public MysqldResource(File baseDir);
Enables the setting of the 'basedir' to deploy the MariaDB files to. Output for standard out and standard err are directed to System.out and System.err.
public MysqldResource();
The basedir is defaulted to a subdirectory of the java.io.tempdir. Output for standard out and standard err are directed to System.out and System.err;
MysqldResource Methods
MysqldResource API includes the following methods:
void start(String threadName, Map mysqldArgs);
Deploys and starts MySQL. The 'threadName' string is used to name the thread which actually performs the execution of the MariaDB command line. The map is the set of arguments and their values to be passed to the command line.
void shutdown();
Shuts down the MariaDB instance managed by the MysqldResource object.
Map getServerOptions();
Returns a map of all the options and their current (or default, if not running) options available for the MariaDB database.
boolean isRunning();
Returns true if the MariaDB database is running.
boolean isReadyForConnections();
Returns true once the database reports that is ready for connections.
void setKillDelay(int millis);
The default "Kill Delay" is 30 seconds. This represents the amount of time to wait between the initial request to shutdown and issuing a "force kill" if the database has not shutdown by itself.
void addCompletionListenser(Runnable listener);
Enables applications to be notified when the server process completes. Each "listener" will be fired off in its own thread.
String getVersion();
Returns the version of MySQL.
void setVersion(int MajorVersion, int minorVersion, int patchLevel);
The standard distribution comes with only one version of MariaDB packaged. However, it is possible to package multiple versions, and specify which version to use.
Connector/MXJ Notes and Tips
- Creating your own Connector/MXJ Package
- Deploying Connector/MXJ with a pre-configured database
- Running within a JMX Agent (custom)
- Deployment in a standard JMX Agent environment (JBoss)
- Deploying Connector/MXJ with a pre-configured database
This section contains notes and tips on using the Connector/MXJ component within your applications.
Creating your own Connector/MXJ Package
To create a custom Connector/MXJ package that includes a specific mysqld
version or platform, extract and rebuild the mysql-connector-mxj.jar
(Connector/MXJ v5.0.3 or earlier) or mysql-connector-mxj-gpl-[ver]-db-files.jar
(Connector/MXJ v5.0.4 or later) file.
First, create a new directory into which you can extract the current connector-mxj.jar
:
shell> mkdir custom-mxj shell> cd custom-mxj shell> jar -xf connector-mxj.jar shell> ls 5-0-22/ ConnectorMXJObjectTestExample.class ConnectorMXJUrlTestExample.class META-INF/ TestDb.class com/ kill.exe
If you are using Connector/MXJ v5.0.4 or later, unpack the connector-mxj-db-files.jar
:
shell> mkdir custom-mxj shell> cd custom-mxj shell> jar -xf connector-mxj-db-files.jar shell> ls 5-0-51a/ META-INF/ connector-mxj.properties
The MariaDB version directory, 5-0-22
or 5-0-51a
in the preceding examples, contains all of the files used to create an instance of MariaDB when Connector/MXJ is executed. All of the files in this directory are required for each version of MariaDB to embed. Note as well the format of the version number, which uses hyphens instead of periods to separate the version number components.
Within the version specific directory are the platform specific directories, and archives of the data
and share
directory required by MariaDB for the various platforms. For example, here is the listing for the default Connector/MXJ package:
shell>> ls Linux-i386/ META-INF/ Mac_OS_X-ppc/ SunOS-sparc/ Win-x86/ com/ data_dir.jar share_dir.jar win_share_dir.jar
Platform specific directories are listed by their OS and platform - for example the mysqld
for Mac OS X PowerPC is located within the Mac_OS_X-ppc
directory. You can delete directories from this location that you do not require, and add new directories for additional platforms that you intend to support.
To add a platform specific mysqld
, create a new directory with the corresponding name for your operating system/platform. For example, you could add a directory for Mac OS X/Intel using the directory Mac_OS_X-i386
.
On Unix systems, you can determine the platform using uname
:
shell> uname -p i386
In Connector/MXJ v5.0.9 and later, an additional platform-map.properties
file is used to associate a specific platform and operating system combination with the directory in which the mysqld
for that combination is located. The determined operating system and platform are on the left, and the directory name where the appropriate mysqld is located is on the right. You can see a sample of the file below:
Linux-i386=Linux-i386 Linux-x86=Linux-i386 Linux-i686=Linux-i386 Linux-x86_64=Linux-i386 Linux-ia64=Linux-i386 #Linux-ppc=Linux-ppc #Linux-ppc64=Linux-ppc Mac_OS_X-i386=Mac_OS_X-i386 Mac_OS_X-ppc=Mac_OS_X-ppc Rhapsody-PowerPC=Mac_OS_X-ppc #Mac_OS-PowerPC= #macos-PowerPC= #MacOS-PowerPC= SunOS-sparc=SunOS-sparc Solaris-sparc=SunOS-sparc SunOS-x86=SunOS-x86 Solaris-x86=SunOS-x86 FreeBSD-x86=FreeBSD-x86 Windows_Vista-x86=Win-x86 Windows_2003-x86=Win-x86 Windows_XP-x86=Win-x86 Windows_2000-x86=Win-x86 Windows_NT-x86=Win-x86 Windows_NT_(unknown)-x86=Win-x86
Now download or compile mysqld
for the MariaDB version and platform you want to include in your custom connector-mxj.jar
package into the new directory.
Create a file called version.txt
in the OS/platform directory you have just created that contains the version string/path of the mysqld binary. For example:
mysql-5.0.22-osx10.3-i386/bin/mysqld
You can now recreate the connector-mxj.jar
file with the added mysqld
:
shell> cd custom-mxj shell> jar -cf ../connector-mxj.jar *
For Connector/MXJ v5.0.4 and later, repackage to the connector-mxj-db-files.jar
:
shell> cd custom-mxj shell> jar -cf ../mysql-connector-mxj-gpl-[ver]-db-files.jar *
Test this package using the steps outlined in , "Connector/MXJ Quick Start Guide".Note
Because the mysql-connector-mxj-gpl-[ver]-db-files.jar
file is separate from the main Connector/MXJ classes you can distribute different mysql-connector-mxj-gpl-[ver]-db-files.jar
files to different hosts or for different projects without having to create a completely new main mysql-connector-mxj-gpl-[ver].jar
file for each one.
Deploying Connector/MXJ with a pre-configured database
To include a pre-configured/populated database within your Connector/MXJ JAR file you must create a custom data_dir.jar
file, as included within the main connector-mxj.jar
(Connector/MXJ 5.0.3 or earlier) or mysql-connector-mxj-gpl-[ver]-db-files.jar
(Connector/MXJ 5.0.4 or later) file:
- First extract the
connector-mxj.jar
ormysql-connector-gpl-[ver]-db-files.jar
file, as outlined in the previous section (see , "Creating your own Connector/MXJ Package"). - First, create your database and populate the database with the information you require in an existing instance of MariaDB - including Connector/MXJ instances. Data file formats are compatible across platforms.
- Shutdown the instance of MySQL.
- Create a JAR file of the data directory and databases that you intend to include your Connector/MXJ package. Include the
MariaDB
database, which includes user authentication information, in addition to the specific databases to include. For example, to create a JAR of theMariaDB
andmxjtest
databases:shell> jar -cf ../data_dir.jar mysql mxjtest
- For Connector/MXJ 5.0.3 or earlier, copy the
data_dir.jar
file into the extractedconnector-mxj.jar
directory, and then create an archive forconnector-mxj.jar
.For Connector/MXJ 5.0.4 or later, copy the
data_dir.jar
file into the extractedmysql-connector-mxj-gpl-[ver]-db-files.jar
directory, and then create an archive formysql-connector-mxj-db-gpl-[ver]--files.jar
.
Note that if you are create databases using the InnoDB engine, you must include the ibdata.*
and ib_logfile*
files within the data_dir.jar
archive.
Running within a JMX Agent (custom)
As a JMX MBean, MariaDB Connector/MXJ requires a JMX v1.2 compliant MBean container, such as JBoss version 4. The MBean will uses the standard JMX management APIs to present (and allow the setting of) parameters which are appropriate for that platform.
If you are not using the SUN Reference implementation of the JMX libraries, skip this section. Or, if you are deploying to JBoss, you can also skip to the next section.
We want to see the MysqldDynamicMBean in action inside of a JMX agent. In the com.mysql.management.jmx.sunri
package is a custom JMX agent with two MBeans:
- The MysqldDynamicMBean, and
- A com.sun.jdmk.comm.HtmlAdaptorServer, which provides a web interface for manipulating the beans inside of a JMX agent.
When this very simple agent is started, it will allow a MariaDB database to be started and stopped with a web browser.
- Complete the testing of the platform as above.
- Current JDK, JUnit, Connector/J, MariaDB Connector/MXJ
- This section requires the SUN reference implementation of JMX
PATH
,JAVA_HOME
,ANT_HOME
,CLASSPATH
- If not building from source, skip to next step
Rebuild with the 'sunri.present'
ant -Dsunri.present=true dist re-run tests: java junit.textui.TestRunner com.mysql.management.AllTestsSuite
- Launch the test agent from the command line:
java com.mysql.management.jmx.sunri.MysqldTestAgentSunHtmlAdaptor &
- From a browser:
http://localhost:9092/
- Under MysqldAgent,
select 'name=mysqld'
- Observe the MBean View
- Scroll to the bottom of the screen press the startMysqld button
- Click
Back to MBean View
- Scroll to the bottom of the screen press stopMysqld button
- Kill the java process running the Test Agent (jmx server)
Deployment in a standard JMX Agent environment (JBoss)
Once there is confidence that the MBean will function on the platform, deploying the MBean inside of a standard JMX Agent is the next step. Included are instructions for deploying to JBoss.
- Ensure a current version of java development kit (v1.4.x), see above.
- Ensure
JAVA_HOME
is set (JBoss requiresJAVA_HOME
) - Ensure
JAVA_HOME/bin
is in thePATH
(You will NOT need to set your CLASSPATH, nor will you need any of the jars used in the previous tests).
- Ensure
- Ensure a current version of JBoss (v4.0RC1 or better)
http://www.jboss.org/index.html select 'Downloads' select 'jboss-4.0.zip' pick a mirror unzip ~/dload/jboss-4.0.zip create a JBOSS_HOME environment variable set to the unzipped directory unix only: cd $JBOSS_HOME/bin chmod +x *.sh
- Deploy (copy) the
connector-mxj.jar
to$JBOSS_HOME/server/default/lib
. - Deploy (copy)
mysql-connector-java-3.1.4-beta-bin.jar
to$JBOSS_HOME/server/default/lib
. - Create a
mxjtest.war
directory in$JBOSS_HOME/server/default/deploy
. - Deploy (copy)
index.jsp
to$JBOSS_HOME/server/default/deploy/mxjtest.war
. - Create a
mysqld-service.xml
file in$JBOSS_HOME/server/default/deploy
.<?xml version="1.0" encoding="UTF-8"?> <server> <mbean code="com.mysql.management.jmx.jboss.JBossMysqldDynamicMBean" name="mysql:type=service,name=mysqld"> <attribute name="datadir">/tmp/xxx_data_xxx</attribute> <attribute name="autostart">true</attribute> </mbean> </server>
- Start jboss:
- On unix: $JBOSS_HOME/bin/run.sh
- On windows: %JBOSS_HOME%\bin\run.bat
Be ready: JBoss sends a lot of output to the screen.
- When JBoss seems to have stopped sending output to the screen, open a web browser to:
http://localhost:8080/jmx-console
- Scroll down to the bottom of the page in the
MariaDB
section, select the bulletedmysqld
link. - Observe the JMX MBean View page. MariaDB should already be running.
- (If 'autostart=true' was set, you may skip this step.) Scroll to the bottom of the screen. You may press the Invoke button to stop (or start) MariaDB observe
Operation completed successfully without a return value.
ClickBack to MBean View
- To confirm MariaDB is running, open a web browser to
http://localhost:8080/mxjtest/
and you should see that the following query:SELECT 1
returned with the following result:
1
- Guided by the
$JBOSS_HOME/server/default/deploy/mxjtest.war/index.jsp
you will be able to use MariaDB in your Web Application. There is atest
database and aroot
user (no password) ready to experiment with. Try creating a table, inserting some rows, and doing some selects. - Shut down MySQL. MariaDB will be stopped automatically when JBoss is stopped, or: from the browser, scroll down to the bottom of the MBean View press the stop service Invoke button to halt the service. Observe
Operation completed successfully without a return value.
Usingps
ortask manager
see that MariaDB is no longer running
As of 1.0.6-beta version is the ability to have the MBean start the MariaDB database upon start up. Also, we've taken advantage of the JBoss life-cycle extension methods so that the database will gracefully shut down when JBoss is shutdown.
Connector/MXJ Samples
This section contains some sample applications using Connector/MXJ.
Using Connector/MXJ with JSP
The following web application was provided by Pavan Venkatesh as an example of a JSP based application using Connector/MXJ to provide contact data. The example consists of two components, insertdata.jsp
and response.jsp
. The insertdata.jsp
provides a form into which you can enter information to be stored within the MariaDB database provided by Connector/MXJ. The response.jsp
file is called when you submit the form and then provides a table of the data.
Because the data is stored through Connector/MXJ the instantiation of the MariaDB database is handled dynamically on the fly, making the script lightweight and self-contained.
Example 20.13. insertdata.jsp
<%@page contentType="text/html" pageEncoding="UTF-8"%> <!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN' 'http://www.w3.org/TR/html4/loose.dtd'> <%@ page import="java.sql.*"%> <%@ page import="java.io.*"%> <%@ page import="java.io.*"%> <%@ page import="java.sql.*"%> <HTML> <HEAD> <TITLE>insert data</TITLE> <script language="Javascript"> function validFields(){ if (document.form2.ID.value == '' || document.form2.ID.value == null){ alert ( 'Please enter ID / Field cannot be left blank' ); return false; } if (document.form2.names.value == '' || document.form2.names.value == null){ alert ( 'Please enter Name / Field cannot be left blank' ); return false; } if (document.form2.place.value == ''|| document.form2.place.value == null){ alert ( 'Please enter Place / Field cannot be left blank' ); return false; } if (document.form2.phone.value == ''|| document.form2.phone.value == null){ alert ( 'Please enter Phone number / Field cannot be left blank' ); return false; } return true; } </script> </HEAD> <BODY > <H1>Welcome to MariaDB world</H1> <H2>MySQL with MXJ Connection</H2> <P>Insert data in existing 'contactdetails2009' table under 'Directory' database</P> <FORM action="response.jsp" method="get" name="form2"> <TABLE > <TR> <TH> <center>ID</center> </TH> <TD><INPUT TYPE="text" NAME="ID"></TD> </TR> <TR> <TH> <center>Name</center> </TH> <TD><INPUT TYPE="text" NAME="names"></TD> </TR> <TR> <TH> <center>City</center> </TH> <TD><INPUT TYPE="text" NAME="place"></TD> </TR> <TR> <TH> <center>Phone</center> </TH> <TD><INPUT TYPE="text" NAME="phone"></TD> </TR> <TR> <TH></TH> <TD><INPUT TYPE="submit" VALUE="Insert" ></TD> </TR> </TABLE> </FORM> </BODY>
Example 20.14. response.jsp
<%@ page import="java.sql.*"%> <%@ page import="java.sql.*"%> <%@ page import="java.io.*"%> <%@ page import="java.io.*"%> <%@ page import="java.sql.*"%> <%@ page import="java.sql.Connection"%> <%@ page import="java.sql.DriverManager"%> <%@ page language="java"%> <%@ page import=" com.mysql.management.util.QueryUtil"%> <%@page contentType="text/html" pageEncoding="UTF-8"%> <!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN' 'http://www.w3.org/TR/html4/loose.dtd'> <HTML> <HEAD> <META http-equiv='Content-Type' content="text/html; charset=UTF-8"> <TITLE>JSP Page</TITLE> </HEAD> <BODY > <P><INPUT type=button value="Back" ></P> <H1>Welcome to Directory Database</H1> <% String ID = request.getParameter('ID'); String name = request.getParameter('names'); String city = request.getParameter('place'); String phone = request.getParameter('phone'); File ourAppDir1 = new File('/tmp/src'); File databaseDir1 = new File(ourAppDir1,'database'); int port = 4336; String dbName = 'Directory'; try { String url = 'jdbc:mysql:mxj://localhost:' + port + '/' + dbName // + '?' + 'server.basedir=' + databaseDir1 // + '&' + 'createDatabaseIfNotExist=true'// + '&' + 'server.initialize-user=true' // ; Connection connection = null; int updateQuery=0; Class.forName('com.mysql.jdbc.Driver').newInstance(); String userName = 'alice'; String password = 'q93uti0opwhkd'; connection = DriverManager.getConnection(url, userName, password); PreparedStatement pstatement = null; String sql = 'SELECT VERSION()'; String queryForString = new QueryUtil(connection).queryForString(sql); String command = 'INSERT INTO contactdetails2009 (ID, name,city,phone) VALUES (?,?,?,?)'; pstatement = connection.prepareStatement(command); pstatement.setString(1, ID); pstatement.setString(2, name); pstatement.setString(3, city); pstatement.setString(4, phone); updateQuery = pstatement.executeUpdate(); ResultSet resultset = pstatement.executeQuery('select * from contactdetails2009'); if (updateQuery != 0) { %> <P>MySQL Version------------> <% out.println(queryForString); %> </P> <TABLE > <TR> <TH >Data successfully inserted into MariaDB database using MXJ connection</TH> </TR> <TR> <th >Storage Engine used is MyISAM</th> </TR> <TR> <TD> <H2>ContactDetails2009 Table</H2> <TABLE > <TR> <TH>ID</TH> <TH>name</TH> <TH>city</TH> <TH>phone</TH> </TR> <% while(resultset.next()){ %> <TR> <TD><%= resultset.getString(1) %></TD> <TD><%= resultset.getString(2) %></TD> <TD><%= resultset.getString(3) %></TD> <TD><%= resultset.getString(4) %></TD> </TR> <% } %> <% resultset.close(); pstatement.close(); connection.close(); } } catch (Exception e) { %> <TR> <TD>ERROR------------> <% out.println('ID or Row already exist'); } %> </TD> </TR> </TABLE> </TD> </TR> </TABLE> </BODY> </HTML>
Connector/MXJ Support
There are a wide variety of options available for obtaining support for using Connector/MXJ. Contact the Connector/MXJ community for help before reporting a potential bug or problem. See , "Connector/MXJ Community Support".
Connector/MXJ Community Support
Oracle provides assistance to the user community by means of a number of mailing lists and web based forums.
You can find help and support through the MySQL and Java mailing list.
For information about subscribing to MariaDB mailing lists or to browse list archives, visit http://lists.mysql.com/. See , "MySQL Mailing Lists".
Community support from experienced users is also available through the JDBC and Java forum. You may also find help from other users in the other MariaDB Forums, located at http://forums.mysql.com. See , "MySQL Community Support at the MariaDB Forums".
How to Report Connector/MXJ Problems
If you encounter difficulties or problems with Connector/MXJ, contact the Connector/MXJ community , "Connector/MXJ Community Support".
If reporting a problem, ideally include the following information with the email:
- Operating system and version
- Connector/MXJ version
- MySQL server version
- Copies of error messages or other unexpected output
- Simple reproducible sample
Remember that the more information you can supply to us, the more likely it is that we can fix the problem.
If you believe the problem to be a bug, then you must report the bug through https://jira.mariadb.org/.
Connector/MXJ Change History
The Connector/MXJ Change History (Changelog) is located with the main Changelog for MySQL. See "MySQL Connector/MXJ Change History".
MySQL Connector/C++
- Installing the MariaDB Connector/C++ Binary
- Installing MariaDB Connector/C++ from Source
- MySQL Connector/C++ Building Windows Applications with Microsoft Visual Studio
- MySQL Connector/C++ Building Linux Applications with NetBeans
- MySQL Connector/C++ Getting Started: Usage Examples
- MySQL Connector/C++ Tutorials
- MySQL Connector/C++ Debug Tracing
- MySQL Connector/C++ Usage Notes
- MySQL Connector/C++ Known Bugs and Issues
- MySQL Connector/C++ Feature requests
- MySQL Connector/C++ Support
- MySQL Connector/C++ FAQ
- Installing MariaDB Connector/C++ from Source
MySQL Connector/C++ is a MariaDB database connector for C++.
The MariaDB Connector/C++ is licensed under the terms of the GPL, like most MariaDB Connectors. There are special exceptions to the terms and conditions of the GPL as it is applied to this software, see FLOSS License Exception. If you need a non-GPL license for commercial distribution please contact us.
The MariaDB Connector/C++ is compatible with the JDBC 4.0 API. However, MariaDB Connector/C++ does not implement all of the JDBC 4.0 API. The MariaDB Connector/C++ current version features the following classes:
Connection
DatabaseMetaData
Driver
PreparedStatement
ResultSet
ResultSetMetaData
Savepoint
Statement
The JDBC 4.0 API defines approximately 450 methods for the above mentioned classes. MariaDB Connector/C++ implements around 80% of these and makes them available in the current release.
The release has been successfully compiled and tested on the following platforms:
AIX
- (PPC32, PPC64)
- (PPC32, PPC64)
FreeBSD
- (x86, x86_64)
HPUX
- (PA-RISC 32bit, PA-RISC 64bit)
Linux
- Debian 3.1 (PPC32, x86)
- FC4 (x86)
- RHEL 3 (ia64, x86, x86_64)
- RHEL 4 (ia64, x86, x86_64)
- RHEL 5 (ia64, x86, x86_64)
- SLES 9 (ia64, x86, x86_64)
- SLES 10 (ia64, x86_64)
- SuSE 10.3, (x86_64)
- Ubuntu 8.04 (x86)
- Ubuntu 8.10 (x86_64)
Mac
- MacOSX 10.3 (PPC32, PPC64)
- MacOSX 10.4 (PPC32, PPC64, x86)
- MacOSX 10.5 (PPC32, PPC64, x86, x86_64)
SunOS
- Solaris 8 (SPARC32, SPARC64, x86)
- Solaris 9 (SPARC32, SPARC64, x86)
- Solaris 10 (SPARC32, SPARC64, x86, x86_64)
Windows
- XP Professional (32bit)
- (64bit)
Future versions will run on all platforms supported by the MariaDB Server.Note
MySQL Connector/C++ supports MariaDB 5.1 and later.Note
MySQL Connector/C++ supports only Microsoft Visual Studio 2003 and above on Windows.
MySQL Connector/C++ Download
You can download the source code for the MariaDB Connector/C++ current release at the MySQL Connector/C++ downloads.
MySQL Connector/C++ Source repository
The latest development version is also available through Launchpad.
Bazaar is used for the MariaDB Connector/C++ code repository. You can check out the latest source code using the bzr command line tool:
shell> bzr branch lp:~mysql/mysql-connector-cpp/trunk .
Binary distributions
Starting with 1.0.4 Beta, binary distributions were made available in addition to source code releases. The releases available are shown below.
Microsoft Windows platform:
- Without installer, a Zip file
- MSI installer package
Other platforms:
- Compressed GNU TAR archive (tar.gz)
Note that source packages are available for all platforms in the Compressed GNU TAR archive (tar.gz) format.
Binary and source packages can be obtained from MySQL Connector/C++ downloads.
MySQL Connector/C++ Advantages
Using MariaDB Connector/C++ instead of the MariaDB C API (MySQL Client Library) offers the following advantages for C++ users:
- Convenience of pure C++, no C function calls required
- Supports an industry standard API, JDBC 4.0
- Supports the object-oriented programming paradigm
- Reduces development time
- MySQL Connector/C++ is licensed under the GPL with the FLOSS License Exception
- MySQL Connector/C++ is available under a commercial license upon request
MySQL Connector/C++ Status
MySQL Connector/C++ is available as a GA version. We kindly ask users and developers to try it out and provide us with feedback.
Note that MariaDB Workbench is successfully using MariaDB Connector/C++.
If you have any queries please contact us.
Installing the MariaDB Connector/C++ Binary
CautionOne problem that can occur is when the tools you use to build your application are not compatible with the tools used to build the binary versions of MariaDB Connector/C++. Ideally, build your application with the same tools that were used to build the MariaDB Connector/C++ binaries. To help with this, the following resources are provided.
All distributions contain a README
file, which contains platform-specific notes. At the end of the README
file contained in the binary distribution you will find the settings used to build the binaries. If you experience build-related issues on a platform, it may help to check the settings used on the platform to build the binary.
Developers using Microsoft Windows must meet the following requirements:
- Use a supported version of Visual Studio, either Visual Studio 2005 or Visual Studio 2008.
- Ensure that your application uses the same run time library as that used to build MariaDB Connector/C++. Visual Studio 2005 builds use Microsoft.VC80.CRT (8.0.50727.762), and Visual Studio 2008 builds use Microsoft.VC90.CRT (9.0.21022.8).
- Your application should use the same linker configuration as MariaDB Connector/C++, for example use one of
/MD
,/MDd
,/MT
, or/MTd
.
To use a variation of the requirements previously listed, such as a different compiler version, release configuration, or run time library, compile MariaDB Connector/C++ from source using your desired settings, and then ensure that your application is built with these same settings. Ensure that the three variables of compiler version, run time library, and run time linker configuration settings are the same for both application and MariaDB Connector/C++ itself, to avoid issues.
For your convenience the same information, but more frequently updated, can be found on the MySQL Forge site.
A better solution is to build your MariaDB Connector/C++ libraries from the source code, using the same tools that you use for building your application. This ensures compatibility.
Downloading MariaDB Connector/C++
Binary and source packages can be obtained from MySQL Connector/C++ downloads.
Archive Package
Unpack the archive into an appropriate directory. If you plan to use a dynamically linked version of MariaDB Connector/C++, make sure that your system can reference the MariaDB Client Library. Consult your operating system documentation on how do modify and expand the search path for libraries. In case you cannot modify the library search path it may help to copy your application, the MariaDB Connector/C++ library and the MariaDB Client Library into the same directory. Most systems search for libraries in the current directory.
Windows MSI Installer
Windows users can choose between two binary packages:
- Without installer (unzip in C:\)
- Windows MSI Installer (x86)
Using the MSI Installer may be the easiest solution. Running the MSI Installer does not require any administrative permissions as it simply copies files.
Figure 20.59. Windows Installer Welcome Screen

Figure 20.60. Windows Installer Overview Screen

The "Typical" installation consists of all required header files and the Release libraries. The only available "Custom" installation option enables you to install additional Debug versions of the connector libraries.
Figure 20.61. Windows Installer Custom Setup Screen

Installing MariaDB Connector/C++ from Source
- Building MariaDB Connector/C++ from Source on Unix, Solaris and Mac OS X
- Building MariaDB Connector/C++ from Source on Windows
- Dynamically Linking MariaDB Connector/C++ against the MariaDB Client Library
- Building MariaDB Connector/C++ from Source on Windows
The MariaDB Connector/C++ is based on the MariaDB Client Library (MySQL C API). MariaDB Connector/C++ is linked against the MariaDB Client Library. You need the MariaDB Client Library installed to compile MariaDB Connector/C++.
You also need the cross-platform build tool CMake 2.4, or newer, and GLib 2.2.3 or newer installed. Check the README
file included with the distribution for platform specific notes on building for Windows and SunOS.
Typically the MariaDB Client Library is installed when the MariaDB Server is installed. However, check your operating system documentation for other installation options.
As of MariaDB Connector/C++ version 1.1.0, it is necessary to have the Boost C++ libraries 1.34.0 or newer installed. Boost is only required to build the connector, it is not required to use the connector. You can obtain Boost and its installation instructions from the official site. Once Boost is installed, tell the make system where the Boost files are, by setting the define -DBOOST_ROOT:STRING=
. This can be done when initially invoking CMake, for example:
shell> CMake . -DBOOST_ROOT:STRING=/usr/local/boost_1_40_0
You might need to change /usr/local/boost_1_40_0/
to match your installation. See the , "Building MariaDB Connector/C++ from Source on Unix, Solaris and Mac OS X" and , "Building MariaDB Connector/C++ from Source on Windows" for further details.
Building MariaDB Connector/C++ from Source on Unix, Solaris and Mac OS X
- Run CMake to build a
Makefile
:
shell> me@host:/path/to/mysql-connector-cpp> cmake . -- Check for working C compiler: /usr/local/bin/gcc -- Check for working C compiler: /usr/local/bin/gcc -- works [...] -- Generating done -- Build files have been written to: /path/to/mysql-connector-cpp/
On non-Windows systems, CMake first checks to see if the CMake variable
MYSQL_CONFIG_EXECUTABLE
is set. If it is not found CMake tries to locatemysql_config
in the default locations.If you have any problems with the configure process please check the troubleshooting instructions below.
- Use make to build the libraries. First make sure you have a clean build:
shell> me@host:/path/to/mysql-connector-cpp> make clean
Then build the connector:
me@host:/path/to/mysql-connector-cpp> make [ 1%] Building CXX object » driver/CMakeFiles/mysqlcppconn.dir/mysql_connection.o [ 3%] Building CXX object » driver/CMakeFiles/mysqlcppconn.dir/mysql_constructed_resultset.o [...] [100%] Building CXX object examples/CMakeFiles/statement.dir/statement.o Linking CXX executable statement
If all goes well, you will find the MariaDB Connector/C++ library in
/path/to/cppconn/libmysqlcppconn.so
. - Finally make sure the header and library files are installed to their correct locations:
make install
Unless you have changed this in the configuration step, the header files are copied to the directory
/usr/local/include
. The header files copied aremysql_connection.h
andmysql_driver.h
.Again, unless you have specified otherwise, the library files are copied to
/usr/local/lib
. The files copied arelibmysqlcppconn.so
, the dynamic library, andlibmysqlcppconn-static.a
, the static library.
If you encounter any errors, please first carry out the checks shown below:
- CMake options: MariaDB installation path, debug version and more
In case of configuration or compilation problems, check the list of CMake options:
shell> me@host:/path/to/mysql-connector-cpp> cmake -L [...] CMAKE_BACKWARDS_COMPATIBILITY:STRING=2.4 CMAKE_BUILD_TYPE:STRING= CMAKE_INSTALL_PREFIX:PATH=/usr/local EXECUTABLE_OUTPUT_PATH:PATH= LIBRARY_OUTPUT_PATH:PATH= MYSQLCPPCONN_GCOV_ENABLE:BOOL=0 MYSQLCPPCONN_TRACE_ENABLE:BOOL=0 MYSQL_CONFIG_EXECUTABLE:FILEPATH=/usr/bin/mysql_config
For example, if your MariaDB Server installation path is not
/usr/local/mysql
and you want to build a debug version of the MariaDB Connector/C++, use:shell> me@host:/path/to/mysql-connector-cpp> cmake » -D CMAKE_BUILD_TYPE:STRING=Debug » -D MYSQL_CONFIG_EXECUTABLE=/path/to/my/mysql/server/bin/mysql_config .
- Verify your settings with cmake
-L
:shell> me@host:/path/to/mysql-connector-cpp> cmake -L [...] CMAKE_BACKWARDS_COMPATIBILITY:STRING=2.4 CMAKE_BUILD_TYPE:STRING= CMAKE_INSTALL_PREFIX:PATH=/usr/local EXECUTABLE_OUTPUT_PATH:PATH= LIBRARY_OUTPUT_PATH:PATH= MYSQLCPPCONN_GCOV_ENABLE:BOOL=0 MYSQLCPPCONN_TRACE_ENABLE:BOOL=0 MYSQL_CONFIG_EXECUTABLE=/path/to/my/mysql/server/bin/mysql_config
Proceed by carrying out a make clean command followed by a make command, as described above.
Once you have installed MariaDB Connector/C++ you can carry out a quick test to check the installation. To do this you can compile and run one of the example programs, such as examples/standalone_example.cpp
. This example is discussed in more detail later, but for now you can use it to test the connector has been correctly installed. This procedure assumes you have a working MariaDB Server that you can connect to.
- First compile the example. To do this change to the
examples
directory and type:
shell> g++ -o test_install -I/usr/local/include -I/usr/local/include/cppconn -Wl,-Bdynamic -lmysqlcppconn standalone_example.cpp
- Make sure the dynamic library which is used in this case can be found at runtime:
shell> export LD_LIBRARY_PATH=/usr/local/lib
- Now run the program to test your installation, substituting the appropriate host, user, password and database names for your system:
./test_install localhost root password database
You will see something similar to the following:
Connector/C++ standalone program example... ... running 'SELECT 'Welcome to Connector/C++' AS _message' ... MariaDB replies: Welcome to Connector/C++ ... say it again, MySQL ....MySQL replies: Welcome to Connector/C++ ... find more at http://www.mysql.com
If you see any errors, take note of them and go through the troubleshooting procedures discussed earlier.
Building MariaDB Connector/C++ from Source on Windows
NotePlease note the only compiler formally supported for Windows is Microsoft Visual Studio 2003 and above.
The basic steps for building the connector on Windows are the same as for Unix. It is important to use CMake 2.6.2 or newer to generate build files for your compiler and to invoke the compiler.Note
On Windows, mysql_config
is not present, so CMake will attempt to retrieve the location of MariaDB from the environment variable $ENV{MYSQL_DIR}
. If MYSQL_DIR
is not set, CMake will then proceed to check for MariaDB in the following locations: $ENV{ProgramFiles}/MySQL/*/include
, and $ENV{SystemDrive}/MySQL/*/include
.
CMake makes it easy for you to try other compilers. However, you may experience compile warnings, compile errors or linking issues not detected by Visual Studio. Patches are gratefully accepted to fix issues with other compilers.
Consult the CMake manual or check cmake --help
to find out which build systems are supported by your CMake version:
C:\>cmake --help cmake version 2.6-patch 2 Usage [...] Generators The following generators are available on this platform: Borland Makefiles = Generates Borland makefiles. MSYS Makefiles = Generates MSYS makefiles. MinGW Makefiles = Generates a make file for use with mingw32-make. NMake Makefiles = Generates NMake makefiles. Unix Makefiles = Generates standard UNIX makefiles. Visual Studio 6 = Generates Visual Studio 6 project files. Visual Studio 7 = Generates Visual Studio .NET 2002 project files. Visual Studio 7 .NET 2003 = Generates Visual Studio .NET 2003 project files. Visual Studio 8 2005 = Generates Visual Studio .NET 2005 project files. Visual Studio 8 2005 Win64 = Generates Visual Studio .NET 2005 Win64 project files. Visual Studio 9 2008 = Generates Visual Studio 9 2008 project fil Visual Studio 9 2008 Win64 = Generates Visual Studio 9 2008 Win64 proje files. [...]
It is likely that your CMake binary will support more compilers, known by CMake as generators, than supported by MariaDB Connector/C++. We have built the connector using the following generators:
- Microsoft Visual Studio 8 (Visual Studio 2005)
- Microsoft Visual Studio 9 (Visual Studio 2008, Visual Studio 2008 Express)
- NMake
Please see the building instructions for Unix, Solaris and Mac OS X for troubleshooting and configuration hints.
The steps to build the connector are given below:
- Run CMake to generate build files for your generator:
Visual Studio
C:\path_to_mysql_cpp>cmake -G 'Visual Studio 9 2008' -- Check for working C compiler: cl -- Check for working C compiler: cl -- works -- Detecting C compiler ABI info -- Detecting C compiler ABI info - done -- Check for working CXX compiler: cl -- Check for working CXX compiler: cl -- works -- Detecting CXX compiler ABI info -- Detecting CXX compiler ABI info - done -- ENV{MYSQL_DIR} = -- MariaDB Include dir: C:/Programme/MySQL/MySQL Server 5.1/include -- MariaDB Library : C:/Progams/MySQL/MySQL Server 5.1/lib/opt/mysqlclient.lib -- MariaDB Library dir: C:/Progams/MySQL/MySQL Server 5.1/lib/opt -- MariaDB CFLAGS: -- MariaDB Link flags: -- MariaDB Include dir: C:/Progams/MySQL/MySQL Server 5.1/include -- MariaDB Library dir: C:/Progams/MySQL/MySQL Server 5.1/lib/opt -- MariaDB CFLAGS: -- MariaDB Link flags: -- Configuring cppconn -- Configuring test cases -- Looking for isinf -- Looking for isinf - not found -- Looking for isinf -- Looking for isinf - not found. -- Looking for finite -- Looking for finite - not found. -- Configuring C/J junit tests port -- Configuring examples -- Configuring done -- Generating done -- Build files have been written to: C:\path_to_mysql_cpp C:\path_to_mysql_cpp>dir *.sln *.vcproj [...] 19.11.2008 12:16 23.332 MYSQLCPPCONN.sln [...] 19.11.2008 12:16 27.564 ALL_BUILD.vcproj 19.11.2008 12:16 27.869 INSTALL.vcproj 19.11.2008 12:16 28.073 PACKAGE.vcproj 19.11.2008 12:16 27.495 ZERO_CHECK.vcproj
NMake
C:\path_to_mysql_cpp>cmake -G 'NMake Makefiles' -- The C compiler identification is MSVC -- The CXX compiler identification is MSVC [...] -- Build files have been written to: C:\path_to_mysql_cpp
- Use your compiler to build MariaDB Connector/C++
Visual Studio - GUI
Open the newly generated project files in the Visual Studio GUI or use a Visual Studio command line to build the driver. The project files contain a variety of different configurations. Among them debug and nondebug versions.
Visual Studio - NMake
C:\path_to_mysql_cpp>nmake Microsoft (R) Program Maintenance Utility Version 9.00.30729.01 Copyright (C) Microsoft Corporation. All rights reserved. Scanning dependencies of target mysqlcppconn [ 2%] Building CXX object driver/CMakeFiles/mysqlcppconn.dir/mysql_connection.obj mysql_connection.cpp [...] Linking CXX executable statement.exe [100%] Built target statement
Dynamically Linking MariaDB Connector/C++ against the MariaDB Client Library
NoteNote this section refers to dynamic linking of the MariaDB Connector/C++ with the client library, not the dynamic linking of the application to MariaDB Connector/C++.
An application that uses MariaDB Connector/C++ can be either statically or dynamically linked to the MariaDB Connector/C++ libraries. MariaDB Connector/C++ is usually statically linked to the underlying MariaDB Client Library (or Connector/C). Note, that unless otherwise stated, reference to the MariaDB Client Library is also taken to include Connector/C, which is a separately packaged, stand alone version of the MariaDB Client Library. From MariaDB Connector/C++ version 1.1.0 it is possible to also dynamically link to the underlying MariaDB Client Library. The ability of MariaDB Connector/C++ to dynamically link to MariaDB Client Library is not enabled by default, and enabling this feature is done through a compile time option, when compiling the MariaDB Connector/C++ source code.
To use the ability to dynamically link the client library to MariaDB Connector/C++, define the MYSQLCLIENT_STATIC_BINDING:BOOL
when building the MariaDB Connector/C++ source code:
rm CMakeCache.txt cmake -DMYSQLCLIENT_STATIC_BINDING:BOOL=1 . make clean make make install
Note that precompiled binaries of MariaDB Connector/C++ use static binding with the client library by default.
Now, in your application, when creating a connection, MariaDB Connector/C++ will select and load a client library at runtime. It will choose the client library by searching defined locations and environment variables depending on the host operating system. It is also possible when creating a connection in an application to define an absolute path to the client library to be loaded at runtime. This can be convenient if you have defined a standard location from which you want the client library to be loaded. This is sometimes done to circumvent possible conflicts with other versions of the client library that may be located on the system.
MySQL Connector/C++ Building Windows Applications with Microsoft Visual Studio
MySQL Connector/C++ is available as a static or dynamic library to use with your application. This section looks at how to link the library to your application.Note
To avoid potential crashes the build configuration of MariaDB Connector/C++ should match the build configuration of the application using it. For example, do not use the release build of MariaDB Connector/C++ with a debug build of the client application.
Static library
The MariaDB Connector/C++ static library file is mysqlcppconn-static.lib
. You link this library statically with your application. Also link against the files libmysql.dll
and libmysql.lib
. Once linking has been successfully completed, the application will require access to libmysql.dll
at run time.
Dynamic library
The MariaDB Connector/C++ dynamic library file is mysqlcppconn.dll
. To build your client application, link it with the file mysqlcppconn.lib
. At run time, the application will require access to the files mysqlcppconn.dll
and libmysql.dll
.
Building a MariaDB Connector/C++ application with Microsoft Visual Studio
Initially, the procedure for building an application to use either the static or dynamic library is the same. You then carry out some additional steps depending on whether you are building your application to use the static or dynamic library.
- Select File, New, Project from the main menu.
Figure 20.62. Creating a New Project
- In the wizard, select Visual C++, Win32. From Visual Studio Installed Templates, select the application type Win32 Console Application. Enter a name for the application, then click OK, to move to the Win32 Application Wizard.
Figure 20.63. The New Project Dialog Box
- In the Win32 Application Wizard, click Application Settings and ensure the defaults are selected. The radio button Console application and the check box Precompiled headers are selected. Click Finish to close the wizard.
Figure 20.64. The Win32 Application Wizard
- From the drop down list box on the toolbar, change from the default Debug build to the Release build.
Figure 20.65. Selecting the Release Build
- From the main menu select Project, Properties. This can also be accessed using the hot key ALT + F7.
Figure 20.66. Selecting Project Properties from the Main Menu
- Under Configuration Properties, open the tree view.
- Select C++, General in the tree view.
Figure 20.67. Setting Properties
- Now ensure that Visual Studio can find the MariaDB include directory. This directory includes header files that can optionally be installed when installing MariaDB Server.
Figure 20.68. MariaDB Include Directory
- In the Additional Include Directories text field, add the MariaDB
include/
directory.Figure 20.69. Select Directory Dialog
- Also set the location of additional libraries that Visual Studio needs to build the application. These are located in the MariaDB
lib/opt
directory, a subdirectory of the MariaDB Server installation directory.Figure 20.70. Typical Contents of MariaDB lib/opt Directory
- In the tree view, open Linker, General, Additional Library Directories.
Figure 20.71. Additional Library Directories
- Add the
lib/opt
directory into the Additional Library Directories text field. This enables the library filelibmysql.lib
to be found.Figure 20.72. Additional Library Directories Dialog
The remaining steps depend on whether you are building an application to use the MariaDB Connector/C++ static or dynamic library. If you are building your application to use the dynamic library go here. If you are building your application to use the static library, carry out the following steps:
- Then open Linker, Input, Additional Dependencies.
Figure 20.73.
- Enter
mysqlcppconn-static.lib
andlibmysql.lib
.Figure 20.74. Adding Additional Dependencies
- By default
CPPCONN_PUBLIC_FUNC
is defined to declare functions to be compatible with an application that calls a DLL. If building an application to call the static library, ensure that function prototypes are compatible with this. In this case, defineCPPCONN_PUBLIC_FUNC
to be an empty string, so that functions are declared with the correct prototype.In the Project, Properties tree view, under C++, Preprocessor, enter
CPPCONN_PUBLIC_FUNC=
into the Preprocessor Definitions text field.Figure 20.75. Setting the CPPCONN_PUBLIC_FUNC Define
Note
Make sure you enter
CPPCONN_PUBLIC_FUNC=
and notCPPCONN_PUBLIC_FUNC
, so that it is defined as an empty string.
If building an application to use the MariaDB Connector/C++ dynamically linked library carry out these steps:
- Under Linker, Input, add
mysqlcppconn.lib
into the Additional Dependencies text field. mysqlcppconn.dll
must be in the same directory as the application executable, or somewhere on the system's path, so that the application can access the MariaDB Connector/C++ Dynamic Linked Library at runtime.Copy
mysqlcppconn.dll
to the same directory as the application. Alternatively, extend thePATH
environment variable usingSET PATH=%PATH%;C:\path\to\cpp
. Alternatively, you can copymysqlcppconn.dll
to the Windows installation Directory, typicallyc:\windows
.
MySQL Connector/C++ Building Linux Applications with NetBeans
This section describes how to build MariaDB Connector/C++ applications for Linux using the NetBeans IDE.
Figure 20.76. The NetBeans IDE

To avoid potential crashes the build configuration of MariaDB Connector/C++ should match the build configuration of the application using it. For example, do not use the release build of MariaDB Connector/C++ with a debug build of the client application.
- The first step of building your application is to create a new project. Select File, New Project. Choose a C/C++ Application and click Next.
- Give the project a name and click Finish. A new project is created.
- In the Projects tab, right-click Source Files and select New, then Main C++ File....
- Change the filename, or simply select the defaults and click Finish to add the new file to the project.
- Now add some working code to your main source file. Explore your MariaDB Connector/C++ installation and navigate to the
examples
directory. - Select a suitable example, such as
standalone_example_docs1.cpp
. Copy all the code in this file, and use it to replace the code in your existing main source file. Amend the code to reflect the connection properties required for your test database. You now have a working example that will access a MariaDB database using MariaDB Connector/C++. - At this point, NetBeans is showing some errors in the source code. Direct NetBeans to the necessary header files to include. Select File, Project Properties from the main menu.
- In the Categories: tree view panel, navigate to Build, C++ Compiler.
- In the General panel, select Include Directories.
- Click the ... button.
- Click Add, then navigate to the directory where the MariaDB Connector/C++ header files are located. This will be
/usr/local/include
unless you have installed the files to a different location. Click Select. Click OK.Figure 20.77. Setting the Header Include Directory
- Click OK again to close the Project Properties dialog.
At this point, you have created a NetBeans project, containing a single C++ source file. You have also ensured that the necessary include files are accessible. Before continuing, decide whether your project is to use the MariaDB Connector/C++ static or dynamic library. The project settings are slightly different in each case, because you link against a different library.
Using the static library
To use the static library, link against two library files, libmysqlcppconn-static.a
and libmysqlclient.a
. The locations of the files depend on your setup, but typically the former are in /usr/local/lib
and the latter in /usr/lib
. Note the file libmysqlclient.a
is not part of MariaDB Connector/C++, but is the MariaDB Client Library file distributed with MariaDB Server. Remember, the MariaDB Client Library is an optional component as part of the MariaDB Server installation process. Note the MariaDB Client Library is also available as part of the MariaDB Connector/C distribution.
- The first step is to set the project to link the necessary library files. Select File, Project Properties from the main menu.
- In the Categories: tree view, navigate to Linker.
- In the General panel, select Additional Library Directories. Click the ... button.
- Select and add the
/usr/lib
and/usr/local/lib
directories. - In the same panel, add the two library files required for static linking as discussed earlier. The properties panel should then look similar to the following screenshot:
Figure 20.78. Setting the Static Library Directories and File Names
- Click OK to close the Project Properties dialog.
Using the dynamic library
For your application to use the MariaDB Connector/C++ dynamic library, you link your project with a single library file, libmysqlcppconn.so
. The location of this file depends on how you configured your installation of MariaDB Connector/C++, but is typically /usr/local/lib
.
- The first step is to set the project to link the necessary library file. Select File, Project Properties from the main menu.
- In the Categories: tree view, navigate to Linker.
- In the General panel, select Additional Library Directories. Click the ... button.
- Select and add the
/usr/local/lib
directories. - In the same panel, add the library file required for static linking as discussed earlier. The properties panel should then look similar to the following screenshot:
Figure 20.79. Setting the Dynamic Library Directory and File Name
- Click OK to close the Project Properties dialog.
Having configured your project, you build it by selecting Run, Build Main Project from the main menu. You then run the project using Run, Run Main Project.
On running the application, you should see a screen similar to the following (this is actually the static version of the application shown):
Figure 20.80. The Example Application Running

Note the above settings and procedures were carried out for the default Debug
configuration. To create a Release
configuration, select that configuration before setting the Project Properties.
MySQL Connector/C++ Getting Started: Usage Examples
- MySQL Connector/C++ Connecting to MySQL
- MySQL Connector/C++ Running a simple query
- MySQL Connector/C++ Fetching results
- MySQL Connector/C++ Using Prepared Statements
- MySQL Connector/C++ Complete Example 1
- MySQL Connector/C++ Complete Example 2
- MySQL Connector/C++ Running a simple query
The download package contains usage examples in the directory examples/
. The examples explain the basic usage of the following classes:
Connection
Driver
PreparedStatement
ResultSet
ResultSetMetaData
Statement
The examples cover:
- Using the
Driver
class to connect to MySQL - Creating tables, inserting rows, fetching rows using (simple) statements
- Creating tables, inserting rows, fetching rows using prepared statements
- Hints for working around prepared statement limitations
- Accessing result set metadata
The examples in this document are only code snippets. The code snippets provide a brief overview on the API. They are not complete programs. Please check the examples/
directory of your MariaDB Connector/C++ installation for complete programs. Please also read the README
file in the examples/
directory. To test the example code, first edit the examples.h
file in the examples/
directory, to add your connection information. Then rebuild the code by issuing a make
command.
The examples in the examples/
directory include:
examples/connect.cpp
:
How to create a connection, insert data into MariaDB and handle exceptions.
examples/connection_meta_schemaobj.cpp
:How to obtain metadata associated with a connection object, for example, a list of tables, databases, MariaDB version, connector version.
examples/debug_output.cpp
:How to activate and deactivate the MariaDB Connector/C++ debug protocol.
examples/exceptions.cpp
:A closer look at the exceptions thrown by the connector and how to fetch error information.
examples/prepared_statements.cpp
:How to run Prepared Statements including an example how to handle SQL commands that cannot be prepared by the MariaDB Server.
examples/resultset.cpp
:How to fetch data and iterate over the result set (cursor).
examples/resultset_meta.cpp
:How to obtain metadata associated with a result set, for example, number of columns and column types.
examples/resultset_types.cpp
:Result sets returned from metadata methods - this is more a test than much of an example.
examples/standalone_example.cpp
:Simple standalone program not integrated into regular CMake builds.
examples/statements.cpp
:How to run SQL commands without using Prepared Statements.
examples/cpp_trace_analyzer.cpp
:This example shows how to filter the output of the debug trace. Please see the inline comments for further documentation. This script is unsupported.
MySQL Connector/C++ Connecting to MariaDB
A connection to MariaDB is established by retrieving an instance of sql::Connection
from a sql::mysql::MySQL_Driver
object. A sql::mysql::MySQL_Driver
object is returned by sql::mysql::MySQL_Driver::get_mysql_driver_instance()
.
sql::mysql::MySQL_Driver *driver; sql::Connection *con; driver = sql::mysql::MySQL_Driver::get_mysql_driver_instance(); con = driver->connect('tcp://127.0.0.1:3306', 'user', 'password'); delete con;
Make sure that you free the sql::Connection
object as soon as you do not need it any more. But do not explicitly free the connector object!
MySQL Connector/C++ Running a simple query
For running simple queries, you can use the methods sql::Statement::execute()
, sql::Statement::executeQuery()
and sql::Statement::executeUpdate()
. Use the method sql::Statement::execute()
if your query does not return a result set or if your query returns more than one result set. See the examples/
directory for more on this.
sql::mysql::MySQL_Driver *driver; sql::Connection *con; sql::Statement *stmt; driver = sql::mysql::get_mysql_driver_instance(); con = driver->connect('tcp://127.0.0.1:3306', 'user', 'password'); stmt = con->createStatement(); stmt->execute('USE ' EXAMPLE_DB); stmt->execute('DROP TABLE IF EXISTS test'); stmt->execute('CREATE TABLE test(id INT, label CHAR(1))'); stmt->execute('INSERT INTO test(id, label) VALUES (1, 'a')'); delete stmt; delete con;
Note that you have to free sql::Statement
and sql::Connection
objects explicitly using delete.
MySQL Connector/C++ Fetching results
The API for fetching result sets is identical for (simple) statements and prepared statements. If your query returns one result set, use sql::Statement::executeQuery()
or sql::PreparedStatement::executeQuery()
to run your query. Both methods return sql::ResultSet
objects. The preview version does buffer all result sets on the client to support cursors.
// ... sql::Connection *con; sql::Statement *stmt; sql::ResultSet *res; // ... stmt = con->createStatement(); // ... res = stmt->executeQuery('SELECT id, label FROM test ORDER BY id ASC'); while (res->next()) { // You can use either numeric offsets... cout << 'id = ' << res->getInt(1); // getInt(1) returns the first column // ... or column names for accessing results. // The latter is recommended. cout << ', label = '' << res->getString('label') << ''' << endl; } delete res; delete stmt; delete con;Note
Note in the preceding code snippet that column indexing starts from 1.
Note that you have to free sql::Statement
, sql::Connection
and sql::ResultSet
objects explicitly using delete.
The usage of cursors is demonstrated in the examples contained in the download package.
MySQL Connector/C++ Using Prepared Statements
If you are not familiar with Prepared Statements on MariaDB have an extra look at the source code comments and explanations in the file examples/prepared_statement.cpp
.
sql::PreparedStatement
is created by passing an SQL query to sql::Connection::prepareStatement()
. As sql::PreparedStatement
is derived from sql::Statement
, you will feel familiar with the API once you have learned how to use (simple) statements (sql::Statement
). For example, the syntax for fetching results is identical.
// ... sql::Connection *con; sql::PreparedStatement *prep_stmt // ... prep_stmt = con->prepareStatement('INSERT INTO test(id, label) VALUES (?, ?)'); prep_stmt->setInt(1, 1); prep_stmt->setString(2, 'a'); prep_stmt->execute(); prep_stmt->setInt(1, 2); prep_stmt->setString(2, 'b'); prep_stmt->execute(); delete prep_stmt; delete con;
As usual, you have to free sql::PreparedStatement
and sql::Connection
objects explicitly.
MySQL Connector/C++ Complete Example 1
The following code shows a complete example of how to use MariaDB Connector/C++:
/* Copyright 2008, 2010, Oracle and/or its affiliates. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License. There are special exceptions to the terms and conditions of the GPL as it is applied to this software. View the full text of the exception in file EXCEPTIONS-CONNECTOR-C++ in the directory of this software distribution. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ /* Standard C++ includes */ #include <stdlib.h> #include <iostream> /* Include directly the different headers from cppconn/ and mysql_driver.h + mysql_util.h (and mysql_connection.h). This will reduce your build time! */ #include 'mysql_connection.h' #include <cppconn/driver.h> #include <cppconn/exception.h> #include <cppconn/resultset.h> #include <cppconn/statement.h> using namespace std; int main(void) { cout << endl; cout << 'Running 'SELECT 'Hello World!' » AS _message'...' << endl; try { sql::Driver *driver; sql::Connection *con; sql::Statement *stmt; sql::ResultSet *res; /* Create a connection */ driver = get_driver_instance(); con = driver->connect('tcp://127.0.0.1:3306', 'root', 'root'); /* Connect to the MariaDB test database */ con->setSchema('test'); stmt = con->createStatement(); res = stmt->executeQuery('SELECT 'Hello World!' AS _message'); while (res->next()) { cout << '\t... MariaDB replies: '; /* Access column data by alias or column name */ cout << res->getString('_message') << endl; cout << '\t... MariaDB says it again: '; /* Access column fata by numeric offset, 1 is the first column */ cout << res->getString(1) << endl; } delete res; delete stmt; delete con; } catch (sql::SQLException &e) { cout << '# ERR: SQLException in ' << __FILE__; cout << '(' << __FUNCTION__ << ') on line ' » << __LINE__ << endl; cout << '# ERR: ' << e.what(); cout << ' (MySQL error code: ' << e.getErrorCode(); cout << ', SQLState: ' << e.getSQLState() << ' )' << endl; } cout << endl; return EXIT_SUCCESS; }
MySQL Connector/C++ Complete Example 2
The following code shows a complete example of how to use MariaDB Connector/C++:
/* Copyright 2008, 2010, Oracle and/or its affiliates. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License. There are special exceptions to the terms and conditions of the GPL as it is applied to this software. View the full text of the exception in file EXCEPTIONS-CONNECTOR-C++ in the directory of this software distribution. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ /* Standard C++ includes */ #include <stdlib.h> #include <iostream> /* Include directly the different headers from cppconn/ and mysql_driver.h + mysql_util.h (and mysql_connection.h). This will reduce your build time! */ #include 'mysql_connection.h' #include <cppconn/driver.h> #include <cppconn/exception.h> #include <cppconn/resultset.h> #include <cppconn/statement.h> #include <cppconn/prepared_statement.h> using namespace std; int main(void) { cout << endl; cout << 'Let's have MariaDB count from 10 to 1...' << endl; try { sql::Driver *driver; sql::Connection *con; sql::Statement *stmt; sql::ResultSet *res; sql::PreparedStatement *pstmt; /* Create a connection */ driver = get_driver_instance(); con = driver->connect('tcp://127.0.0.1:3306', 'root', 'root'); /* Connect to the MariaDB test database */ con->setSchema('test'); stmt = con->createStatement(); stmt->execute('DROP TABLE IF EXISTS test'); stmt->execute('CREATE TABLE test(id INT)'); delete stmt; /* '?' is the supported placeholder syntax */ pstmt = con->prepareStatement('INSERT INTO test(id) VALUES (?)'); for (int i = 1; i <= 10; i++) { pstmt->setInt(1, i); pstmt->executeUpdate(); } delete pstmt; /* Select in ascending order */ pstmt = con->prepareStatement('SELECT id FROM test ORDER BY id ASC'); res = pstmt->executeQuery(); /* Fetch in reverse = descending order! */ res->afterLast(); while (res->previous()) cout << '\t... MariaDB counts: ' << res->getInt('id') << endl; delete res; delete pstmt; delete con; } catch (sql::SQLException &e) { cout << '# ERR: SQLException in ' << __FILE__; cout << '(' << __FUNCTION__ << ') on line ' » << __LINE__ << endl; cout << '# ERR: ' << e.what(); cout << ' (MySQL error code: ' << e.getErrorCode(); cout << ', SQLState: ' << e.getSQLState() << » ' )' << endl; } cout << endl; return EXIT_SUCCESS; }
MySQL Connector/C++ Tutorials
- Tutorial: Calling Stored Procedures with Statements in MariaDB Connector/C++
- Tutorial: Calling Stored Procedures with Prepared Statements in MariaDB Connector/C++
Here are some tutorials on using MariaDB Connector/C++. Also consult the examples in , "MySQL Connector/C++ Getting Started: Usage Examples".
Setting up the World database for use in the tutorials
These tutorials refer to tables and sample data from the World
database, which you can download from the MySQL Documentation page. Look for the section called "Example Databases".
Tutorial framework code
These examples all use the following framework, to avoid repeating code:
#include <stdlib.h> #include <iostream> #include <sstream> #include <stdexcept> #include 'mysql_connection.h' #include <cppconn/driver.h> #include <cppconn/exception.h> #include <cppconn/resultset.h> #include <cppconn/statement.h> #include <cppconn/prepared_statement.h> #define EXAMPLE_HOST 'localhost' #define EXAMPLE_USER 'root' #define EXAMPLE_PASS '' #define EXAMPLE_DB 'world' using namespace std; int main(int argc, const char **argv) { string url(argc >= 2 ? argv[1] : EXAMPLE_HOST); const string user(argc >= 3 ? argv[2] : EXAMPLE_USER); const string pass(argc >= 4 ? argv[3] : EXAMPLE_PASS); const string database(argc >= 5 ? argv[4] : EXAMPLE_DB); cout << 'Connector/C++ tutorial framework...' << endl; cout << endl; try { /* INSERT TUTORIAL CODE HERE! */ } catch (sql::SQLException &e) { /* The MariaDB Connector/C++ throws three different exceptions: - sql::MethodNotImplementedException (derived from sql::SQLException) - sql::InvalidArgumentException (derived from sql::SQLException) - sql::SQLException (derived from std::runtime_error) */ cout << '# ERR: SQLException in ' << __FILE__; cout << '(' << __FUNCTION__ << ') on line ' << __LINE__ << endl; /* Use what() (derived from std::runtime_error) to fetch the error message */ cout << '# ERR: ' << e.what(); cout << ' (MySQL error code: ' << e.getErrorCode(); cout << ', SQLState: ' << e.getSQLState() << ' )' << endl; return EXIT_FAILURE; } cout << 'Done.' << endl; return EXIT_SUCCESS; }
To compile and run the framework
First, copy and paste the framework code to a file such as frmwk.cpp
. Edit the #define
statements to reflect your connection details (server, user, password, database).
To compile the framework, for example on Mac OS X, type:
shell> g++ -o frmwk -I/usr/local/include -I/usr/local/include/cppconn -lmysqlcppconn frmwk.cpp
To run the framework, enter the following:
shell> ./frmwk
You will see a simple message. You are now ready to continue to the tutorials.
Tutorial: Calling Stored Procedures with Statements in MariaDB Connector/C++
Stored procedures can be called using both Statements and Prepared Statements. This tutorial looks at calling stored procedures using Statements. The following tutorial , "Tutorial: Calling Stored Procedures with Prepared Statements in MariaDB Connector/C++" will cover the use of Prepared Statements.
You can construct and call various combinations of stored procedures:
- A stored procedure that does not return any result. For example, such a stored procedure can log non-critical information, or change database data in a straightforward way.
- A stored procedure that returns an output parameter. For example, such a procedure can indicate success or failure, query a single item of data, or combine multiple data items into a single result.
- A stored procedure that returns a result set. The procedure can execute a query that matches an arbitrary number of table rows. Your application loops through the result set to display, transform, or otherwise process each item.
The following stored procedures illustrate each of these scenarios.
The following routine adds a country into the World database, but does not return a result. This corresponds to Scenario 1 above.
CREATE PROCEDURE add_country (IN country_code CHAR(3), IN country_name CHAR(52), IN continent_name CHAR(30)) BEGIN INSERT INTO Country(Code, Name, Continent) VALUES (country_code, country_name, continent_name); END
The next routine returns the population of a specified country, and corresponds to Scenario 2 above:
CREATE PROCEDURE get_pop (IN country_name CHAR(52), OUT country_pop INT(11)) BEGIN SELECT Population INTO country_pop FROM Country WHERE Name = country_name; END
The next routine is an example of a procedure returning a result set containing multiple records. This routine corresponds to Scenario 3 above.
CREATE PROCEDURE get_data () BEGIN SELECT Code, Name, Population, Continent FROM Country WHERE Continent = 'Oceania' AND Population < 10000; SELECT Code, Name, Population, Continent FROM Country WHERE Continent = 'Europe' AND Population < 10000; SELECT Code, Name, Population, Continent FROM Country WHERE Continent = 'North America' AND Population < 10000; END
Enter and test the stored procedures to ensure no errors have been introduced. You are now ready to start writing applications using Connector/C++ that call stored procedures.
Scenario 1 - Stored procedure does not return a result set
The first case illustrates Scenario 1, calling a Stored procedure that does not return a result set.
- Make a copy of the tutorial framework code.
- Insert the following code into the framework at the correct location (denoted by an INSERT HERE comment in the framework).
sql::Driver* driver = get_driver_instance(); std::auto_ptr<sql::Connection> con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr<sql::Statement> stmt(con->createStatement()); // We don't need to check the return value explicitly, if it indicates // an error Connector/C++ will generate an exception. stmt->execute('CALL add_country(\'ATL\', \'Atlantis\', \'North America\')');
- Compile the program using the following command:
shell> g++ -o sp_scenario1 -I/usr/local/include/cppconn/ -lmysqlcppconn sp_scenario1.cpp
- Run the program by typing:
shell> ./sp_scenario1
- Using the mysql Command Line Client, or other suitable tool, check the World database to determine that it has been updated correctly. You can use a query such as:
SELECT Code, Name, Continent FROM Country WHERE Code="ATL";
The code in this case simply creates a statement and then invokes the execute method on it, passing the call to the stored procedure as a parameter. The stored procedure itself does not return a value, although it is important to note there will always be a return value from the call - this is simply the call status. MariaDB Connector/C++ handles this status for you, so you do not need code to handle it explicitly. If the call fails for some reason, an exception will be raised, and this will be handled by the catch
statement in the code.
Scenario 2 - Stored procedure returns an output parameter
You will now see how to handle a stored procedure that returns an output parameter.
- Enter the following code into the tutorial framework code:
sql::Driver* driver = get_driver_instance(); std::auto_ptr<sql::Connection> con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr<sql::Statement> stmt(con->createStatement()); stmt->execute('CALL get_pop(\'Uganda\', @pop)'); std::auto_ptr<sql::ResultSet> res(stmt->executeQuery('SELECT @pop AS _reply')); while (res->next()) cout << 'Population of Uganda: ' << res->getString('_reply') << endl; stmt->execute('CALL get_pop_continent(\'Asia\', @pop)'); res.reset(stmt->executeQuery('SELECT @pop AS _reply')); while (res->next()) cout << 'Population of Asia: ' << res->getString('_reply') << endl; stmt->execute('CALL get_world_pop(@pop)'); res.reset(stmt->executeQuery('SELECT @pop AS _reply')); while (res->next()) cout << 'Population of World: ' << res->getString('_reply') << endl;
- Compile the program using the following command:
shell> g++ -o sp_scenario2 -I/usr/local/include/cppconn/ -lmysqlcppconn sp_scenario2.cpp
- Run the program by typing:
shell> ./sp_scenario2
Note the output generated by the program.
In this scenario, the stored procedure sets an output parameter. This is not returned as such, but needs to be obtained using a query. If running the SQL statements directly, this might be similar to the following:
CALL get_world_pop(@pop); SELECT @pop;
In the C++ code, a similar sequence is carried out. First, the CALL
is executed as seen earlier. To obtain the output parameter, an additional query must be executed. This query results in a ResultSet
that can then be processed in a while
loop. The simplest way to retrieve the data in this case is to use a getString
method on the ResultSet
, passing the name of the variable to access. In this example _reply
is used as a placeholder for the variable and therefore is used as the key to access the correct element of the result dictionary.
Scenario 3 - Stored procedure returns a Result Set
You will now see how to handle a stored procedure that returns a result set.
- Enter the following code into the tutorial framework code:
sql::Driver* driver = get_driver_instance(); std::auto_ptr<sql::Connection> con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr<sql::Statement> stmt(con->createStatement()); stmt->execute('CALL get_stats()'); std::auto_ptr< sql::ResultSet > res; do { res.reset(stmt->getResultSet()); while (res->next()) { cout << 'Result: ' << res->getString(1) << endl; } } while (stmt->getMoreResults());
- Compile the program using the following command:
shell> g++ -o sp_scenario3 -I/usr/local/include/cppconn/ -lmysqlcppconn sp_scenario3.cpp
- Run the program by typing:
shell> ./sp_scenario3
Note the output generated by the program.
The code is similar to the examples you have previously seen. The code of particular interest in this case is:
do { res.reset(stmt->getResultSet()); while (res->next()) { cout << 'Name: ' << res->getString('Name') << ' Population: ' << res->getInt('Population') << endl; } } while (stmt->getMoreResults());
The CALL
is executed as before, with the results being returned into multiple ResultSet
s. This is because the Stored Procedure in this case uses multiple SELECT
statements. In this example, the output shows that three Result Sets are processed, because there are three SELECT
statements in the Stored Procedure. All of the Result Sets have more than one row.
The results are processed using the pattern:
do { Get Result Set while (Get Result) { Process Result } } while (Get More Result Sets);Note
This pattern would be used even if the Stored Procedure carried out a single SELECT
and you knew there was only one result set. This is a requirement of the underlying protocol.
Tutorial: Calling Stored Procedures with Prepared Statements in MariaDB Connector/C++
Before working through this tutorial, it is recommended you first work through the previous tutorial , "Tutorial: Calling Stored Procedures with Statements in MariaDB Connector/C++".
Scenario 1 - Using a Prepared Statement to prepare a Stored Procedure that does not return a result set
- Add the following code to the
try
block of the tutorial framework:
vector<string> code_vector; code_vector.push_back('SLD'); code_vector.push_back('DSN'); code_vector.push_back('ATL'); vector<string> name_vector; name_vector.push_back('Sealand'); name_vector.push_back('Disneyland'); name_vector.push_back('Atlantis'); vector<string> cont_vector; cont_vector.push_back('Europe'); cont_vector.push_back('North America'); cont_vector.push_back('Oceania'); sql::Driver * driver = get_driver_instance(); std::auto_ptr< sql::Connection > con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr< sql::PreparedStatement > pstmt; pstmt.reset(con->prepareStatement('CALL add_country(?,?,?)')); for (int i=0; i<3; i++) { pstmt->setString(1,code_vector[i]); pstmt->setString(2,name_vector[i]); pstmt->setString(3,cont_vector[i]); pstmt->execute(); }
Also, add
#include <vector>
to the top of your code, because vectors are used to store sample data. - Compile the code using the following command:
g++ -o ps_scenario1 -I/usr/local/include/cppconn/ -lmysqlcppconn ps_scenario1.cpp
- Run the code using the command:
./ps_scenario1
- You can test the database has been updated correctly by using a query such as:
SELECT Code, Name, Continent FROM Country WHERE Code = 'DSN' OR Code="ATL" OR Code="SLD";
The code is relatively simple, as no processing is required to handle Result Sets. The procedure call, CALL add_country(?,?,?)
, is made using placeholders for input parameters denoted by '?'. These placeholders are replaced by values using the Prepared Statement's setString
method in this case. The for
loop is set up to iterate 3 times, as there are three data sets in this example. The same Prepared Statement is executed three times, each time with different input parameters.
Scenario 2 - Using a Prepared Statement to prepare a Stored Procedure that uses an output parameter
In this scenario a different Stored Procedure is going to be used compared to the one used in the tutorial , "Tutorial: Calling Stored Procedures with Statements in MariaDB Connector/C++". This is to illustrate passing an input parameter as well as fetching an output parameter. The stored routine is as follows:
CREATE PROCEDURE get_pop_continent (IN continent_name CHAR(30), OUT continent_pop INT(11)) BEGIN SELECT SUM(Population) INTO continent_pop FROM Country WHERE Continent = continent_name; END
- Copy the following code into the try block of the tutorial framework code:
vector<string> cont_vector; cont_vector.push_back('Europe'); cont_vector.push_back('North America'); cont_vector.push_back('Oceania'); sql::Driver * driver = get_driver_instance(); std::auto_ptr< sql::Connection > con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr< sql::Statement > stmt(con->createStatement()); std::auto_ptr< sql::PreparedStatement > pstmt; std::auto_ptr< sql::ResultSet > res; pstmt.reset(con->prepareStatement('CALL get_pop_continent(?,@pop)')); for (int i=0; i<3; i++) { pstmt->setString(1,cont_vector[i]); pstmt->execute(); res.reset(stmt->executeQuery('SELECT @pop AS _population')); while (res->next()) cout << 'Population of ' << cont_vector[i] << ' is ' << res->getString('_population') << endl; }
You will also need to add the line
#include <vector>
to the top of the code, as vectors are used in this example. - Compile the code using:
shell> g++ -o ps_scenario2 -I/usr/local/include/cppconn/ -lmysqlcppconn ps_scenario2.cpp
- Run the code using:
shell> ./ps_scenario2
- Make a note of the output.
In this scenario a Prepared Statement is created that calls the Stored Procedure get_pop_continent
. This procedure takes an input parameter, and also returns an output parameter. The approach used is to create another statement that can be used to fetch the output parameter using a SELECT
query. Note that when the Prepared Statement is created, the input parameter to the Stored Procedure is denoted by '?'. Prior to execution of Prepared Statement it is necessary to replace this placeholder by an actual value. This is done using methods such as setString
and setInt
, for example:
pstmt->setString(1,cont_vector[i]);
Although for the query used to obtain the output parameter a single result set is expected, it is important to use the while
loop to catch more than one result, to avoid the possibility of the connection becoming unstable.
Scenario 3 - Using a Prepared Statement to prepare a Stored Procedure that returns multiple Result Sets
NoteNote this scenario is not supported on versions of MariaDB prior to 5.5.3. This is due to a limitation in the client/server protocol.
- Enter the following code into the
try
block of the tutorial framework:
sql::Driver * driver = get_driver_instance(); std::auto_ptr< sql::Connection > con(driver->connect(url, user, pass)); con->setSchema(database); std::auto_ptr< sql::PreparedStatement > pstmt; std::auto_ptr< sql::ResultSet > res; pstmt.reset(con->prepareStatement('CALL get_data()')); res.reset(pstmt->executeQuery()); do { res.reset(pstmt->getResultSet()); while (res->next()) { cout << 'Name: ' << res->getString('Name') << ' Population: ' << res->getInt('Population') << endl; } } while (pstmt->getMoreResults());
- Compile the code using the following command:
shell> g++ -o ps_scenario3 -I/usr/local/include/cppconn/ -lmysqlcppconn ps_scenario3.cpp
- Run the program using the command:
shell> ./ps_scenario3
- Make a note of the output generated.
The code executes the Stored Procedure using a Prepared Statement. The standard do-while construct is used to ensure that all Result Sets are fetched. In this case the returned values are fetched from the Result Sets using the getInt
and getString
methods.
MySQL Connector/C++ Debug Tracing
Although a debugger can be used to debug your application, you may find it beneficial to turn on the debug traces of the connector. Some problems happen randomly which makes them difficult to debug using a debugger. In such cases debug traces and protocol files are more useful because they allow you to trace the activities of all instances of your program.
DTrace is a very powerful technology to trace any application without having to develop an extra trace module for your application. Unfortunately, DTrace is currently only available on Solaris, MacOS 10.5, and FreeBSD.
The MariaDB Connector/C++ can write two trace files:
- Trace file generated by the MariaDB Client Library
- Trace file generated internally by MariaDB Connector/C++
The first trace file can be generated by the underlying MariaDB Client Library (libmysql). To enable this trace, the connector will call the C-API function mysql_debug()
internally. As only debug versions of the MariaDB Client Library are capable of writing a trace file, compile MariaDB Connector/C++ against a debug version of the library if you want to utilize this trace. The trace shows the internal function calls and the addresses of internal objects as shown below:
>mysql_stmt_init | >_mymalloc | | enter: Size: 816 | | exit: ptr: 0x68e7b8 | <_mymalloc | >init_alloc_root | | enter: root: 0x68e7b8 | | >_mymalloc | | | enter: Size: 2064 | | | exit: ptr: 0x68eb28 [...]
The second trace is the MariaDB Connector/C++ internal trace. It is available with debug and nondebug builds of the connector as long as you have enabled the tracing module at compile time using cmake -DMYSQLCPPCONN_TRACE_ENABLE:BOOL=1
. By default, the tracing functionality is not available and calls to trace functions are removed by the preprocessor.
Compiling the connector with tracing functionality enabled will cause two additional tracing function calls per each connector function call. Run your own benchmark to find out how much this will impact the performance of your application.
A simple test using a loop running 30,000 INSERT SQL statements showed no significant real-time impact. The two variants of this application using a trace enabled and trace disabled version of the connector performed equally well. The run time measured in real-time was not significantly impacted as long as writing a debug trace was not enabled. However, there will be a difference in the time spent in the application. When writing a debug trace the IO subsystem may become a bottleneck.
In summary, use connector builds with tracing enabled carefully. Trace enabled versions may cause higher CPU usage even if the overall run time of your application is not impacted significantly.
| INF: Tracing enabled <MySQL_Connection::setClientOption >MySQL_Prepared_Statement::setInt | INF: this=0x69a2e0 | >MySQL_Prepared_Statement::checkClosed | <MySQL_Prepared_Statement::checkClosed | <MySQL_Prepared_Statement::setInt [...]
The example from examples/debug_output.cpp
demonstrates how to activate the debug traces in your program. Currently they can only be activated through API calls. The traces are controlled on a per-connection basis. You can use the setClientOptions()
method of a connection object to activate and deactivate the generation of a trace. The MariaDB Client Library trace is always written into a file, whereas the connector's protocol messages are printed to standard out.
sql::Driver *driver; int on_off = 1; /* Using the Driver to create a connection */ driver = get_driver_instance(); std::auto_ptr< sql::Connection > con(driver->connect(host, user, pass)); /* Activate debug trace of the MariaDB Client Library (C-API) Only available with a debug build of the MariaDB Client Library! */ con->setClientOption('libmysql_debug', 'd:t:O,client.trace'); /* Tracing is available if you have compiled the driver using cmake -DMYSQLCPPCONN_TRACE_ENABLE:BOOL=1 */ con->setClientOption('client_trace', &on_off);
MySQL Connector/C++ Usage Notes
See the JDBC overview for information on JDBC 4.0. Please also check the examples/
directory of the download package.
DatabaseMetaData::supportsBatchUpdates()
returnstrue
because MariaDB supports batch updates in general. However, no API calls for batch updates are provided by the MariaDB Connector/C++ API.- Two non-JDBC methods have been introduced for fetching and setting unsigned integers:
getUInt64()
andgetUInt()
. These are available forResultSet
andPrepared_Statement
:ResultSet::getUInt64()
ResultSet::getUInt()
Prepared_Statement::setUInt64()
Prepared_Statement::setUInt()
The corresponding
getLong()
andsetLong()
methods have been removed. - The method
DatabaseMetaData::getColumns()
has 23 columns in its result set, rather than the 22 columns defined by JDBC. The first 22 columns are as described in the JDBC documentation, but column 23 is new:IS_AUTOINCREMENT
: String which is "YES" if the column is an auto-increment column. Otherwise the string contains "NO". - MySQL Connector/C++ may return different metadata for the same column.
When you have any column that accepts a charset and a collation in its specification and you specify a binary collation, such as:
CHAR(250) CHARACTER SET 'latin1' COLLATE 'latin1_bin'
The server sets the
BINARY
flag in the result set metadata of this column. The methodResultSetMetadata::getColumnTypeName()
uses the metadata and will report, due to theBINARY
flag, that the column type name isBINARY
. This is illustrated below:mysql> create table varbin(a varchar(20) character set utf8 collate utf8_bin); Query OK, 0 rows affected (0.00 sec) mysql> select * from varbin; Field 1: `a` Catalog: `def` Database: `test` Table: `varbin` Org_table: `varbin` Type: VAR_STRING Collation: latin1_swedish_ci (8) Length: 20 Max_length: 0 Decimals: 0 Flags: BINARY 0 rows in set (0.00 sec) mysql> select * from information_schema.columns where table_name='varbin'\G *************************** 1. row *************************** TABLE_CATALOG: NULL TABLE_SCHEMA: test TABLE_NAME: varbin COLUMN_NAME: a ORDINAL_POSITION: 1 COLUMN_DEFAULT: NULL IS_NULLABLE: YES DATA_TYPE: varchar CHARACTER_MAXIMUM_LENGTH: 20 CHARACTER_OCTET_LENGTH: 60 NUMERIC_PRECISION: NULL NUMERIC_SCALE: NULL CHARACTER_SET_NAME: utf8 COLLATION_NAME: utf8_bin COLUMN_TYPE: varchar(20) COLUMN_KEY: EXTRA: PRIVILEGES: select,insert,update,references COLUMN_COMMENT: 1 row in set (0.01 sec)
However,
INFORMATION_SCHEMA
gives no hint in itsCOLUMNS
table that metadata will contain theBINARY
flag.DatabaseMetaData::getColumns()
usesINFORMATION_SCHEMA
. It will report the type nameCHAR
for the same column. Note, a different type code is also returned. - The MariaDB Connector/C++ class
sql::DataType
defines the following JDBC standard data types:UNKNOWN
,BIT
,TINYINT
,SMALLINT
,MEDIUMINT
,INTEGER
,BIGINT
,REAL
,DOUBLE
,DECIMAL
,NUMERIC
,CHAR
,BINARY
,VARCHAR
,VARBINARY
,LONGVARCHAR
,LONGVARBINARY
,TIMESTAMP
,DATE
,TIME
,GEOMETRY
,ENUM
,SET
,SQLNULL
.However, the following JDBC standard data types are not supported by MariaDB Connector/C++:
ARRAY
,BLOB
,CLOB
,DISTINCT
,FLOAT
,OTHER
,REF
,STRUCT
. - When inserting or updating
BLOB
orTEXT
columns, MariaDB Connector/C++ developers are advised not to usesetString()
. Instead, use the dedicated API functionsetBlob()
.The use of
setString()
can cause a Packet too large error message. The error will occur if the length of the string passed to the connector usingsetString()
exceedsmax_allowed_packet
(minus a few bytes reserved in the protocol for control purposes). This situation is not handled in MariaDB Connector/C++, as this could lead to security issues, such as extremely large memory allocation requests due to malevolently long strings.However, if
setBlob()
is used, this problem does not arise. This is becausesetBlob()
takes a streaming approach based onstd::istream
. When sending the data from the stream to MariaDB Server, MariaDB Connector/C++ will split the stream into chunks appropriate for MariaDB Server and observe themax_allowed_packet
setting currently being used.CautionWhen using
setString()
it is not possible to setmax_allowed_packet
to a value large enough for the string, prior to passing it to MariaDB Connector/C++. The MariaDB 5.1 documentation formax_allowed_packet
states: "As of MariaDB 5.1.31, the session value of this variable is read only. Before 5.1.31, setting the session value is permitted but has no effect."This difference with the JDBC specification ensures that MariaDB Connector/C++ is not vulnerable to memory flooding attacks.
- In general MariaDB Connector/C++ works with MariaDB 5.0, but it is not completely supported. Some methods may not be available when connecting to MariaDB 5.0. This is because the Information Schema is used to obtain the requested information. There are no plans to improve the support for 5.0 because the current GA version of MariaDB Server is 5.5. As a new product, MariaDB Connector/C++ is primarily targeted at the MariaDB Server GA version that was available on its release.
The following methods will throw a
sql::MethodNotImplemented
exception when you connect to MariaDB earlier than 5.1.0:DatabaseMetadata::getCrossReference()
DatabaseMetadata::getExportedKeys()
- MySQL Connector/C++ includes a method
Connection::getClientOption()
which is not included in the JDBC API specification. The prototype is:void getClientOption(const std::string & optionName, void * optionValue)
The method can be used to check the value of connection properties set when establishing a database connection. The values are returned through the
optionValue
argument passed to the method with the typevoid *
.Currently,
getClientOption()
supports fetching theoptionValue
of the following options:metadataUseInfoSchema
defaultStatementResultType
defaultPreparedStatementResultType
The connection option
metadataUseInfoSchema
controls whether to use theInformation_Schemata
for returning the meta data ofSHOW
commands. In the case ofmetadataUseInfoSchema
, interpret theoptionValue
argument as a boolean upon return.In the case of both
defaultStatementResultType
anddefaultPreparedStatementResultType
, interpret theoptionValue
argument as an integer upon return.The connection property can be either set when establishing the connection through the connection property map or using
void Connection::setClientOption(const std::string & optionName, const void * optionValue)
whereoptionName
is assigned the valuemetadataUseInfoSchema
.Some examples are given below:
int defaultStmtResType; int defaultPStmtResType; conn->getClientOption('defaultStatementResultType', (void *) &defaultStmtResType); conn->getClientOption('defaultPreparedStatementResultType', (void *) &defaultPStmtResType); bool isInfoSchemaUsed; conn->getClientOption('metadataUseInfoSchema', (void *) &isInfoSchemaUsed);
- MySQL Connector/C++ also supports the following methods not found in the JDBC API standard:
std::string MySQL_Connection::getSessionVariable(const std::string & varname)
void MySQL_Connection::setSessionVariable(const std::string & varname, const std::string & value)
Note that both methods are members of the
MySQL_Connection
class. The methods get and set MariaDB session variables.setSessionVariable()
is equivalent to executing:SET SESSION <varname> = <value>
getSessionVariable()
is equivalent to executing the following and fetching the first return value:SHOW SESSION VARIABLES LIKE '<varname>'
You can use "%" and other placeholders in <varname>, if the underlying MariaDB server supports this.
- Fetching the value of a column can sometimes return different values depending on whether the call is made from a Statement or Prepared Statement. This is because the protocol used to communicate with the server differs depending on whether a Statement or Prepared Statement is used.
To illustrate this, consider the case where a column has been defined as of type
BIGINT
. The most negativeBIGINT
value is then inserted into the column. If a Statement and Prepared Statement are created that perform aGetUInt64()
call, then the results will be different in each case. The Statement returns the maximum positive value forBIGINT
. The Prepared Statement returns 0.The reason for the different results is due to the fact that Statements use a text protocol, and Prepared Statements use a binary protocol. With the binary protocol in this case, a binary value is returned from the server that can be interpreted as an
int64
. In the above scenario a very large negative value was fetched withGetUInt64()
, which fetches unsigned integers. As the large negative value cannot be sensibly converted to an unsigned value 0 is returned.In the case of the Statement, which uses the text protocol, values are returned from the server as strings, and then converted as required. When a string value is returned from the server in the above scenario, the large negative value must be converted by the runtime library function
strtoul()
, whichGetUInt64()
calls. The behavior ofstrtoul()
is dependent upon the specific runtime and host operating system, so the results can be variable. In the case given a large positive value was actually returned.Although it is very rare, there are some cases where Statements and Prepared Statements can return different values unexpectedly, but this usually only happens in extreme cases such as the one mentioned.
- The JDBC documentation lists many fields for the
DatabaseMetaData
class. JDBC also appears to define certain values for those fields. However, MariaDB Connector/C++ does not define certain values for those fields. Internally enumerations are used and the compiler determines the values to assign to a field.To compare a value with the field, use code such as the following, rather than making assumptions about specific values for the attribute:
// dbmeta is an instance of DatabaseMetaData if (myvalue == dbmeta->attributeNoNulls) { ... }
Usually
myvalue
will be a column from a result set holding metadata information. MariaDB Connector/C++ does not guarantee thatattributeNoNulls
is 0. It can be any value. - When programming Stored Procedures, JDBC has available an extra class, an extra abstraction layer for callable statements, the
CallableStatement
class. As this class is not present in MariaDB Connector/C++, use the methods from theStatement
andPrepared Statement
classes to run a Stored Procedure usingCALL
.
MySQL Connector/C++ Known Bugs and Issues
NotePlease report bugs through MySQL Bug System .
Known bugs:
None.
Known issues:
- When linking against a static library for 1.0.3 on Windows, define
CPPDBC_PUBLIC_FUNC
either in the compiler options (preferable) or with/D 'CPPCONN_PUBLIC_FUNC='
. You can also explicitly define it in your code by placing#define CPPCONN_PUBLIC_FUNC
before the header inclusions. - Generally speaking, C++ library binaries are less portable than C library binaries. Issues can be caused by name mangling, different Standard Template Library (STL) versions and using different compilers and linkers for linking against the libraries than were used for building the library itself.
Even a small change in the compiler version can, but does not have to, cause problems. If you obtain error messages, that you suspect are related to binary incompatibilities, build MariaDB Connector/C++ from source, using the same compiler and linker that you will use to build and link your application.
Due to the variations between Linux distributions, compiler and linker versions and STL versions, it is not possible to provide binaries for each and every possible configuration. However, the MariaDB Connector/C++ binary distributions contain a
README
file that describes the environment and settings used to build the binary versions of the libraries. - To avoid potential crashes the build configuration of MariaDB Connector/C++ should match the build configuration of the application using it. For example, do not use the release build of MariaDB Connector/C++ with a debug build of the client application.
See also the MariaDB Connector/C++ Changelogs which can be found here "MySQL Connector/C++ Change History".
MySQL Connector/C++ Feature requests
You can suggest new features in the first instance by joining the mailing list or forum and talking with the developers directly. See , "MySQL Connector/C++ Support"
The following feature requests are currently being worked on:
- C++ references for
Statements
,ResultSets
, and exceptions, are being considered, instead of pointers to heap memory. This reduces the exception handling burden for the programmer. - Adopt STL (suggestions are welcome).
- JDBC compliance: data type interfaces and support through
ResultSet:getType()
andPreparedStatement:bind()
. Introducesql::Blob
,sql::Clob
,sql::Date
,sql::Time
,sql::Timestamp
,sql::URL
. Supportget|setBlob()
,get|setClob()
,get|setDate()
,get|setTime()
,get|setTimestamp()
,get|setURL()
- Add support for all C-API connection options. Improved support for
mysql_options
. - Add connect method which supports passing options using HashMaps.
- Create Windows installer.
MySQL Connector/C++ Support
For general discussion of the MariaDB Connector/C++ please use the C/C++ community forum or join the MySQL Connector/C++ mailing list.
Bugs can be reported at the MySQL bug Web site.
For Licensing questions, and to purchase MariaDB Products and Services, please http://www.mysql.com/buy-mysql/
The MariaDB Connector/C++ Changelogs can be found here "MySQL Connector/C++ Change History"
MySQL Connector/C++ FAQ
Questions
- : What is MariaDB Connector/C++?
- : Are any MariaDB products using MariaDB Connector/C++?
- : Does MariaDB Connector/C++ implement the client/server protocol?
- : Which MariaDB Server version(s) is MariaDB Connector/C++ compatible with?
Questions and Answers
21.5.12.1: What is MariaDB Connector/C++?
MySQL Connector/C++ is a MariaDB database connector for C++. It allows you develop applications in C++ that connect to the MariaDB Server. MariaDB Connector/C++ is compatible with the JDBC 4.0 API.
21.5.12.2: Are any MariaDB products using MariaDB Connector/C++?
Yes, MariaDB Workbench and MariaDB Connector/OpenOffice.org.
21.5.12.3: Does MariaDB Connector/C++ implement the client/server protocol?
No. MariaDB Connector/C++ uses the MariaDB Client Library for the client/server communication.
21.5.12.4: Which MariaDB Server version(s) is MariaDB Connector/C++ compatible with?
MySQL Connector/C++ fully supports MariaDB Server 5.1 and later.
MySQL Connector/C
What is MariaDB Connector/C?
MySQL Connector/C is a C client library for client/server communication. It is a standalone replacement for the MariaDB Client Library shipped with the MariaDB Server.
Why have a replacement for MariaDB Client Library?
There is no need to compile or install the MariaDB Server package if you only need the client library.
MySQL Connector/C does not rely on the MariaDB Server release cycle, so bug fixes and new features are released more often.
MySQL Connector/C API documentation is available here , "C API Function Descriptions".
Supported platforms include:
- Windows
- Windows x64
- Linux
- Solaris
- FreeBSD
- Mac OS X
- HP-UX
- IBM AIX
- IBM i5/OS
Building MariaDB Connector/C from the Source Code
Obtaining the Source Code
You can download a tar file containing the source code from the MariaDB Developers site. Select the source code package from the drop down list.
The source code for development releases of the connector can be found at http://launchpad.net/libmysql on the Launchpad site.
The source code for the 1.0 branch is also available on the Launchpad site.
To get the code, you must have Bazaar installed. Use the command bzr branch lp:libmysql
.
- Building on Unix
Examples of supported Unix or Unix-like operating systems include:
- Solaris
- Linux
- HP-UX
- AIX
- OS X
Compiler Tools
Ideally, the native compiler tool set for the target platform is used for compilation. This would be SunStudio for Solaris and aCC for HP-UX for example. However, the GNU tool-chain can be used across all platforms.
You also need CMake 2.6 or newer, which is available online.
To Build
If using GNU AutoTools, change to the MariaDB Connector/C source directory and follow the procedure below.
- To generate the makefile, enter:
shell> cmake -G 'Unix Makefiles'
or for a Debug build, enter:
shell> cmake -G 'Unix Makefiles' -DCMAKE_BUILD_TYPE=Debug
- Then build the project using:
shell> make
To Install
By default,
make install
installs the MariaDB Connector/C files in the/usr/local
directory. To change this location, specify another directory when generating themakefile
:shell> cmake -G 'Unix Makefiles' -DCMAKE_INSTALL_PREFIX=/mypath
Now, in the root shell, enter the following to install the MariaDB Connector/C libraries and tools:
root-shell> make install
At this point, all of the MariaDB Connector/C files will be in place.
- Building on Microsoft Windows
Older versions of Microsoft Windows are not supported. Supported versions are Windows 2000, Windows XP, Windows Vista, Windows Server 2003, or Windows Server 2008.
Compiler Tools
Microsoft Visual Studio 8 and 9 are recommended. The Express Edition of Visual Studio and other compilers might work, but are untested.
You also need CMake 2.6 or newer, available at http://www.cmake.org.
To Build
Set the environment variables for the Visual Studio toolchain. Visual Studio includes a batch file to set these for you, and installs a shortcut into the Start menu to open a command prompt with these variables set.
Build MariaDB Connector/C using the CMake command-line tool by entering the following from the source root directory in a command prompt window:
shell> cmake -G 'Visual Studio 9 2008'
This produces a project file that you can open with Visual Studio or build from the command line with either of:
shell> devenv.com libmysql.sln /build Release
shell> devenv.com libmysql.sln /build RelWithDebInfo
For other versions of Visual Studio or
nmake
based build, run the following command:shell> cmake --help
to check the supported generators.
To compile the Debug build, you must run set the CMake build type so the correct version of external libraries are used:
shell> cmake -G 'Visual Studio 8 2005' -DCMAKE_BUILD_TYPE=Debug
Followed by:
shell> devenv.com libmysql.sln /build Debug
To Install
To create a install package you can choose between two variants:
- Creating a Zip package
- Creating an MSI install package
- Zip package
To create a Zip package, run the
cpack
command from the root of your MariaDB Connector/C source directory. - MSI Install package
The required tools include Windows XML Installer toolset (WIX), which is available online.
To create the MSI install package change to the subdirectory
win
and generate themakefile
:shell> cmake -G 'NMake Makefiles'
Create the MSI install package by calling
nmake
:shell> nmake
Build Options
The following options can be used when building the MariaDB Connector/C source code:
Build Option | Description |
---|---|
-DWITH_OPENSSL=1 | Enables dynamic linking to the system OpenSSL library. |
-DWITH_EXTERNAL_ZLIB=1 | Enables dynamic linking to the system Zlib library. |
Testing MariaDB Connector/C
For testing MariaDB Connector/C, you need a running MariaDB server instance. Before you run the test suite, specify the following environment variables:
MYSQL_TEST_HOST
(default localhost)MYSQL_TEST_USER
MYSQL_TEST_PASSWD
MYSQL_TEST_PORT
MYSQL_TEST_SOCKET
MYSQL_TEST_DB
(default test)
To run the test suite, execute ctest
from the command line:
shell> ctest
MySQL Connector/C FAQ
Questions
- : What is the "MySQL Native C API"? What are its typical benefits and use cases?
- : What is "libmysql"?
- : What is "libmysqld"?
- : What is "MySQL Connector/C"?
- : What is the difference between "Native C API", "libmysql", "libmysqld" and "MySQL Connector/C"?
- : Does MariaDB Connector/C replace any of "Native C API", "libmysql" and "libmysqld"?
Questions and Answers
21.6.3.1: What is the "MySQL Native C API"? What are its typical benefits and use cases?
MySQL Connector/C, also known as libmysql
, or MariaDB Native C API, is a standalone, C-based API and library that you can use in C applications to connect with the MariaDB Server. It implements the same MariaDB client API that has been in use for a decade.
It is also used as the foundation for drivers for standard database APIs such as ODBC, Perl's DBI, and Python's DB API.
21.6.3.2: What is "libmysql"?
libmysql
is the name of the library that MariaDB Connector/C provides.
21.6.3.3: What is "libmysqld"?
libmysqld
is an embedded database server with the same API as MariaDB Connector/C. It is included with the MariaDB Server distribution.
21.6.3.4: What is "MySQL Connector/C"?
MySQL Connector/C is a standalone distribution of the libmysql
library, which was previously only available as part of the MariaDB Server distribution. The version of libmysql
included with MariaDB Connector/C and the version bundled with the server are functionally equivalent, but the cross-platform build system for MariaDB Connector/C uses CMake.
21.6.3.5: What is the difference between "Native C API", "libmysql", "libmysqld" and "MySQL Connector/C"?
MySQL Connector/C and libmysql
are the "native C API for MySQL", and all three terms can be used interchangeably. "libmysqld" is the embedded version of the MariaDB Server, and is included in the server distribution.
21.6.3.6: Does MariaDB Connector/C replace any of "Native C API", "libmysql" and "libmysqld"?
MySQL Connector/C contains libmysql
, and implements a native C API. It does not include libmysqld
, which can be found with the MariaDB server distribution.
MySQL Connector/OpenOffice.org
- Installation
- Getting Started: Connecting to MySQL
- Getting Started: Usage Examples
- References
- Known Bugs
- Contact
- Getting Started: Connecting to MySQL
MySQL Connector/OpenOffice.org is a native MariaDB database connector for OpenOffice.org. Currently, it is in preview status and supports OpenOffice.org 3.1 and above. It can be used to connect OpenOffice.org applications to a MariaDB server.
Before MariaDB Connector/OpenOffice.org became available you would have to use MariaDB Connector/J (JDBC) or MariaDB Connector/ODBC to connect to a MariaDB server.
Connector/OpenOffice.org is a community project. The source code for Connector/OpenOffice.org is available under GPL with the FLOSS License Exception.
Advantages
Using MariaDB Connector/OpenOffice.org has the following advantages:
- Easy installation through the OpenOffice.org Extension Manager.
- Seamless integration into OpenOffice.org.
- No need to go through an additional Connector installation routine (ODBC/JDBC)
- No need to configure or register an additional Connector (ODBC)
- No need to install or configure a driver manager (ODBC)
Status
MySQL Connector/OpenOffice.org is currently at version 1.0 GA.
If you have any queries please contact us through our mailing list at <users@dba.openoffice.org>
Installation
- Install or upgrade to OpenOffice.org 3.1.
- Download MariaDB Connector/OpenOffice.org from The OpenOffice.org extension download site. Save the file corresponding to your platform. Currently supported platforms are Windows, Linux, Linux x86-64, Mac OS X, Solaris x86 and Solaris SPARC.
- Add the
.oxt
extension through the Extension Manager of OpenOffice.org. In OpenOffice.org, select Tools, Extension Manager... and specify the.oxt
file as a new extension. When done, MariaDB Connector/OpenOffice.org will show up as a new extension in the Extension Manager.Figure 20.81. Adding an Extension
- Restart OpenOffice.org.
Getting Started: Connecting to MariaDB
MySQL Connector/OpenOffice.org enables you to access the MariaDB Server and its schemata from the OpenOffice.org suite.
The following example demonstrates the creation of a new OpenOffice.org Base database which uses a local MariaDB Server for storage and the new connector for connecting.
- Select the database
Create a new database by selecting File, New, Database. This starts a wizard that enables you to create a new database, open an existing database, or connect to an existing database. Select the Connect to existing database radio button. From the listbox select MySQL. Click Next >>.
Figure 20.82. Selecting the Database
- You will be asked how you would like to connect to the database. Select the Connect native radio button.
Figure 20.83. Selecting the connection type
Click Next >>.
- Fill in the connection settings
Enter the name of the database, server URL, and optionally the socket to connect on (if not using the default).
Note that if you do not specify a database all databases will be available for selection.
Figure 20.84. Entering Connection Settings
Click Next >>.
- Set up user authentication
If you are using MariaDB server's anonymous account without a password, you do not have to fill in anything in this step. Otherwise, fill in your MariaDB user name and check the password check box. Note, for security reasons, you should not normally use the anonymous account without a password.
Figure 20.85. Setting Up User Authentication
You can now test your connection to the MariaDB database server by clicking the Test Connection button. Check the check box if you do not want OpenOffice.org to ask you for your password again in the current session. Testing the connection is optional, although recommended.
Click Next >>.
- Decide how to proceed after connecting to the database
Figure 20.86. After Connecting to the Database
Keep the default settings.
Click Finish.
- You will then be prompted to save you database as a database file. Enter the name of the database and the location in which to save the file.
Figure 20.87. Entering the Database File Name
Click Save.
You will be located in the Base application with your database tables displayed.
Getting Started: Usage Examples
Listing Tables
In the Database area of the Base main window, select Tables. If this is the first time you are accessing the database you will be prompted for your credentials (user name and password); you can store these settings for your current Base session.
Figure 20.88. Listing Tables

Depending on your connection settings you will now see all databases with all their tables, or just the database you have specified in the connection settings.
References
See the OpenOffice.org Web site for documentation of the office suite and its Extension Manager.
Known Bugs
If you discover a bug in Connector/OpenOffice.org please add it to this list and send an email to <users@dba.openoffice.org>
. You need to be logged in with an OpenOffice.org account for both; see the project mailing list for details.
Contact
To discuss the new MariaDB Connector/OpenOffice.org, please subscribe to the mailing list <users@dba.openoffice.org>
. It is a low-volume list with less than 10 mails per day.
libmysqld, the Embedded MariaDB Server Library
- Compiling Programs with
libmysqld
- Restrictions When Using the Embedded MariaDB Server
- Options with the Embedded Server
- Embedded Server Examples
- Licensing the Embedded Server
- Restrictions When Using the Embedded MariaDB Server
The embedded MariaDB server library makes it possible to run a full-featured MariaDB server inside a client application. The main benefits are increased speed and more simple management for embedded applications.
The embedded server library is based on the client/server version of MySQL, which is written in C/C++. Consequently, the embedded server also is written in C/C++. There is no embedded server available in other languages.
The API is identical for the embedded MariaDB version and the client/server version. To change a threaded application to use the embedded library, you normally only have to add calls to the following functions.
Function | When to Call |
---|---|
mysql_library_init()
| Call it before any other MariaDB function is called, preferably early in the main() function.
|
mysql_library_end()
| Call it before your program exits. |
mysql_thread_init()
| Call it in each thread you create that accesses MySQL. |
mysql_thread_end()
| Call it before calling pthread_exit() |
Then, link your code with libmysqld.a
instead of libmysqlclient.a
. To ensure binary compatibility between your application and the server library, always compile your application against headers for the same series of MariaDB that was used to compile the server library. For example, if libmysqld
was compiled against MariaDB 5.1 headers, do not compile your application against MariaDB 5.5 headers, or vice versa.
Because the mysql_library_
functions are also included in xxx
()libmysqlclient.a
, you can change between the embedded and the client/server version by just linking your application with the right library. See , "mysql_library_init()
".
One difference between the embedded server and the standalone server is that for the embedded server, authentication for connections is disabled by default. To use authentication for the embedded server, define the HAVE_EMBEDDED_PRIVILEGE_CONTROL
compiler flag when you invoke CMake to configure your MariaDB distribution. See , "MySQL Source-Configuration Options".
Compiling Programs with libmysqld
In precompiled binary MariaDB distributions that include libmysqld
, the embedded server library, MariaDB builds the library using the appropriate vendor compiler if there is one.
To get a libmysqld
library if you build MariaDB from source yourself, you should configure MariaDB with the -DWITH_EMBEDDED_SERVER=1
option. See , "MySQL Source-Configuration Options".
When you link your program with libmysqld
, you must also include the system-specific pthread
libraries and some libraries that the MariaDB server uses. You can get the full list of libraries by executing mysql_config --libmysqld-libs.
The correct flags for compiling and linking a threaded program must be used, even if you do not directly call any thread functions in your code.
To compile a C program to include the necessary files to embed the MariaDB server library into an executable version of a program, the compiler will need to know where to find various files and need instructions on how to compile the program. The following example shows how a program could be compiled from the command line, assuming that you are using gcc, use the GNU C compiler:
gcc mysql_test.c -o mysql_test -lz \ `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
Immediately following the gcc command is the name of the C program source file. After it, the -o
option is given to indicate that the file name that follows is the name that the compiler is to give to the output file, the compiled program. The next line of code tells the compiler to obtain the location of the include files and libraries and other settings for the system on which it is compiled. Because of a problem with mysql_config, the option -lz
(for compression) is added here. The mysql_config command is contained in backticks, not single quotation marks.
On some non-gcc platforms, the embedded library depends on C++ runtime libraries and linking against the embedded library might result in missing-symbol errors. To solve this, link using a C++ compiler or explicitly list the required libraries on the link command line.
Restrictions When Using the Embedded MariaDB Server
The embedded server has the following limitations:
- No user-defined functions (UDFs).
- No stack trace on core dump.
- You cannot set this up as a master or a slave (no replication).
- Very large result sets may be unusable on low memory systems.
- You cannot connect to an embedded server from an outside process with sockets or TCP/IP. However, you can connect to an intermediate application, which in turn can connect to an embedded server on the behalf of a remote client or outside process.
InnoDB
is not reentrant in the embedded server and cannot be used for multiple connections, either successively or simultaneously.- The Event Scheduler is not available. Because of this, the
event_scheduler
system variable is disabled.
Some of these limitations can be changed by editing the mysql_embed.h
include file and recompiling MySQL.
Options with the Embedded Server
Any options that may be given with the mysqld server daemon, may be used with an embedded server library. Server options may be given in an array as an argument to the mysql_library_init()
, which initializes the server. They also may be given in an option file like my.cnf
. To specify an option file for a C program, use the --defaults-file
option as one of the elements of the second argument of the mysql-library-init()
function. See , "mysql_library_init()
", for more information on the mysql_library_init()
function.
Using option files can make it easier to switch between a client/server application and one where MariaDB is embedded. Put common options under the [server]
group. These are read by both MariaDB versions. Client/server-specific options should go under the [mysqld]
section. Put options specific to the embedded MariaDB server library in the [embedded]
section. Options specific to applications go under section labeled [ApplicationName_SERVER]
. See , "Using Option Files".
Embedded Server Examples
These two example programs should work without any changes on a Linux or FreeBSD system. For other operating systems, minor changes are needed, mostly with file paths. These examples are designed to give enough details for you to understand the problem, without the clutter that is a necessary part of a real application. The first example is very straightforward. The second example is a little more advanced with some error checking. The first is followed by a command-line entry for compiling the program. The second is followed by a GNUmake file that may be used for compiling instead.
Example 1
test1_libmysqld.c
#include <stdio.h> #include <stdlib.h> #include <stdarg.h> #include 'mysql.h' MYSQL *mysql; MYSQL_RES *results; MYSQL_ROW record; static char *server_options[] = \ { 'mysql_test', '--defaults-file=my.cnf', NULL }; int num_elements = (sizeof(server_options) / sizeof(char *)) - 1; static char *server_groups[] = { 'libmysqld_server', 'libmysqld_client', NULL }; int main(void) { mysql_library_init(num_elements, server_options, server_groups); mysql = mysql_init(NULL); mysql_options(mysql, MYSQL_READ_DEFAULT_GROUP, 'libmysqld_client'); mysql_options(mysql, MYSQL_OPT_USE_EMBEDDED_CONNECTION, NULL); mysql_real_connect(mysql, NULL,NULL,NULL, 'database1', 0,NULL,0); mysql_query(mysql, 'SELECT column1, column2 FROM table1'); results = mysql_store_result(mysql); while((record = mysql_fetch_row(results))) { printf('%s - %s \n', record[0], record[1]); } mysql_free_result(results); mysql_close(mysql); mysql_library_end(); return 0; }
Here is the command line for compiling the above program:
gcc test1_libmysqld.c -o test1_libmysqld -lz \ `/usr/local/mysql/bin/mysql_config --include --libmysqld-libs`
Example 2
To try the example, create an test2_libmysqld
directory at the same level as the MariaDB source directory. Save the test2_libmysqld.c
source and the GNUmakefile
in the directory, and run GNU make
from inside the test2_libmysqld
directory.
test2_libmysqld.c
/* * A simple example client, using the embedded MariaDB server library */ #include <mysql.h> #include <stdarg.h> #include <stdio.h> #include <stdlib.h> MYSQL *db_connect(const char *dbname); void db_disconnect(MYSQL *db); void db_do_query(MYSQL *db, const char *query); const char *server_groups[] = { 'test2_libmysqld_SERVER', 'embedded', 'server', NULL }; int main(int argc, char **argv) { MYSQL *one, *two; /* mysql_library_init() must be called before any other mysql * functions. * * You can use mysql_library_init(0, NULL, NULL), and it * initializes the server using groups = { * 'server', 'embedded', NULL * }. * * In your $HOME/.my.cnf file, you probably want to put: [test2_libmysqld_SERVER] language = /path/to/source/of/mysql/sql/share/english * You could, of course, modify argc and argv before passing * them to this function. Or you could create new ones in any * way you like. But all of the arguments in argv (except for * argv[0], which is the program name) should be valid options * for the MariaDB server. * * If you link this client against the normal mysqlclient * library, this function is just a stub that does nothing. */ mysql_library_init(argc, argv, (char **)server_groups); one = db_connect('test'); two = db_connect(NULL); db_do_query(one, 'SHOW TABLE STATUS'); db_do_query(two, 'SHOW DATABASES'); mysql_close(two); mysql_close(one); /* This must be called after all other mysql functions */ mysql_library_end(); exit(EXIT_SUCCESS); } static void die(MYSQL *db, char *fmt, ...) { va_list ap; va_start(ap, fmt); vfprintf(stderr, fmt, ap); va_end(ap); (void)putc('\n', stderr); if (db) db_disconnect(db); exit(EXIT_FAILURE); } MYSQL * db_connect(const char *dbname) { MYSQL *db = mysql_init(NULL); if (!db) die(db, 'mysql_init failed: no memory'); /* * Notice that the client and server use separate group names. * This is critical, because the server does not accept the * client's options, and vice versa. */ mysql_options(db, MYSQL_READ_DEFAULT_GROUP, 'test2_libmysqld_CLIENT'); if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0)) die(db, 'mysql_real_connect failed: %s', mysql_error(db)); return db; } void db_disconnect(MYSQL *db) { mysql_close(db); } void db_do_query(MYSQL *db, const char *query) { if (mysql_query(db, query) != 0) goto err; if (mysql_field_count(db) > 0) { MYSQL_RES *res; MYSQL_ROW row, end_row; int num_fields; if (!(res = mysql_store_result(db))) goto err; num_fields = mysql_num_fields(res); while ((row = mysql_fetch_row(res))) { (void)fputs('>> ', stdout); for (end_row = row + num_fields; row < end_row; ++row) (void)printf('%s\t', row ? (char*)*row : 'NULL'); (void)fputc('\n', stdout); } (void)fputc('\n', stdout); mysql_free_result(res); } else (void)printf('Affected rows: %lld\n', mysql_affected_rows(db)); return; err: die(db, 'db_do_query failed: %s [%s]', mysql_error(db), query); }
GNUmakefile
# This assumes the MariaDB software is installed in /usr/local/mysql inc := /usr/local/mysql/include/mysql lib := /usr/local/mysql/lib # If you have not installed the MariaDB software yet, try this instead #inc := $(HOME)/mysql-5.6/include #lib := $(HOME)/mysql-5.6/libmysqld CC := gcc CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT CFLAGS := -g -W -Wall LDFLAGS := -static # You can change -lmysqld to -lmysqlclient to use the # client/server library LDLIBS = -L$(lib) -lmysqld -lz -lm -ldl -lcrypt ifneq (,$(shell grep FreeBSD /COPYRIGHT 2>/dev/null)) # FreeBSD LDFLAGS += -pthread else # Assume Linux LDLIBS += -lpthread endif # This works for simple one-file test programs sources := $(wildcard *.c) objects := $(patsubst %c,%o,$(sources)) targets := $(basename $(sources)) all: $(targets) clean: rm -f $(targets) $(objects) *.core
Licensing the Embedded Server
We encourage everyone to promote free software by releasing code under the GPL or a compatible license. For those who are not able to do this, another option is to purchase a commercial license for the MariaDB code from Oracle Corporation. For details, please see http://www.mysql.com/company/legal/licensing/.
MySQL C API
- C API Data Structures
- C API Function Overview
- C API Function Descriptions
- C API Prepared Statements
- C API Prepared Statement Data Structures
- C API Prepared Statement Function Overview
- C API Prepared Statement Function Descriptions
- C API Threaded Function Descriptions
- C API Embedded Server Function Descriptions
- C API Client Plugin Functions
- Common Questions and Problems When Using the C API
- Controlling Automatic Reconnection Behavior
- C API Support for Multiple Statement Execution
- C API Prepared Statement Problems
- C API Prepared Statement Handling of Date and Time Values
- C API Support for Prepared
CALL
Statements- Building Client Programs
- C API Function Overview
The C API code is distributed with MySQL. It is included in the mysqlclient
library and enables C programs to access a database.
Many of the clients in the MariaDB source distribution are written in C. If you are looking for examples that demonstrate how to use the C API, take a look at these clients. You can find these in the client
directory in the MariaDB source distribution.
Most of the other client APIs (all except Connector/J and Connector/Net) use the mysqlclient
library to communicate with the MariaDB server. This means that, for example, you can take advantage of many of the same environment variables that are used by other client programs, because they are referenced from the library. See , MySQL Programs, for a list of these variables.
The client has a maximum communication buffer size. The size of the buffer that is allocated initially (16KB) is automatically increased up to the maximum size (the maximum is 16MB). Because buffer sizes are increased only as demand warrants, simply increasing the default maximum limit does not in itself cause more resources to be used. This size check is mostly a check for erroneous statements and communication packets.
The communication buffer must be large enough to contain a single SQL statement (for client-to-server traffic) and one row of returned data (for server-to-client traffic). Each thread's communication buffer is dynamically enlarged to handle any query or row up to the maximum limit. For example, if you have BLOB
values that contain up to 16MB of data, you must have a communication buffer limit of at least 16MB (in both server and client). The client's default maximum is 16MB, but the default maximum in the server is 1MB. You can increase this by changing the value of the max_allowed_packet
parameter when the server is started. See , "Tuning Server Parameters".
The MariaDB server shrinks each communication buffer to net_buffer_length
bytes after each query. For clients, the size of the buffer associated with a connection is not decreased until the connection is closed, at which time client memory is reclaimed.
For programming with threads, see , "How to Write a Threaded Client". For creating a standalone application which includes the 'server' and 'client' in the same program (and does not communicate with an external MariaDB server), see , "libmysqld, the Embedded MariaDB Server Library".Note
If, after an upgrade, you experience problems with compiled client programs, such as Commands out of sync
or unexpected core dumps, you probably have used old header or library files when compiling your programs. In this case, check the date for your mysql.h
file and libmysqlclient.a
library to verify that they are from the new MariaDB distribution. If not, recompile your programs with the new headers and libraries. Recompilation might also be necessary for programs compiled against the shared client library if the library major version number has changed (for example from libmysqlclient.so.15
to libmysqlclient.so.16
.
C API Data Structures
This section describes C API data structures other than those used for prepared statements. For information about the latter, see , "C API Prepared Statement Data Structures".
MariaDB
This structure represents a handle to one database connection. It is used for almost all MariaDB functions. Do not try to make a copy of a
MariaDB
structure. There is no guarantee that such a copy will be usable.MYSQL_RES
This structure represents the result of a query that returns rows (
SELECT
,SHOW
,DESCRIBE
,EXPLAIN
). The information returned from a query is called the result set in the remainder of this section.MYSQL_ROW
This is a type-safe representation of one row of data. It is currently implemented as an array of counted byte strings. (You cannot treat these as null-terminated strings if field values may contain binary data, because such values may contain null bytes internally.) Rows are obtained by calling
mysql_fetch_row()
.MYSQL_FIELD
This structure contains metadata: information about a field, such as the field's name, type, and size. Its members are described in more detail later in this section. You may obtain the
MYSQL_FIELD
structures for each field by callingmysql_fetch_field()
repeatedly. Field values are not part of this structure; they are contained in aMYSQL_ROW
structure.MYSQL_FIELD_OFFSET
This is a type-safe representation of an offset into a MariaDB field list. (Used by
mysql_field_seek()
.) Offsets are field numbers within a row, beginning at zero.my_ulonglong
The type used for the number of rows and for
mysql-affected-rows()
,mysql_num_rows()
, andmysql_insert_id()
. This type provides a range of0
to1.84e19
.On some systems, attempting to print a value of type
my_ulonglong
does not work. To print such a value, convert it tounsigned long
and use a%lu
print format. Example:printf ('Number of rows: %lu\n', (unsigned long) mysql_num_rows(result));
my_bool
A boolean type, for values that are true (nonzero) or false (zero).
The MYSQL_FIELD
structure contains the members described in the following list. The definitions apply primarily for columns of result sets such as those produced by SELECT
statements. In MariaDB 5.6, MYSQL_FIELD
structures are also used to provide metadata for OUT
and INOUT
parameters returned from stored procedures executed using prepared CALL
statements. For such parameters, some of the structure members have a meaning different from the meaning for column values.
char * name
The name of the field, as a null-terminated string. If the field was given an alias with an
AS
clause, the value ofname
is the alias. For a procedure parameter, the parameter name.char * org_name
The name of the field, as a null-terminated string. Aliases are ignored. For a procedure parameter, the parameter name.
char * table
The name of the table containing this field, if it isn't a calculated field. For calculated fields, the
table
value is an empty string. If the column is selected from a view,table
names the view. If the table or view was given an alias with anAS
clause, the value oftable
is the alias. For aUNION
, the value is the empty string. For a procedure parameter, the procedure name.char * org_table
The name of the table, as a null-terminated string. Aliases are ignored. If the column is selected from a view,
org_table
names the underlying table. For aUNION
, the value is the empty string. For a procedure parameter, the procedure name.char * db
The name of the database that the field comes from, as a null-terminated string. If the field is a calculated field,
db
is an empty string. For aUNION
, the value is the empty string. For a procedure parameter, the name of the database containing the procedure.char * catalog
The catalog name. This value is always
'def'
.char * def
The default value of this field, as a null-terminated string. This is set only if you use
mysql_list_fields()
.unsigned long length
The width of the field. This corresponds to the display length, in bytes.
The server determines the
length
value before it generates the result set, so this is the minimum length required for a data type capable of holding the largest possible value from the result column, without knowing in advance the actual values that will be produced by the query for the result set.unsigned long max_length
The maximum width of the field for the result set (the length in bytes of the longest field value for the rows actually in the result set). If you use
mysql_store_result()
ormysql_list_fields()
, this contains the maximum length for the field. If you usemysql_use_result()
, the value of this variable is zero.The value of
max_length
is the length of the string representation of the values in the result set. For example, if you retrieve aFLOAT
column and the "widest" value is-12.345
,max_length
is 7 (the length of'-12.345'
).If you are using prepared statements,
max_length
is not set by default because for the binary protocol the lengths of the values depend on the types of the values in the result set. (See , "C API Prepared Statement Data Structures".) If you want themax_length
values anyway, enable theSTMT_ATTR_UPDATE_MAX_LENGTH
option withmysql_stmt_attr_set()
and the lengths will be set when you callmysql-stmt-store-result()
. (See , "mysql_stmt_attr_set()
", and , "mysql_stmt_store_result()
".)unsigned int name_length
The length of
name
.unsigned int org_name_length
The length of
org_name
.unsigned int table_length
The length of
table
.unsigned int org_table_length
The length of
org_table
.unsigned int db_length
The length of
db
.unsigned int catalog_length
The length of
catalog
.unsigned int def_length
The length of
def
.unsigned int flags
Bit-flags that describe the field. The
flags
value may have zero or more of the bits set that are shown in the following table.Flag Value Flag Description NOT_NULL_FLAG
Field can't be NULL
PRI_KEY_FLAG
Field is part of a primary key UNIQUE_KEY_FLAG
Field is part of a unique key MULTIPLE_KEY_FLAG
Field is part of a nonunique key UNSIGNED_FLAG
Field has the UNSIGNED
attributeZEROFILL_FLAG
Field has the ZEROFILL
attributeBINARY_FLAG
Field has the BINARY
attributeAUTO_INCREMENT_FLAG
Field has the AUTO_INCREMENT
attributeENUM_FLAG
Field is an ENUM
(deprecated)SET_FLAG
Field is a SET
(deprecated)BLOB_FLAG
Field is a BLOB
orTEXT
(deprecated)TIMESTAMP_FLAG
Field is a TIMESTAMP
(deprecated)NUM_FLAG
Field is numeric; see additional notes following table NO_DEFAULT_VALUE_FLAG
Field has no default value; see additional notes following table Some of these flags indicate data type information and are superseded by or used in conjunction with the
MYSQL_TYPE_
value in thexxx
field->type
member described later:- To check for
BLOB
orTIMESTAMP
values, check whethertype
isMYSQL_TYPE_BLOB
orMYSQL_TYPE_TIMESTAMP
. (TheBLOB_FLAG
andTIMESTAMP_FLAG
flags are unneeded.) ENUM
andSET
values are returned as strings. For these, check that thetype
value isMYSQL_TYPE_STRING
and that theENUM_FLAG
orSET_FLAG
flag is set in theflags
value.
NUM_FLAG
indicates that a column is numeric. This includes columns with a type ofMYSQL_TYPE_DECIMAL
,MYSQL_TYPE_NEWDECIMAL
,MYSQL_TYPE_TINY
,MYSQL_TYPE_SHORT
,MYSQL_TYPE_LONG
,MYSQL_TYPE_FLOAT
,MYSQL_TYPE_DOUBLE
,MYSQL_TYPE_NULL
,MYSQL_TYPE_LONGLONG
,MYSQL_TYPE_INT24
, andMYSQL_TYPE_YEAR
.NO_DEFAULT_VALUE_FLAG
indicates that a column has noDEFAULT
clause in its definition. This does not apply toNULL
columns (because such columns have a default ofNULL
), or toAUTO_INCREMENT
columns (which have an implied default value).The following example illustrates a typical use of the
flags
value:if (field->flags & NOT_NULL_FLAG) printf('Field can't be null\n');
You may use the convenience macros shown in the following table to determine the boolean status of the
flags
value.Flag Status Description IS_NOT_NULL(flags)
True if this field is defined as NOT NULL
IS_PRI_KEY(flags)
True if this field is a primary key IS_BLOB(flags)
True if this field is a BLOB
orTEXT
(deprecated; testfield->type
instead)- To check for
unsigned int decimals
The number of decimals for numeric fields, and (as of MariaDB 5.6.4) the fractional seconds precision for temporal fields.
unsigned int charsetnr
An ID number that indicates the character set/collation pair for the field.
To distinguish between binary and nonbinary data for string data types, check whether the
charsetnr
value is 63. If so, the character set isbinary
, which indicates binary rather than nonbinary data. This enables you to distinguishBINARY
fromCHAR
,VARBINARY
fromVARCHAR
, and theBLOB
types from theTEXT
types.charsetnr
values are the same as those displayed in theId
column of theSHOW COLLATION
statement or theID
column of theINFORMATION_SCHEMA
COLLATIONS
table. You can use those information sources to see which character set and collation specificcharsetnr
values indicate:mysql>
SHOW COLLATION WHERE Id = 63;
+-----------+---------+----+---------+----------+---------+ | Collation | Charset | Id | Default | Compiled | Sortlen | +-----------+---------+----+---------+----------+---------+ | binary | binary | 63 | Yes | Yes | 1 | +-----------+---------+----+---------+----------+---------+ mysql>SELECT COLLATION_NAME, CHARACTER_SET_NAME
->FROM INFORMATION_SCHEMA.COLLATIONS WHERE ID = 33;
+-----------------+--------------------+ | COLLATION_NAME | CHARACTER_SET_NAME | +-----------------+--------------------+ | utf8_general_ci | utf8 | +-----------------+--------------------+enum enum_field_types type
The type of the field. The
type
value may be one of theMYSQL_TYPE_
symbols shown in the following table.Type Value Type Description MYSQL_TYPE_TINY
TINYINT
fieldMYSQL_TYPE_SHORT
SMALLINT
fieldMYSQL_TYPE_LONG
INTEGER
fieldMYSQL_TYPE_INT24
MEDIUMINT
fieldMYSQL_TYPE_LONGLONG
BIGINT
fieldMYSQL_TYPE_DECIMAL
DECIMAL
orNUMERIC
fieldMYSQL_TYPE_NEWDECIMAL
Precision math DECIMAL
orNUMERIC
MYSQL_TYPE_FLOAT
FLOAT
fieldMYSQL_TYPE_DOUBLE
DOUBLE
orREAL
fieldMYSQL_TYPE_BIT
BIT
fieldMYSQL_TYPE_TIMESTAMP
TIMESTAMP
fieldMYSQL_TYPE_DATE
DATE
fieldMYSQL_TYPE_TIME
TIME
fieldMYSQL_TYPE_DATETIME
DATETIME
fieldMYSQL_TYPE_YEAR
YEAR
fieldMYSQL_TYPE_STRING
CHAR
orBINARY
fieldMYSQL_TYPE_VAR_STRING
VARCHAR
orVARBINARY
fieldMYSQL_TYPE_BLOB
BLOB
orTEXT
field (usemax_length
to determine the maximum length)MYSQL_TYPE_SET
SET
fieldMYSQL_TYPE_ENUM
ENUM
fieldMYSQL_TYPE_GEOMETRY
Spatial field MYSQL_TYPE_NULL
NULL
-type fieldThe
MYSQL_TYPE_TIME2
,MYSQL_TYPE_DATETIME2
, andMYSQL_TYPE_TIMESTAMP2
) type codes are used only on the server side. Clients see theMYSQL_TYPE_TIME
,MYSQL_TYPE_DATETIME
, andMYSQL_TYPE_TIMESTAMP
codes.You can use the
IS_NUM()
macro to test whether a field has a numeric type. Pass thetype
value toIS_NUM()
and it evaluates to TRUE if the field is numeric:if (IS_NUM(field->type)) printf('Field is numeric\n');
ENUM
andSET
values are returned as strings. For these, check that thetype
value isMYSQL_TYPE_STRING
and that theENUM_FLAG
orSET_FLAG
flag is set in theflags
value.
C API Function Overview
The functions available in the C API are summarized here and described in greater detail in a later section. See , "C API Function Descriptions".
Table 20.7. C API Function Names and Descriptions
Function | Description |
---|---|
my_init()
| Initialize global variables, and thread handler in thread-safe programs |
mysql_affected_rows()
| Returns the number of rows changed/deleted/inserted by the last UPDATE , DELETE , or INSERT query
|
mysql_autocommit()
| Toggles autocommit mode on/off |
mysql_change_user()
| Changes user and database on an open connection |
mysql_character_set_name()
| Return default character set name for current connection |
mysql_client_find_plugin()
| Return pointer to plugin |
mysql_client_register_plugin()
| Register a plugin |
mysql_close()
| Closes a server connection |
mysql_commit()
| Commits the transaction |
mysql_connect()
| Connects to a MariaDB server (this function is deprecated; use mysql_real_connect() instead)
|
mysql_create_db()
| Creates a database (this function is deprecated; use the SQL statement CREATE DATABASE instead)
|
mysql_data_seek()
| Seeks to an arbitrary row number in a query result set |
mysql_debug()
| Does a DBUG_PUSH with the given string
|
mysql_drop_db()
| Drops a database (this function is deprecated; use the SQL statement DROP DATABASE instead)
|
mysql_dump_debug_info()
| Makes the server write debug information to the log |
mysql_eof()
| Determines whether the last row of a result set has been read (this function is deprecated; mysql_errno() or mysql_error() may be used instead)
|
mysql_errno()
| Returns the error number for the most recently invoked MariaDB function |
mysql_error()
| Returns the error message for the most recently invoked MariaDB function |
mysql_escape_string()
| Escapes special characters in a string for use in an SQL statement |
mysql_fetch_field()
| Returns the type of the next table field |
mysql_fetch_field_direct()
| Returns the type of a table field, given a field number |
mysql_fetch_fields()
| Returns an array of all field structures |
mysql_fetch_lengths()
| Returns the lengths of all columns in the current row |
mysql_fetch_row()
| Fetches the next row from the result set |
mysql_field_count()
| Returns the number of result columns for the most recent statement |
mysql_field_seek()
| Puts the column cursor on a specified column |
mysql_field_tell()
| Returns the position of the field cursor used for the last mysql_fetch_field()
|
mysql_free_result()
| Frees memory used by a result set |
mysql_get_character_set_info()
| Return information about default character set |
mysql_get_client_info()
| Returns client version information as a string |
mysql_get_client_version()
| Returns client version information as an integer |
mysql_get_host_info()
| Returns a string describing the connection |
mysql_get_proto_info()
| Returns the protocol version used by the connection |
mysql_get_server_info()
| Returns the server version number |
mysql_get_server_version()
| Returns version number of server as an integer |
mysql_get_ssl_cipher()
| Return current SSL cipher |
mysql_hex_string()
| Encode string in hexadecimal format |
mysql_info()
| Returns information about the most recently executed query |
mysql_init()
| Gets or initializes a MariaDB structure
|
mysql_insert_id()
| Returns the ID generated for an AUTO_INCREMENT column by the previous query
|
mysql_kill()
| Kills a given thread |
mysql_library_end()
| Finalize the MariaDB C API library |
mysql_library_init()
| Initialize the MariaDB C API library |
mysql_list_dbs()
| Returns database names matching a simple regular expression |
mysql_list_fields()
| Returns field names matching a simple regular expression |
mysql_list_processes()
| Returns a list of the current server threads |
mysql_list_tables()
| Returns table names matching a simple regular expression |
mysql_load_plugin()
| Load a plugin |
mysql_load_plugin_v()
| Load a plugin |
mysql_more_results()
| Checks whether any more results exist |
mysql_next_result()
| Returns/initiates the next result in multiple-result executions |
mysql_num_fields()
| Returns the number of columns in a result set |
mysql_num_rows()
| Returns the number of rows in a result set |
mysql_options()
| Sets connect options for mysql_real_connect()
|
mysql_ping()
| Checks whether the connection to the server is working, reconnecting as necessary |
mysql_plugin_options()
| Set a plugin option |
mysql_query()
| Executes an SQL query specified as a null-terminated string |
mysql_real_connect()
| Connects to a MariaDB server |
mysql_real_escape_string()
| Escapes special characters in a string for use in an SQL statement, taking into account the current character set of the connection |
mysql_real_query()
| Executes an SQL query specified as a counted string |
mysql_refresh()
| Flush or reset tables and caches |
mysql_reload()
| Tells the server to reload the grant tables |
mysql_rollback()
| Rolls back the transaction |
mysql_row_seek()
| Seeks to a row offset in a result set, using value returned from mysql_row_tell()
|
mysql_row_tell()
| Returns the row cursor position |
mysql_select_db()
| Selects a database |
mysql_server_end()
| Finalize the MariaDB C API library |
mysql_server_init()
| Initialize the MariaDB C API library |
mysql_set_character_set()
| Set default character set for current connection |
mysql_set_local_infile_default()
| Set the LOAD DATA LOCAL INFILE handler callbacks to their default values
|
mysql_set_local_infile_handler()
| Install application-specific LOAD DATA LOCAL INFILE handler callbacks
|
mysql_set_server_option()
| Sets an option for the connection (like multi-statements )
|
mysql_sqlstate()
| Returns the SQLSTATE error code for the last error |
mysql_shutdown()
| Shuts down the database server |
mysql_ssl_set()
| Prepare to establish SSL connection to server |
mysql_stat()
| Returns the server status as a string |
mysql_store_result()
| Retrieves a complete result set to the client |
mysql_thread_end()
| Finalize thread handler |
mysql_thread_id()
| Returns the current thread ID |
mysql_thread_init()
| Initialize thread handler |
mysql_thread_safe()
| Returns 1 if the clients are compiled as thread-safe |
mysql_use_result()
| Initiates a row-by-row result set retrieval |
mysql_warning_count()
| Returns the warning count for the previous SQL statement |
Application programs should use this general outline for interacting with MySQL:
- Initialize the MariaDB library by calling
mysql_library_init()
. This function exists in both themysqlclient
C client library and themysqld
embedded server library, so it is used whether you build a regular client program by linking with the-libmysqlclient
flag, or an embedded server application by linking with the-libmysqld
flag.
- Initialize a connection handler by calling
mysql-init()
and connect to the server by callingmysql_real_connect()
. - Issue SQL statements and process their results. (The following discussion provides more information about how to do this.)
- Close the connection to the MariaDB server by calling
mysql_close()
. - End use of the MariaDB library by calling
mysql_library_end()
.
The purpose of calling mysql-library-init()
and mysql_library_end()
is to provide proper initialization and finalization of the MariaDB library. For applications that are linked with the client library, they provide improved memory management. If you don't call mysql_library_end()
, a block of memory remains allocated. (This does not increase the amount of memory used by the application, but some memory leak detectors will complain about it.) For applications that are linked with the embedded server, these calls start and stop the server.
In a nonmulti-threaded environment, the call to mysql_library_init()
may be omitted, because mysql_init()
will invoke it automatically as necessary. However, mysql_library_init()
is not thread-safe in a multi-threaded environment, and thus neither is mysql_init()
, which calls mysql_library_init()
. You must either call mysql_library_init()
prior to spawning any threads, or else use a mutex to protect the call, whether you invoke mysql_library_init()
or indirectly through mysql_init()
. This should be done prior to any other client library call.
To connect to the server, call mysql-init()
to initialize a connection handler, then call mysql_real_connect()
with that handler (along with other information such as the host name, user name, and password). Upon connection, mysql_real_connect()
sets the reconnect
flag (part of the MariaDB
structure) to a value of 1
in versions of the API older than 5.0.3, or 0
in newer versions. A value of 1
for this flag indicates that if a statement cannot be performed because of a lost connection, to try reconnecting to the server before giving up. You can use the MYSQL_OPT_RECONNECT
option to mysql_options()
to control reconnection behavior. When you are done with the connection, call mysql_close()
to terminate it.
While a connection is active, the client may send SQL statements to the server using mysql_query()
or mysql_real_query()
. The difference between the two is that mysql_query()
expects the query to be specified as a null-terminated string whereas mysql_real_query()
expects a counted string. If the string contains binary data (which may include null bytes), you must use mysql_real_query()
.
For each non-SELECT
query (for example, INSERT
, UPDATE
, DELETE
), you can find out how many rows were changed (affected) by calling mysql_affected_rows()
.
For SELECT
queries, you retrieve the selected rows as a result set. (Note that some statements are SELECT
-like in that they return rows. These include SHOW
, DESCRIBE
, and EXPLAIN
. Treat these statements the same way as SELECT
statements.)
There are two ways for a client to process result sets. One way is to retrieve the entire result set all at once by calling mysql_store_result()
. This function acquires from the server all the rows returned by the query and stores them in the client. The second way is for the client to initiate a row-by-row result set retrieval by calling mysql_use_result()
. This function initializes the retrieval, but does not actually get any rows from the server.
In both cases, you access rows by calling mysql-fetch-row()
. With mysql_store_result()
, mysql_fetch_row()
accesses rows that have previously been fetched from the server. With mysql-use-result()
, mysql_fetch_row()
actually retrieves the row from the server. Information about the size of the data in each row is available by calling mysql_fetch_lengths()
.
After you are done with a result set, call mysql_free_result()
to free the memory used for it.
The two retrieval mechanisms are complementary. Choose the approach that is most appropriate for each client application. In practice, clients tend to use mysql_store_result()
more commonly.
An advantage of mysql_store_result()
is that because the rows have all been fetched to the client, you not only can access rows sequentially, you can move back and forth in the result set using mysql-data-seek()
or mysql_row_seek()
to change the current row position within the result set. You can also find out how many rows there are by calling mysql_num_rows()
. On the other hand, the memory requirements for mysql_store_result()
may be very high for large result sets and you are more likely to encounter out-of-memory conditions.
An advantage of mysql_use_result()
is that the client requires less memory for the result set because it maintains only one row at a time (and because there is less allocation overhead, mysql_use_result()
can be faster). Disadvantages are that you must process each row quickly to avoid tying up the server, you don't have random access to rows within the result set (you can only access rows sequentially), and you don't know how many rows are in the result set until you have retrieved them all. Furthermore, you must retrieve all the rows even if you determine in mid-retrieval that you've found the information you were looking for.
The API makes it possible for clients to respond appropriately to statements (retrieving rows only as necessary) without knowing whether the statement is a SELECT
. You can do this by calling mysql-store-result()
after each mysql_query()
(or mysql_real_query()
). If the result set call succeeds, the statement was a SELECT
and you can read the rows. If the result set call fails, call mysql_field_count()
to determine whether a result was actually to be expected. If mysql_field_count()
returns zero, the statement returned no data (indicating that it was an INSERT
, UPDATE
, DELETE
, and so forth), and was not expected to return rows. If mysql_field_count()
is nonzero, the statement should have returned rows, but didn't. This indicates that the statement was a SELECT
that failed. See the description for mysql_field_count()
for an example of how this can be done.
Both mysql-store-result()
and mysql_use_result()
enable you to obtain information about the fields that make up the result set (the number of fields, their names and types, and so forth). You can access field information sequentially within the row by calling mysql-fetch-field()
repeatedly, or by field number within the row by calling mysql_fetch_field_direct()
. The current field cursor position may be changed by calling mysql_field_seek()
. Setting the field cursor affects subsequent calls to mysql_fetch_field()
. You can also get information for fields all at once by calling mysql_fetch_fields()
.
For detecting and reporting errors, MariaDB provides access to error information by means of the mysql_errno()
and mysql_error()
functions. These return the error code or error message for the most recently invoked function that can succeed or fail, enabling you to determine when an error occurred and what it was.
C API Function Descriptions
mysql_affected_rows()
mysql_autocommit()
mysql_change_user()
mysql_character_set_name()
mysql_close()
mysql_commit()
mysql_connect()
mysql_create_db()
mysql_data_seek()
mysql_debug()
mysql_drop_db()
mysql_dump_debug_info()
mysql_eof()
mysql_errno()
mysql_error()
mysql_escape_string()
mysql_fetch_field()
mysql_fetch_field_direct()
mysql_fetch_fields()
mysql_fetch_lengths()
mysql_fetch_row()
mysql_field_count()
mysql_field_seek()
mysql_field_tell()
mysql_free_result()
mysql_get_character_set_info()
mysql_get_client_info()
mysql_get_client_version()
mysql_get_host_info()
mysql_get_proto_info()
mysql_get_server_info()
mysql_get_server_version()
mysql_get_ssl_cipher()
mysql_hex_string()
mysql_info()
mysql_init()
mysql_insert_id()
mysql_kill()
mysql_library_end()
mysql_library_init()
mysql_list_dbs()
mysql_list_fields()
mysql_list_processes()
mysql_list_tables()
mysql_more_results()
mysql_next_result()
mysql_num_fields()
mysql_num_rows()
mysql_options()
mysql_ping()
mysql_query()
mysql_real_connect()
mysql_real_escape_string()
mysql_real_query()
mysql_refresh()
mysql_reload()
mysql_rollback()
mysql_row_seek()
mysql_row_tell()
mysql_select_db()
mysql_set_character_set()
mysql_set_local_infile_default()
mysql_set_local_infile_handler()
mysql_set_server_option()
mysql_shutdown()
mysql_sqlstate()
mysql_ssl_set()
mysql_stat()
mysql_store_result()
mysql_thread_id()
mysql_use_result()
mysql_warning_count()
In the descriptions here, a parameter or return value of NULL
means NULL
in the sense of the C programming language, not a MariaDB NULL
value.
Functions that return a value generally return a pointer or an integer. Unless specified otherwise, functions returning a pointer return a non-NULL
value to indicate success or a NULL
value to indicate an error, and functions returning an integer return zero to indicate success or nonzero to indicate an error. Note that "nonzero" means just that. Unless the function description says otherwise, do not test against a value other than zero:
if (result) /* correct */ ... error ... if (result < 0) /* incorrect */ ... error ... if (result == -1) /* incorrect */ ... error ...
When a function returns an error, the Errors subsection of the function description lists the possible types of errors. You can find out which of these occurred by calling mysql_errno()
. A string representation of the error may be obtained by calling mysql_error()
.
mysql_affected_rows()
my_ulonglong mysql_affected_rows(MYSQL *mysql)
Description
mysql-affected-rows()
may be called immediately after executing a statement with mysql_query()
or mysql_real_query()
. It returns the number of rows changed, deleted, or inserted by the last statement if it was an UPDATE
, DELETE
, or INSERT
. For SELECT
statements, mysql-affected-rows()
works like mysql_num_rows()
.
For UPDATE
statements, the affected-rows value by default is the number of rows actually changed. If you specify the CLIENT_FOUND_ROWS
flag to mysql-real-connect()
when connecting to mysqld, the affected-rows value is the number of rows "found"; that is, matched by the WHERE
clause.
For REPLACE
statements, the affected-rows value is 2 if the new row replaced an old row, because in this case, one row was inserted after the duplicate was deleted.
For INSERT ... ON DUPLICATE KEY UPDATE
statements, the affected-rows value is 1 if the row is inserted as a new row and 2 if an existing row is updated.
Following a CALL
statement for a stored procedure, mysql_affected_rows()
returns the value that it would return for the last statement executed within the procedure, or 0
if that statement would return -1
. Within the procedure, you can use ROW_COUNT()
at the SQL level to obtain the affected-rows value for individual statements.
In MariaDB 5.6, mysql_affected_rows()
returns a meaningful value for a wider range of statements. For details, see the description for ROW-COUNT()
in , "Information Functions".
Return Values
An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records were updated for an UPDATE
statement, no rows matched the WHERE
clause in the query or that no query has yet been executed. -1 indicates that the query returned an error or that, for a SELECT
query, mysql_affected_rows()
was called prior to calling mysql_store_result()
.
Because mysql_affected_rows()
returns an unsigned value, you can check for -1 by comparing the return value to (my_ulonglong)-1
(or to (my_ulonglong)~0
, which is equivalent).
Errors
None.
Example
char *stmt = 'UPDATE products SET cost=cost*1.25 WHERE group=10'; mysql_query(&mysql,stmt); printf('%ld products updated', (long) mysql_affected_rows(&mysql));
mysql_autocommit()
my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)
Description
Sets autocommit mode on if mode
is 1, off if mode
is 0.
Return Values
Zero if successful. Nonzero if an error occurred.
Errors
None.
mysql_change_user()
my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password, const char *db)
Description
Changes the user and causes the database specified by db
to become the default (current) database on the connection specified by MariaDB
. In subsequent queries, this database is the default for table references that do not include an explicit database specifier.
mysql_change_user()
fails if the connected user cannot be authenticated or doesn't have permission to use the database. In this case, the user and database are not changed.
The db
parameter may be set to NULL
if you don't want to have a default database.
This command resets the state as if one had done a new connect. (See , "Controlling Automatic Reconnection Behavior".) It always performs a ROLLBACK
of any active transactions, closes and drops all temporary tables, and unlocks all locked tables. Session system variables are reset to the values of the corresponding global system variables. Prepared statements are released and HANDLER
variables are closed. Locks acquired with GET_LOCK()
are released. These effects occur even if the user didn't change.
Return Values
Zero for success. Nonzero if an error occurred.
Errors
The same that you can get from mysql_real_connect()
.
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
ER_UNKNOWN_COM_ERROR
The MariaDB server doesn't implement this command (probably an old server).
ER_ACCESS_DENIED_ERROR
The user or password was wrong.
ER_BAD_DB_ERROR
The database didn't exist.
ER_DBACCESS_DENIED_ERROR
The user did not have access rights to the database.
ER_WRONG_DB_NAME
The database name was too long.
Example
if (mysql_change_user(&mysql, 'user', 'password', 'new_database')) { fprintf(stderr, 'Failed to change user. Error: %s\n', mysql_error(&mysql)); }
mysql_character_set_name()
const char *mysql_character_set_name(MYSQL *mysql)
Description
Returns the default character set name for the current connection.
Return Values
The default character set name
Errors
None.
mysql_close()
void mysql_close(MYSQL *mysql)
Description
Closes a previously opened connection. mysql_close()
also deallocates the connection handle pointed to by MariaDB
if the handle was allocated automatically by mysql-init()
or mysql_connect()
.
Return Values
None.
Errors
None.
mysql_commit()
my_bool mysql_commit(MYSQL *mysql)
Description
Commits the current transaction.
The action of this function is subject to the value of the completion_type
system variable. In particular, if the value of completion_type
is RELEASE
(or 2), the server performs a release after terminating a transaction and closes the client connection. Call mysql_close()
from the client program to close the connection from the client side.
Return Values
Zero if successful. Nonzero if an error occurred.
Errors
None.
mysql_connect()
MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)
Description
This function is deprecated. Use mysql_real_connect()
instead.
mysql_connect()
attempts to establish a connection to a MariaDB database engine running on host
. mysql_connect()
must complete successfully before you can execute any of the other API functions, with the exception of mysql_get_client_info()
.
The meanings of the parameters are the same as for the corresponding parameters for mysql_real_connect()
with the difference that the connection parameter may be NULL
. In this case, the C API allocates memory for the connection structure automatically and frees it when you call mysql_close()
. The disadvantage of this approach is that you can't retrieve an error message if the connection fails. (To get error information from mysql_errno()
or mysql_error()
, you must provide a valid MariaDB
pointer.)
Return Values
Same as for mysql_real_connect()
.
Errors
Same as for mysql_real_connect()
.
mysql_create_db()
int mysql_create_db(MYSQL *mysql, const char *db)
Description
Creates the database named by the db
parameter.
This function is deprecated. It is preferable to use mysql-query()
to issue an SQL CREATE DATABASE
statement instead.
Return Values
Zero if the database was created successfully. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
Example
if(mysql_create_db(&mysql, 'my_database')) { fprintf(stderr, 'Failed to create new database. Error: %s\n', mysql_error(&mysql)); }
mysql_data_seek()
void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)
Description
Seeks to an arbitrary row in a query result set. The offset
value is a row number. Specify a value in the range from 0
to mysql_num_rows(result)-1
.
This function requires that the result set structure contains the entire result of the query, so mysql_data_seek()
may be used only in conjunction with mysql-store-result()
, not with mysql_use_result()
.
Return Values
None.
Errors
None.
mysql_debug()
void mysql_debug(const char *debug)
Description
Does a DBUG_PUSH
with the given string. mysql_debug()
uses the Fred Fish debug library. To use this function, you must compile the client library to support debugging. See MySQL Internals: Porting.
Return Values
None.
Errors
None.
Example
The call shown here causes the client library to generate a trace file in /tmp/client.trace
on the client machine:
mysql_debug('d:t:O,/tmp/client.trace');
mysql_drop_db()
int mysql_drop_db(MYSQL *mysql, const char *db)
Description
Drops the database named by the db
parameter.
This function is deprecated. It is preferable to use mysql-query()
to issue an SQL DROP DATABASE
statement instead.
Return Values
Zero if the database was dropped successfully. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
Example
if(mysql_drop_db(&mysql, 'my_database')) fprintf(stderr, 'Failed to drop the database: Error: %s\n', mysql_error(&mysql));
mysql_dump_debug_info()
int mysql_dump_debug_info(MYSQL *mysql)
Description
Instructs the server to write some debug information to the log. For this to work, the connected user must have the SUPER
privilege.
Return Values
Zero if the command was successful. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_eof()
my_bool mysql_eof(MYSQL_RES *result)
Description
This function is deprecated. mysql-errno()
or mysql_error()
may be used instead.
mysql_eof()
determines whether the last row of a result set has been read.
If you acquire a result set from a successful call to mysql_store_result()
, the client receives the entire set in one operation. In this case, a NULL
return from mysql_fetch_row()
always means the end of the result set has been reached and it is unnecessary to call mysql-eof()
. When used with mysql_store_result()
, mysql_eof()
always returns true.
On the other hand, if you use mysql_use_result()
to initiate a result set retrieval, the rows of the set are obtained from the server one by one as you call mysql_fetch_row()
repeatedly. Because an error may occur on the connection during this process, a NULL
return value from mysql_fetch_row()
does not necessarily mean the end of the result set was reached normally. In this case, you can use mysql-eof()
to determine what happened. mysql_eof()
returns a nonzero value if the end of the result set was reached and zero if an error occurred.
Historically, mysql-eof()
predates the standard MariaDB error functions mysql_errno()
and mysql_error()
. Because those error functions provide the same information, their use is preferred over mysql_eof()
, which is deprecated. (In fact, they provide more information, because mysql_eof()
returns only a boolean value whereas the error functions indicate a reason for the error when one occurs.)
Return Values
Zero if no error occurred. Nonzero if the end of the result set has been reached.
Errors
None.
Example
The following example shows how you might use mysql_eof()
:
mysql_query(&mysql,'SELECT * FROM some_table'); result = mysql_use_result(&mysql); while((row = mysql_fetch_row(result))) { // do something with data } if(!mysql_eof(result)) // mysql_fetch_row() failed due to an error { fprintf(stderr, 'Error: %s\n', mysql_error(&mysql)); }
However, you can achieve the same effect with the standard MariaDB error functions:
mysql_query(&mysql,'SELECT * FROM some_table'); result = mysql_use_result(&mysql); while((row = mysql_fetch_row(result))) { // do something with data } if(mysql_errno(&mysql)) // mysql_fetch_row() failed due to an error { fprintf(stderr, 'Error: %s\n', mysql_error(&mysql)); }
mysql_errno()
unsigned int mysql_errno(MYSQL *mysql)
Description
For the connection specified by MariaDB
, mysql_errno()
returns the error code for the most recently invoked API function that can succeed or fail. A return value of zero means that no error occurred. Client error message numbers are listed in the MariaDB errmsg.h
header file. Server error message numbers are listed in mysqld_error.h
. Errors also are listed at Appendix C, Errors, Error Codes, and Common Problems.
Note that some functions like mysql-fetch-row()
don't set mysql_errno()
if they succeed.
A rule of thumb is that all functions that have to ask the server for information reset mysql_errno()
if they succeed.
MySQL-specific error numbers returned by mysql-errno()
differ from SQLSTATE values returned by mysql_sqlstate()
. For example, the mysql client program displays errors using the following format, where 1146
is the mysql_errno()
value and '42S02'
is the corresponding mysql_sqlstate()
value:
shell> SELECT * FROM no_such_table;
ERROR 1146 (42S02): Table 'test.no_such_table' doesn't exist
Return Values
An error code value for the last mysql_
call, if it failed. zero means no error occurred.
xxx
()
Errors
None.
mysql_error()
const char *mysql_error(MYSQL *mysql)
Description
For the connection specified by MariaDB
, mysql_error()
returns a null-terminated string containing the error message for the most recently invoked API function that failed. If a function didn't fail, the return value of mysql_error()
may be the previous error or an empty string to indicate no error.
A rule of thumb is that all functions that have to ask the server for information reset mysql_error()
if they succeed.
For functions that reset mysql_error()
, the following two tests are equivalent:
if(*mysql_error(&mysql)) { // an error occurred } if(mysql_error(&mysql)[0]) { // an error occurred }
The language of the client error messages may be changed by recompiling the MariaDB client library. Currently, you can choose error messages in several different languages. See , "Setting the Error Message Language".
Return Values
A null-terminated character string that describes the error. An empty string if no error occurred.
Errors
None.
mysql_escape_string()
Use mysql_real_escape_string()
instead!
This function is identical to mysql_real_escape_string()
except that mysql_real_escape_string()
takes a connection handler as its first argument and escapes the string according to the current character set. mysql_escape_string()
does not take a connection argument and does not respect the current character set.
mysql_fetch_field()
MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)
Description
Returns the definition of one column of a result set as a MYSQL_FIELD
structure. Call this function repeatedly to retrieve information about all columns in the result set. mysql_fetch_field()
returns NULL
when no more fields are left.
mysql_fetch_field()
is reset to return information about the first field each time you execute a new SELECT
query. The field returned by mysql_fetch_field()
is also affected by calls to mysql_field_seek()
.
If you've called mysql-query()
to perform a SELECT
on a table but have not called mysql_store_result()
, MariaDB returns the default blob length (8KB) if you call mysql-fetch-field()
to ask for the length of a BLOB
field. (The 8KB size is chosen because MariaDB doesn't know the maximum length for the BLOB
. This should be made configurable sometime.) Once you've retrieved the result set, field->max_length
contains the length of the largest value for this column in the specific query.
Return Values
The MYSQL_FIELD
structure for the current column. NULL
if no columns are left.
Errors
None.
Example
MYSQL_FIELD *field; while((field = mysql_fetch_field(result))) { printf('field name %s\n', field->name); }
mysql_fetch_field_direct()
MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)
Description
Given a field number fieldnr
for a column within a result set, returns that column's field definition as a MYSQL_FIELD
structure. Use this function to retrieve the definition for an arbitrary column. Specify a value for fieldnr
in the range from 0 to mysql_num_fields(result)-1
.
Return Values
The MYSQL_FIELD
structure for the specified column.
Errors
None.
Example
unsigned int num_fields; unsigned int i; MYSQL_FIELD *field; num_fields = mysql_num_fields(result); for(i = 0; i < num_fields; i++) { field = mysql_fetch_field_direct(result, i); printf('Field %u is %s\n', i, field->name); }
mysql_fetch_fields()
MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)
Description
Returns an array of all MYSQL_FIELD
structures for a result set. Each structure provides the field definition for one column of the result set.
Return Values
An array of MYSQL_FIELD
structures for all columns of a result set.
Errors
None.
Example
unsigned int num_fields; unsigned int i; MYSQL_FIELD *fields; num_fields = mysql_num_fields(result); fields = mysql_fetch_fields(result); for(i = 0; i < num_fields; i++) { printf('Field %u is %s\n', i, fields[i].name); }
mysql_fetch_lengths()
unsigned long *mysql_fetch_lengths(MYSQL_RES *result)
Description
Returns the lengths of the columns of the current row within a result set. If you plan to copy field values, this length information is also useful for optimization, because you can avoid calling strlen()
. In addition, if the result set contains binary data, you must use this function to determine the size of the data, because strlen()
returns incorrect results for any field containing null characters.
The length for empty columns and for columns containing NULL
values is zero. To see how to distinguish these two cases, see the description for mysql_fetch_row()
.
Return Values
An array of unsigned long integers representing the size of each column (not including any terminating null characters). NULL
if an error occurred.
Errors
mysql_fetch_lengths()
is valid only for the current row of the result set. It returns NULL
if you call it before calling mysql_fetch_row()
or after retrieving all rows in the result.
Example
MYSQL_ROW row; unsigned long *lengths; unsigned int num_fields; unsigned int i; row = mysql_fetch_row(result); if (row) { num_fields = mysql_num_fields(result); lengths = mysql_fetch_lengths(result); for(i = 0; i < num_fields; i++) { printf('Column %u is %lu bytes in length.\n', i, lengths[i]); } }
mysql_fetch_row()
MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)
Description
Retrieves the next row of a result set. When used after mysql-store-result()
, mysql_fetch_row()
returns NULL
when there are no more rows to retrieve. When used after mysql_use_result()
, mysql_fetch_row()
returns NULL
when there are no more rows to retrieve or if an error occurred.
The number of values in the row is given by mysql_num_fields(result)
. If row
holds the return value from a call to mysql_fetch_row()
, pointers to the values are accessed as row[0]
to row[mysql_num_fields(result)-1]
. NULL
values in the row are indicated by NULL
pointers.
The lengths of the field values in the row may be obtained by calling mysql_fetch_lengths()
. Empty fields and fields containing NULL
both have length 0; you can distinguish these by checking the pointer for the field value. If the pointer is NULL
, the field is NULL
; otherwise, the field is empty.
Return Values
A MYSQL_ROW
structure for the next row. NULL
if there are no more rows to retrieve or if an error occurred.
Errors
Note that error is not reset between calls to mysql_fetch_row()
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
Example
MYSQL_ROW row; unsigned int num_fields; unsigned int i; num_fields = mysql_num_fields(result); while ((row = mysql_fetch_row(result))) { unsigned long *lengths; lengths = mysql_fetch_lengths(result); for(i = 0; i < num_fields; i++) { printf('[%.*s] ', (int) lengths[i], row[i] ? row[i] : 'NULL'); } printf('\n'); }
mysql_field_count()
unsigned int mysql_field_count(MYSQL *mysql)
Description
Returns the number of columns for the most recent query on the connection.
The normal use of this function is when mysql_store_result()
returned NULL
(and thus you have no result set pointer). In this case, you can call mysql_field_count()
to determine whether mysql_store_result()
should have produced a nonempty result. This enables the client program to take proper action without knowing whether the query was a SELECT
(or SELECT
-like) statement. The example shown here illustrates how this may be done.
See , "Why mysql_store_result()
Sometimes Returns NULL
After mysql_query()
Returns Success".
Return Values
An unsigned integer representing the number of columns in a result set.
Errors
None.
Example
MYSQL_RES *result; unsigned int num_fields; unsigned int num_rows; if (mysql_query(&mysql,query_string)) { // error } else // query succeeded, process any data returned by it { result = mysql_store_result(&mysql); if (result) // there are rows { num_fields = mysql_num_fields(result); // retrieve rows, then call mysql_free_result(result) } else // mysql_store_result() returned nothing; should it have? { if(mysql_field_count(&mysql) == 0) { // query does not return data // (it was not a SELECT) num_rows = mysql_affected_rows(&mysql); } else // mysql_store_result() should have returned data { fprintf(stderr, 'Error: %s\n', mysql_error(&mysql)); } } }
An alternative is to replace the mysql-field-count(&mysql)
call with mysql_errno(&mysql)
. In this case, you are checking directly for an error from mysql_store_result()
rather than inferring from the value of mysql_field_count()
whether the statement was a SELECT
.
mysql_field_seek()
MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)
Description
Sets the field cursor to the given offset. The next call to mysql_fetch_field()
retrieves the field definition of the column associated with that offset.
To seek to the beginning of a row, pass an offset
value of zero.
Return Values
The previous value of the field cursor.
Errors
None.
mysql_field_tell()
MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)
Description
Returns the position of the field cursor used for the last mysql_fetch_field()
. This value can be used as an argument to mysql_field_seek()
.
Return Values
The current offset of the field cursor.
Errors
None.
mysql_free_result()
void mysql_free_result(MYSQL_RES *result)
Description
Frees the memory allocated for a result set by mysql-store-result()
, mysql_use_result()
, mysql_list_dbs()
, and so forth. When you are done with a result set, you must free the memory it uses by calling mysql_free_result()
.
Do not attempt to access a result set after freeing it.
Return Values
None.
Errors
None.
mysql_get_character_set_info()
void mysql_get_character_set_info(MYSQL *mysql, MY_CHARSET_INFO *cs)
Description
This function provides information about the default client character set. The default character set may be changed with the mysql_set_character_set()
function.
Example
This example shows the fields that are available in the MY_CHARSET_INFO
structure:
if (!mysql_set_character_set(&mysql, 'utf8')) { MY_CHARSET_INFO cs; mysql_get_character_set_info(&mysql, &cs); printf('character set information:\n'); printf('character set+collation number: %d\n', cs.number); printf('character set name: %s\n', cs.name); printf('collation name: %s\n', cs.csname); printf('comment: %s\n', cs.comment); printf('directory: %s\n', cs.dir); printf('multi byte character min. length: %d\n', cs.mbminlen); printf('multi byte character max. length: %d\n', cs.mbmaxlen); }
mysql_get_client_info()
const char *mysql_get_client_info(void)
Description
Returns a string that represents the client library version.
Return Values
A character string that represents the MariaDB client library version.
Errors
None.
mysql_get_client_version()
unsigned long mysql_get_client_version(void)
Description
Returns an integer that represents the client library version. The value has the format XYYZZ
where X
is the major version, YY
is the release level, and ZZ
is the version number within the release level. For example, a value of 40102
represents a client library version of 4.1.2
.
Return Values
An integer that represents the MariaDB client library version.
Errors
None.
mysql_get_host_info()
const char *mysql_get_host_info(MYSQL *mysql)
Description
Returns a string describing the type of connection in use, including the server host name.
Return Values
A character string representing the server host name and the connection type.
Errors
None.
mysql_get_proto_info()
unsigned int mysql_get_proto_info(MYSQL *mysql)
Description
Returns the protocol version used by current connection.
Return Values
An unsigned integer representing the protocol version used by the current connection.
Errors
None.
mysql_get_server_info()
const char *mysql_get_server_info(MYSQL *mysql)
Description
Returns a string that represents the server version number.
Return Values
A character string that represents the server version number.
Errors
None.
mysql_get_server_version()
unsigned long mysql_get_server_version(MYSQL *mysql)
Description
Returns the version number of the server as an integer.
Return Values
A number that represents the MariaDB server version in this format:
major_version*10000 + minor_version *100 + sub_version
For example, 5.1.5 is returned as 50105.
This function is useful in client programs for quickly determining whether some version-specific server capability exists.
Errors
None.
mysql_get_ssl_cipher()
const char *mysql_get_ssl_cipher(MYSQL *mysql)
Description
mysql_get_ssl_cipher()
returns the SSL cipher used for the given connection to the server. MariaDB
is the connection handler returned from mysql_init()
.
Return Values
A string naming the SSL cipher used for the connection, or NULL
if no cipher is being used.
mysql_hex_string()
unsigned long mysql_hex_string(char *to, const char *from, unsigned long length)
Description
This function is used to create a legal SQL string that you can use in an SQL statement. See , "String Literals".
The string in from
is encoded to hexadecimal format, with each character encoded as two hexadecimal digits. The result is placed in to
and a terminating null byte is appended.
The string pointed to by from
must be length
bytes long. You must allocate the to
buffer to be at least length*2+1
bytes long. When mysql_hex_string()
returns, the contents of to
is a null-terminated string. The return value is the length of the encoded string, not including the terminating null character.
The return value can be placed into an SQL statement using either 0x
or value
X'
format. However, the return value does not include the value
'0x
or X'...'
. The caller must supply whichever of those is desired.
Example
char query[1000],*end; end = strmov(query,'INSERT INTO test_table values('); end = strmov(end,'0x'); end += mysql_hex_string(end,'What is this',12); end = strmov(end,',0x'); end += mysql_hex_string(end,'binary data: \0\r\n',16); *end++ = ')'; if (mysql_real_query(&mysql,query,(unsigned int) (end - query))) { fprintf(stderr, 'Failed to insert row, Error: %s\n', mysql_error(&mysql)); }
The strmov()
function used in the example is included in the mysqlclient
library and works like strcpy()
but returns a pointer to the terminating null of the first parameter.
Return Values
The length of the value placed into to
, not including the terminating null character.
Errors
None.
mysql_info()
const char *mysql_info(MYSQL *mysql)
Description
Retrieves a string providing information about the most recently executed statement, but only for the statements listed here. For other statements, mysql_info()
returns NULL
. The format of the string varies depending on the type of statement, as described here. The numbers are illustrative only; the string contains values appropriate for the statement.
INSERT INTO ... SELECT ...
String format:
Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO ... VALUES (...),(...),(...)...
String format:
Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ...
String format:
Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE
String format:
Records: 3 Duplicates: 0 Warnings: 0
UPDATE
String format:
Rows matched: 40 Changed: 40 Warnings: 0
Note that mysql-info()
returns a non-NULL
value for INSERT ... VALUES
only for the multiple-row form of the statement (that is, only if multiple value lists are specified).
Return Values
A character string representing additional information about the most recently executed statement. NULL
if no information is available for the statement.
Errors
None.
mysql_init()
MYSQL *mysql_init(MYSQL *mysql)
Description
Allocates or initializes a MariaDB
object suitable for mysql_real_connect()
. If MariaDB
is a NULL
pointer, the function allocates, initializes, and returns a new object. Otherwise, the object is initialized and the address of the object is returned. If mysql_init()
allocates a new object, it is freed when mysql_close()
is called to close the connection.
Return Values
An initialized MYSQL*
handle. NULL
if there was insufficient memory to allocate a new object.
Errors
In case of insufficient memory, NULL
is returned.
mysql_insert_id()
my_ulonglong mysql_insert_id(MYSQL *mysql)
Description
Returns the value generated for an AUTO_INCREMENT
column by the previous INSERT
or UPDATE
statement. Use this function after you have performed an INSERT
statement into a table that contains an AUTO_INCREMENT
field, or have used INSERT
or UPDATE
to set a column value with LAST_INSERT_ID(
.
expr
)
The return value of mysql_insert_id()
is always zero unless explicitly updated under one of the following conditions:
INSERT
statements that store a value into anAUTO_INCREMENT
column. This is true whether the value is automatically generated by storing the special valuesNULL
or0
into the column, or is an explicit nonspecial value.- In the case of a multiple-row
INSERT
statement, the return value ofmysql_insert_id()
depends on the MariaDB server version.mysql_insert_id()
returns the first automatically generatedAUTO_INCREMENT
value that was successfully inserted.If no rows are successfully inserted,
mysql_insert_id()
returns 0. - If an
INSERT ... SELECT
statement is executed, and no automatically generated value is successfully inserted,mysql_insert_id()
returns the ID of the last inserted row. - If an
INSERT ... SELECT
statement usesLAST_INSERT_ID(
,expr
)mysql_insert_id()
returnsexpr
. INSERT
statements that generate anAUTO_INCREMENT
value by insertingLAST_INSERT_ID(
into any column or by updating any column toexpr
)LAST_INSERT_ID(
.expr
)- If the previous statement returned an error, the value of
mysql_insert_id()
is undefined.
The return value of mysql_insert_id()
can be simplified to the following sequence:
- If there is an
AUTO_INCREMENT
column, and an automatically generated value was successfully inserted, return the first such value. - If
LAST_INSERT_ID(
occurred in the statement, returnexpr
)expr
, even if there was anAUTO_INCREMENT
column in the affected table. - The return value varies depending on the statement used. When called after an
INSERT
statement:- If there is an
AUTO_INCREMENT
column in the table, and there were some explicit values for this column that were successfully inserted into the table, return the last of the explicit values.
When called after an
INSERT ... ON DUPLICATE KEY UPDATE
statement:- If there is an
AUTO_INCREMENT
column in the table and there were some explicit successfully inserted values, or some updated rows, return the last of the inserted or updated values.
- If there is an
mysql_insert_id()
returns 0
if the previous statement does not use an AUTO_INCREMENT
value. If you need to save the value for later, be sure to call mysql_insert_id()
immediately after the statement that generates the value.
The value of mysql_insert_id()
is affected only by statements issued within the current client connection. It is not affected by statements issued by other clients.
The LAST_INSERT_ID()
SQL function will contain the value of the first automatically generated value that was successfully inserted. LAST_INSERT_ID()
is not reset between statements because the value of that function is maintained in the server. Another difference from mysql_insert_id()
is that LAST_INSERT_ID()
is not updated if you set an AUTO_INCREMENT
column to a specific nonspecial value. See , "Information Functions".
mysql-insert-id()
returns 0
following a CALL
statement for a stored procedure that generates an AUTO_INCREMENT
value because in this case mysql_insert_id()
applies to CALL
and not the statement within the procedure. Within the procedure, you can use LAST_INSERT_ID()
at the SQL level to obtain the AUTO_INCREMENT
value.
The reason for the differences between LAST-INSERT-ID()
and mysql_insert_id()
is that LAST-INSERT-ID()
is made easy to use in scripts while mysql_insert_id()
tries to provide more exact information about what happens to the AUTO_INCREMENT
column.
Return Values
Described in the preceding discussion.
Errors
None.
mysql_kill()
int mysql_kill(MYSQL *mysql, unsigned long pid)
Description
Asks the server to kill the thread specified by pid
.
This function is deprecated. It is preferable to use mysql-query()
to issue an SQL KILL
statement instead.
Return Values
Zero for success. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_library_end()
void mysql_library_end(void)
Description
This function finalizes the MariaDB library. Call it when you are done using the library (for example, after disconnecting from the server). The action taken by the call depends on whether your application is linked to the MariaDB client library or the MariaDB embedded server library. For a client program linked against the libmysqlclient
library by using the -lmysqlclient
flag, mysql_library_end()
performs some memory management to clean up. For an embedded server application linked against the libmysqld
library by using the -lmysqld
flag, mysql_library_end()
shuts down the embedded server and then cleans up.
For usage information, see , "C API Function Overview", and , "mysql_library_init()
".
mysql_library_init()
int mysql_library_init(int argc, char **argv, char **groups)
Description
Call this function to initialize the MariaDB library before you call any other MariaDB function, whether your application is a regular client program or uses the embedded server. If the application uses the embedded server, this call starts the server and initializes any subsystems (mysys
, InnoDB
, and so forth) that the server uses.
After your application is done using the MariaDB library, call mysql_library_end()
to clean up. See , "mysql_library_end()
".
The choice of whether the application operates as a regular client or uses the embedded server depends on whether you use the libmysqlclient
or libmysqld
library at link time to produce the final executable. For additional information, see , "C API Function Overview".
In a nonmulti-threaded environment, the call to mysql_library_init()
may be omitted, because mysql_init()
will invoke it automatically as necessary. However, mysql_library_init()
is not thread-safe in a multi-threaded environment, and thus neither is mysql_init()
, which calls mysql_library_init()
. You must either call mysql_library_init()
prior to spawning any threads, or else use a mutex to protect the call, whether you invoke mysql_library_init()
or indirectly through mysql_init()
. Do this prior to any other client library call.
The argc
and argv
arguments are analogous to the arguments to main()
, and enable passing of options to the embedded server. For convenience, argc
may be 0
(zero) if there are no command-line arguments for the server. This is the usual case for applications intended for use only as regular (nonembedded) clients, and the call typically is written as mysql_library_init(0, NULL, NULL)
.
#include <mysql.h> #include <stdlib.h> int main(void) { if (mysql_library_init(0, NULL, NULL)) { fprintf(stderr, 'could not initialize MariaDB library\n'); exit(1); } /* Use any MariaDB API functions here */ mysql_library_end(); return EXIT_SUCCESS; }
When arguments are to be passed (argc
is greater than 0
), the first element of argv
is ignored (it typically contains the program name). mysql_library_init()
makes a copy of the arguments so it is safe to destroy argv
or groups
after the call.
For embedded applications, if you want to connect to an external server without starting the embedded server, you have to specify a negative value for argc
.
The groups
argument is an array of strings that indicate the groups in option files from which to read options. See , "Using Option Files". Make the final entry in the array NULL
. For convenience, if the groups
argument itself is NULL
, the [server]
and [embedded]
groups are used by default.
#include <mysql.h> #include <stdlib.h> static char *server_args[] = { 'this_program', /* this string is not used */ '--datadir=.', '--key_buffer_size=32M' }; static char *server_groups[] = { 'embedded', 'server', 'this_program_SERVER', (char *)NULL }; int main(void) { if (mysql_library_init(sizeof(server_args) / sizeof(char *), server_args, server_groups)) { fprintf(stderr, 'could not initialize MariaDB library\n'); exit(1); } /* Use any MariaDB API functions here */ mysql_library_end(); return EXIT_SUCCESS; }
Return Values
Zero if successful. Nonzero if an error occurred.
mysql_list_dbs()
MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)
Description
Returns a result set consisting of database names on the server that match the simple regular expression specified by the wild
parameter. wild
may contain the wildcard characters "%
" or "_
", or may be a NULL
pointer to match all databases. Calling mysql_list_dbs()
is similar to executing the query SHOW DATABASES [LIKE
.
wild
]
You must free the result set with mysql_free_result()
.
Return Values
A MYSQL_RES
result set for success. NULL
if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_OUT_OF_MEMORY
Out of memory.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_list_fields()
MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)
Description
Returns a result set consisting of field names in the given table that match the simple regular expression specified by the wild
parameter. wild
may contain the wildcard characters "%
" or "_
", or may be a NULL
pointer to match all fields. Calling mysql_list_fields()
is similar to executing the query SHOW COLUMNS FROM
.
tbl_name
[LIKE wild
]
It is preferable to use SHOW COLUMNS FROM
instead of tbl_name
mysql_list_fields()
.
You must free the result set with mysql_free_result()
.
Return Values
A MYSQL_RES
result set for success. NULL
if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_list_processes()
MYSQL_RES *mysql_list_processes(MYSQL *mysql)
Description
Returns a result set describing the current server threads. This is the same kind of information as that reported by mysqladmin processlist or a SHOW PROCESSLIST
query.
You must free the result set with mysql_free_result()
.
Return Values
A MYSQL_RES
result set for success. NULL
if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_list_tables()
MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)
Description
Returns a result set consisting of table names in the current database that match the simple regular expression specified by the wild
parameter. wild
may contain the wildcard characters "%
" or "_
", or may be a NULL
pointer to match all tables. Calling mysql_list_tables()
is similar to executing the query SHOW TABLES [LIKE
.
wild
]
You must free the result set with mysql_free_result()
.
Return Values
A MYSQL_RES
result set for success. NULL
if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_more_results()
my_bool mysql_more_results(MYSQL *mysql)
Description
This function is used when you execute multiple statements specified as a single statement string, or when you execute CALL
statements, which can return multiple result sets.
mysql_more_results()
true if more results exist from the currently executed statement, in which case the application must call mysql_next_result()
to fetch the results.
Return Values
TRUE
(1) if more results exist. FALSE
(0) if no more results exist.
In most cases, you can call mysql_next_result()
instead to test whether more results exist and initiate retrieval if so.
See , "C API Support for Multiple Statement Execution", and , "mysql_next_result()
".
Errors
None.
mysql_next_result()
int mysql_next_result(MYSQL *mysql)
Description
This function is used when you execute multiple statements specified as a single statement string, or when you use CALL
statements to execute stored procedures, which can return multiple result sets.
mysql_next_result()
reads the next statement result and returns a status to indicate whether more results exist. If mysql_next_result()
returns an error, there are no more results.
Before each call to mysql-next-result()
, you must call mysql_free_result()
for the current statement if it is a statement that returned a result set (rather than just a result status).
After calling mysql_next_result()
the state of the connection is as if you had called mysql_real_query()
or mysql_query()
for the next statement. This means that you can call mysql_store_result()
, mysql_warning_count()
, mysql_affected_rows()
, and so forth.
If your program uses CALL
statements to execute stored procedures, the CLIENT_MULTI_RESULTS
flag must be enabled. This is because each CALL
returns a result to indicate the call status, in addition to any result sets that might be returned by statements executed within the procedure. Because CALL
can return multiple results, process them using a loop that calls mysql_next_result()
to determine whether there are more results.
CLIENT_MULTI_RESULTS
can be enabled when you call mysql_real_connect()
, either explicitly by passing the CLIENT_MULTI_RESULTS
flag itself, or implicitly by passing CLIENT_MULTI_STATEMENTS
(which also enables CLIENT_MULTI_RESULTS
). In MariaDB 5.6, CLIENT_MULTI_RESULTS
is enabled by default.
It is also possible to test whether there are more results by calling mysql_more_results()
. However, this function does not change the connection state, so if it returns true, you must still call mysql_next_result()
to advance to the next result.
For an example that shows how to use mysql-next-result()
, see , "C API Support for Multiple Statement Execution".
Return Values
Return Value | Description |
---|---|
0 | Successful and there are more results |
-1 | Successful and there are no more results |
>0 | An error occurred |
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order. For example, if you didn't call
mysql_use_result()
for a previous result set.CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_num_fields()
unsigned int mysql_num_fields(MYSQL_RES *result)
To pass a MYSQL*
argument instead, use unsigned int mysql_field_count(MYSQL *mysql)
.
Description
Returns the number of columns in a result set.
Note that you can get the number of columns either from a pointer to a result set or to a connection handle. You would use the connection handle if mysql_store_result()
or mysql_use_result()
returned NULL
(and thus you have no result set pointer). In this case, you can call mysql-field-count()
to determine whether mysql_store_result()
should have produced a nonempty result. This enables the client program to take proper action without knowing whether the query was a SELECT
(or SELECT
-like) statement. The example shown here illustrates how this may be done.
See , "Why mysql_store_result()
Sometimes Returns NULL
After mysql_query()
Returns Success".
Return Values
An unsigned integer representing the number of columns in a result set.
Errors
None.
Example
MYSQL_RES *result; unsigned int num_fields; unsigned int num_rows; if (mysql_query(&mysql,query_string)) { // error } else // query succeeded, process any data returned by it { result = mysql_store_result(&mysql); if (result) // there are rows { num_fields = mysql_num_fields(result); // retrieve rows, then call mysql_free_result(result) } else // mysql_store_result() returned nothing; should it have? { if (mysql_errno(&mysql)) { fprintf(stderr, 'Error: %s\n', mysql_error(&mysql)); } else if (mysql_field_count(&mysql) == 0) { // query does not return data // (it was not a SELECT) num_rows = mysql_affected_rows(&mysql); } } }
An alternative (if you know that your query should have returned a result set) is to replace the mysql_errno(&mysql)
call with a check whether mysql_field_count(&mysql)
returns 0. This happens only if something went wrong.
mysql_num_rows()
my_ulonglong mysql_num_rows(MYSQL_RES *result)
Description
Returns the number of rows in the result set.
The use of mysql-num-rows()
depends on whether you use mysql_store_result()
or mysql_use_result()
to return the result set. If you use mysql-store-result()
, mysql_num_rows()
may be called immediately. If you use mysql_use_result()
, mysql_num_rows()
does not return the correct value until all the rows in the result set have been retrieved.
mysql-num-rows()
is intended for use with statements that return a result set, such as SELECT
. For statements such as INSERT
, UPDATE
, or DELETE
, the number of affected rows can be obtained with mysql_affected_rows()
.
Return Values
The number of rows in the result set.
Errors
None.
mysql_options()
int mysql_options(MYSQL *mysql, enum mysql_option option, const void *arg)
Description
Can be used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options.
Call mysql-options()
after mysql_init()
and before mysql-connect()
or mysql_real_connect()
.
The option
argument is the option that you want to set; the arg
argument is the value for the option. If the option is an integer, specify a pointer to the value of the integer as the arg
argument.
The following list describes the possible options, their effect, and how arg
is used for each option. Several of the options apply only when the application is linked against the libmysqld
embedded server library and are unused for applications linked against the libmysql
client library. For option descriptions that indicate arg
is unused, its value is irrelevant; it is conventional to pass 0.
MYSQL_DEFAULT_AUTH
(argument type:char *
)
The name of the authentication plugin to use.
MYSQL_INIT_COMMAND
(argument type:char *
)SQL statement to execute when connecting to the MariaDB server. Automatically re-executed if reconnection occurs.
MYSQL_OPT_BIND
(argument:char *
)The network interface from which to connect to the server. This is used when the client host has multiple network interfaces. The argument is a host name or IP address (specified as a string). This option was added in MariaDB 5.6.1.
MYSQL_OPT_COMPRESS
(argument: not used)Use the compressed client/server protocol.
MYSQL_OPT_CONNECT_TIMEOUT
(argument type:unsigned int *
)Connect timeout in seconds.
MYSQL_OPT_GUESS_CONNECTION
(argument: not used)For an application linked against the
libmysqld
embedded server library, this enables the library to guess whether to use the embedded server or a remote server. "Guess" means that if the host name is set and is notlocalhost
, it uses a remote server. This behavior is the default.MYSQL_OPT_USE_EMBEDDED_CONNECTION
andMYSQL_OPT_USE_REMOTE_CONNECTION
can be used to override it. This option is ignored for applications linked against thelibmysqlclient
client library.MYSQL_OPT_LOCAL_INFILE
(argument type: optional pointer tounsigned int
)If no pointer is given or if pointer points to an
unsigned int
that has a nonzero value, theLOAD LOCAL INFILE
statement is enabled.MYSQL_OPT_NAMED_PIPE
(argument: not used)Use named pipes to connect to a MariaDB server on Windows, if the server permits named-pipe connections.
MYSQL_OPT_PROTOCOL
(argument type:unsigned int *
)Type of protocol to use. Specify one of the enum values of
mysql_protocol_type
defined inmysql.h
.MYSQL_OPT_READ_TIMEOUT
(argument type:unsigned int *
)The timeout in seconds for attempts to read from the server. Each attempt uses this timeout value and there are retries if necessary, so the total effective timeout value is three times the option value. You can set the value so that a lost connection can be detected earlier than the TCP/IP
Close_Wait_Timeout
value of 10 minutes.MYSQL_OPT_RECONNECT
(argument type:my_bool *
)Enable or disable automatic reconnection to the server if the connection is found to have been lost. Reconnect is off by default; this option provides a way to set reconnection behavior explicitly.
MYSQL_OPT_SSL_CA
(argument type:char *
)The path to a file that contains a list of trusted SSL CAs. This option was added in MariaDB 5.6.3.
MYSQL_OPT_SSL_CAPATH
(argument type:char *
)The path to a directory that contains trusted SSL CA certificates in PEM format. This option was added in MariaDB 5.6.3.
MYSQL_OPT_SSL_CERT
(argument type:char *
)The name of the SSL certificate file to use for establishing a secure connection. This option was added in MariaDB 5.6.3.
MYSQL_OPT_SSL_CIPHER
(argument type:char *
)A list of permissible ciphers to use for SSL encryption. This option was added in MariaDB 5.6.3.
MYSQL_OPT_SSL_CRL
(argument type:char *
)The path to a file containing certificate revocation lists in PEM format. This option was added in MariaDB 5.6.3.
MYSQL_OPT_SSL_CRLPATH
(argument type:char *
)The path to a directory that contains files containing certificate revocation lists in PEM format. This option was added in MariaDB 5.6.3.
MYSQL_OPT_SSL_KEY
(argument type:char *
)The name of the SSL key file to use for establishing a secure connection. This option was added in MariaDB 5.6.3.
MYSQL_OPT_SSL_VERIFY_SERVER_CERT
(argument type:my_bool *
)Enable or disable verification of the server's Common Name value in its certificate against the host name used when connecting to the server. The connection is rejected if there is a mismatch. This feature can be used to prevent man-in-the-middle attacks. Verification is disabled by default.
MYSQL_OPT_USE_EMBEDDED_CONNECTION
(argument: not used)For an application linked against the
libmysqld
embedded server library, this forces the use of the embedded server for the connection. This option is ignored for applications linked against thelibmysqlclient
client library.MYSQL_OPT_USE_REMOTE_CONNECTION
(argument: not used)For an application linked against the
libmysqld
embedded server library, this forces the use of a remote server for the connection. This option is ignored for applications linked against thelibmysqlclient
client library.MYSQL_OPT_USE_RESULT
(argument: not used)This option is unused.
MYSQL_OPT_WRITE_TIMEOUT
(argument type:unsigned int *
)The timeout in seconds for attempts to write to the server. Each attempt uses this timeout value and there are
net_retry_count
retries if necessary, so the total effective timeout value isnet_retry_count
times the option value.MYSQL_PLUGIN_DIR
(argument type:char *
)The directory in which to look for client plugins.
MYSQL_READ_DEFAULT_FILE
(argument type:char *
)Read options from the named option file instead of from
my.cnf
.MYSQL_READ_DEFAULT_GROUP
(argument type:char *
)Read options from the named group from
my.cnf
or the file specified withMYSQL_READ_DEFAULT_FILE
.MYSQL_REPORT_DATA_TRUNCATION
(argument type:my_bool *
)Enable or disable reporting of data truncation errors for prepared statements using the
error
member ofMYSQL_BIND
structures. (Default: enabled.)MYSQL_SECURE_AUTH
(argument type:my_bool *
)Whether to connect to a server that does not support the password hashing used in MariaDB and later.
MYSQL_SET_CHARSET_DIR
(argument type:char *
)The path name to the directory that contains character set definition files.
MYSQL_SET_CHARSET_NAME
(argument type:char *
)The name of the character set to use as the default character set. The argument can be
MYSQL_AUTODETECT_CHARSET_NAME
to cause the character set to be autodetected based on the operating system setting (see , "Connection Character Sets and Collations").MYSQL_SET_CLIENT_IP
(argument type:char *
)For an application linked against the
libmysqld
embedded server library (whenlibmysqld
is compiled with authentication support), this means that the user is considered to have connected from the specified IP address (specified as a string) for authentication purposes. This option is ignored for applications linked against thelibmysqlclient
client library.MYSQL_SHARED_MEMORY_BASE_NAME
(argument type:char *
)The name of the shared-memory object for communication to the server on Windows, if the server supports shared-memory connections. Specify the same value as the
--shared-memory-base-name
option used for the mysqld server you want to connect to.
The client
group is always read if you use MYSQL_READ_DEFAULT_FILE
or MYSQL_READ_DEFAULT_GROUP
.
The specified group in the option file may contain the following options.
Option | Description |
---|---|
character-sets-dir=
| The directory where character sets are installed. |
compress
| Use the compressed client/server protocol. |
connect-timeout=
| Connect timeout in seconds. On Linux this timeout is also used for waiting for the first answer from the server. |
database=
| Connect to this database if no database was specified in the connect command. |
debug
| Debug options. |
default-character-set=
| The default character set to use. |
disable-local-infile
| Disable use of LOAD DATA LOCAL .
|
host=
| Default host name. |
init-command=
| Statement to execute when connecting to MariaDB server. Automatically re-executed if reconnection occurs. |
interactive-timeout=
| Same as specifying CLIENT_INTERACTIVE to mysql_real_connect() . See , "mysql_real_connect() ".
|
local-infile[={0|1}]
| If no argument or nonzero argument, enable use of LOAD DATA LOCAL ; otherwise disable.
|
max_allowed_packet=
| Maximum size of packet that client can read from server. |
multi-queries , multi-results
| Enable multiple result sets from multiple-statement executions or stored procedures. |
multi-statements
| Enable the client to send multiple statements in a single string (separated by "; ").
|
password=
| Default password. |
pipe
| Use named pipes to connect to a MariaDB server on Windows. |
port=
| Default port number. |
protocol={TCP|SOCKET|PIPE|MEMORY}
| The protocol to use when connecting to the server. |
return-found-rows
| Tell mysql-info() to return found rows instead of updated rows when using UPDATE .
|
shared-memory-base-name=
| Shared-memory name to use to connect to server. |
socket=
| Default socket file. |
ssl-ca=
| Certificate Authority file. |
ssl-capath=
| Certificate Authority directory. |
ssl-cert=
| Certificate file. |
ssl-cipher=
| Permissible SSL ciphers. |
ssl-key=
| Key file. |
timeout=
| Like connect-timeout .
|
user
| Default user. |
timeout
has been replaced by connect-timeout
, but timeout
is still supported in MariaDB 5.6 for backward compatibility.
For more information about option files, see , "Using Option Files".
Return Values
Zero for success. Nonzero if you specify an unknown option.
Example
The following mysql_options()
calls request the use of compression in the client/server protocol, cause options to be read from the [odbc]
group of option files, and disable transaction autocommit mode:
MYSQL mysql; mysql_init(&mysql); mysql_options(&mysql,MYSQL_OPT_COMPRESS,0); mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,'odbc'); mysql_options(&mysql,MYSQL_INIT_COMMAND,'SET autocommit=0'); if (!mysql_real_connect(&mysql,'host','user','passwd','database',0,NULL,0)) { fprintf(stderr, 'Failed to connect to database: Error: %s\n', mysql_error(&mysql)); }
This code requests that the client use the compressed client/server protocol and read the additional options from the odbc
section in the my.cnf
file.
mysql_ping()
int mysql_ping(MYSQL *mysql)
Description
Checks whether the connection to the server is working. If the connection has gone down and auto-reconnect is enabled an attempt to reconnect is made. If the connection is down and auto-reconnect is disabled, mysql_ping()
returns an error.
Auto-reconnect is disabled by default. To enable it, call mysql_options()
with the MYSQL_OPT_RECONNECT
option. For details, see , "mysql_options()
".
mysql_ping()
can be used by clients that remain idle for a long while, to check whether the server has closed the connection and reconnect if necessary.
If mysql_ping()
) does cause a reconnect, there is no explicit indication of it. To determine whether a reconnect occurs, call mysql_thread_id()
to get the original connection identifier before calling mysql_ping()
, then call mysql_thread_id()
again to see whether the identifier has changed.
If reconnect occurs, some characteristics of the connection will have been reset. For details about these characteristics, see , "Controlling Automatic Reconnection Behavior".
Return Values
Zero if the connection to the server is active. Nonzero if an error occurred. A nonzero return does not indicate whether the MariaDB server itself is down; the connection might be broken for other reasons such as network problems.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_query()
int mysql_query(MYSQL *mysql, const char *stmt_str)
Description
Executes the SQL statement pointed to by the null-terminated string stmt_str
. Normally, the string must consist of a single SQL statement without a terminating semicolon (";
") or \g
. If multiple-statement execution has been enabled, the string can contain several statements separated by semicolons. See , "C API Support for Multiple Statement Execution".
mysql-query()
cannot be used for statements that contain binary data; you must use mysql_real_query()
instead. (Binary data may contain the "\0
" character, which mysql_query()
interprets as the end of the statement string.)
If you want to know whether the statement returns a result set, you can use mysql_field_count()
to check for this. See , "mysql_field_count()
".
Return Values
Zero if the statement was successful. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_real_connect()
MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag)
Description
mysql_real_connect()
attempts to establish a connection to a MariaDB database engine running on host
. mysql_real_connect()
must complete successfully before you can execute any other API functions that require a valid MariaDB
connection handle structure.
The parameters are specified as follows:
- For the first parameter, specify the address of an existing
MariaDB
structure. Before callingmysql_real_connect()
, callmysql_init()
to initialize theMariaDB
structure. You can change a lot of connect options with themysql-options()
call. See , "mysql_options()
". - The value of
host
may be either a host name or an IP address. Ifhost
isNULL
or the string'localhost'
, a connection to the local host is assumed. For Windows, the client connects using a shared-memory connection, if the server has shared-memory connections enabled. Otherwise, TCP/IP is used. For Unix, the client connects using a Unix socket file. For local connections, you can also influence the type of connection to use with theMYSQL_OPT_PROTOCOL
orMYSQL_OPT_NAMED_PIPE
options tomysql_options()
. The type of connection must be supported by the server. For ahost
value of'.'
on Windows, the client connects using a named pipe, if the server has named-pipe connections enabled. If named-pipe connections are not enabled, an error occurs. - The
user
parameter contains the user's MariaDB login ID. Ifuser
isNULL
or the empty string''
, the current user is assumed. Under Unix, this is the current login name. Under Windows ODBC, the current user name must be specified explicitly. See the Connector/ODBC section of , Connectors and APIs. - The
passwd
parameter contains the password foruser
. Ifpasswd
isNULL
, only entries in theuser
table for the user that have a blank (empty) password field are checked for a match. This enables the database administrator to set up the MariaDB privilege system in such a way that users get different privileges depending on whether they have specified a password.NoteDo not attempt to encrypt the password before calling
mysql_real_connect()
; password encryption is handled automatically by the client API. - The
user
andpasswd
parameters use whatever character set has been configured for theMariaDB
object. By default, this islatin1
, but can be changed by callingmysql_options(mysql, MYSQL_SET_CHARSET_NAME, '
prior to connecting.charset_name
') db
is the database name. Ifdb
is notNULL
, the connection sets the default database to this value.- If
port
is not 0, the value is used as the port number for the TCP/IP connection. Note that thehost
parameter determines the type of the connection. - If
unix_socket
is notNULL
, the string specifies the socket or named pipe to use. Note that thehost
parameter determines the type of the connection. - The value of
client_flag
is usually 0, but can be set to a combination of the following flags to enable certain features.Flag Name Flag Description CLIENT_COMPRESS
Use compression protocol. CLIENT_FOUND_ROWS
Return the number of found (matched) rows, not the number of changed rows. CLIENT_IGNORE_SIGPIPE
Prevents the client library from installing a SIGPIPE
signal handler. This can be used to avoid conflicts with a handler that the application has already installed.CLIENT_IGNORE_SPACE
Permit spaces after function names. Makes all functions names reserved words. CLIENT_INTERACTIVE
Permit interactive-timeout
seconds (instead ofwait_timeout
seconds) of inactivity before closing the connection. The client's sessionwait_timeout
variable is set to the value of the sessioninteractive_timeout
variable.CLIENT_LOCAL_FILES
Enable LOAD DATA LOCAL
handling.CLIENT_MULTI_RESULTS
Tell the server that the client can handle multiple result sets from multiple-statement executions or stored procedures. This flag is automatically enabled if CLIENT_MULTI_STATEMENTS
is enabled. See the note following this table for more information about this flag.CLIENT_MULTI_STATEMENTS
Tell the server that the client may send multiple statements in a single string (separated by " ;
"). If this flag is not set, multiple-statement execution is disabled. See the note following this table for more information about this flag.CLIENT_NO_SCHEMA
Do not permit the db_name.tbl_name.col_name
syntax. This is for ODBC. It causes the parser to generate an error if you use that syntax, which is useful for trapping bugs in some ODBC programs.CLIENT_ODBC
Unused. CLIENT_SSL
Use SSL (encrypted protocol). Do not set this option within an application program; it is set internally in the client library. Instead, use mysql_ssl_set()
before callingmysql_real_connect()
.CLIENT_REMEMBER_OPTIONS
Remember options specified by calls to mysql-options()
. Without this option, ifmysql_real_connect()
fails, you must repeat themysql_options()
calls before trying to connect again. With this option, themysql_options()
calls need not be repeated.
If your program uses CALL
statements to execute stored procedures, the CLIENT_MULTI_RESULTS
flag must be enabled. This is because each CALL
returns a result to indicate the call status, in addition to any result sets that might be returned by statements executed within the procedure. Because CALL
can return multiple results, process them using a loop that calls mysql_next_result()
to determine whether there are more results.
CLIENT_MULTI_RESULTS
can be enabled when you call mysql_real_connect()
, either explicitly by passing the CLIENT_MULTI_RESULTS
flag itself, or implicitly by passing CLIENT_MULTI_STATEMENTS
(which also enables CLIENT_MULTI_RESULTS
). In MariaDB 5.6, CLIENT_MULTI_RESULTS
is enabled by default.
If you enable CLIENT_MULTI_STATEMENTS
or CLIENT_MULTI_RESULTS
, process the result for every call to mysql_query()
or mysql-real-query()
by using a loop that calls mysql_next_result()
to determine whether there are more results. For an example, see , "C API Support for Multiple Statement Execution".
For some parameters, it is possible to have the value taken from an option file rather than from an explicit value in the mysql_real_connect()
call. To do this, call mysql_options()
with the MYSQL_READ_DEFAULT_FILE
or MYSQL_READ_DEFAULT_GROUP
option before calling mysql_real_connect()
. Then, in the mysql_real_connect()
call, specify the "no-value" value for each parameter to be read from an option file:
- For
host
, specify a value ofNULL
or the empty string (''
). - For
user
, specify a value ofNULL
or the empty string. - For
passwd
, specify a value ofNULL
. (For the password, a value of the empty string in themysql_real_connect()
call cannot be overridden in an option file, because the empty string indicates explicitly that the MariaDB account must have an empty password.) - For
db
, specify a value ofNULL
or the empty string. - For
port
, specify a value of 0. - For
unix_socket
, specify a value ofNULL
.
If no value is found in an option file for a parameter, its default value is used as indicated in the descriptions given earlier in this section.
Return Values
A MYSQL*
connection handle if the connection was successful, NULL
if the connection was unsuccessful. For a successful connection, the return value is the same as the value of the first parameter.
Errors
CR_CONN_HOST_ERROR
Failed to connect to the MariaDB server.
CR_CONNECTION_ERROR
Failed to connect to the local MariaDB server.
CR_IPSOCK_ERROR
Failed to create an IP socket.
CR_OUT_OF_MEMORY
Out of memory.
CR_SOCKET_CREATE_ERROR
Failed to create a Unix socket.
CR_UNKNOWN_HOST
Failed to find the IP address for the host name.
CR_VERSION_ERROR
A protocol mismatch resulted from attempting to connect to a server with a client library that uses a different protocol version.
CR_NAMEDPIPEOPEN_ERROR
Failed to create a named pipe on Windows.
CR_NAMEDPIPEWAIT_ERROR
Failed to wait for a named pipe on Windows.
CR_NAMEDPIPESETSTATE_ERROR
Failed to get a pipe handler on Windows.
CR_SERVER_LOST
If
connect-timeout
> 0 and it took longer thanconnect_timeout
seconds to connect to the server or if the server died while executing theinit-command
.CR_ALREADY_CONNECTED
The
MariaDB
connection handle is already connected.
Example
MYSQL mysql; mysql_init(&mysql); mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,'your_prog_name'); if (!mysql_real_connect(&mysql,'host','user','passwd','database',0,NULL,0)) { fprintf(stderr, 'Failed to connect to database: Error: %s\n', mysql_error(&mysql)); }
By using mysql_options()
the MariaDB library reads the [client]
and [your_prog_name]
sections in the my.cnf
file which ensures that your program works, even if someone has set up MariaDB in some nonstandard way.
Note that upon connection, mysql_real_connect()
sets the reconnect
flag (part of the MariaDB
structure) to a value of 1
in versions of the API older than 5.0.3, or 0
in newer versions. A value of 1
for this flag indicates that if a statement cannot be performed because of a lost connection, to try reconnecting to the server before giving up. You can use the MYSQL_OPT_RECONNECT
option to mysql_options()
to control reconnection behavior.
mysql_real_escape_string()
unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)
Note that MariaDB
must be a valid, open connection. This is needed because the escaping depends on the character set in use by the server.
Description
This function is used to create a legal SQL string that you can use in an SQL statement. See , "String Literals".
The string in from
is encoded to an escaped SQL string, taking into account the current character set of the connection. The result is placed in to
and a terminating null byte is appended. Characters encoded are "\
", "'
", "'
", NUL
(ASCII 0), "\n
", "\r
", and Control+Z. Strictly speaking, MariaDB requires only that backslash and the quote character used to quote the string in the query be escaped. mysql_real_escape_string()
quotes the other characters to make them easier to read in log files. For comparison, see the quoting rules for literal strings and the QUOTE()
SQL function in , "String Literals", and , "String Functions".
The string pointed to by from
must be length
bytes long. You must allocate the to
buffer to be at least length*2+1
bytes long. (In the worst case, each character may need to be encoded as using two bytes, and you need room for the terminating null byte.) When mysql_real_escape_string()
returns, the contents of to
is a null-terminated string. The return value is the length of the encoded string, not including the terminating null character.
If you need to change the character set of the connection, use the mysql_set_character_set()
function rather than executing a SET NAMES
(or SET CHARACTER SET
) statement. mysql_set_character_set()
works like SET NAMES
but also affects the character set used by mysql_real_escape_string()
, which SET NAMES
does not.
Example
char query[1000],*end; end = strmov(query,'INSERT INTO test_table values('); *end++ = '\''; end += mysql_real_escape_string(&mysql, end,'What is this',12); *end++ = '\''; *end++ = ','; *end++ = '\''; end += mysql_real_escape_string(&mysql, end,'binary data: \0\r\n',16); *end++ = '\''; *end++ = ')'; if (mysql_real_query(&mysql,query,(unsigned int) (end - query))) { fprintf(stderr, 'Failed to insert row, Error: %s\n', mysql_error(&mysql)); }
The strmov()
function used in the example is included in the mysqlclient
library and works like strcpy()
but returns a pointer to the terminating null of the first parameter.
Return Values
The length of the value placed into to
, not including the terminating null character.
Errors
None.
mysql_real_query()
int mysql_real_query(MYSQL *mysql, const char *stmt_str, unsigned long length)
Description
Executes the SQL statement pointed to by stmt_str
, a string length
bytes long. Normally, the string must consist of a single SQL statement without a terminating semicolon (";
") or \g
. If multiple-statement execution has been enabled, the string can contain several statements separated by semicolons. See , "C API Support for Multiple Statement Execution".
mysql-query()
cannot be used for statements that contain binary data; you must use mysql_real_query()
instead. (Binary data may contain the "\0
" character, which mysql_query()
interprets as the end of the statement string.) In addition, mysql_real_query()
is faster than mysql_query()
because it does not call strlen()
on the statement string.
If you want to know whether the statement returns a result set, you can use mysql_field_count()
to check for this. See , "mysql_field_count()
".
Return Values
Zero if the statement was successful. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_refresh()
int mysql_refresh(MYSQL *mysql, unsigned int options)
Description
This function flushes tables or caches, or resets replication server information. The connected user must have the RELOAD
privilege.
The options
argument is a bit mask composed from any combination of the following values. Multiple values can be OR'ed together to perform multiple operations with a single call.
REFRESH_GRANT
Refresh the grant tables, like
FLUSH PRIVILEGES
.REFRESH_LOG
Flush the logs, like
FLUSH LOGS
.REFRESH_TABLES
Flush the table cache, like
FLUSH TABLES
.REFRESH_HOSTS
Flush the host cache, like
FLUSH HOSTS
.REFRESH_STATUS
Reset status variables, like
FLUSH STATUS
.REFRESH_THREADS
Flush the thread cache.
REFRESH_SLAVE
On a slave replication server, reset the master server information and restart the slave, like
RESET SLAVE
.REFRESH_MASTER
On a master replication server, remove the binary log files listed in the binary log index and truncate the index file, like
RESET MASTER
.
Return Values
Zero for success. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_reload()
int mysql_reload(MYSQL *mysql)
Description
Asks the MariaDB server to reload the grant tables. The connected user must have the RELOAD
privilege.
This function is deprecated. It is preferable to use mysql-query()
to issue an SQL FLUSH PRIVILEGES
statement instead.
Return Values
Zero for success. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_rollback()
my_bool mysql_rollback(MYSQL *mysql)
Description
Rolls back the current transaction.
The action of this function is subject to the value of the completion_type
system variable. In particular, if the value of completion_type
is RELEASE
(or 2), the server performs a release after terminating a transaction and closes the client connection. Call mysql_close()
from the client program to close the connection from the client side.
Return Values
Zero if successful. Nonzero if an error occurred.
Errors
None.
mysql_row_seek()
MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)
Description
Sets the row cursor to an arbitrary row in a query result set. The offset
value is a row offset, typically a value returned from mysql_row_tell()
or from mysql_row_seek()
. This value is not a row number; to seek to a row within a result set by number, use mysql_data_seek()
instead.
This function requires that the result set structure contains the entire result of the query, so mysql_row_seek()
may be used only in conjunction with mysql-store-result()
, not with mysql_use_result()
.
Return Values
The previous value of the row cursor. This value may be passed to a subsequent call to mysql_row_seek()
.
Errors
None.
mysql_row_tell()
MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)
Description
Returns the current position of the row cursor for the last mysql_fetch_row()
. This value can be used as an argument to mysql_row_seek()
.
Use mysql-row-tell()
only after mysql_store_result()
, not after mysql_use_result()
.
Return Values
The current offset of the row cursor.
Errors
None.
mysql_select_db()
int mysql_select_db(MYSQL *mysql, const char *db)
Description
Causes the database specified by db
to become the default (current) database on the connection specified by MariaDB
. In subsequent queries, this database is the default for table references that do not include an explicit database specifier.
mysql_select_db()
fails unless the connected user can be authenticated as having permission to use the database.
Return Values
Zero for success. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_set_character_set()
int mysql_set_character_set(MYSQL *mysql, const char *csname)
Description
This function is used to set the default character set for the current connection. The string csname
specifies a valid character set name. The connection collation becomes the default collation of the character set. This function works like the SET NAMES
statement, but also sets the value of mysql->charset
, and thus affects the character set used by mysql_real_escape_string()
Return Values
Zero for success. Nonzero if an error occurred.
Example
MYSQL mysql; mysql_init(&mysql); if (!mysql_real_connect(&mysql,'host','user','passwd','database',0,NULL,0)) { fprintf(stderr, 'Failed to connect to database: Error: %s\n', mysql_error(&mysql)); } if (!mysql_set_character_set(&mysql, 'utf8')) { printf('New client character set: %s\n', mysql_character_set_name(&mysql)); }
mysql_set_local_infile_default()
void mysql_set_local_infile_default(MYSQL *mysql);
Description
Sets the LOAD LOCAL DATA INFILE
handler callback functions to the defaults used internally by the C client library. The library calls this function automatically if mysql_set_local_infile_handler()
has not been called or does not supply valid functions for each of its callbacks.
Return Values
None.
Errors
None.
mysql_set_local_infile_handler()
void mysql_set_local_infile_handler(MYSQL *mysql, int (*local_infile_init)(void **, const char *, void *), int (*local_infile_read)(void *, char *, unsigned int), void (*local_infile_end)(void *), int (*local_infile_error)(void *, char*, unsigned int), void *userdata);
Description
This function installs callbacks to be used during the execution of LOAD DATA LOCAL INFILE
statements. It enables application programs to exert control over local (client-side) data file reading. The arguments are the connection handler, a set of pointers to callback functions, and a pointer to a data area that the callbacks can use to share information.
To use mysql_set_local_infile_handler()
, you must write the following callback functions:
int local_infile_init(void **ptr, const char *filename, void *userdata);
The initialization function. This is called once to do any setup necessary, open the data file, allocate data structures, and so forth. The first void**
argument is a pointer to a pointer. You can set the pointer (that is, *ptr
) to a value that will be passed to each of the other callbacks (as a void*
). The callbacks can use this pointed-to value to maintain state information. The userdata
argument is the same value that is passed to mysql_set_local_infile_handler()
.
Make the initialization function return zero for success, nonzero for an error.
int local_infile_read(void *ptr, char *buf, unsigned int buf_len);
The data-reading function. This is called repeatedly to read the data file. buf
points to the buffer where the read data is stored, and buf_len
is the maximum number of bytes that the callback can read and store in the buffer. (It can read fewer bytes, but should not read more.)
The return value is the number of bytes read, or zero when no more data could be read (this indicates EOF). Return a value less than zero if an error occurs.
void local_infile_end(void *ptr)
The termination function. This is called once after local_infile_read()
has returned zero (EOF) or an error. Within this function, deallocate any memory allocated by local_infile_init()
and perform any other cleanup necessary. It is invoked even if the initialization function returns an error.
int local_infile_error(void *ptr, char *error_msg, unsigned int error_msg_len);
The error-handling function. This is called to get a textual error message to return to the user in case any of your other functions returns an error. error_msg
points to the buffer into which the message is written, and error_msg_len
is the length of the buffer. Write the message as a null-terminated string, at most error_msg_len
-1 bytes long.
The return value is the error number.
Typically, the other callbacks store the error message in the data structure pointed to by ptr
, so that local_infile_error()
can copy the message from there into error_msg
.
After calling mysql_set_local_infile_handler()
in your C code and passing pointers to your callback functions, you can then issue a LOAD DATA LOCAL INFILE
statement (for example, by using mysql_query()
). The client library automatically invokes your callbacks. The file name specified in LOAD DATA LOCAL INFILE
will be passed as the second parameter to the local_infile_init()
callback.
Return Values
None.
Errors
None.
mysql_set_server_option()
int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)
Description
Enables or disables an option for the connection. option
can have one of the following values.
Option | Description |
---|---|
MYSQL_OPTION_MULTI_STATEMENTS_ON
| Enable multiple-statement support |
MYSQL_OPTION_MULTI_STATEMENTS_OFF
| Disable multiple-statement support |
If you enable multiple-statement support, you should retrieve results from calls to mysql_query()
or mysql_real_query()
by using a loop that calls mysql_next_result()
to determine whether there are more results. For an example, see , "C API Support for Multiple Statement Execution".
Enabling multiple-statement support with MYSQL_OPTION_MULTI_STATEMENTS_ON
does not have quite the same effect as enabling it by passing the CLIENT_MULTI_STATEMENTS
flag to mysql_real_connect()
: CLIENT_MULTI_STATEMENTS
also enables CLIENT_MULTI_RESULTS
. If you are using the CALL
SQL statement in your programs, multiple-result support must be enabled; this means that MYSQL_OPTION_MULTI_STATEMENTS_ON
by itself is insufficient to permit the use of CALL
.
Return Values
Zero for success. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
ER_UNKNOWN_COM_ERROR
The server didn't support
mysql_set_server_option()
(which is the case that the server is older than 4.1.1) or the server didn't support the option one tried to set.
mysql_shutdown()
int mysql_shutdown(MYSQL *mysql, enum mysql_enum_shutdown_level shutdown_level)
Description
Asks the database server to shut down. The connected user must have the SHUTDOWN
privilege. MariaDB 5.6 servers support only one type of shutdown; shutdown_level
must be equal to SHUTDOWN_DEFAULT
. Additional shutdown levels are planned to make it possible to choose the desired level. Dynamically linked executables which have been compiled with older versions of the libmysqlclient
headers and call mysql_shutdown()
need to be used with the old libmysqlclient
dynamic library.
The shutdown process is described in , "The Shutdown Process".
Return Values
Zero for success. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_sqlstate()
const char *mysql_sqlstate(MYSQL *mysql)
Description
Returns a null-terminated string containing the SQLSTATE error code for the most recently executed SQL statement. The error code consists of five characters. '00000'
means "no error." The values are specified by ANSI SQL and ODBC. For a list of possible values, see Appendix C, Errors, Error Codes, and Common Problems.
SQLSTATE values returned by mysql_sqlstate()
differ from MySQL-specific error numbers returned by mysql_errno()
. For example, the mysql client program displays errors using the following format, where 1146
is the mysql_errno()
value and '42S02'
is the corresponding mysql_sqlstate()
value:
shell> SELECT * FROM no_such_table;
ERROR 1146 (42S02): Table 'test.no_such_table' doesn't exist
Not all MariaDB error numbers are mapped to SQLSTATE error codes. The value 'HY000'
(general error) is used for unmapped error numbers.
If you call mysql-sqlstate()
after mysql_real_connect()
fails, mysql_sqlstate()
might not return a useful value. For example, this happens if a host is blocked by the server and the connection is closed without any SQLSTATE value being sent to the client.
Return Values
A null-terminated character string containing the SQLSTATE error code.
See Also
See , "mysql-errno()
", , "mysql_error()
", and , "mysql_stmt_sqlstate()
".
mysql_ssl_set()
my_bool mysql_ssl_set(MYSQL *mysql, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher)
Description
mysql_ssl_set()
is used for establishing secure connections using SSL. It must be called before mysql_real_connect()
.
mysql_ssl_set()
does nothing unless SSL support is enabled in the client library.
MariaDB
is the connection handler returned from mysql_init()
. The other parameters are specified as follows:
key
is the path name to the key file.cert
is the path name to the certificate file.ca
is the path name to the certificate authority file.capath
is the path name to a directory that contains trusted SSL CA certificates in PEM format.cipher
is a list of permissible ciphers to use for SSL encryption.
Any unused SSL parameters may be given as NULL
.
Return Values
This function always returns 0
. If SSL setup is incorrect, mysql_real_connect()
returns an error when you attempt to connect.
mysql_stat()
const char *mysql_stat(MYSQL *mysql)
Description
Returns a character string containing information similar to that provided by the mysqladmin status command. This includes uptime in seconds and the number of running threads, questions, reloads, and open tables.
Return Values
A character string describing the server status. NULL
if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_store_result()
MYSQL_RES *mysql_store_result(MYSQL *mysql)
Description
After invoking mysql-query()
or mysql_real_query()
, you must call mysql-store-result()
or mysql_use_result()
for every statement that successfully produces a result set (SELECT
, SHOW
, DESCRIBE
, EXPLAIN
, CHECK TABLE
, and so forth). You must also call mysql_free_result()
after you are done with the result set.
You don't have to call mysql-store-result()
or mysql_use_result()
for other statements, but it does not do any harm or cause any notable performance degradation if you call mysql_store_result()
in all cases. You can detect whether the statement has a result set by checking whether mysql_store_result()
returns a nonzero value (more about this later).
If you enable multiple-statement support, you should retrieve results from calls to mysql_query()
or mysql_real_query()
by using a loop that calls mysql_next_result()
to determine whether there are more results. For an example, see , "C API Support for Multiple Statement Execution".
If you want to know whether a statement should return a result set, you can use mysql_field_count()
to check for this. See , "mysql_field_count()
".
mysql_store_result()
reads the entire result of a query to the client, allocates a MYSQL_RES
structure, and places the result into this structure.
mysql_store_result()
returns a null pointer if the statement didn't return a result set (for example, if it was an INSERT
statement).
mysql_store_result()
also returns a null pointer if reading of the result set failed. You can check whether an error occurred by checking whether mysql-error()
returns a nonempty string, mysql_errno()
returns nonzero, or mysql_field_count()
returns zero.
An empty result set is returned if there are no rows returned. (An empty result set differs from a null pointer as a return value.)
After you have called mysql_store_result()
and gotten back a result that isn't a null pointer, you can call mysql_num_rows()
to find out how many rows are in the result set.
You can call mysql-fetch-row()
to fetch rows from the result set, or mysql_row_seek()
and mysql_row_tell()
to obtain or set the current row position within the result set.
See , "Why mysql_store_result()
Sometimes Returns NULL
After mysql_query()
Returns Success".
Return Values
A MYSQL_RES
result structure with the results. NULL
(0) if an error occurred.
Errors
mysql-store-result()
resets mysql_error()
and mysql_errno()
if it succeeds.
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_OUT_OF_MEMORY
Out of memory.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_thread_id()
unsigned long mysql_thread_id(MYSQL *mysql)
Description
Returns the thread ID of the current connection. This value can be used as an argument to mysql_kill()
to kill the thread.
If the connection is lost and you reconnect with mysql_ping()
, the thread ID changes. This means you should not get the thread ID and store it for later. You should get it when you need it.
Return Values
The thread ID of the current connection.
Errors
None.
mysql_use_result()
MYSQL_RES *mysql_use_result(MYSQL *mysql)
Description
After invoking mysql-query()
or mysql_real_query()
, you must call mysql-store-result()
or mysql_use_result()
for every statement that successfully produces a result set (SELECT
, SHOW
, DESCRIBE
, EXPLAIN
, CHECK TABLE
, and so forth). You must also call mysql_free_result()
after you are done with the result set.
mysql_use_result()
initiates a result set retrieval but does not actually read the result set into the client like mysql_store_result()
does. Instead, each row must be retrieved individually by making calls to mysql_fetch_row()
. This reads the result of a query directly from the server without storing it in a temporary table or local buffer, which is somewhat faster and uses much less memory than mysql_store_result()
. The client allocates memory only for the current row and a communication buffer that may grow up to max_allowed_packet
bytes.
On the other hand, you shouldn't use mysql_use_result()
if you are doing a lot of processing for each row on the client side, or if the output is sent to a screen on which the user may type a ^S
(stop scroll). This ties up the server and prevent other threads from updating any tables from which the data is being fetched.
When using mysql-use-result()
, you must execute mysql_fetch_row()
until a NULL
value is returned, otherwise, the unfetched rows are returned as part of the result set for your next query. The C API gives the error Commands out of sync; you can't run this command now
if you forget to do this!
You may not use mysql-data-seek()
, mysql_row_seek()
, mysql-row-tell()
, mysql_num_rows()
, or mysql_affected_rows()
with a result returned from mysql-use-result()
, nor may you issue other queries until mysql_use_result()
has finished. (However, after you have fetched all the rows, mysql_num_rows()
accurately returns the number of rows fetched.)
You must call mysql_free_result()
once you are done with the result set.
When using the libmysqld
embedded server, the memory benefits are essentially lost because memory usage incrementally increases with each row retrieved until mysql_free_result()
is called.
Return Values
A MYSQL_RES
result structure. NULL
if an error occurred.
Errors
mysql-use-result()
resets mysql_error()
and mysql_errno()
if it succeeds.
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_OUT_OF_MEMORY
Out of memory.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_warning_count()
unsigned int mysql_warning_count(MYSQL *mysql)
Description
Returns the number of errors, warnings, and notes generated during execution of the previous SQL statement.
Return Values
The warning count.
Errors
None.
C API Prepared Statements
The MariaDB client/server protocol provides for the use of prepared statements. This capability uses the MYSQL_STMT
statement handler data structure returned by the mysql_stmt_init()
initialization function. Prepared execution is an efficient way to execute a statement more than once. The statement is first parsed to prepare it for execution. Then it is executed one or more times at a later time, using the statement handle returned by the initialization function.
Prepared execution is faster than direct execution for statements executed more than once, primarily because the query is parsed only once. In the case of direct execution, the query is parsed every time it is executed. Prepared execution also can provide a reduction of network traffic because for each execution of the prepared statement, it is necessary only to send the data for the parameters.
Prepared statements might not provide a performance increase in some situations. For best results, test your application both with prepared and nonprepared statements and choose whichever yields best performance.
Another advantage of prepared statements is that it uses a binary protocol that makes data transfer between client and server more efficient.
The following SQL statements can be used as prepared statements:
CALL CREATE TABLE DELETE DO INSERT REPLACE SELECT SET UPDATE ANALYZE TABLE OPTIMIZE TABLE REPAIR TABLE CACHE INDEX CHANGE MASTER CHECKSUM {TABLE | TABLES} {CREATE | RENAME | DROP} DATABASE {CREATE | RENAME | DROP} USER FLUSH {TABLE | TABLES | TABLES WITH READ LOCK | HOSTS | PRIVILEGES | LOGS | STATUS | MASTER | SLAVE | DES_KEY_FILE | USER_RESOURCES} GRANT REVOKE KILL LOAD INDEX INTO CACHE RESET {MASTER | SLAVE | QUERY CACHE} SHOW BINLOG EVENTS SHOW CREATE {PROCEDURE | FUNCTION | EVENT | TABLE | VIEW} SHOW {AUTHORS | CONTRIBUTORS | WARNINGS | ERRORS} SHOW {MASTER | BINARY} LOGS SHOW {MASTER | SLAVE} STATUS SLAVE {START | STOP} INSTALL PLUGIN UNINSTALL PLUGIN
Other statements are not yet supported in MariaDB 5.6.
Metadata changes to tables or views referred to by prepared statements are detected and cause automatic repreparation of the statement when it is next executed. For more information, see , "Automatic Prepared Statement Repreparation".
C API Prepared Statement Data Structures
Prepared statements use several data structures:
- To obtain a statement handle, pass a
MariaDB
connection handler tomysql_stmt_init()
, which returns a pointer to aMYSQL_STMT
data structure. This structure is used for further operations with the statement. To specify the statement to prepare, pass theMYSQL_STMT
pointer and the statement string tomysql_stmt_prepare()
. - To provide input parameters for a prepared statement, set up
MYSQL_BIND
structures and pass them tomysql_stmt_bind_param()
. To receive output column values, set upMYSQL_BIND
structures and pass them tomysql_stmt_bind_result()
. - The
MYSQL_TIME
structure is used to transfer temporal data in both directions.
The following discussion describes the prepared statement data types in detail. For examples that show how to use them, see , "mysql_stmt_execute()
", and , "mysql_stmt_fetch()
".
MYSQL_STMT
This structure is a handle for a prepared statement. A handle is created by calling
mysql_stmt_init()
, which returns a pointer to aMYSQL_STMT
. The handle is used for all subsequent operations with the statement until you close it withmysql_stmt_close()
, at which point the handle becomes invalid.The
MYSQL_STMT
structure has no members intended for application use. Applications should not try to copy aMYSQL_STMT
structure. There is no guarantee that such a copy will be usable.Multiple statement handles can be associated with a single connection. The limit on the number of handles depends on the available system resources.
MYSQL_BIND
This structure is used both for statement input (data values sent to the server) and output (result values returned from the server):
- For input, use
MYSQL_BIND
structures withmysql_stmt_bind_param()
to bind parameter data values to buffers for use bymysql_stmt_execute()
. - For output, use
MYSQL_BIND
structures withmysql_stmt_bind_result()
to bind buffers to result set columns, for use in fetching rows withmysql_stmt_fetch()
.
To use a
MYSQL_BIND
structure, zero its contents to initialize it, then set its members appropriately. For example, to declare and initialize an array of threeMYSQL_BIND
structures, use this code:MYSQL_BIND bind[3]; memset(bind, 0, sizeof(bind));
The
MYSQL_BIND
structure contains the following members for use by application programs. For several of the members, the manner of use depends on whether the structure is used for input or output.enum enum_field_types buffer_type
The type of the buffer. This member indicates the data type of the C language variable bound to a statement parameter or result set column. For input,
buffer_type
indicates the type of the variable containing the value to be sent to the server. For output, it indicates the type of the variable into which a value received from the server should be stored. For permissiblebuffer_type
values, see , "C API Prepared Statement Type Codes".void *buffer
A pointer to the buffer to be used for data transfer. This is the address of a C language variable.
For input,
buffer
is a pointer to the variable in which you store the data value for a statement parameter. When you callmysql_stmt_execute()
, MariaDB use the value stored in the variable in place of the corresponding parameter marker in the statement (specified with?
in the statement string).For output,
buffer
is a pointer to the variable in which to return a result set column value. When you callmysql_stmt_fetch()
, MariaDB stores a column value from the current row of the result set in this variable. You can access the value when the call returns.To minimize the need for MariaDB to perform type conversions between C language values on the client side and SQL values on the server side, use C variables that have types similar to those of the corresponding SQL values:
- For numeric data types,
buffer
should point to a variable of the proper numeric C type. For integer variables (which can bechar
for single-byte values or an integer type for larger values), you should also indicate whether the variable has theunsigned
attribute by setting theis_unsigned
member, described later. - For character (nonbinary) and binary string data types,
buffer
should point to a character buffer. - For date and time data types,
buffer
should point to aMYSQL_TIME
structure.
For guidelines about mapping between C types and SQL types and notes about type conversions, see , "C API Prepared Statement Type Codes", and , "C API Prepared Statement Type Conversions".
- For numeric data types,
unsigned long buffer_length
The actual size of
*buffer
in bytes. This indicates the maximum amount of data that can be stored in the buffer. For character and binary C data, thebuffer_length
value specifies the length of*buffer
when used withmysql_stmt_bind_param()
to specify input values, or the maximum number of output data bytes that can be fetched into the buffer when used withmysql_stmt_bind_result()
.unsigned long *length
A pointer to an
unsigned long
variable that indicates the actual number of bytes of data stored in*buffer
.length
is used for character or binary C data.For input parameter data binding, set
*length
to indicate the actual length of the parameter value stored in*buffer
. This is used bymysql_stmt_execute()
.For output value binding, MariaDB sets
*length
when you callmysql_stmt_fetch()
. Themysql_stmt_fetch()
return value determines how to interpret the length:- If the return value is 0,
*length
indicates the actual length of the parameter value. - If the return value is
MYSQL_DATA_TRUNCATED
,*length
indicates the nontruncated length of the parameter value. In this case, the minimum of*length
andbuffer_length
indicates the actual length of the value.
length
is ignored for numeric and temporal data types because thebuffer_type
value determines the length of the data value.If you must determine the length of a returned value before fetching it, see , "
mysql_stmt_fetch()
", for some strategies.- If the return value is 0,
my_bool *is_null
This member points to a
my_bool
variable that is true if a value isNULL
, false if it is notNULL
. For input, set*is_null
to true to indicate that you are passing aNULL
value as a statement parameter.is_null
is a pointer to a boolean scalar, not a boolean scalar, to provide flexibility in how you specifyNULL
values:- If your data values are always
NULL
, useMYSQL_TYPE_NULL
as thebuffer_type
value when you bind the column. The otherMYSQL_BIND
members, includingis_null
, do not matter. - If your data values are always
NOT NULL
, setis_null = (my_bool*) 0
, and set the other members appropriately for the variable you are binding. - In all other cases, set the other members appropriately and set
is_null
to the address of amy_bool
variable. Set that variable's value to true or false appropriately between executions to indicate whether the corresponding data value isNULL
orNOT NULL
, respectively.
For output, when you fetch a row, MariaDB sets the value pointed to by
is_null
to true or false according to whether the result set column value returned from the statement is or is notNULL
.- If your data values are always
my_bool is_unsigned
This member applies for C variables with data types that can be
unsigned
(char
,short int
,int
,long long int
). Setis_unsigned
to true if the variable pointed to bybuffer
isunsigned
and false otherwise. For example, if you bind asigned char
variable tobuffer
, specify a type code ofMYSQL_TYPE_TINY
and setis_unsigned
to false. If you bind anunsigned char
instead, the type code is the same butis_unsigned
should be true. (Forchar
, it is not defined whether it is signed or unsigned, so it is best to be explicit about signedness by usingsigned char
orunsigned char
.)is_unsigned
applies only to the C language variable on the client side. It indicates nothing about the signedness of the corresponding SQL value on the server side. For example, if you use anint
variable to supply a value for aBIGINT UNSIGNED
column,is_unsigned
should be false becauseint
is a signed type. If you use anunsigned int
variable to supply a value for aBIGINT
column,is_unsigned
should be true becauseunsigned int
is an unsigned type. MariaDB performs the proper conversion between signed and unsigned values in both directions, although a warning occurs if truncation results.my_bool *error
For output, set this member to point to a
my_bool
variable to have truncation information for the parameter stored there after a row fetching operation. When truncation reporting is enabled,mysql_stmt_fetch()
returnsMYSQL_DATA_TRUNCATED
and*error
is true in theMYSQL_BIND
structures for parameters in which truncation occurred. Truncation indicates loss of sign or significant digits, or that a string was too long to fit in a column. Truncation reporting is enabled by default, but can be controlled by callingmysql_options()
with theMYSQL_REPORT_DATA_TRUNCATION
option.
- For input, use
MYSQL_TIME
This structure is used to send and receive
DATE
,TIME
,DATETIME
, andTIMESTAMP
data directly to and from the server. Set thebuffer
member to point to aMYSQL_TIME
structure, and set thebuffer_type
member of aMYSQL_BIND
structure to one of the temporal types (MYSQL_TYPE_TIME
,MYSQL_TYPE_DATE
,MYSQL_TYPE_DATETIME
,MYSQL_TYPE_TIMESTAMP
).The
MYSQL_TIME
structure contains the members listed in the following table.Member Description unsigned int year
The year unsigned int month
The month of the year unsigned int day
The day of the month unsigned int hour
The hour of the day unsigned int minute
The minute of the hour unsigned int second
The second of the minute my_bool neg
A boolean flag indicating whether the time is negative unsigned long second_part
The fractional part of the second in microseconds (unused before MariaDB 5.6.4) Only those parts of a
MYSQL_TIME
structure that apply to a given type of temporal value are used. Theyear
,month
, andday
elements are used forDATE
,DATETIME
, andTIMESTAMP
values. Thehour
,minute
, andsecond
elements are used forTIME
,DATETIME
, andTIMESTAMP
values. See , "C API Prepared Statement Handling of Date and Time Values".
C API Prepared Statement Type Codes
The buffer_type
member of MYSQL_BIND
structures indicates the data type of the C language variable bound to a statement parameter or result set column. For input, buffer_type
indicates the type of the variable containing the value to be sent to the server. For output, it indicates the type of the variable into which a value received from the server should be stored.
The following table shows the permissible values for the buffer_type
member of MYSQL_BIND
structures for input values sent to the server. The table shows the C variable types that you can use, the corresponding type codes, and the SQL data types for which the supplied value can be used without conversion. Choose the buffer_type
value according to the data type of the C language variable that you are binding. For the integer types, you should also set the is_unsigned
member to indicate whether the variable is signed or unsigned.
Input Variable C Type | buffer_type Value
| SQL Type of Destination Value |
---|---|---|
signed char
| MYSQL_TYPE_TINY
| TINYINT
|
short int
| MYSQL_TYPE_SHORT
| SMALLINT
|
int
| MYSQL_TYPE_LONG
| INT
|
long long int
| MYSQL_TYPE_LONGLONG
| BIGINT
|
float
| MYSQL_TYPE_FLOAT
| FLOAT
|
double
| MYSQL_TYPE_DOUBLE
| DOUBLE
|
MYSQL_TIME
| MYSQL_TYPE_TIME
| TIME
|
MYSQL_TIME
| MYSQL_TYPE_DATE
| DATE
|
MYSQL_TIME
| MYSQL_TYPE_DATETIME
| DATETIME
|
MYSQL_TIME
| MYSQL_TYPE_TIMESTAMP
| TIMESTAMP
|
char[]
| MYSQL_TYPE_STRING
| TEXT , CHAR , VARCHAR
|
char[]
| MYSQL_TYPE_BLOB
| BLOB , BINARY , VARBINARY
|
MYSQL_TYPE_NULL
| NULL |
Use MYSQL_TYPE_NULL
as indicated in the description for the is_null
member in , "C API Prepared Statement Data Structures".
For input string data, use MYSQL_TYPE_STRING
or MYSQL_TYPE_BLOB
depending on whether the value is a character (nonbinary) or binary string:
MYSQL_TYPE_STRING
indicates character input string data. The value is assumed to be in the character set indicated by thecharacter_set_client
system variable. If the server stores the value into a column with a different character set, it converts the value to that character set.MYSQL_TYPE_BLOB
indicates binary input string data. The value is treated as having thebinary
character set. That is, it is treated as a byte string and no conversion occurs.
The following table shows the permissible values for the buffer_type
member of MYSQL_BIND
structures for output values received from the server. The table shows the SQL types of received values, the corresponding type codes that such values have in result set metadata, and the recommended C language data types to bind to the MYSQL_BIND
structure to receive the SQL values without conversion. Choose the buffer_type
value according to the data type of the C language variable that you are binding. For the integer types, you should also set the is_unsigned
member to indicate whether the variable is signed or unsigned.
SQL Type of Received Value | buffer_type Value
| Output Variable C Type |
---|---|---|
TINYINT
| MYSQL_TYPE_TINY
| signed char
|
SMALLINT
| MYSQL_TYPE_SHORT
| short int
|
MEDIUMINT
| MYSQL_TYPE_INT24
| int
|
INT
| MYSQL_TYPE_LONG
| int
|
BIGINT
| MYSQL_TYPE_LONGLONG
| long long int
|
FLOAT
| MYSQL_TYPE_FLOAT
| float
|
DOUBLE
| MYSQL_TYPE_DOUBLE
| double
|
DECIMAL
| MYSQL_TYPE_NEWDECIMAL
| char[]
|
YEAR
| MYSQL_TYPE_SHORT
| short int
|
TIME
| MYSQL_TYPE_TIME
| MYSQL_TIME
|
DATE
| MYSQL_TYPE_DATE
| MYSQL_TIME
|
DATETIME
| MYSQL_TYPE_DATETIME
| MYSQL_TIME
|
TIMESTAMP
| MYSQL_TYPE_TIMESTAMP
| MYSQL_TIME
|
CHAR , BINARY
| MYSQL_TYPE_STRING
| char[]
|
VARCHAR , VARBINARY
| MYSQL_TYPE_VAR_STRING
| char[]
|
TINYBLOB , TINYTEXT
| MYSQL_TYPE_TINY_BLOB
| char[]
|
BLOB , TEXT
| MYSQL_TYPE_BLOB
| char[]
|
MEDIUMBLOB , MEDIUMTEXT
| MYSQL_TYPE_MEDIUM_BLOB
| char[]
|
LONGBLOB , LONGTEXT
| MYSQL_TYPE_LONG_BLOB
| char[]
|
BIT
| MYSQL_TYPE_BIT
| char[] |
C API Prepared Statement Type Conversions
Prepared statements transmit data between the client and server using C language variables on the client side that correspond to SQL values on the server side. If there is a mismatch between the C variable type on the client side and the corresponding SQL value type on the server side, MariaDB performs implicit type conversions in both directions.
MySQL knows the type code for the SQL value on the server side. The buffer_type
value in the MYSQL_BIND
structure indicates the type code of the C variable that holds the value on the client side. The two codes together tell MariaDB what conversion must be performed, if any. Here are some examples:
- If you use
MYSQL_TYPE_LONG
with anint
variable to pass an integer value to the server that is to be stored into aFLOAT
column, MariaDB converts the value to floating-point format before storing it. - If you fetch an SQL
MEDIUMINT
column value, but specify abuffer_type
value ofMYSQL_TYPE_LONGLONG
and use a C variable of typelong long int
as the destination buffer, MariaDB converts theMEDIUMINT
value (which requires less than 8 bytes) for storage into thelong long int
(an 8-byte variable). - If you fetch a numeric column with a value of 255 into a
char[4]
character array and specify abuffer_type
value ofMYSQL_TYPE_STRING
, the resulting value in the array is a 4-byte string'255\0'
. - MySQL returns
DECIMAL
values as the string representation of the original server-side value, which is why the corresponding C type ischar[]
. For example,12.345
is returned to the client as'12.345'
. If you specifyMYSQL_TYPE_NEWDECIMAL
and bind a string buffer to theMYSQL_BIND
structure,mysql_stmt_fetch()
stores the value in the buffer as a string without conversion. If instead you specify a numeric variable and type code,mysql-stmt-fetch()
converts the string-formatDECIMAL
value to numeric form. - For the
MYSQL_TYPE_BIT
type code,BIT
values are returned into a string buffer, which is why the corresponding C type ischar[]
. The value represents a bit string that requires interpretation on the client side. To return the value as a type that is easier to deal with, you can cause the value to be cast to integer using either of the following types of expressions:SELECT bit_col + 0 FROM t SELECT CAST(bit_col AS UNSIGNED) FROM t
To retrieve the value, bind an integer variable large enough to hold the value and specify the appropriate corresponding integer type code.
Before binding variables to the MYSQL_BIND
structures that are to be used for fetching column values, you can check the type codes for each column of the result set. This might be desirable if you want to determine which variable types would be best to use to avoid type conversions. To get the type codes, call mysql_stmt_result_metadata()
after executing the prepared statement with mysql_stmt_execute()
. The metadata provides access to the type codes for the result set as described in , "mysql_stmt_result_metadata()
", and , "C API Data Structures".
To determine whether output string values in a result set returned from the server contain binary or nonbinary data, check whether the charsetnr
value of the result set metadata is 63 (see , "C API Data Structures"). If so, the character set is binary
, which indicates binary rather than nonbinary data. This enables you to distinguish BINARY
from CHAR
, VARBINARY
from VARCHAR
, and the BLOB
types from the TEXT
types.
If you cause the max_length
member of the MYSQL_FIELD
column metadata structures to be set (by calling mysql_stmt_attr_set()
), be aware that the max_length
values for the result set indicate the lengths of the longest string representation of the result values, not the lengths of the binary representation. That is, max_length
does not necessarily correspond to the size of the buffers needed to fetch the values with the binary protocol used for prepared statements. Choose the size of the buffers according to the types of the variables into which you fetch the values. For example, a TINYINT
column containing the value -128 might have a max_length
value of 4. But the binary representation of any TINYINT
value requires only 1 byte for storage, so you can supply a signed char
variable in which to store the value and set is_unsigned
to indicate that values are signed.
Metadata changes to tables or views referred to by prepared statements are detected and cause automatic repreparation of the statement when it is next executed. For more information, see , "Automatic Prepared Statement Repreparation".
C API Prepared Statement Function Overview
The functions available for prepared statement processing are summarized here and described in greater detail in a later section. See , "C API Prepared Statement Function Descriptions".
Function | Description |
---|---|
mysql_stmt_affected_rows()
| Returns the number of rows changed, deleted, or inserted by prepared UPDATE , DELETE , or INSERT statement
|
mysql_stmt_attr_get()
| Gets value of an attribute for a prepared statement |
mysql_stmt_attr_set()
| Sets an attribute for a prepared statement |
mysql_stmt_bind_param()
| Associates application data buffers with the parameter markers in a prepared SQL statement |
mysql_stmt_bind_result()
| Associates application data buffers with columns in a result set |
mysql_stmt_close()
| Frees memory used by a prepared statement |
mysql_stmt_data_seek()
| Seeks to an arbitrary row number in a statement result set |
mysql_stmt_errno()
| Returns the error number for the last statement execution |
mysql_stmt_error()
| Returns the error message for the last statement execution |
mysql_stmt_execute()
| Executes a prepared statement |
mysql_stmt_fetch()
| Fetches the next row of data from a result set and returns data for all bound columns |
mysql_stmt_fetch_column()
| Fetch data for one column of the current row of a result set |
mysql_stmt_field_count()
| Returns the number of result columns for the most recent statement |
mysql_stmt_free_result()
| Free the resources allocated to a statement handle |
mysql_stmt_init()
| Allocates memory for a MYSQL_STMT structure and initializes it
|
mysql_stmt_insert_id()
| Returns the ID generated for an AUTO_INCREMENT column by a prepared statement
|
mysql_stmt_next_result()
| Returns/initiates the next result in a multiple-result execution |
mysql_stmt_num_rows()
| Returns the row count from a buffered statement result set |
mysql_stmt_param_count()
| Returns the number of parameters in a prepared statement |
mysql_stmt_param_metadata()
| (Return parameter metadata in the form of a result set) Currently, this function does nothing |
mysql_stmt_prepare()
| Prepares an SQL statement string for execution |
mysql_stmt_reset()
| Resets the statement buffers in the server |
mysql_stmt_result_metadata()
| Returns prepared statement metadata in the form of a result set |
mysql_stmt_row_seek()
| Seeks to a row offset in a statement result set, using value returned from mysql_stmt_row_tell()
|
mysql_stmt_row_tell()
| Returns the statement row cursor position |
mysql_stmt_send_long_data()
| Sends long data in chunks to server |
mysql_stmt_sqlstate()
| Returns the SQLSTATE error code for the last statement execution |
mysql_stmt_store_result()
| Retrieves a complete result set to the client |
Call mysql-stmt-init()
to create a statement handle, then mysql_stmt_prepare()
to prepare the statement string, mysql_stmt_bind_param()
to supply the parameter data, and mysql_stmt_execute()
to execute the statement. You can repeat the mysql_stmt_execute()
by changing parameter values in the respective buffers supplied through mysql_stmt_bind_param()
.
You can send text or binary data in chunks to server using mysql_stmt_send_long_data()
. See , "mysql_stmt_send_long_data()
".
If the statement is a SELECT
or any other statement that produces a result set, mysql_stmt_prepare()
also returns the result set metadata information in the form of a MYSQL_RES
result set through mysql_stmt_result_metadata()
.
You can supply the result buffers using mysql_stmt_bind_result()
, so that the mysql_stmt_fetch()
automatically returns data to these buffers. This is row-by-row fetching.
When statement execution has been completed, close the statement handle using mysql_stmt_close()
so that all resources associated with it can be freed.
If you obtained a SELECT
statement's result set metadata by calling mysql_stmt_result_metadata()
, you should also free the metadata using mysql_free_result()
.
Execution Steps
To prepare and execute a statement, an application follows these steps:
- Create a prepared statement handle with
mysql_stmt_init()
. To prepare the statement on the server, callmysql_stmt_prepare()
and pass it a string containing the SQL statement. - If the statement will produce a result set, call
mysql_stmt_result_metadata()
to obtain the result set metadata. This metadata is itself in the form of result set, albeit a separate one from the one that contains the rows returned by the query. The metadata result set indicates how many columns are in the result and contains information about each column. - Set the values of any parameters using
mysql_stmt_bind_param()
. All parameters must be set. Otherwise, statement execution returns an error or produces unexpected results. - Call
mysql_stmt_execute()
to execute the statement. - If the statement produces a result set, bind the data buffers to use for retrieving the row values by calling
mysql_stmt_bind_result()
. - Fetch the data into the buffers row by row by calling
mysql_stmt_fetch()
repeatedly until no more rows are found. - Repeat steps 3 through 6 as necessary, by changing the parameter values and re-executing the statement.
When mysql_stmt_prepare()
is called, the MariaDB client/server protocol performs these actions:
- The server parses the statement and sends the okay status back to the client by assigning a statement ID. It also sends total number of parameters, a column count, and its metadata if it is a result set oriented statement. All syntax and semantics of the statement are checked by the server during this call.
- The client uses this statement ID for the further operations, so that the server can identify the statement from among its pool of statements.
When mysql_stmt_execute()
is called, the MariaDB client/server protocol performs these actions:
- The client uses the statement handle and sends the parameter data to the server.
- The server identifies the statement using the ID provided by the client, replaces the parameter markers with the newly supplied data, and executes the statement. If the statement produces a result set, the server sends the data back to the client. Otherwise, it sends an okay status and the number of rows changed, deleted, or inserted.
When mysql_stmt_fetch()
is called, the MariaDB client/server protocol performs these actions:
- The client reads the data from the current row of the result set and places it into the application data buffers by doing the necessary conversions. If the application buffer type is same as that of the field type returned from the server, the conversions are straightforward.
If an error occurs, you can get the statement error number, error message, and SQLSTATE code using mysql_stmt_errno()
, mysql_stmt_error()
, and mysql_stmt_sqlstate()
, respectively.
Prepared Statement Logging
For prepared statements that are executed with the mysql-stmt-prepare()
and mysql_stmt_execute()
C API functions, the server writes Prepare
and Execute
lines to the general query log so that you can tell when statements are prepared and executed.
Suppose that you prepare and execute a statement as follows:
- Call
mysql_stmt_prepare()
to prepare the statement string'SELECT ?'
. - Call
mysql_stmt_bind_param()
to bind the value3
to the parameter in the prepared statement. - Call
mysql_stmt_execute()
to execute the prepared statement.
As a result of the preceding calls, the server writes the following lines to the general query log:
Prepare [1] SELECT ? Execute [1] SELECT 3
Each Prepare
and Execute
line in the log is tagged with a [
statement identifier so that you can keep track of which prepared statement is being logged. N
]N
is a positive integer. If there are multiple prepared statements active simultaneously for the client, N
may be greater than 1. Each Execute
lines shows a prepared statement after substitution of data values for ?
parameters.
C API Prepared Statement Function Descriptions
mysql_stmt_affected_rows()
mysql_stmt_attr_get()
mysql_stmt_attr_set()
mysql_stmt_bind_param()
mysql_stmt_bind_result()
mysql_stmt_close()
mysql_stmt_data_seek()
mysql_stmt_errno()
mysql_stmt_error()
mysql_stmt_execute()
mysql_stmt_fetch()
mysql_stmt_fetch_column()
mysql_stmt_field_count()
mysql_stmt_free_result()
mysql_stmt_init()
mysql_stmt_insert_id()
mysql_stmt_next_result()
mysql_stmt_num_rows()
mysql_stmt_param_count()
mysql_stmt_param_metadata()
mysql_stmt_prepare()
mysql_stmt_reset()
mysql_stmt_result_metadata()
mysql_stmt_row_seek()
mysql_stmt_row_tell()
mysql_stmt_send_long_data()
mysql_stmt_sqlstate()
mysql_stmt_store_result()
To prepare and execute queries, use the functions described in detail in the following sections.
All functions that operate with a MYSQL_STMT
structure begin with the prefix mysql_stmt_
.
To create a MYSQL_STMT
handle, use the mysql_stmt_init()
function.
mysql_stmt_affected_rows()
my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)
Description
mysql_stmt_affected_rows()
may be called immediately after executing a statement with mysql_stmt_execute()
. It is like mysql_affected_rows()
but for prepared statements. For a description of what the affected-rows value returned by this function means, See , "mysql_affected_rows()
".
Errors
None.
Example
See the Example in , "mysql_stmt_execute()
".
mysql_stmt_attr_get()
my_bool mysql_stmt_attr_get(MYSQL_STMT *stmt, enum enum_stmt_attr_type option, void *arg)
Description
Can be used to get the current value for a statement attribute.
The option
argument is the option that you want to get; the arg
should point to a variable that should contain the option value. If the option is an integer, arg
should point to the value of the integer.
See , "mysql_stmt_attr_set()
", for a list of options and option types.
Return Values
Zero if successful. Nonzero if option
is unknown.
Errors
None.
mysql_stmt_attr_set()
my_bool mysql_stmt_attr_set(MYSQL_STMT *stmt, enum enum_stmt_attr_type option, const void *arg)
Description
Can be used to affect behavior for a prepared statement. This function may be called multiple times to set several options.
The option
argument is the option that you want to set. The arg
argument is the value for the option. arg
should point to a variable that is set to the desired attribute value. The variable type is as indicated in the following table.
The following table shows the possible option
values.
Option | Argument Type | Function |
---|---|---|
STMT_ATTR_UPDATE_MAX_LENGTH
| my_bool *
| If set to 1, causes mysql_stmt_store_result() to update the metadata MYSQL_FIELD->max_length value.
|
STMT_ATTR_CURSOR_TYPE
| unsigned long *
| Type of cursor to open for statement when mysql_stmt_execute() is invoked. *arg can be CURSOR_TYPE_NO_CURSOR (the default) or CURSOR_TYPE_READ_ONLY .
|
STMT_ATTR_PREFETCH_ROWS
| unsigned long *
| Number of rows to fetch from server at a time when using a cursor. *arg can be in the range from 1 to the maximum value of unsigned long . The default is 1. |
If you use the STMT_ATTR_CURSOR_TYPE
option with CURSOR_TYPE_READ_ONLY
, a cursor is opened for the statement when you invoke mysql_stmt_execute()
. If there is already an open cursor from a previous mysql_stmt_execute()
call, it closes the cursor before opening a new one. mysql_stmt_reset()
also closes any open cursor before preparing the statement for re-execution. mysql_stmt_free_result()
closes any open cursor.
If you open a cursor for a prepared statement, mysql_stmt_store_result()
is unnecessary, because that function causes the result set to be buffered on the client side.
Return Values
Zero if successful. Nonzero if option
is unknown.
Errors
None.
Example
The following example opens a cursor for a prepared statement and sets the number of rows to fetch at a time to 5:
MYSQL_STMT *stmt; int rc; unsigned long type; unsigned long prefetch_rows = 5; stmt = mysql_stmt_init(mysql); type = (unsigned long) CURSOR_TYPE_READ_ONLY; rc = mysql_stmt_attr_set(stmt, STMT_ATTR_CURSOR_TYPE, (void*) &type); /* ... check return value ... */ rc = mysql_stmt_attr_set(stmt, STMT_ATTR_PREFETCH_ROWS, (void*) &prefetch_rows); /* ... check return value ... */
mysql_stmt_bind_param()
my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)
Description
mysql_stmt_bind_param()
is used to bind input data for the parameter markers in the SQL statement that was passed to mysql_stmt_prepare()
. It uses MYSQL_BIND
structures to supply the data. bind
is the address of an array of MYSQL_BIND
structures. The client library expects the array to contain one element for each "?
" parameter marker that is present in the query.
Suppose that you prepare the following statement:
INSERT INTO mytbl VALUES(?,?,?)
When you bind the parameters, the array of MYSQL_BIND
structures must contain three elements, and can be declared like this:
MYSQL_BIND bind[3];
, "C API Prepared Statement Data Structures", describes the members of each MYSQL_BIND
element and how they should be set to provide input values.
Return Values
Zero if the bind operation was successful. Nonzero if an error occurred.
Errors
CR_UNSUPPORTED_PARAM_TYPE
The conversion is not supported. Possibly the
buffer_type
value is illegal or is not one of the supported types.CR_OUT_OF_MEMORY
Out of memory.
CR_UNKNOWN_ERROR
An unknown error occurred.
Example
See the Example in , "mysql_stmt_execute()
".
mysql_stmt_bind_result()
my_bool mysql_stmt_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)
Description
mysql_stmt_bind_result()
is used to associate (that is, bind) output columns in the result set to data buffers and length buffers. When mysql_stmt_fetch()
is called to fetch data, the MariaDB client/server protocol places the data for the bound columns into the specified buffers.
All columns must be bound to buffers prior to calling mysql_stmt_fetch()
. bind
is the address of an array of MYSQL_BIND
structures. The client library expects the array to contain one element for each column of the result set. If you do not bind columns to MYSQL_BIND
structures, mysql_stmt_fetch()
simply ignores the data fetch. The buffers should be large enough to hold the data values, because the protocol doesn't return data values in chunks.
A column can be bound or rebound at any time, even after a result set has been partially retrieved. The new binding takes effect the next time mysql_stmt_fetch()
is called. Suppose that an application binds the columns in a result set and calls mysql_stmt_fetch()
. The client/server protocol returns data in the bound buffers. Then suppose that the application binds the columns to a different set of buffers. The protocol places data into the newly bound buffers when the next call to mysql_stmt_fetch()
occurs.
To bind a column, an application calls mysql_stmt_bind_result()
and passes the type, address, and length of the output buffer into which the value should be stored. , "C API Prepared Statement Data Structures", describes the members of each MYSQL_BIND
element and how they should be set to receive output values.
Return Values
Zero if the bind operation was successful. Nonzero if an error occurred.
Errors
CR_UNSUPPORTED_PARAM_TYPE
The conversion is not supported. Possibly the
buffer_type
value is illegal or is not one of the supported types.CR_OUT_OF_MEMORY
Out of memory.
CR_UNKNOWN_ERROR
An unknown error occurred.
Example
See the Example in , "mysql_stmt_fetch()
".
mysql_stmt_close()
my_bool mysql_stmt_close(MYSQL_STMT *)
Description
Closes the prepared statement. mysql_stmt_close()
also deallocates the statement handle pointed to by stmt
.
If the current statement has pending or unread results, this function cancels them so that the next query can be executed.
Return Values
Zero if the statement was freed successfully. Nonzero if an error occurred.
Errors
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_UNKNOWN_ERROR
An unknown error occurred.
Example
See the Example in , "mysql_stmt_execute()
".
mysql_stmt_data_seek()
void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset)
Description
Seeks to an arbitrary row in a statement result set. The offset
value is a row number and should be in the range from 0
to mysql_stmt_num_rows(stmt)-1
.
This function requires that the statement result set structure contains the entire result of the last executed query, so mysql_stmt_data_seek()
may be used only in conjunction with mysql_stmt_store_result()
.
Return Values
None.
Errors
None.
mysql_stmt_errno()
unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)
Description
For the statement specified by stmt
, mysql_stmt_errno()
returns the error code for the most recently invoked statement API function that can succeed or fail. A return value of zero means that no error occurred. Client error message numbers are listed in the MariaDB errmsg.h
header file. Server error message numbers are listed in mysqld_error.h
. Errors also are listed at Appendix C, Errors, Error Codes, and Common Problems.
Return Values
An error code value. Zero if no error occurred.
Errors
None.
mysql_stmt_error()
const char *mysql_stmt_error(MYSQL_STMT *stmt)
Description
For the statement specified by stmt
, mysql_stmt_error()
returns a null-terminated string containing the error message for the most recently invoked statement API function that can succeed or fail. An empty string (''
) is returned if no error occurred. This means the following two tests are equivalent:
if(*mysql_stmt_errno(stmt)) { // an error occurred } if (mysql_stmt_error(stmt)[0]) { // an error occurred }
The language of the client error messages may be changed by recompiling the MariaDB client library. Currently, you can choose error messages in several different languages.
Return Values
A character string that describes the error. An empty string if no error occurred.
Errors
None.
mysql_stmt_execute()
int mysql_stmt_execute(MYSQL_STMT *stmt)
Description
mysql_stmt_execute()
executes the prepared query associated with the statement handle. The currently bound parameter marker values are sent to server during this call, and the server replaces the markers with this newly supplied data.
Statement processing following mysql_stmt_execute()
depends on the type of statement:
- For an
UPDATE
,DELETE
, orINSERT
, the number of changed, deleted, or inserted rows can be found by callingmysql_stmt_affected_rows()
. - For a statement such as
SELECT
that generates a result set, you must callmysql_stmt_fetch()
to fetch the data prior to calling any other functions that result in query processing. For more information on how to fetch the results, refer to , "mysql_stmt_fetch()
".Do not following invocation of
mysql-stmt-execute()
with a call tomysql_store_result()
ormysql_use_result()
. Those functions are not intended for processing results from prepared statements.
For statements that generate a result set, you can request that mysql_stmt_execute()
open a cursor for the statement by calling mysql_stmt_attr_set()
before executing the statement. If you execute a statement multiple times, mysql_stmt_execute()
closes any open cursor before opening a new one.
Metadata changes to tables or views referred to by prepared statements are detected and cause automatic repreparation of the statement when it is next executed. For more information, see , "Automatic Prepared Statement Repreparation".
Return Values
Zero if execution was successful. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_OUT_OF_MEMORY
Out of memory.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
Example
The following example demonstrates how to create and populate a table using mysql_stmt_init()
, mysql_stmt_prepare()
, mysql_stmt_param_count()
, mysql-stmt-bind-param()
, mysql_stmt_execute()
, and mysql_stmt_affected_rows()
. The MariaDB
variable is assumed to be a valid connection handle. For an example that shows how to retrieve data, see , "mysql_stmt_fetch()
".
#define STRING_SIZE 50 #define DROP_SAMPLE_TABLE 'DROP TABLE IF EXISTS test_table' #define CREATE_SAMPLE_TABLE 'CREATE TABLE test_table(col1 INT,\ col2 VARCHAR(40),\ col3 SMALLINT,\ col4 TIMESTAMP)' #define INSERT_SAMPLE 'INSERT INTO \ test_table(col1,col2,col3) \ VALUES(?,?,?)' MYSQL_STMT *stmt; MYSQL_BIND bind[3]; my_ulonglong affected_rows; int param_count; short small_data; int int_data; char str_data[STRING_SIZE]; unsigned long str_length; my_bool is_null; if (mysql_query(mysql, DROP_SAMPLE_TABLE)) { fprintf(stderr, ' DROP TABLE failed\n'); fprintf(stderr, ' %s\n', mysql_error(mysql)); exit(0); } if (mysql_query(mysql, CREATE_SAMPLE_TABLE)) { fprintf(stderr, ' CREATE TABLE failed\n'); fprintf(stderr, ' %s\n', mysql_error(mysql)); exit(0); } /* Prepare an INSERT query with 3 parameters */ /* (the TIMESTAMP column is not named; the server */ /* sets it to the current date and time) */ stmt = mysql_stmt_init(mysql); if (!stmt) { fprintf(stderr, ' mysql_stmt_init(), out of memory\n'); exit(0); } if (mysql_stmt_prepare(stmt, INSERT_SAMPLE, strlen(INSERT_SAMPLE))) { fprintf(stderr, ' mysql_stmt_prepare(), INSERT failed\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); } fprintf(stdout, ' prepare, INSERT successful\n'); /* Get the parameter count from the statement */ param_count= mysql_stmt_param_count(stmt); fprintf(stdout, ' total parameters in INSERT: %d\n', param_count); if (param_count != 3) /* validate parameter count */ { fprintf(stderr, ' invalid parameter count returned by MySQL\n'); exit(0); } /* Bind the data for all 3 parameters */ memset(bind, 0, sizeof(bind)); /* INTEGER PARAM */ /* This is a number type, so there is no need to specify buffer_length */ bind[0].buffer_type= MYSQL_TYPE_LONG; bind[0].buffer= (char *)&int_data; bind[0].is_null= 0; bind[0].length= 0; /* STRING PARAM */ bind[1].buffer_type= MYSQL_TYPE_STRING; bind[1].buffer= (char *)str_data; bind[1].buffer_length= STRING_SIZE; bind[1].is_null= 0; bind[1].length= &str_length; /* SMALLINT PARAM */ bind[2].buffer_type= MYSQL_TYPE_SHORT; bind[2].buffer= (char *)&small_data; bind[2].is_null= &is_null; bind[2].length= 0; /* Bind the buffers */ if (mysql_stmt_bind_param(stmt, bind)) { fprintf(stderr, ' mysql_stmt_bind_param() failed\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); } /* Specify the data values for the first row */ int_data= 10; /* integer */ strncpy(str_data, 'MySQL', STRING_SIZE); /* string */ str_length= strlen(str_data); /* INSERT SMALLINT data as NULL */ is_null= 1; /* Execute the INSERT statement - 1*/ if (mysql_stmt_execute(stmt)) { fprintf(stderr, ' mysql_stmt_execute(), 1 failed\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); } /* Get the number of affected rows */ affected_rows= mysql_stmt_affected_rows(stmt); fprintf(stdout, ' total affected rows(insert 1): %lu\n', (unsigned long) affected_rows); if (affected_rows != 1) /* validate affected rows */ { fprintf(stderr, ' invalid affected rows by MySQL\n'); exit(0); } /* Specify data values for second row, then re-execute the statement */ int_data= 1000; strncpy(str_data, ' The most popular Open Source database', STRING_SIZE); str_length= strlen(str_data); small_data= 1000; /* smallint */ is_null= 0; /* reset */ /* Execute the INSERT statement - 2*/ if (mysql_stmt_execute(stmt)) { fprintf(stderr, ' mysql_stmt_execute, 2 failed\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); } /* Get the total rows affected */ affected_rows= mysql_stmt_affected_rows(stmt); fprintf(stdout, ' total affected rows(insert 2): %lu\n', (unsigned long) affected_rows); if (affected_rows != 1) /* validate affected rows */ { fprintf(stderr, ' invalid affected rows by MySQL\n'); exit(0); } /* Close the statement */ if (mysql_stmt_close(stmt)) { fprintf(stderr, ' failed while closing the statement\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); }Note
For complete examples on the use of prepared statement functions, refer to the file tests/mysql_client_test.c
. This file can be obtained from a MariaDB source distribution or from the Bazaar source repository.
mysql_stmt_fetch()
int mysql_stmt_fetch(MYSQL_STMT *stmt)
Description
mysql_stmt_fetch()
returns the next row in the result set. It can be called only while the result set exists; that is, after a call to mysql-stmt-execute()
for a statement such as SELECT
that produces a result set.
mysql-stmt-fetch()
returns row data using the buffers bound by mysql_stmt_bind_result()
. It returns the data in those buffers for all the columns in the current row set and the lengths are returned to the length
pointer. All columns must be bound by the application before it calls mysql_stmt_fetch()
.
By default, result sets are fetched unbuffered a row at a time from the server. To buffer the entire result set on the client, call mysql_stmt_store_result()
after binding the data buffers and before calling mysql_stmt_fetch()
.
If a fetched data value is a NULL
value, the *is_null
value of the corresponding MYSQL_BIND
structure contains TRUE (1). Otherwise, the data and its length are returned in the *buffer
and *length
elements based on the buffer type specified by the application. Each numeric and temporal type has a fixed length, as listed in the following table. The length of the string types depends on the length of the actual data value, as indicated by data_length
.
Type | Length |
---|---|
MYSQL_TYPE_TINY
| 1 |
MYSQL_TYPE_SHORT
| 2 |
MYSQL_TYPE_LONG
| 4 |
MYSQL_TYPE_LONGLONG
| 8 |
MYSQL_TYPE_FLOAT
| 4 |
MYSQL_TYPE_DOUBLE
| 8 |
MYSQL_TYPE_TIME
| sizeof(MYSQL_TIME)
|
MYSQL_TYPE_DATE
| sizeof(MYSQL_TIME)
|
MYSQL_TYPE_DATETIME
| sizeof(MYSQL_TIME)
|
MYSQL_TYPE_STRING
| data length
|
MYSQL_TYPE_BLOB
| data_length |
In some cases you might want to determine the length of a column value before fetching it with mysql_stmt_fetch()
. For example, the value might be a long string or BLOB
value for which you want to know how much space must be allocated. To accomplish this, you can use these strategies:
- Before invoking
mysql_stmt_fetch()
to retrieve individual rows, passSTMT_ATTR_UPDATE_MAX_LENGTH
tomysql-stmt-attr-set()
, then invokemysql_stmt_store_result()
to buffer the entire result on the client side. Setting theSTMT_ATTR_UPDATE_MAX_LENGTH
attribute causes the maximal length of column values to be indicated by themax_length
member of the result set metadata returned bymysql_stmt_result_metadata()
. - Invoke
mysql_stmt_fetch()
with a zero-length buffer for the column in question and a pointer in which the real length can be stored. Then use the real length withmysql_stmt_fetch_column()
.real_length= 0; bind[0].buffer= 0; bind[0].buffer_length= 0; bind[0].length= &real_length mysql_stmt_bind_result(stmt, bind); mysql_stmt_fetch(stmt); if (real_length > 0) { data= malloc(real_length); bind[0].buffer= data; bind[0].buffer_length= real_length; mysql_stmt_fetch_column(stmt, bind, 0, 0); }
Return Values
Return Value | Description |
---|---|
0 | Successful, the data has been fetched to application data buffers. |
1 | Error occurred. Error code and message can be obtained by calling mysql_stmt_errno() and mysql_stmt_error() .
|
MYSQL_NO_DATA
| No more rows/data exists |
MYSQL_DATA_TRUNCATED
| Data truncation occurred |
MYSQL_DATA_TRUNCATED
is returned when truncation reporting is enabled. To determine which column values were truncated when this value is returned, check the error
members of the MYSQL_BIND
structures used for fetching values. Truncation reporting is enabled by default, but can be controlled by calling mysql_options()
with the MYSQL_REPORT_DATA_TRUNCATION
option.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_OUT_OF_MEMORY
Out of memory.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
CR_UNSUPPORTED_PARAM_TYPE
The buffer type is
MYSQL_TYPE_DATE
,MYSQL_TYPE_TIME
,MYSQL_TYPE_DATETIME
, orMYSQL_TYPE_TIMESTAMP
, but the data type is notDATE
,TIME
,DATETIME
, orTIMESTAMP
.- All other unsupported conversion errors are returned from
mysql_stmt_bind_result()
.
Example
The following example demonstrates how to fetch data from a table using mysql_stmt_result_metadata()
, mysql_stmt_bind_result()
, and mysql_stmt_fetch()
. (This example expects to retrieve the two rows inserted by the example shown in , "mysql_stmt_execute()
".) The MariaDB
variable is assumed to be a valid connection handle.
#define STRING_SIZE 50 #define SELECT_SAMPLE 'SELECT col1, col2, col3, col4 \ FROM test_table' MYSQL_STMT *stmt; MYSQL_BIND bind[4]; MYSQL_RES *prepare_meta_result; MYSQL_TIME ts; unsigned long length[4]; int param_count, column_count, row_count; short small_data; int int_data; char str_data[STRING_SIZE]; my_bool is_null[4]; my_bool error[4]; /* Prepare a SELECT query to fetch data from test_table */ stmt = mysql_stmt_init(mysql); if (!stmt) { fprintf(stderr, ' mysql_stmt_init(), out of memory\n'); exit(0); } if (mysql_stmt_prepare(stmt, SELECT_SAMPLE, strlen(SELECT_SAMPLE))) { fprintf(stderr, ' mysql_stmt_prepare(), SELECT failed\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); } fprintf(stdout, ' prepare, SELECT successful\n'); /* Get the parameter count from the statement */ param_count= mysql_stmt_param_count(stmt); fprintf(stdout, ' total parameters in SELECT: %d\n', param_count); if (param_count != 0) /* validate parameter count */ { fprintf(stderr, ' invalid parameter count returned by MySQL\n'); exit(0); } /* Fetch result set meta information */ prepare_meta_result = mysql_stmt_result_metadata(stmt); if (!prepare_meta_result) { fprintf(stderr, ' mysql_stmt_result_metadata(), \ returned no meta information\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); } /* Get total columns in the query */ column_count= mysql_num_fields(prepare_meta_result); fprintf(stdout, ' total columns in SELECT statement: %d\n', column_count); if (column_count != 4) /* validate column count */ { fprintf(stderr, ' invalid column count returned by MySQL\n'); exit(0); } /* Execute the SELECT query */ if (mysql_stmt_execute(stmt)) { fprintf(stderr, ' mysql_stmt_execute(), failed\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); } /* Bind the result buffers for all 4 columns before fetching them */ memset(bind, 0, sizeof(bind)); /* INTEGER COLUMN */ bind[0].buffer_type= MYSQL_TYPE_LONG; bind[0].buffer= (char *)&int_data; bind[0].is_null= &is_null[0]; bind[0].length= &length[0]; bind[0].error= &error[0]; /* STRING COLUMN */ bind[1].buffer_type= MYSQL_TYPE_STRING; bind[1].buffer= (char *)str_data; bind[1].buffer_length= STRING_SIZE; bind[1].is_null= &is_null[1]; bind[1].length= &length[1]; bind[1].error= &error[1]; /* SMALLINT COLUMN */ bind[2].buffer_type= MYSQL_TYPE_SHORT; bind[2].buffer= (char *)&small_data; bind[2].is_null= &is_null[2]; bind[2].length= &length[2]; bind[2].error= &error[2]; /* TIMESTAMP COLUMN */ bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP; bind[3].buffer= (char *)&ts; bind[3].is_null= &is_null[3]; bind[3].length= &length[3]; bind[3].error= &error[3]; /* Bind the result buffers */ if (mysql_stmt_bind_result(stmt, bind)) { fprintf(stderr, ' mysql_stmt_bind_result() failed\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); } /* Now buffer all results to client (optional step) */ if (mysql_stmt_store_result(stmt)) { fprintf(stderr, ' mysql_stmt_store_result() failed\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); } /* Fetch all rows */ row_count= 0; fprintf(stdout, 'Fetching results ...\n'); while (!mysql_stmt_fetch(stmt)) { row_count++; fprintf(stdout, ' row %d\n', row_count); /* column 1 */ fprintf(stdout, ' column1 (integer) : '); if (is_null[0]) fprintf(stdout, ' NULL\n'); else fprintf(stdout, ' %d(%ld)\n', int_data, length[0]); /* column 2 */ fprintf(stdout, ' column2 (string) : '); if (is_null[1]) fprintf(stdout, ' NULL\n'); else fprintf(stdout, ' %s(%ld)\n', str_data, length[1]); /* column 3 */ fprintf(stdout, ' column3 (smallint) : '); if (is_null[2]) fprintf(stdout, ' NULL\n'); else fprintf(stdout, ' %d(%ld)\n', small_data, length[2]); /* column 4 */ fprintf(stdout, ' column4 (timestamp): '); if (is_null[3]) fprintf(stdout, ' NULL\n'); else fprintf(stdout, ' %04d-%02d-%02d %02d:%02d:%02d (%ld)\n', ts.year, ts.month, ts.day, ts.hour, ts.minute, ts.second, length[3]); fprintf(stdout, '\n'); } /* Validate rows fetched */ fprintf(stdout, ' total rows fetched: %d\n', row_count); if (row_count != 2) { fprintf(stderr, ' MariaDB failed to return all rows\n'); exit(0); } /* Free the prepared result metadata */ mysql_free_result(prepare_meta_result); /* Close the statement */ if (mysql_stmt_close(stmt)) { fprintf(stderr, ' failed while closing the statement\n'); fprintf(stderr, ' %s\n', mysql_stmt_error(stmt)); exit(0); }
mysql_stmt_fetch_column()
int mysql_stmt_fetch_column(MYSQL_STMT *stmt, MYSQL_BIND *bind, unsigned int column, unsigned long offset)
Description
Fetch one column from the current result set row. bind
provides the buffer where data should be placed. It should be set up the same way as for mysql_stmt_bind_result()
. column
indicates which column to fetch. The first column is numbered 0. offset
is the offset within the data value at which to begin retrieving data. This can be used for fetching the data value in pieces. The beginning of the value is offset 0.
Return Values
Zero if the value was fetched successfully. Nonzero if an error occurred.
Errors
CR_INVALID_PARAMETER_NO
Invalid column number.
CR_NO_DATA
The end of the result set has already been reached.
mysql_stmt_field_count()
unsigned int mysql_stmt_field_count(MYSQL_STMT *stmt)
Description
Returns the number of columns for the most recent statement for the statement handler. This value is zero for statements such as INSERT
or DELETE
that do not produce result sets.
mysql_stmt_field_count()
can be called after you have prepared a statement by invoking mysql_stmt_prepare()
.
Return Values
An unsigned integer representing the number of columns in a result set.
Errors
None.
mysql_stmt_free_result()
my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)
Description
Releases memory associated with the result set produced by execution of the prepared statement. If there is a cursor open for the statement, mysql_stmt_free_result()
closes it.
Return Values
Zero if the result set was freed successfully. Nonzero if an error occurred.
Errors
mysql_stmt_init()
MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)
Description
Create a MYSQL_STMT
handle. The handle should be freed with mysql_stmt_close(MYSQL_STMT *)
.
See also , "C API Prepared Statement Data Structures", for more information.
Return Values
A pointer to a MYSQL_STMT
structure in case of success. NULL
if out of memory.
Errors
CR_OUT_OF_MEMORY
Out of memory.
mysql_stmt_insert_id()
my_ulonglong mysql_stmt_insert_id(MYSQL_STMT *stmt)
Description
Returns the value generated for an AUTO_INCREMENT
column by the prepared INSERT
or UPDATE
statement. Use this function after you have executed a prepared INSERT
statement on a table which contains an AUTO_INCREMENT
field.
See , "mysql_insert_id()
", for more information.
Return Values
Value for AUTO_INCREMENT
column which was automatically generated or explicitly set during execution of prepared statement, or value generated by LAST_INSERT_ID(
function. Return value is undefined if statement does not set expr
)AUTO_INCREMENT
value.
Errors
None.
mysql_stmt_next_result()
int mysql_stmt_next_result(MYSQL_STMT *mysql)
Description
This function is used when you use prepared CALL
statements to execute stored procedures, which can return multiple result sets. Use a loop that calls mysql_stmt_next_result()
to determine whether there are more results. If a procedure has OUT
or INOUT
parameters, their values will be returned as a single-row result set following any other result sets. The values will appear in the order in which they are declared in the procedure parameter list.
mysql_stmt_next_result()
returns a status to indicate whether more results exist. If mysql_stmt_next_result()
returns an error, there are no more results.
Before each call to mysql-stmt-next-result()
, you must call mysql_stmt_free_result()
for the current result if it produced a result set (rather than just a result status).
After calling mysql_stmt_next_result()
the state of the connection is as if you had called mysql_stmt_execute()
. This means that you can call mysql_stmt_bind_result()
, mysql_stmt_affected_rows()
, and so forth.
It is also possible to test whether there are more results by calling mysql_more_results()
. However, this function does not change the connection state, so if it returns true, you must still call mysql_stmt_next_result()
to advance to the next result.
For an example that shows how to use mysql_stmt_next_result()
, see , "C API Support for Prepared CALL
Statements".
Return Values
Return Value | Description |
---|---|
0 | Successful and there are more results |
-1 | Successful and there are no more results |
>0 | An error occurred |
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_stmt_num_rows()
my_ulonglong mysql_stmt_num_rows(MYSQL_STMT *stmt)
Description
Returns the number of rows in the result set.
The use of mysql-stmt-num-rows()
depends on whether you used mysql_stmt_store_result()
to buffer the entire result set in the statement handle. If you use mysql_stmt_store_result()
, mysql_stmt_num_rows()
may be called immediately. Otherwise, the row count is unavailable unless you count the rows as you fetch them.
mysql-stmt-num-rows()
is intended for use with statements that return a result set, such as SELECT
. For statements such as INSERT
, UPDATE
, or DELETE
, the number of affected rows can be obtained with mysql_stmt_affected_rows()
.
Return Values
The number of rows in the result set.
Errors
None.
mysql_stmt_param_count()
unsigned long mysql_stmt_param_count(MYSQL_STMT *stmt)
Description
Returns the number of parameter markers present in the prepared statement.
Return Values
An unsigned long integer representing the number of parameters in a statement.
Errors
None.
Example
See the Example in , "mysql_stmt_execute()
".
mysql_stmt_param_metadata()
MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)
This function currently does nothing.
Description
Return Values
Errors
mysql_stmt_prepare()
int mysql_stmt_prepare(MYSQL_STMT *stmt, const char *stmt_str, unsigned long length)
Description
Given the statement handle returned by mysql_stmt_init()
, prepares the SQL statement pointed to by the string stmt_str
and returns a status value. The string length should be given by the length
argument. The string must consist of a single SQL statement. You should not add a terminating semicolon (";
") or \g
to the statement.
The application can include one or more parameter markers in the SQL statement by embedding question mark ("?
") characters into the SQL string at the appropriate positions.
The markers are legal only in certain places in SQL statements. For example, they are permitted in the VALUES()
list of an INSERT
statement (to specify column values for a row), or in a comparison with a column in a WHERE
clause to specify a comparison value. However, they are not permitted for identifiers (such as table or column names), or to specify both operands of a binary operator such as the =
equal sign. The latter restriction is necessary because it would be impossible to determine the parameter type. In general, parameters are legal only in Data Manipulation Language (DML) statements, and not in Data Definition Language (DDL) statements.
The parameter markers must be bound to application variables using mysql_stmt_bind_param()
before executing the statement.
Metadata changes to tables or views referred to by prepared statements are detected and cause automatic repreparation of the statement when it is next executed. For more information, see , "Automatic Prepared Statement Repreparation".
Return Values
Zero if the statement was prepared successfully. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_OUT_OF_MEMORY
Out of memory.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query
CR_UNKNOWN_ERROR
An unknown error occurred.
If the prepare operation was unsuccessful (that is, mysql_stmt_prepare()
returns nonzero), the error message can be obtained by calling mysql_stmt_error()
.
Example
See the Example in , "mysql_stmt_execute()
".
mysql_stmt_reset()
my_bool mysql_stmt_reset(MYSQL_STMT *stmt)
Description
Resets a prepared statement on client and server to state after prepare. It resets the statement on the server, data sent using mysql_stmt_send_long_data()
, unbuffered result sets and current errors. It does not clear bindings or stored result sets. Stored result sets will be cleared when executing the prepared statement (or closing it).
To re-prepare the statement with another query, use mysql_stmt_prepare()
.
Return Values
Zero if the statement was reset successfully. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query
CR_UNKNOWN_ERROR
An unknown error occurred.
mysql_stmt_result_metadata()
MYSQL_RES *mysql_stmt_result_metadata(MYSQL_STMT *stmt)
Description
If a statement passed to mysql_stmt_prepare()
is one that produces a result set, mysql_stmt_result_metadata()
returns the result set metadata in the form of a pointer to a MYSQL_RES
structure that can be used to process the meta information such as number of fields and individual field information. This result set pointer can be passed as an argument to any of the field-based API functions that process result set metadata, such as:
mysql_num_fields()
mysql_fetch_field()
mysql_fetch_field_direct()
mysql_fetch_fields()
mysql_field_count()
mysql_field_seek()
mysql_field_tell()
mysql_free_result()
The result set structure should be freed when you are done with it, which you can do by passing it to mysql_free_result()
. This is similar to the way you free a result set obtained from a call to mysql_store_result()
.
The result set returned by mysql_stmt_result_metadata()
contains only metadata. It does not contain any row results. The rows are obtained by using the statement handle with mysql_stmt_fetch()
.
Return Values
A MYSQL_RES
result structure. NULL
if no meta information exists for the prepared query.
Errors
CR_OUT_OF_MEMORY
Out of memory.
CR_UNKNOWN_ERROR
An unknown error occurred.
Example
See the Example in , "mysql_stmt_fetch()
".
mysql_stmt_row_seek()
MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT *stmt, MYSQL_ROW_OFFSET offset)
Description
Sets the row cursor to an arbitrary row in a statement result set. The offset
value is a row offset that should be a value returned from mysql_stmt_row_tell()
or from mysql_stmt_row_seek()
. This value is not a row number; if you want to seek to a row within a result set by number, use mysql_stmt_data_seek()
instead.
This function requires that the result set structure contains the entire result of the query, so mysql_stmt_row_seek()
may be used only in conjunction with mysql_stmt_store_result()
.
Return Values
The previous value of the row cursor. This value may be passed to a subsequent call to mysql_stmt_row_seek()
.
Errors
None.
mysql_stmt_row_tell()
MYSQL_ROW_OFFSET mysql_stmt_row_tell(MYSQL_STMT *stmt)
Description
Returns the current position of the row cursor for the last mysql_stmt_fetch()
. This value can be used as an argument to mysql_stmt_row_seek()
.
You should use mysql-stmt-row-tell()
only after mysql_stmt_store_result()
.
Return Values
The current offset of the row cursor.
Errors
None.
mysql_stmt_send_long_data()
my_bool mysql_stmt_send_long_data(MYSQL_STMT *stmt, unsigned int parameter_number, const char *data, unsigned long length)
Description
Enables an application to send parameter data to the server in pieces (or "chunks"). Call this function after mysql_stmt_bind_param()
and before mysql_stmt_execute()
. It can be called multiple times to send the parts of a character or binary data value for a column, which must be one of the TEXT
or BLOB
data types.
parameter_number
indicates which parameter to associate the data with. Parameters are numbered beginning with 0. data
is a pointer to a buffer containing data to be sent, and length
indicates the number of bytes in the buffer.Note
The next mysql_stmt_execute()
call ignores the bind buffer for all parameters that have been used with mysql_stmt_send_long_data()
since last mysql_stmt_execute()
or mysql_stmt_reset()
.
If you want to reset/forget the sent data, you can do it with mysql_stmt_reset()
. See , "mysql_stmt_reset()
".
As of MariaDB 5.6.3, the max_allowed_packet
system variable controls the maximum size of parameter values that can be sent with mysql_stmt_send_long_data()
.
Return Values
Zero if the data is sent successfully to server. Nonzero if an error occurred.
Errors
CR_INVALID_BUFFER_USE
The parameter does not have a string or binary type.
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_OUT_OF_MEMORY
Out of memory.
CR_UNKNOWN_ERROR
An unknown error occurred.
Example
The following example demonstrates how to send the data for a TEXT
column in chunks. It inserts the data value 'MySQL - The most popular Open Source database'
into the text_column
column. The MariaDB
variable is assumed to be a valid connection handle.
#define INSERT_QUERY 'INSERT INTO \ test_long_data(text_column) VALUES(?)' MYSQL_BIND bind[1]; long length; stmt = mysql_stmt_init(mysql); if (!stmt) { fprintf(stderr, ' mysql_stmt_init(), out of memory\n'); exit(0); } if (mysql_stmt_prepare(stmt, INSERT_QUERY, strlen(INSERT_QUERY))) { fprintf(stderr, '\n mysql_stmt_prepare(), INSERT failed'); fprintf(stderr, '\n %s', mysql_stmt_error(stmt)); exit(0); } memset(bind, 0, sizeof(bind)); bind[0].buffer_type= MYSQL_TYPE_STRING; bind[0].length= &length; bind[0].is_null= 0; /* Bind the buffers */ if (mysql_stmt_bind_param(stmt, bind)) { fprintf(stderr, '\n param bind failed'); fprintf(stderr, '\n %s', mysql_stmt_error(stmt)); exit(0); } /* Supply data in chunks to server */ if (mysql_stmt_send_long_data(stmt,0,'MySQL',5)) { fprintf(stderr, '\n send_long_data failed'); fprintf(stderr, '\n %s', mysql_stmt_error(stmt)); exit(0); } /* Supply the next piece of data */ if (mysql_stmt_send_long_data(stmt,0, ' - The most popular Open Source database',40)) { fprintf(stderr, '\n send_long_data failed'); fprintf(stderr, '\n %s', mysql_stmt_error(stmt)); exit(0); } /* Now, execute the query */ if (mysql_stmt_execute(stmt)) { fprintf(stderr, '\n mysql_stmt_execute failed'); fprintf(stderr, '\n %s', mysql_stmt_error(stmt)); exit(0); }
mysql_stmt_sqlstate()
const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)
Description
For the statement specified by stmt
, mysql_stmt_sqlstate()
returns a null-terminated string containing the SQLSTATE error code for the most recently invoked prepared statement API function that can succeed or fail. The error code consists of five characters. '00000'
means "no error." The values are specified by ANSI SQL and ODBC. For a list of possible values, see Appendix C, Errors, Error Codes, and Common Problems.
Note that not all MariaDB errors are yet mapped to SQLSTATE codes. The value 'HY000'
(general error) is used for unmapped errors.
Return Values
A null-terminated character string containing the SQLSTATE error code.
mysql_stmt_store_result()
int mysql_stmt_store_result(MYSQL_STMT *stmt)
Description
Result sets are produced by calling mysql_stmt_execute()
to executed prepared statements for SQL statements such as SELECT
, SHOW
, DESCRIBE
, and EXPLAIN
. By default, result sets for successfully executed prepared statements are not buffered on the client and mysql_stmt_fetch()
fetches them one at a time from the server. To cause the complete result set to be buffered on the client, call mysql_stmt_store_result()
after binding data buffers with mysql_stmt_bind_result()
and before calling mysql_stmt_fetch()
to fetch rows. (For an example, see , "mysql_stmt_fetch()
".)
mysql_stmt_store_result()
is optional for result set processing, unless you will call mysql_stmt_data_seek()
, mysql_stmt_row_seek()
, or mysql_stmt_row_tell()
. Those functions require a seekable result set.
It is unnecessary to call mysql_stmt_store_result()
after executing an SQL statement that does not produce a result set, but if you do, it does not harm or cause any notable performance problem. You can detect whether the statement produced a result set by checking if mysql_stmt_result_metadata()
returns NULL
. For more information, refer to , "mysql_stmt_result_metadata()
".Note
MySQL doesn't by default calculate MYSQL_FIELD->max_length
for all columns in mysql_stmt_store_result()
because calculating this would slow down mysql_stmt_store_result()
considerably and most applications don't need max_length
. If you want max_length
to be updated, you can call mysql_stmt_attr_set(MYSQL_STMT, STMT_ATTR_UPDATE_MAX_LENGTH, &flag)
to enable this. See , "mysql_stmt_attr_set()
".
Return Values
Zero if the results are buffered successfully. Nonzero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order.
CR_OUT_OF_MEMORY
Out of memory.
CR_SERVER_GONE_ERROR
The MariaDB server has gone away.
CR_SERVER_LOST
The connection to the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error occurred.
C API Threaded Function Descriptions
To create a threaded client, use the functions described in the following sections. See also , "How to Write a Threaded Client".
my_init()
void my_init(void)
Description
my-init()
initializes some global variables that MariaDB needs. It also calls mysql_thread_init()
for this thread.
It is necessary for my_init()
to be called early in the initialization phase of a program's use of the MariaDB library. However, my_init()
is automatically called by mysql_init()
, mysql-library-init()
, mysql_server_init()
, and mysql_connect()
. If you ensure that your program invokes one of those functions before any other MariaDB calls, there is no need to invoke my_init()
explicitly.
To access the prototype for my_init()
, your program should include these header files:
#include <my_global.h> #include <my_sys.h>
Return Values
None.
mysql_thread_end()
void mysql_thread_end(void)
Description
This function needs to be called before calling pthread_exit()
to free memory allocated by mysql_thread_init()
.
mysql_thread_end()
is not invoked automatically by the client library. It must be called explicitly to avoid a memory leak.
Return Values
None.
mysql_thread_init()
my_bool mysql_thread_init(void)
Description
This function must be called early within each created thread to initialize thread-specific variables. However, you may not necessarily need to invoke it explicitly: mysql_thread_init()
is automatically called by my_init()
, which itself is automatically called by mysql-init()
, mysql_library_init()
, mysql-server-init()
, and mysql_connect()
. If you invoke any of those functions, mysql_thread_init()
will be called for you.
Return Values
Zero if successful. Nonzero if an error occurred.
mysql_thread_safe()
unsigned int mysql_thread_safe(void)
Description
This function indicates whether the client library is compiled as thread-safe.
Return Values
1 if the client library is thread-safe, 0 otherwise.
C API Embedded Server Function Descriptions
MySQL applications can be written to use an embedded server. See , "libmysqld, the Embedded MariaDB Server Library". To write such an application, you must link it against the libmysqld
library by using the -lmysqld
flag rather than linking it against the libmysqlclient
client library by using the -lmysqlclient
flag. However, the calls to initialize and finalize the library are the same whether you write a client application or one that uses the embedded server: Call mysql_library_init()
to initialize the library and mysql_library_end()
when you are done with it. See , "C API Function Overview".
mysql_server_init()
int mysql_server_init(int argc, char **argv, char **groups)
Description
This function initializes the MariaDB library, which must be done before you call any other MariaDB function. However, mysql_server_init()
is deprecated and you should call mysql_library_init()
instead. See , "mysql_library_init()
".
Return Values
Zero if successful. Nonzero if an error occurred.
mysql_server_end()
void mysql_server_end(void)
Description
This function finalizes the MariaDB library, which should be done when you are done using the library. However, mysql_server_end()
is deprecated and mysql-library-end()
should be used instead. See , "mysql_library_end()
".
Return Values
None.
C API Client Plugin Functions
mysql_client_find_plugin()
mysql_client_register_plugin()
mysql_load_plugin()
mysql_load_plugin_v()
mysql_plugin_options()
This section describes functions used for the client-side plugin API. They enable management of client plugins. For a description of the st_mysql_client_plugin
structure used by these functions, see , "Client Plugin Descriptors".
It is unlikely that a client program needs to call the functions in this section. For example, a client that supports the use of authentication plugins normally causes a plugin to be loaded by calling mysql_options()
to set the MYSQL_DEFAULT_AUTH
and MYSQL_PLUGIN_DIR
options:
char *plugin_dir = 'path_to_plugin_dir
'; char *default_auth = 'plugin_name
'; /* ... process command-line options ... */ mysql_options(&mysql, MYSQL_PLUGIN_DIR, plugin_dir); mysql_options(&mysql, MYSQL_DEFAULT_AUTH, default_auth);
Typically, the program will also accept --plugin-dir
and --default-auth
options that enable users to override the default values.
mysql_client_find_plugin()
struct st_mysql_client_plugin *mysql_client_find_plugin(MYSQL *mysql, const char *name, int type)
Description
Returns a pointer to a loaded plugin, loading the plugin first if necessary. An error occurs if the type is invalid or the plugin cannot be found or loaded.
Specify the parameters as follows:
MariaDB
: A pointer to aMariaDB
structure. The plugin API does not require a connection to a MariaDB server, but this structure must be properly initialized. The structure is used to obtain connection-related information.name
: The plugin name.type
: The plugin type.
Return Values
A pointer to the plugin for success. NULL
if an error occurred.
Errors
To check for errors, call the mysql-error()
or mysql_errno()
function. See , "mysql-error()
", and , "mysql_errno()
".
Example
MYSQL mysql; struct st_mysql_client_plugin *p; if ((p = mysql_client_find_plugin(&mysql, 'myplugin', MYSQL_AUTHENTICATION_PLUGIN, 0))) { printf('Plugin version: %d.%d.%d\n', p->version[0], p->version[1], p->version[2]); }
mysql_client_register_plugin()
struct st_mysql_client_plugin *mysql_client_register_plugin(MYSQL *mysql, struct st_mysql_client_plugin *plugin)
Description
Adds a plugin structure to the list of loaded plugins. An error occurs if the plugin is already loaded.
Specify the parameters as follows:
MariaDB
: A pointer to aMariaDB
structure. The plugin API does not require a connection to a MariaDB server, but this structure must be properly initialized. The structure is used to obtain connection-related information.plugin
: A pointer to the plugin structure.
Return Values
A pointer to the plugin for success. NULL
if an error occurred.
Errors
To check for errors, call the mysql-error()
or mysql_errno()
function. See , "mysql-error()
", and , "mysql_errno()
".
mysql_load_plugin()
struct st_mysql_client_plugin *mysql_load_plugin(MYSQL *mysql, const char *name, int type, int argc, ...)
Description
Loads a MariaDB client plugin, specified by name and type. An error occurs if the type is invalid or the plugin cannot be loaded.
It is not possible to load multiple plugins of the same type. An error occurs if you try to load a plugin of a type already loaded.
Specify the parameters as follows:
MariaDB
: A pointer to aMariaDB
structure. The plugin API does not require a connection to a MariaDB server, but this structure must be properly initialized. The structure is used to obtain connection-related information.name
: The name of the plugin to load.type
: The type of plugin to load, or -1 to disable type checking. If type is not -1, only plugins matching the type are considered for loading.argc
: The number of following arguments (0 if there are none). Interpretation of any following arguments depends on the plugin type.
Another way to cause plugins to be loaded is to set the LIBMYSQL_PLUGINS
environment variable to a semicolon-separated list of plugin names. For example:
shell> export LIBMYSQL_PLUGINS='myplugin1;myplugin2'
Plugins named by LIBMYSQL_PLUGINS
are loaded when the client program calls mysql_library_init()
. No error is reported if problems occur loading these plugins.
Return Values
A pointer to the plugin if it was loaded successfully. NULL
if an error occurred.
Errors
To check for errors, call the mysql-error()
or mysql_errno()
function. See , "mysql-error()
", and , "mysql_errno()
".
Example
MYSQL mysql; if(!mysql_load_plugin(&mysql, 'myplugin', MYSQL_AUTHENTICATION_PLUGIN, 0)) { fprintf(stderr, 'Error: %s\n', mysql_error(&mysql)); exit(-1); }
See Also
See also , "mysql-load-plugin()
", , "mysql_error()
", , "mysql_errno()
".
mysql_load_plugin_v()
struct st_mysql_client_plugin *mysql_load_plugin_v(MYSQL *mysql, const char *name, int type, int argc, va_list args)
Description
This function is equivalent to mysql_load_plugin()
, but it accepts a va_list
instead of a variable list of parameters.
See Also
See also , "mysql_load_plugin()
".
mysql_plugin_options()
int mysql_plugin_options(struct st_mysql_client_plugin *plugin, const char *option, const void *value)
Description
Passes an option type and value to a plugin. This function can be called multiple times to set several options. If the plugin does not have an option handler, an error occurs.
Specify the parameters as follows:
plugin
: A pointer to the plugin structure.option
: The option to be set.value
: A pointer to the option value.
Return Values
Zero for success, 1 if an error occurred. If the plugin has an option handler, that handler should also return zero for success and 1 if an error occurred.
Common Questions and Problems When Using the C API
- Why
mysql_store_result()
Sometimes ReturnsNULL
Aftermysql_query()
Returns Success- What Results You Can Get from a Query
- How to Get the Unique ID for the Last Inserted Row
- What Results You Can Get from a Query
Why mysql_store_result()
Sometimes Returns NULL
After mysql_query()
Returns Success
It is possible for mysql_store_result()
to return NULL
following a successful call to mysql_query()
. When this happens, it means one of the following conditions occurred:
- There was a
malloc()
failure (for example, if the result set was too large). - The data could not be read (an error occurred on the connection).
- The query returned no data (for example, it was an
INSERT
,UPDATE
, orDELETE
).
You can always check whether the statement should have produced a nonempty result by calling mysql_field_count()
. If mysql_field_count()
returns zero, the result is empty and the last query was a statement that does not return values (for example, an INSERT
or a DELETE
). If mysql_field_count()
returns a nonzero value, the statement should have produced a nonempty result. See the description of the mysql_field_count()
function for an example.
You can test for an error by calling mysql-error()
or mysql_errno()
.
What Results You Can Get from a Query
In addition to the result set returned by a query, you can also get the following information:
mysql-affected-rows()
returns the number of rows affected by the last query when doing anINSERT
,UPDATE
, orDELETE
.
For a fast re-create, use
TRUNCATE TABLE
.mysql-num-rows()
returns the number of rows in a result set. Withmysql_store_result()
,mysql_num_rows()
may be called as soon asmysql_store_result()
returns. Withmysql_use_result()
,mysql_num_rows()
may be called only after you have fetched all the rows withmysql_fetch_row()
.mysql_insert_id()
returns the ID generated by the last query that inserted a row into a table with anAUTO_INCREMENT
index. See , "mysql_insert_id()
".- Some queries (
LOAD DATA INFILE ...
,INSERT INTO ... SELECT ...
,UPDATE
) return additional information. The result is returned bymysql_info()
. See the description formysql_info()
for the format of the string that it returns.mysql_info()
returns aNULL
pointer if there is no additional information.
How to Get the Unique ID for the Last Inserted Row
If you insert a record into a table that contains an AUTO_INCREMENT
column, you can obtain the value stored into that column by calling the mysql_insert_id()
function.
You can check from your C applications whether a value was stored in an AUTO_INCREMENT
column by executing the following code (which assumes that you've checked that the statement succeeded). It determines whether the query was an INSERT
with an AUTO_INCREMENT
index:
if ((result = mysql_store_result(&mysql)) == 0 && mysql_field_count(&mysql) == 0 && mysql_insert_id(&mysql) != 0) { used_id = mysql_insert_id(&mysql); }
When a new AUTO_INCREMENT
value has been generated, you can also obtain it by executing a SELECT LAST_INSERT_ID()
statement with mysql_query()
and retrieving the value from the result set returned by the statement.
When inserting multiple values, the last automatically incremented value is returned.
For LAST_INSERT_ID()
, the most recently generated ID is maintained in the server on a per-connection basis. It is not changed by another client. It is not even changed if you update another AUTO_INCREMENT
column with a nonmagic value (that is, a value that is not NULL
and not 0
). Using LAST_INSERT_ID()
and AUTO_INCREMENT
columns simultaneously from multiple clients is perfectly valid. Each client will receive the last inserted ID for the last statement that client executed.
If you want to use the ID that was generated for one table and insert it into a second table, you can use SQL statements like this:
INSERT INTO foo (auto,text) VALUES(NULL,'text'); # generate ID by inserting NULL INSERT INTO foo2 (id,text) VALUES(LAST_INSERT_ID(),'text'); # use ID in second table
Note that mysql_insert_id()
returns the value stored into an AUTO_INCREMENT
column, whether that value is automatically generated by storing NULL
or 0
or was specified as an explicit value. LAST_INSERT_ID()
returns only automatically generated AUTO_INCREMENT
values. If you store an explicit value other than NULL
or 0
, it does not affect the value returned by LAST_INSERT_ID()
.
For more information on obtaining the last ID in an AUTO_INCREMENT
column:
- For information on
LAST-INSERT-ID()
, which can be used within an SQL statement, see , "Information Functions". - For information on
mysql-insert-id()
, the function you use from within the C API, see , "mysql_insert_id()
". - For information on obtaining the auto-incremented value when using Connector/J, see , "Retrieving
AUTO_INCREMENT
Column Values". - For information on obtaining the auto-incremented value when using Connector/ODBC, see , "Obtaining Auto-Increment Values".
Controlling Automatic Reconnection Behavior
The MariaDB client library can perform an automatic reconnection to the server if it finds that the connection is down when you attempt to send a statement to the server to be executed. In this case, the library tries once to reconnect to the server and send the statement again.
In MariaDB 5.6, auto-reconnect is disabled by default.
If it is important for your application to know that the connection has been dropped (so that is can exit or take action to adjust for the loss of state information), be sure that auto-reconnect is disabled. To ensure this, call mysql_options()
with the MYSQL_OPT_RECONNECT
option:
my_bool reconnect = 0; mysql_options(&mysql, MYSQL_OPT_RECONNECT, &reconnect);
If the connection has gone down, the effect of mysql_ping()
depends on the auto-reconnect state. If auto-reconnect is enabled, mysql_ping()
performs a reconnect. Otherwise, it returns an error.
Some client programs might provide the capability of controlling automatic reconnection. For example, mysql reconnects by default, but the --skip-reconnect
option can be used to suppress this behavior.
If an automatic reconnection does occur (for example, as a result of calling mysql_ping()
), there is no explicit indication of it. To check for reconnection, call mysql-thread-id()
to get the original connection identifier before calling mysql_ping()
, then call mysql_thread_id()
again to see whether the identifier has changed.
Automatic reconnection can be convenient because you need not implement your own reconnect code, but if a reconnection does occur, several aspects of the connection state are reset on the server side and your application will not know about it. The connection-related state is affected as follows:
- Any active transactions are rolled back and autocommit mode is reset.
- All table locks are released.
- All
TEMPORARY
tables are closed (and dropped). - Session variables are reinitialized to the values of the corresponding variables. This also affects variables that are set implicitly by statements such as
SET NAMES
. - User variable settings are lost.
- Prepared statements are released.
HANDLER
variables are closed.- The value of
LAST_INSERT_ID()
is reset to 0. - Locks acquired with
GET_LOCK()
are released. - The association of the client with the Performance Schema
threads
table row that determines connection thread instrumentation is lost. If the client reconnects after a disconnect, the session will be associated with a new row in thethreads
table and the thread monitoring state may be different. See , "Thethreads
Table".
If the connection drops, it is possible that the session associated with the connection on the server side will still be running if the server has not yet detected that the client is no longer connected. In this case, any locks held by the original connection still belong to that session, so you may want to kill it by calling mysql_kill()
.
C API Support for Multiple Statement Execution
By default, mysql-query()
and mysql_real_query()
interpret their statement string argument as a single statement to be executed, and you process the result according to whether the statement produces a result set (a set of rows, as for SELECT
) or an affected-rows count (as for INSERT
, UPDATE
, and so forth).
MySQL 5.6 also supports the execution of a string containing multiple statements separated by semicolon (";
") characters. This capability is enabled by special options that are specified either when you connect to the server with mysql_real_connect()
or after connecting by calling` mysql_set_server_option()
.
Executing a multiple-statement string can produce multiple result sets or row-count indicators. Processing these results involves a different approach than for the single-statement case: After handling the result from the first statement, it is necessary to check whether more results exist and process them in turn if so. To support multiple-result processing, the C API includes the mysql_more_results()
and mysql_next_result()
functions. These functions are used at the end of a loop that iterates as long as more results are available. Failure to process the result this way may result in a dropped connection to the server.
Multiple-result processing also is required if you execute CALL
statements for stored procedures. Results from a stored procedure have these characteristics:
- Statements within the procedure may produce result sets (for example, if it executes
SELECT
statements). These result sets are returned in the order that they are produced as the procedure executes.
In general, the caller cannot know how many result sets a procedure will return. Procedure execution may depend on loops or conditional statements that cause the execution path to differ from one call to the next. Therefore, you must be prepared to retrieve multiple results.
- The final result from the procedure is a status result that includes no result set. The status indicates whether the procedure succeeded or an error occurred.
The multiple statement and result capabilities can be used only with mysql-query()
or mysql_real_query()
. They cannot be used with the prepared statement interface. Prepared statement handles are defined to work only with strings that contain a single statement. See , "C API Prepared Statements".
To enable multiple-statement execution and result processing, the following options may be used:
- The
mysql_real_connect()
function has aflags
argument for which two option values are relevant:
CLIENT_MULTI_RESULTS
enables the client program to process multiple results. This option must be enabled if you executeCALL
statements for stored procedures that produce result sets. Otherwise, such procedures result in an errorError 1312 (0A000): PROCEDURE
. In MariaDB 5.6,proc_name
can't return a result set in the given contextCLIENT_MULTI_RESULTS
is enabled by default.CLIENT_MULTI_STATEMENTS
enablesmysql-query()
andmysql_real_query()
to execute statement strings containing multiple statements separated by semicolons. This option also enablesCLIENT_MULTI_RESULTS
implicitly, so aflags
argument ofCLIENT_MULTI_STATEMENTS
tomysql_real_connect()
is equivalent to an argument ofCLIENT_MULTI_STATEMENTS | CLIENT_MULTI_RESULTS
. That is,CLIENT_MULTI_STATEMENTS
is sufficient to enable multiple-statement execution and all multiple-result processing.
- After the connection to the server has been established, you can use the
mysql_set_server_option()
function to enable or disable multiple-statement execution by passing it an argument ofMYSQL_OPTION_MULTI_STATEMENTS_ON
orMYSQL_OPTION_MULTI_STATEMENTS_OFF
. Enabling multiple-statement execution with this function also enables processing of "simple" results for a multiple-statement string where each statement produces a single result, but is not sufficient to permit processing of stored procedures that produce result sets.
The following procedure outlines a suggested strategy for handling multiple statements:
- Pass
CLIENT_MULTI_STATEMENTS
tomysql_real_connect()
, to fully enable multiple-statement execution and multiple-result processing. - After calling
mysql-query()
ormysql_real_query()
and verifying that it succeeds, enter a loop within which you process statement results. - For each iteration of the loop, handle the current statement result, retrieving either a result set or an affected-rows count. If an error occurs, exit the loop.
- At the end of the loop, call
mysql_next_result()
to check whether another result exists and initiate retrieval for it if so. If no more results are available, exit the loop.
One possible implementation of the preceding strategy is shown following. The final part of the loop can be reduced to a simple test of whether mysql_next_result()
returns nonzero. The code as written distinguishes between no more results and an error, which enables a message to be printed for the latter occurrence.
/* connect to server with the CLIENT_MULTI_STATEMENTS option */ if (mysql_real_connect (mysql, host_name, user_name, password, db_name, port_num, socket_name, CLIENT_MULTI_STATEMENTS) == NULL) { printf('mysql_real_connect() failed\n'); mysql_close(mysql); exit(1); } /* execute multiple statements */ status = mysql_query(mysql, 'DROP TABLE IF EXISTS test_table;\ CREATE TABLE test_table(id INT);\ INSERT INTO test_table VALUES(10);\ UPDATE test_table SET id=20 WHERE id=10;\ SELECT * FROM test_table;\ DROP TABLE test_table'); if (status) { printf('Could not execute statement(s)'); mysql_close(mysql); exit(0); } /* process each statement result */ do { /* did current statement return data? */ result = mysql_store_result(mysql); if (result) { /* yes; process rows and free the result set */ process_result_set(mysql, result); mysql_free_result(result); } else /* no result set or error */ { if (mysql_field_count(mysql) == 0) { printf('%lld rows affected\n', mysql_affected_rows(mysql)); } else /* some error occurred */ { printf('Could not retrieve result set\n'); break; } } /* more results? -1 = no, >0 = error, 0 = yes (keep looping) */ if ((status = mysql_next_result(mysql)) > 0) printf('Could not execute statement\n'); } while (status == 0); mysql_close(mysql);
C API Prepared Statement Problems
Here follows a list of the currently known problems with prepared statements:
TIME
,TIMESTAMP
, andDATETIME
do not support parts of seconds (for example, fromDATE_FORMAT()
).- When converting an integer to string,
ZEROFILL
is honored with prepared statements in some cases where the MariaDB server doesn't print the leading zeros. (For example, withMIN(
).number-with-zerofill
) - When converting a floating-point number to a string in the client, the rightmost digits of the converted value may differ slightly from those of the original value.
- Prepared statements use the query cache under the conditions described in , "How the Query Cache Operates".
- Prepared statements do not support multi-statements (that is, multiple statements within a single string separated by "
;
" characters). - The capabilities of prepared
CALL
statements are described in , "C API Support for PreparedCALL
Statements".
C API Prepared Statement Handling of Date and Time Values
The binary (prepared statement) protocol enables you to send and receive date and time values (DATE
, TIME
, DATETIME
, and TIMESTAMP
), using the MYSQL_TIME
structure. The members of this structure are described in , "C API Prepared Statement Data Structures".
To send temporal data values, create a prepared statement using mysql_stmt_prepare()
. Then, before calling mysql_stmt_execute()
to execute the statement, use the following procedure to set up each temporal parameter:
- In the
MYSQL_BIND
structure associated with the data value, set thebuffer_type
member to the type that indicates what kind of temporal value you're sending. ForDATE
,TIME
,DATETIME
, orTIMESTAMP
values, setbuffer_type
toMYSQL_TYPE_DATE
,MYSQL_TYPE_TIME
,MYSQL_TYPE_DATETIME
, orMYSQL_TYPE_TIMESTAMP
, respectively. - Set the
buffer
member of theMYSQL_BIND
structure to the address of theMYSQL_TIME
structure in which you pass the temporal value. - Fill in the members of the
MYSQL_TIME
structure that are appropriate for the type of temporal value to be passed.
Use mysql_stmt_bind_param()
to bind the parameter data to the statement. Then you can call mysql_stmt_execute()
.
To retrieve temporal values, the procedure is similar, except that you set the buffer_type
member to the type of value you expect to receive, and the buffer
member to the address of a MYSQL_TIME
structure into which the returned value should be placed. Use mysql_stmt_bind_result()
to bind the buffers to the statement after calling mysql_stmt_execute()
and before fetching the results.
Here is a simple example that inserts DATE
, TIME
, and TIMESTAMP
data. The MariaDB
variable is assumed to be a valid connection handle.
MYSQL_TIME ts; MYSQL_BIND bind[3]; MYSQL_STMT *stmt; strmov(query, 'INSERT INTO test_table(date_field, time_field, \ timestamp_field) VALUES(?,?,?'); stmt = mysql_stmt_init(mysql); if (!stmt) { fprintf(stderr, ' mysql_stmt_init(), out of memory\n'); exit(0); } if (mysql_stmt_prepare(mysql, query, strlen(query))) { fprintf(stderr, '\n mysql_stmt_prepare(), INSERT failed'); fprintf(stderr, '\n %s', mysql_stmt_error(stmt)); exit(0); } /* set up input buffers for all 3 parameters */ bind[0].buffer_type= MYSQL_TYPE_DATE; bind[0].buffer= (char *)&ts; bind[0].is_null= 0; bind[0].length= 0; ... bind[1]= bind[2]= bind[0]; ... mysql_stmt_bind_param(stmt, bind); /* supply the data to be sent in the ts structure */ ts.year= 2002; ts.month= 02; ts.day= 03; ts.hour= 10; ts.minute= 45; ts.second= 20; mysql_stmt_execute(stmt); ..
C API Support for Prepared CALL
Statements
This section describes prepared-statement support in the C API for stored procedures executed using CALL
statements:
In MariaDB 5.6, stored procedures executed using prepared CALL
statements can be used in the following ways:
- A stored procedure can produce any number of result sets. The number of columns and the data types of the columns need not be the same for all result sets.
- The final values of
OUT
andINOUT
parameters are available to the calling application after the procedure returns. These parameters are returned as an extra single-row result set following any result sets produced by the procedure itself. The row contains the values of theOUT
andINOUT
parameters in the order in which they are declared in the procedure parameter list.
The following discussion shows how to use these capabilities through the C API for prepared statements. To use prepared CALL
statements through the PREPARE
and EXECUTE
statements, see , "CALL
Syntax".
If an application might be compiled or executed in a context where a version of MariaDB older than 5.5.3 is used, prepared CALL
capabilities for multiple result sets and OUT
or INOUT
parameters might not be available:
- For the client side, the application will not compile unless the libraries are from MariaDB 5.5.3 or higher (the API function and symbols introduced in that version will not be present).
- To verify at runtime that the server is recent enough, a client can use this test:
if (mysql_get_server_version(mysql) < 50503) { fprintf(stderr, 'Server does not support required CALL capabilities\n'); mysql_close(mysql); exit (1); }
An application that executes a prepared CALL
statement should use a loop that fetches a result and then invokes mysql_stmt_next_result()
to determine whether there are more results. The results consist of any result sets produced by the stored procedure followed by a final status value that indicates whether the procedure terminated successfully.
If the procedure has OUT
or INOUT
parameters, the result set preceding the final status value contains their values. To determine whether a result set contains parameter values, test whether the SERVER_PS_OUT_PARAMS
bit is set in the server_status
member of the MariaDB
connection handler:
mysql->server_status & SERVER_PS_OUT_PARAMS
The following example uses a prepared CALL
statement to execute a stored procedure that produces multiple result sets and that provides parameter values back to the caller by means of OUT
and INOUT
parameters. The procedure takes parameters of all three types (IN
, OUT
, INOUT
), displays their initial values, assigns new values, displays the updated values, and returns. The expected return information from the procedure therefore consists of multiple result sets and a final status:
- One result set from a
SELECT
that displays the initial parameter values:10
,NULL
,30
. (TheOUT
parameter is assigned a value by the caller, but this assignment is expected to be ineffective:OUT
parameters are seen asNULL
within a procedure until assigned a value within the procedure.) - One result set from a
SELECT
that displays the modified parameter values:100
,200
,300
. - One result set containing the final
OUT
andINOUT
parameter values:200
,300
. - A final status packet.
The code to execute the procedure:
MYSQL_STMT *stmt; MYSQL_BIND ps_params[3]; /* input parameter buffers */ int int_data[3]; /* input/output values */ my_bool is_null[3]; /* output value nullability */ int status; /* set up stored procedure */ status = mysql_query(mysql, 'DROP PROCEDURE IF EXISTS p1'); test_error(mysql, status); status = mysql_query(mysql, 'CREATE PROCEDURE p1(' ' IN p_in INT, ' ' OUT p_out INT, ' ' INOUT p_inout INT) ' 'BEGIN ' ' SELECT p_in, p_out, p_inout; ' ' SET p_in = 100, p_out = 200, p_inout = 300; ' ' SELECT p_in, p_out, p_inout; ' 'END'); test_error(mysql, status); /* initialize and prepare CALL statement with parameter placeholders */ stmt = mysql_stmt_init(mysql); if (!stmt) { printf('Could not initialize statement\n'); exit(1); } status = mysql_stmt_prepare(stmt, 'CALL p1(?, ?, ?)', 16); test_stmt_error(stmt, status); /* initialize parameters: p_in, p_out, p_inout (all INT) */ memset(ps_params, 0, sizeof (ps_params)); ps_params[0].buffer_type = MYSQL_TYPE_LONG; ps_params[0].buffer = (char *) &int_data[0]; ps_params[0].length = 0; ps_params[0].is_null = 0; ps_params[1].buffer_type = MYSQL_TYPE_LONG; ps_params[1].buffer = (char *) &int_data[1]; ps_params[1].length = 0; ps_params[1].is_null = 0; ps_params[2].buffer_type = MYSQL_TYPE_LONG; ps_params[2].buffer = (char *) &int_data[2]; ps_params[2].length = 0; ps_params[2].is_null = 0; /* bind parameters */ status = mysql_stmt_bind_param(stmt, ps_params); test_stmt_error(stmt, status); /* assign values to parameters and execute statement */ int_data[0]= 10; /* p_in */ int_data[1]= 20; /* p_out */ int_data[2]= 30; /* p_inout */ status = mysql_stmt_execute(stmt); test_stmt_error(stmt, status); /* process results until there are no more */ do { int i; int num_fields; /* number of columns in result */ MYSQL_FIELD *fields; /* for result set metadata */ MYSQL_BIND *rs_bind; /* for output buffers */ /* the column count is > 0 if there is a result set */ /* 0 if the result is only the final status packet */ num_fields = mysql_stmt_field_count(stmt); if (num_fields > 0) { /* there is a result set to fetch */ printf('Number of columns in result: %d\n', (int) num_fields); /* what kind of result set is this? */ printf('Data: '); if(mysql->server_status & SERVER_PS_OUT_PARAMS) printf('this result set contains OUT/INOUT parameters\n'); else printf('this result set is produced by the procedure\n'); MYSQL_RES *rs_metadata = mysql_stmt_result_metadata(stmt); test_stmt_error(stmt, rs_metadata == NULL); fields = mysql_fetch_fields(rs_metadata); rs_bind = (MYSQL_BIND *) malloc(sizeof (MYSQL_BIND) * num_fields); if (!rs_bind) { printf('Cannot allocate output buffers\n'); exit(1); } memset(rs_bind, 0, sizeof (MYSQL_BIND) * num_fields); /* set up and bind result set output buffers */ for (i = 0; i < num_fields; ++i) { rs_bind[i].buffer_type = fields[i].type; rs_bind[i].is_null = &is_null[i]; switch (fields[i].type) { case MYSQL_TYPE_LONG: rs_bind[i].buffer = (char *) &(int_data[i]); rs_bind[i].buffer_length = sizeof (int_data); break; default: fprintf(stderr, 'ERROR: unexpected type: %d.\n', fields[i].type); exit(1); } } status = mysql_stmt_bind_result(stmt, rs_bind); test_stmt_error(stmt, status); /* fetch and display result set rows */ while (1) { status = mysql_stmt_fetch(stmt); if (status == 1 || status == MYSQL_NO_DATA) break; for (i = 0; i < num_fields; ++i) { switch (rs_bind[i].buffer_type) { case MYSQL_TYPE_LONG: if (*rs_bind[i].is_null) printf(' val[%d] = NULL;', i); else printf(' val[%d] = %ld;', i, (long) *((int *) rs_bind[i].buffer)); break; default: printf(' unexpected type (%d)\n', rs_bind[i].buffer_type); } } printf('\n'); } mysql_free_result(rs_metadata); /* free metadata */ free(rs_bind); /* free output buffers */ } else { /* no columns = final status packet */ printf('End of procedure output\n'); } /* more results? -1 = no, >0 = error, 0 = yes (keep looking) */ status = mysql_stmt_next_result(stmt); if (status > 0) test_stmt_error(stmt, status); } while (status == 0); mysql_stmt_close(stmt);
Execution of the procedure should produce the following output:
Number of columns in result: 3 Data: this result set is produced by the procedure val[0] = 10; val[1] = NULL; val[2] = 30; Number of columns in result: 3 Data: this result set is produced by the procedure val[0] = 100; val[1] = 200; val[2] = 300; Number of columns in result: 2 Data: this result set contains OUT/INOUT parameters val[0] = 200; val[1] = 300; End of procedure output
The code uses two utility routines, test_error()
test_stmt_error()
, to check for errors and terminate after printing diagnostic information if an error occurred:
static void test_error(MYSQL *mysql, int status) { if (status) { fprintf(stderr, 'Error: %s (errno: %d)\n', mysql_error(mysql), mysql_errno(mysql)); exit(1); } } static void test_stmt_error(MYSQL_STMT *stmt, int status) { if (status) { fprintf(stderr, 'Error: %s (errno: %d)\n', mysql_stmt_error(stmt), mysql_stmt_errno(stmt)); exit(1); } }
Building Client Programs
If you compile MariaDB clients that you've written yourself or that you obtain from a third-party, they must be linked using the -lmysqlclient -lz
options in the link command. You may also need to specify a -L
option to tell the linker where to find the library. For example, if the library is installed in /usr/local/mysql/lib
, use -L/usr/local/mysql/lib -lmysqlclient -lz
in the link command.
For clients that use MariaDB header files, you may need to specify an -I
option when you compile them (for example, -I/usr/local/mysql/include
), so that the compiler can find the header files.
Compiling MariaDB Clients on Unix
To make it simpler to compile MariaDB programs on Unix, we have provided the mysql_config script for you. See , "mysql_config - Get Compile Options for Compiling Clients".
You can use it to compile a MariaDB client as follows:
CFG=/usr/local/mysql/bin/mysql_config sh -c 'gcc -o progname `$CFG --cflags` progname.c `$CFG --libs`'
The sh -c
is needed to get the shell not to treat the output from mysql_config as one word.
Compiling MariaDB Clients on Microsoft Windows
On Windows, you can link your code with either the dynamic or static client library. The static library is named mysqlclient
and the dynamic library is named libmysql
.
If you link with the static library, failure can occur if certain conditions are not satisfied:
- The client application must be compiled with exactly the same version of Visual Studio as that used to compile the library.
- The client application should link the C runtime statically by using the
/MT
compiler option.
If the client application is built in in debug mode and uses the static debug C runtime (/MTd
compiler option), it can link the mysqlclient
if that library was built using the same option. If the client application uses the dynamic C runtime (/MD
option, or /MDd
option in debug mode), it cannot link with the static client library and must use the dynamic library.
The MSDN page describing the link options can be found here: http://msdn.microsoft.com/en-us/library/2kzt1wy3.aspx
Problems Linking to the MariaDB Client Library
When linking with the C API, the following errors may occur on some systems:
gcc -g -o client test.o -L/usr/local/lib/mysql \ -lmysqlclient -lsocket -lnsl Undefined first referenced symbol in file floor /usr/local/lib/mysql/libmysqlclient.a(password.o) ld: fatal: Symbol referencing errors. No output written to client
If this happens on your system, you must include the math library by adding -lm
to the end of the compile/link line.
When you are linking an application program to use the MariaDB client library, you might get undefined reference errors for symbols that start with mysql_
, such as those shown here:
/tmp/ccFKsdPa.o: In function `main': /tmp/ccFKsdPa.o(.text+0xb): undefined reference to `mysql_init' /tmp/ccFKsdPa.o(.text+0x31): undefined reference to `mysql_real_connect' /tmp/ccFKsdPa.o(.text+0x57): undefined reference to `mysql_real_connect' /tmp/ccFKsdPa.o(.text+0x69): undefined reference to `mysql_error' /tmp/ccFKsdPa.o(.text+0x9a): undefined reference to `mysql_close'
You should be able to solve this problem by adding -Ldir_path -lmysqlclient
at the end of your link command, where dir_path
represents the path name of the directory where the client library is located. To determine the correct directory, try this command:
shell> mysql_config --libs
The output from mysql_config might indicate other libraries that should be specified on the link command as well.
If you get undefined reference
errors for the uncompress
or compress
function, add -lz
to the end of your link command and try again.
If you get undefined reference
errors for a function that should exist on your system, such as connect
, check the manual page for the function in question to determine which libraries you should add to the link command.
You might get undefined reference
errors such as the following for functions that don't exist on your system:
mf_format.o(.text+0x201): undefined reference to `__lxstat'
This usually means that your MariaDB client library was compiled on a system that is not 100% compatible with yours. In this case, you should download the latest MariaDB source distribution and compile MariaDB yourself. See , "Installing MariaDB from Source".
You might get undefined reference errors at runtime when you try to execute a MariaDB program. If these errors specify symbols that start with mysql_
or indicate that the mysqlclient
library can't be found, it means that your system can't find the shared libmysqlclient.so
library. The fix for this is to tell your system to search for shared libraries where the library is located. Use whichever of the following methods is appropriate for your system:
- Add the path to the directory where
libmysqlclient.so
is located to theLD_LIBRARY_PATH
environment variable. - Add the path to the directory where
libmysqlclient.so
is located to theLD_LIBRARY
environment variable. - Copy
libmysqlclient.so
to some directory that is searched by your system, such as/lib
, and update the shared library information by executingldconfig
.
How to Write a Threaded Client
The client library is almost thread-safe. The biggest problem is that the subroutines in net.c
that read from sockets are not interrupt safe. This was done with the thought that you might want to have your own alarm that can break a long read to a server. If you install interrupt handlers for the SIGPIPE
interrupt, the socket handling should be thread-safe.
To avoid aborting the program when a connection terminates, MariaDB blocks SIGPIPE
on the first call to mysql_library_init()
, mysql-init()
, or mysql_connect()
. If you want to use your own SIGPIPE
handler, you should first call mysql_library_init()
and then install your handler.
If "undefined symbol" errors occur when linking against the libmysqlclient
client library, in most cases this is because you have not included the thread libraries on the link/compile command.
The client library is thread-safe per connection. You can let two threads share the same connection with the following caveats:
- Two threads can't send a query to the MariaDB server at the same time on the same connection. In particular, you have to ensure that between calls to
mysql_query()
andmysql_store_result()
no other thread is using the same connection. - Many threads can access different result sets that are retrieved with
mysql_store_result()
. - If you use
mysql_use_result()
, you must ensure that no other thread is using the same connection until the result set is closed. However, it really is best for threaded clients that share the same connection to usemysql_store_result()
. - If you want to use multiple threads on the same connection, you must have a mutex lock around your pair of
mysql_query()
andmysql_store_result()
calls. Oncemysql_store_result()
is ready, the lock can be released and other threads may query the same connection. - If you use POSIX threads, you can use
pthread_mutex_lock()
andpthread_mutex_unlock()
to establish and release a mutex lock.
You need to know the following if you have a thread that did not create the connection to the MariaDB database but is calling MariaDB functions:
When you call mysql_init()
, MariaDB creates a thread-specific variable for the thread that is used by the debug library (among other things). If you call a MariaDB function before the thread has called mysql_init()
, the thread does not have the necessary thread-specific variables in place and you are likely to end up with a core dump sooner or later. To avoid problems, you must do the following:
- Call
mysql_library_init()
before any other MariaDB functions. It is not thread-safe, so call it before threads are created, or protect the call with a mutex. - Arrange for
mysql_thread_init()
to be called early in the thread handler before calling any MariaDB function. If you callmysql_init()
, it will callmysql_thread_init()
for you. - In the thread, call
mysql_thread_end()
before callingpthread_exit()
. This frees the memory used by MariaDB thread-specific variables.
The preceding notes regarding mysql-init()
also apply to mysql_connect()
, which calls mysql_init()
.
MySQL PHP API
- Original MariaDB API (
MariaDB
)- MySQL Improved Extension (
Mysqli
)- MySQL Native Driver (
Mysqlnd
)- MySQL Functions (PDO_MYSQL) (
MySQL (PDO)
)- Connector/PHP
- Common Problems with MariaDB and PHP
- Enabling Both
MariaDB
andmysqli
in PHP - MySQL Improved Extension (
PHP is a server-side, HTML-embedded scripting language that may be used to create dynamic Web pages. It is available for most operating systems and Web servers, and can access most common databases, including MySQL. PHP may be run as a separate program or compiled as a module for use with the Apache Web server.
PHP provides three different MariaDB API extensions:
- , "Original MariaDB API (
MariaDB
)": Available for PHP versions 4 and 5, this extension is intended for use with MariaDB versions prior to MariaDB 4.1. This extension does not support the improved authentication protocol used in MySQL, nor does it support prepared statements or multiple statements. To use this extension with MySQL, you will likely configure the MariaDB server to use the--old-passwords
option (see "Client does not support authentication protocol
"). - , "MySQL Improved Extension (
Mysqli
)" - Stands for "MySQL, Improved"; this extension is available only in PHP 5. It is intended for use with MariaDB and later. This extension fully supports the authentication protocol used in MariaDB 5.0, as well as the Prepared Statements and Multiple Statements APIs. In addition, this extension provides an advanced, object-oriented programming interface. - , "MySQL Functions (PDO_MYSQL) (
MySQL (PDO)
)" Not its own API, but instead it's a MariaDB driver for the PHP database abstraction layer PDO (PHP Data Objects). The PDO MariaDB driver sits in the layer below PDO itself, and provides MySQL-specific functionality. This extension is available as of PHP 5.1.
If you're experiencing problems with enabling both the MariaDB
and the mysqli
extension when building PHP on Linux yourself, see , "Enabling Both MariaDB
and mysqli
in PHP".
The PHP distribution and documentation are available from the PHP Web site.
Portions of this section are Copyright (c) 1997-2008 the PHP Documentation Group This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution 3.0 License or later. A copy of the Creative Commons Attribution 3.0 license is distributed with this manual. The latest version is presently available at This material may be distributed only subject to the terms and conditio\ ns set forth in the Open Publication License, v1.0.8 or later (the latest version is presently available at http://www.opencontent.org/openpub/).
Original MariaDB API (MariaDB
)
These functions allow you to access MariaDB database servers. More information about MariaDB can be found at http://www.mysql.com/.
Documentation for MariaDB can be found at http://dev.mysql.com/doc/.
For an overview of MariaDB database connectivity terms and products see , "Overview".
Installing/Configuring
Requirements
In order to have these functions available, you must compile PHP with MariaDB support.
Installation
For compiling, simply use the --with-mysql[=DIR]
configuration option where the optional [DIR]
points to the MariaDB installation directory.
Although this MariaDB extension is compatible with MariaDB 4.1.0 and greater, it doesn't support the extra functionality that these versions provide. For that, use the MySQLi extension.
If you would like to install the mysql extension along with the mysqli extension you have to use the same client library to avoid any conflicts.
Installation on Linux Systems
Note: [DIR]
is the path to the MariaDB client library files (headers and libraries), which can be downloaded from MySQL.
Table 20.8. ext/mysql compile time support matrix
PHP Version | Default | Configure Options: mysqlnd | Configure Options: libmysql
| Changelog |
---|---|---|---|---|
4.x.x | libmysql | Not Available | --without-mysql to disable
| MySQL enabled by default, MariaDB client libraries are bundled |
5.0.x, 5.1.x, 5.2.x | libmysql | Not Available | --with-mysql=[DIR]
| MySQL is no longer enabled by default, and the MariaDB client libraries are no longer bundled |
5.3.x | libmysql | --with-mysql=mysqlnd
| --with-mysql=[DIR]
| mysqlnd is now available |
5.4.x | mysqlnd | --with-mysql
| --with-mysql=[DIR]
| mysqlnd is now the default |
Installation on Windows Systems
PHP 4
The PHP MariaDB extension is compiled into PHP.
PHP 5.0.x, 5.1.x, 5.2.x
MySQL is no longer enabled by default, so the php_mysql.dll
DLL must be enabled inside of php.ini
. Also, PHP needs access to the MariaDB client library. A file named libmysql.dll
is included in the Windows PHP distribution and in order for PHP to talk to MariaDB this file needs to be available to the Windows systems PATH
. See the FAQ titled 'How do I add my PHP directory to the PATH
on Windows' for information on how to do this. Although copying libmysql.dll
to the Windows system directory also works (because the system directory is by default in the system's PATH
), it's not recommended.
As with enabling any PHP extension (such as php_mysql.dll
), the PHP directive extension_dir should be set to the directory where the PHP extensions are located. See also the Manual Windows Installation Instructions. An example extension_dir value for PHP 5 is c:\php\ext
Note
If when starting the web server an error similar to the following occurs: 'Unable to load dynamic library './php_mysql.dll''
, this is because php_mysql.dll
and/or libmysql.dll
cannot be found by the system.
PHP 5.3.0+
The MySQL Native Driver is enabled by default. Include php_mysql.dll
, but libmysql.dll
is no longer required or used.
MySQL Installation Notes
WarningCrashes and startup problems of PHP may be encountered when loading this extension in conjunction with the recode extension. See the recode extension for more information.Note
If you need charsets other than latin (default), you have to install external (not bundled) libmysql with compiled charset support.
Runtime Configuration
The behaviour of these functions is affected by settings in php.ini
.
Table 20.9. MariaDB Configuration Options
Name | Default | Changeable | Changelog |
---|---|---|---|
mysql.allow_local_infile | '1' | PHP_INI_SYSTEM | |
mysql.allow_persistent | '1' | PHP_INI_SYSTEM | |
mysql.max_persistent | '-1' | PHP_INI_SYSTEM | |
mysql.max_links | '-1' | PHP_INI_SYSTEM | |
mysql.trace_mode | '0' | PHP_INI_ALL | Available since PHP 4.3.0. |
mysql.default_port | NULL | PHP_INI_ALL | |
mysql.default_socket | NULL | PHP_INI_ALL | Available since PHP 4.0.1. |
mysql.default_host | NULL | PHP_INI_ALL | |
mysql.default_user | NULL | PHP_INI_ALL | |
mysql.default_password | NULL | PHP_INI_ALL | |
mysql.connect_timeout | '60' | PHP_INI_ALL | PHP_INI_SYSTEM in PHP <= 4.3.2. Available since PHP 4.3.0. |
For further details and definitions of the PHP_INI_* modes, see the http://www.php.net/manual/en/configuration.changes.modes.
Here's a short explanation of the configuration directives.
mysql.allow_local_infile
integer-
Allow accessing, from PHP's perspective, local files with LOAD DATA statements
mysql.allow_persistent
boolean-
Whether to allow persistent connections to MariaDB.
mysql.max_persistent
integer-
The maximum number of persistent MariaDB connections per process.
mysql.max_links
integer-
The maximum number of MariaDB connections per process, including persistent connections.
mysql.trace_mode
boolean-
Trace mode. When
mysql.trace_mode
is enabled, warnings for table/index scans, non free result sets, and SQL-Errors will be displayed. (Introduced in PHP 4.3.0) mysql.default_port
string-
The default TCP port number to use when connecting to the database server if no other port is specified. If no default is specified, the port will be obtained from the
MYSQL_TCP_PORT
environment variable, themysql-tcp
entry in/etc/services
or the compile-timeMYSQL_PORT
constant, in that order. Win32 will only use theMYSQL_PORT
constant. mysql.default_socket
string-
The default socket name to use when connecting to a local database server if no other socket name is specified.
mysql.default_host
string-
The default server host to use when connecting to the database server if no other host is specified. Doesn't apply in SQL safe mode.
mysql.default_user
string-
The default user name to use when connecting to the database server if no other name is specified. Doesn't apply in SQL safe mode.
mysql.default_password
string-
The default password to use when connecting to the database server if no other password is specified. Doesn't apply in SQL safe mode.
mysql.connect_timeout
integer-
Connect timeout in seconds. On Linux this timeout is also used for waiting for the first answer from the server.
Resource Types
There are two resource types used in the MariaDB module. The first one is the link identifier for a database connection, the second a resource which holds the result of a query.
Predefined Constants
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Since PHP 4.3.0 it is possible to specify additional client flags for the mysql_connect
and mysql_pconnect
functions. The following constants are defined:
Table 20.10. MariaDB client constants
Constant | Description |
---|---|
MYSQL_CLIENT_COMPRESS
| Use compression protocol |
MYSQL_CLIENT_IGNORE_SPACE
| Allow space after function names |
MYSQL_CLIENT_INTERACTIVE
| Allow interactive_timeout seconds (instead of wait_timeout ) of inactivity before closing the connection.
|
MYSQL_CLIENT_SSL
| Use SSL encryption. This flag is only available with version 4.x of the MariaDB client library or newer. Version 3.23.x is bundled both with PHP 4 and Windows binaries of PHP 5. |
The function mysql_fetch_array
uses a constant for the different types of result arrays. The following constants are defined:
Table 20.11. MariaDB fetch constants
Constant | Description |
---|---|
MYSQL_ASSOC
| Columns are returned into the array having the fieldname as the array index. |
MYSQL_BOTH
| Columns are returned into the array having both a numerical index and the fieldname as the array index. |
MYSQL_NUM
| Columns are returned into the array having a numerical index to the fields. This index starts with 0, the first field in the result. |
Examples
MySQL extension overview example
This simple example shows how to connect, execute a query, print resulting rows and disconnect from a MariaDB database.
Example 20.15. MariaDB extension overview example
<?php // Connecting, selecting database $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password') or die('Could not connect: ' . mysql_error()); echo 'Connected successfully'; mysql_select_db('my_database') or die('Could not select database'); // Performing SQL query $query = 'SELECT * FROM my_table'; $result = mysql_query($query) or die('Query failed: ' . mysql_error()); // Printing results in HTML echo '<table>\n'; while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) { echo '\t<tr>\n'; foreach ($line as $col_value) { echo '\t\t<td>$col_value</td>\n'; } echo '\t</tr>\n'; } echo '</table>\n'; // Free resultset mysql_free_result($result); // Closing connection mysql_close($link); ?>
MySQL Functions
mysql_affected_rows
mysql_client_encoding
mysql_close
mysql_connect
mysql_create_db
mysql_data_seek
mysql_db_name
mysql_db_query
mysql_drop_db
mysql_errno
mysql_error
mysql_escape_string
mysql_fetch_array
mysql_fetch_assoc
mysql_fetch_field
mysql_fetch_lengths
mysql_fetch_object
mysql_fetch_row
mysql_field_flags
mysql_field_len
mysql_field_name
mysql_field_seek
mysql_field_table
mysql_field_type
mysql_free_result
mysql_get_client_info
mysql_get_host_info
mysql_get_proto_info
mysql_get_server_info
mysql_info
mysql_insert_id
mysql_list_dbs
mysql_list_fields
mysql_list_processes
mysql_list_tables
mysql_num_fields
mysql_num_rows
mysql_pconnect
mysql_ping
mysql_query
mysql_real_escape_string
mysql_result
mysql_select_db
mysql_set_charset
mysql_stat
mysql_tablename
mysql_thread_id
mysql_unbuffered_query
Most MariaDB functions accept link_identifier
as the last optional parameter. If it is not provided, last opened connection is used. If it doesn't exist, connection is tried to establish with default parameters defined in php.ini
. If it is not successful, functions return FALSE
.
mysql_affected_rows
mysql_affected_rows
Get number of affected rows in previous MariaDB operation
Description
int mysql_affected_rows(resource link_identifier= =NULL);
Get the number of affected rows by the last INSERT, UPDATE, REPLACE or DELETE query associated with link_identifier
.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns the number of affected rows on success, and -1 if the last query failed.
If the last query was a DELETE query with no WHERE clause, all of the records will have been deleted from the table but this function will return zero with MariaDB versions prior to 4.1.2.
When using UPDATE, MariaDB will not update columns where the new value is the same as the old value. This creates the possibility that mysql_affected_rows
may not actually equal the number of rows matched, only the number of rows that were literally affected by the query.
The REPLACE statement first deletes the record with the same primary key and then inserts the new record. This function returns the number of deleted records plus the number of inserted records.
Examples
Example 20.16. mysql_affected_rows
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } mysql_select_db('mydb'); /* this should return the correct numbers of deleted records */ mysql_query('DELETE FROM mytable WHERE id < 10'); printf('Records deleted: %d\n', mysql_affected_rows()); /* with a where clause that is never true, it should return 0 */ mysql_query('DELETE FROM mytable WHERE 0'); printf('Records deleted: %d\n', mysql_affected_rows()); ?>
The above example will output something similar to:
Records deleted: 10 Records deleted: 0
Example 20.17. mysql_affected_rows
example using transactions
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } mysql_select_db('mydb'); /* Update records */ mysql_query('UPDATE mytable SET used=1 WHERE id < 10'); printf ('Updated records: %d\n', mysql_affected_rows()); mysql_query('COMMIT'); ?>
The above example will output something similar to:
Updated Records: 10
Notes
TransactionsIf you are using transactions, you need to call mysql_affected_rows
after your INSERT, UPDATE, or DELETE query, not after the COMMIT.SELECT Statements
To retrieve the number of rows returned by a SELECT, it is possible to use mysql_num_rows
.Cascaded Foreign Keys
mysql_affected_rows
does not count rows affected implicitly through the use of ON DELETE CASCADE and/or ON UPDATE CASCADE in foreign key constraints.
See Also
mysql_num_rows
|
mysql_info |
mysql_client_encoding
mysql_client_encoding
Returns the name of the character set
Description
string mysql_client_encoding(resource link_identifier= =NULL);
Retrieves the character_set
variable from MySQL.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns the default character set name for the current connection.
Examples
Example 20.18. mysql_client_encoding
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); $charset = mysql_client_encoding($link); echo 'The current character set is: $charset\n'; ?>
The above example will output something similar to:
The current character set is: latin1
See Also
mysql_set_charset
|
mysql_real_escape_string |
mysql_close
mysql_close
Close MariaDB connection
Description
bool mysql_close(resource link_identifier= =NULL);
mysql_close
closes the non-persistent connection to the MariaDB server that's associated with the specified link identifier. If link_identifier
isn't specified, the last opened link is used.
Using mysql_close
isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution. See also freeing resources.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.19. mysql_close
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } echo 'Connected successfully'; mysql_close($link); ?>
The above example will output:
Connected successfully
Notes
Notemysql_close
will not close persistent links created by mysql_pconnect
.
See Also
mysql_connect
|
mysql_free_result |
mysql_connect
mysql_connect
Open a connection to a MariaDB Server
Description
resource mysql_connect(string server= =ini_get('mysql.default_host'),
string username= =ini_get('mysql.default_user'),
string password= =ini_get('mysql.default_password'),
bool new_link= =false,
int client_flags= =0);
Opens or reuses a connection to a MariaDB server.
Parameters
server
-
The MariaDB server. It can also include a port number. e.g. 'hostname:port' or a path to a local socket e.g. ':/path/to/socket' for the localhost.
If the PHP directive mysql.default_host is undefined (default), then the default value is 'localhost:3306'. In SQL safe mode, this parameter is ignored and value 'localhost:3306' is always used.
username
-
The username. Default value is defined by mysql.default_user. In SQL safe mode, this parameter is ignored and the name of the user that owns the server process is used.
password
-
The password. Default value is defined by mysql.default_password. In SQL safe mode, this parameter is ignored and empty password is used.
new_link
-
If a second call is made to
mysql_connect
with the same arguments, no new link will be established, but instead, the link identifier of the already opened link will be returned. Thenew_link
parameter modifies this behavior and makesmysql_connect
always open a new link, even ifmysql_connect
was called before with the same parameters. In SQL safe mode, this parameter is ignored. client_flags
-
The
client_flags
parameter can be a combination of the following constants: 128 (enableLOAD DATA LOCAL
handling),MYSQL_CLIENT_SSL
,MYSQL_CLIENT_COMPRESS
,MYSQL_CLIENT_IGNORE_SPACE
orMYSQL_CLIENT_INTERACTIVE
. Read the section about Table 20.10, "MySQL client constants" for further information. In SQL safe mode, this parameter is ignored.
Return Values
Returns a MariaDB link identifier on success or FALSE
on failure.
Changelog
Version | Description |
---|---|
4.3.0 | Added the client_flags parameter.
|
4.2.0 | Added the new_link parameter. |
Examples
Example 20.20. mysql_connect
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } echo 'Connected successfully'; mysql_close($link); ?>
Example 20.21. mysql_connect
example using hostname:port
syntax
<?php // we connect to example.com and port 3307 $link = mysql_connect('example.com:3307', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } echo 'Connected successfully'; mysql_close($link); // we connect to localhost at port 3307 $link = mysql_connect('127.0.0.1:3307', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } echo 'Connected successfully'; mysql_close($link); ?>
Example 20.22. mysql_connect
example using ':/path/to/socket' syntax
<?php // we connect to localhost and socket e.g. /tmp/mysql.sock // variant 1: omit localhost $link = mysql_connect(':/tmp/mysql', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } echo 'Connected successfully'; mysql_close($link); // variant 2: with localhost $link = mysql_connect('localhost:/tmp/mysql.sock', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } echo 'Connected successfully'; mysql_close($link); ?>
Notes
NoteWhenever you specify 'localhost' or 'localhost:port' as server, the MariaDB client library will override this and try to connect to a local socket (named pipe on Windows). If you want to use TCP/IP, use '127.0.0.1' instead of 'localhost'. If the MariaDB client library tries to connect to the wrong local socket, you should set the correct path as mysql.default_host
string in your PHP configuration and leave the server field blank.Note
The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling mysql_close
.Note
You can suppress the error message on failure by prepending a @ to the function name.Note
Error 'Can't create TCP/IP socket (10106)' usually means that the variables_order configure directive doesn't contain character E
. On Windows, if the environment is not copied the SYSTEMROOT
environment variable won't be available and PHP will have problems loading Winsock.
See Also
mysql_pconnect
|
mysql_close |
mysql_create_db
mysql_create_db
Create a MariaDB database
Description
bool mysql_create_db(string database_name,
resource link_identifier= =NULL);
mysql_create_db
attempts to create a new database on the server associated with the specified link identifier.
Parameters
database_name
-
The name of the database being created.
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.23. mysql_create_db
alternative example
The function mysql_create_db
is deprecated. It is preferable to use mysql_query
to issue an sql CREATE DATABASE
statement instead.
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } $sql = 'CREATE DATABASE my_db'; if (mysql_query($sql, $link)) { echo 'Database my_db created successfully\n'; } else { echo 'Error creating database: ' . mysql_error() . '\n'; } ?>
The above example will output something similar to:
Database my_db created successfully
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_createdb
Note
This function will not be available if the MariaDB extension was built against a MariaDB 4.x client library.
See Also
mysql_query
|
mysql_select_db |
mysql_data_seek
mysql_data_seek
Move internal result pointer
Description
bool mysql_data_seek(resource result,
int row_number);
mysql_data_seek
moves the internal row pointer of the MariaDB result associated with the specified result identifier to point to the specified row number. The next call to a MariaDB fetch function, such as mysql_fetch_assoc
, would return that row.
row_number
starts at 0. The row_number
should be a value in the range from 0 to mysql_num_rows
- 1. However if the result set is empty (mysql_num_rows
== 0), a seek to 0 will fail with a E_WARNING and mysql_data_seek
will return FALSE
.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. row_number
-
The desired row number of the new result pointer.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.24. mysql_data_seek
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } $db_selected = mysql_select_db('sample_db'); if (!$db_selected) { die('Could not select database: ' . mysql_error()); } $query = 'SELECT last_name, first_name FROM friends'; $result = mysql_query($query); if (!$result) { die('Query failed: ' . mysql_error()); } /* fetch rows in reverse order */ for ($i = mysql_num_rows($result) - 1; $i >= 0; $i--) { if (!mysql_data_seek($result, $i)) { echo 'Cannot seek to row $i: ' . mysql_error() . '\n'; continue; } if (!($row = mysql_fetch_assoc($result))) { continue; } echo $row['last_name'] . ' ' . $row['first_name'] . '<br />\n'; } mysql_free_result($result); ?>
Notes
NoteThe function mysql_data_seek
can be used in conjunction only with mysql_query
, not with mysql_unbuffered_query
.
See Also
mysql_query
|
mysql_num_rows
|
mysql_fetch_row
|
mysql_fetch_assoc
|
mysql_fetch_array
|
mysql_fetch_object |
mysql_db_name
mysql_db_name
Retrieves database name from the call to
mysql_list_dbs
Description
string mysql_db_name(resource result,
int row,
mixed field= =NULL);
Retrieve the database name from a call to mysql_list_dbs
.
Parameters
result
-
The result pointer from a call to
mysql_list_dbs
. row
-
The index into the result set.
field
-
The field name.
Return Values
Returns the database name on success, and FALSE
on failure. If FALSE
is returned, use mysql_error
to determine the nature of the error.
Examples
Example 20.25. mysql_db_name
example
<?php error_reporting(E_ALL); $link = mysql_connect('dbhost', 'username', 'password'); $db_list = mysql_list_dbs($link); $i = 0; $cnt = mysql_num_rows($db_list); while ($i < $cnt) { echo mysql_db_name($db_list, $i) . '\n'; $i++; } ?>
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_dbname
See Also
mysql_list_dbs
|
mysql_tablename |
mysql_db_query
mysql_db_query
Selects a database and executes a query on it
Description
resource mysql_db_query(string database,
string query,
resource link_identifier= =NULL);
mysql_db_query
selects a database, and executes a query on it.Warning
This function has been DEPRECATED as of PHP 5.3.0. Relying on this feature is highly discouraged.
Parameters
database
-
The name of the database that will be selected.
query
-
The MariaDB query.
Data inside the query should be properly escaped.
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns a positive MariaDB result resource to the query result, or FALSE
on error. The function also returns TRUE
/ FALSE
for INSERT
/UPDATE
/DELETE
queries to indicate success/failure.
Changelog
Version | Description |
---|---|
5.3.0 | This function now throws an E_DEPRECATED notice. |
4.0.6 | This function is deprecated, do not use this function. Use mysql_select_db and mysql_query instead. |
Examples
Example 20.26. mysql_db_query
alternative example
<?php if (!$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) { echo 'Could not connect to mysql'; exit; } if (!mysql_select_db('mysql_dbname', $link)) { echo 'Could not select database'; exit; } $sql = 'SELECT foo FROM bar WHERE id = 42'; $result = mysql_query($sql, $link); if (!$result) { echo 'DB Error, could not query the database\n'; echo 'MySQL Error: ' . mysql_error(); exit; } while ($row = mysql_fetch_assoc($result)) { echo $row['foo']; } mysql_free_result($result); ?>
Notes
NoteBe aware that this function does NOT switch back to the database you were connected before. In other words, you can't use this function to temporarily run a sql query on another database, you would have to manually switch back. Users are strongly encouraged to use the database.table
syntax in their sql queries or mysql_select_db
instead of this function.
See Also
mysql_query
|
mysql_select_db |
mysql_drop_db
mysql_drop_db
Drop (delete) a MariaDB database
Description
bool mysql_drop_db(string database_name,
resource link_identifier= =NULL);
mysql_drop_db
attempts to drop (remove) an entire database from the server associated with the specified link identifier. This function is deprecated, it is preferable to use mysql_query
to issue an sql DROP DATABASE
statement instead.
Parameters
database_name
-
The name of the database that will be deleted.
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.27. mysql_drop_db
alternative example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } $sql = 'DROP DATABASE my_db'; if (mysql_query($sql, $link)) { echo 'Database my_db was successfully dropped\n'; } else { echo 'Error dropping database: ' . mysql_error() . '\n'; } ?>
Notes
WarningThis function will not be available if the MariaDB extension was built against a MariaDB 4.x client library.Note
For backward compatibility, the following deprecated alias may be used: mysql_dropdb
See Also
mysql_query |
mysql_errno
mysql_errno
Returns the numerical value of the error message from previous MariaDB operation
Description
int mysql_errno(resource link_identifier= =NULL);
Returns the error number from the last MariaDB function.
Errors coming back from the MariaDB database backend no longer issue warnings. Instead, use mysql_errno
to retrieve the error code. Note that this function only returns the error code from the most recently executed MariaDB function (not including mysql_error
and mysql_errno
), so if you want to use it, make sure you check the value before calling another MariaDB function.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns the error number from the last MariaDB function, or 0
(zero) if no error occurred.
Examples
Example 20.28. mysql_errno
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!mysql_select_db('nonexistentdb', $link)) { echo mysql_errno($link) . ': ' . mysql_error($link). '\n'; } mysql_select_db('kossu', $link); if (!mysql_query('SELECT * FROM nonexistenttable', $link)) { echo mysql_errno($link) . ': ' . mysql_error($link) . '\n'; } ?>
The above example will output something similar to:
1049: Unknown database 'nonexistentdb' 1146: Table 'kossu.nonexistenttable' doesn't exist
See Also
mysql_error
|
MySQL error codes |
mysql_error
mysql_error
Returns the text of the error message from previous MariaDB operation
Description
string mysql_error(resource link_identifier= =NULL);
Returns the error text from the last MariaDB function. Errors coming back from the MariaDB database backend no longer issue warnings. Instead, use mysql_error
to retrieve the error text. Note that this function only returns the error text from the most recently executed MariaDB function (not including mysql_error
and mysql_errno
), so if you want to use it, make sure you check the value before calling another MariaDB function.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns the error text from the last MariaDB function, or ''
(empty string) if no error occurred.
Examples
Example 20.29. mysql_error
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); mysql_select_db('nonexistentdb', $link); echo mysql_errno($link) . ': ' . mysql_error($link). '\n'; mysql_select_db('kossu', $link); mysql_query('SELECT * FROM nonexistenttable', $link); echo mysql_errno($link) . ': ' . mysql_error($link) . '\n'; ?>
The above example will output something similar to:
1049: Unknown database 'nonexistentdb' 1146: Table 'kossu.nonexistenttable' doesn't exist
See Also
mysql_errno
|
MySQL error codes |
mysql_escape_string
mysql_escape_string
Escapes a string for use in a mysql_query
Description
string mysql_escape_string(string unescaped_string);
This function will escape the unescaped_string
, so that it is safe to place it in a mysql_query
. This function is deprecated.
This function is identical to mysql_real_escape_string
except that mysql_real_escape_string
takes a connection handler and escapes the string according to the current character set. mysql_escape_string
does not take a connection argument and does not respect the current charset setting.Warning
This function has been DEPRECATED as of PHP 5.3.0. Relying on this feature is highly discouraged.
Parameters
unescaped_string
-
The string that is to be escaped.
Return Values
Returns the escaped string.
Changelog
Version | Description |
---|---|
5.3.0 | This function now throws an E_DEPRECATED notice. |
4.3.0 | This function became deprecated, do not use this function. Instead, use mysql_real_escape_string . |
Examples
Example 20.30. mysql_escape_string
example
<?php $item = 'Zak's Laptop'; $escaped_item = mysql_escape_string($item); printf('Escaped string: %s\n', $escaped_item); ?>
The above example will output:
Escaped string: Zak\'s Laptop
Notes
Notemysql_escape_string
does not escape %
and _
.
See Also
mysql_real_escape_string
|
addslashes
|
The magic_quotes_gpc directive. |
mysql_fetch_array
mysql_fetch_array
Fetch a result row as an associative array, a numeric array, or both
Description
array mysql_fetch_array(resource result,
int result_type= =MYSQL_BOTH);
Returns an array that corresponds to the fetched row and moves the internal data pointer ahead.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. result_type
-
The type of array that is to be fetched. It's a constant and can take the following values:
MYSQL_ASSOC
,MYSQL_NUM
, andMYSQL_BOTH
.
Return Values
Returns an array of strings that corresponds to the fetched row, or FALSE
if there are no more rows. The type of returned array depends on how result_type
is defined. By using MYSQL_BOTH
(default), you'll get an array with both associative and number indices. Using MYSQL_ASSOC
, you only get associative indices (as mysql_fetch_assoc
works), using MYSQL_NUM
, you only get number indices (as mysql_fetch_row
works).
If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you must use the numeric index of the column or make an alias for the column. For aliased columns, you cannot access the contents with the original column name.
Examples
Example 20.31. Query with aliased duplicate field names
SELECT table1.field AS foo, table2.field AS bar FROM table1, table2
Example 20.32. mysql_fetch_array
with MYSQL_NUM
<?php mysql_connect('localhost', 'mysql_user', 'mysql_password') or die('Could not connect: ' . mysql_error()); mysql_select_db('mydb'); $result = mysql_query('SELECT id, name FROM mytable'); while ($row = mysql_fetch_array($result, MYSQL_NUM)) { printf('ID: %s Name: %s', $row[0], $row[1]); } mysql_free_result($result); ?>
Example 20.33. mysql_fetch_array
with MYSQL_ASSOC
<?php mysql_connect('localhost', 'mysql_user', 'mysql_password') or die('Could not connect: ' . mysql_error()); mysql_select_db('mydb'); $result = mysql_query('SELECT id, name FROM mytable'); while ($row = mysql_fetch_array($result, MYSQL_ASSOC)) { printf('ID: %s Name: %s', $row['id'], $row['name']); } mysql_free_result($result); ?>
Example 20.34. mysql_fetch_array
with MYSQL_BOTH
<?php mysql_connect('localhost', 'mysql_user', 'mysql_password') or die('Could not connect: ' . mysql_error()); mysql_select_db('mydb'); $result = mysql_query('SELECT id, name FROM mytable'); while ($row = mysql_fetch_array($result, MYSQL_BOTH)) { printf ('ID: %s Name: %s', $row[0], $row['name']); } mysql_free_result($result); ?>
Notes
PerformanceAn important thing to note is that using mysql_fetch_array
is not significantly slower than using mysql_fetch_row
, while it provides a significant added value.Note
Field names returned by this function are case-sensitive.Note
This function sets NULL fields to the PHP NULL
value.
See Also
mysql_fetch_row
|
mysql_fetch_assoc
|
mysql_data_seek
|
mysql_query |
mysql_fetch_assoc
mysql_fetch_assoc
Fetch a result row as an associative array
Description
array mysql_fetch_assoc(resource result);
Returns an associative array that corresponds to the fetched row and moves the internal data pointer ahead. mysql_fetch_assoc
is equivalent to calling mysql_fetch_array
with MYSQL_ASSOC for the optional second parameter. It only returns an associative array.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
.
Return Values
Returns an associative array of strings that corresponds to the fetched row, or FALSE
if there are no more rows.
If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you either need to access the result with numeric indices by using mysql_fetch_row
or add alias names. See the example at the mysql_fetch_array
description about aliases.
Examples
Example 20.35. An expanded mysql_fetch_assoc
example
<?php $conn = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$conn) { echo 'Unable to connect to DB: ' . mysql_error(); exit; } if (!mysql_select_db('mydbname')) { echo 'Unable to select mydbname: ' . mysql_error(); exit; } $sql = 'SELECT id as userid, fullname, userstatus FROM sometable WHERE userstatus = 1'; $result = mysql_query($sql); if (!$result) { echo 'Could not successfully run query ($sql) from DB: ' . mysql_error(); exit; } if (mysql_num_rows($result) == 0) { echo 'No rows found, nothing to print so am exiting'; exit; } // While a row of data exists, put that row in $row as an associative array // Note: If you're expecting just one row, no need to use a loop // Note: If you put extract($row); inside the following loop, you'll // then create $userid, $fullname, and $userstatus while ($row = mysql_fetch_assoc($result)) { echo $row['userid']; echo $row['fullname']; echo $row['userstatus']; } mysql_free_result($result); ?>
Notes
PerformanceAn important thing to note is that using mysql_fetch_assoc
is not significantly slower than using mysql_fetch_row
, while it provides a significant added value.Note
Field names returned by this function are case-sensitive.Note
This function sets NULL fields to the PHP NULL
value.
See Also
mysql_fetch_row
|
mysql_fetch_array
|
mysql_data_seek
|
mysql_query
|
mysql_error |
mysql_fetch_field
mysql_fetch_field
Get column information from a result and return as an object
Description
object mysql_fetch_field(resource result,
int field_offset= =0);
Returns an object containing field information. This function can be used to obtain information about fields in the provided query result.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. field_offset
-
The numerical field offset. If the field offset is not specified, the next field that was not yet retrieved by this function is retrieved. The
field_offset
starts at0
.
Return Values
Returns an object containing field information. The properties of the object are:
- name - column name
- table - name of the table the column belongs to
- max_length - maximum length of the column
- not_null - 1 if the column cannot be
NULL
- primary_key - 1 if the column is a primary key
- unique_key - 1 if the column is a unique key
- multiple_key - 1 if the column is a non-unique key
- numeric - 1 if the column is numeric
- blob - 1 if the column is a BLOB
- type - the type of the column
- unsigned - 1 if the column is unsigned
- zerofill - 1 if the column is zero-filled
Examples
Example 20.36. mysql_fetch_field
example
<?php $conn = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$conn) { die('Could not connect: ' . mysql_error()); } mysql_select_db('database'); $result = mysql_query('select * from table'); if (!$result) { die('Query failed: ' . mysql_error()); } /* get column metadata */ $i = 0; while ($i < mysql_num_fields($result)) { echo 'Information for column $i:<br />\n'; $meta = mysql_fetch_field($result, $i); if (!$meta) { echo 'No information available<br />\n'; } echo '<pre> blob: $meta->blob max_length: $meta->max_length multiple_key: $meta->multiple_key name: $meta->name not_null: $meta->not_null numeric: $meta->numeric primary_key: $meta->primary_key table: $meta->table type: $meta->type unique_key: $meta->unique_key unsigned: $meta->unsigned zerofill: $meta->zerofill </pre>'; $i++; } mysql_free_result($result); ?>
Notes
NoteField names returned by this function are case-sensitive.
See Also
mysql_field_seek |
mysql_fetch_lengths
mysql_fetch_lengths
Get the length of each output in a result
Description
array mysql_fetch_lengths(resource result);
Returns an array that corresponds to the lengths of each field in the last row fetched by MySQL.
mysql_fetch_lengths
stores the lengths of each result column in the last row returned by mysql_fetch_row
, mysql_fetch_assoc
, mysql_fetch_array
, and mysql_fetch_object
in an array, starting at offset 0.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
.
Return Values
An array of lengths on success or FALSE
on failure.
Examples
Example 20.37. A mysql_fetch_lengths
example
<?php $result = mysql_query('SELECT id,email FROM people WHERE id = '42''); if (!$result) { echo 'Could not run query: ' . mysql_error(); exit; } $row = mysql_fetch_assoc($result); $lengths = mysql_fetch_lengths($result); print_r($row); print_r($lengths); ?>
The above example will output something similar to:
Array ( [id] => 42 [email] => user@example.com ) Array ( [0] => 2 [1] => 16 )
See Also
mysql_field_len
|
mysql_fetch_row
|
strlen |
mysql_fetch_object
mysql_fetch_object
Fetch a result row as an object
Description
object mysql_fetch_object(resource result,
string class_name,
array params);
Returns an object with properties that correspond to the fetched row and moves the internal data pointer ahead.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. class_name
-
The name of the class to instantiate, set the properties of and return. If not specified, a
stdClass
object is returned. params
-
An optional array of parameters to pass to the constructor for
class_name
objects.
Return Values
Returns an object with string properties that correspond to the fetched row, or FALSE
if there are no more rows.
Changelog
Version | Description |
---|---|
5.0.0 | Added the ability to return as a different object. |
Examples
Example 20.38. mysql_fetch_object
example
<?php mysql_connect('hostname', 'user', 'password'); mysql_select_db('mydb'); $result = mysql_query('select * from mytable'); while ($row = mysql_fetch_object($result)) { echo $row->user_id; echo $row->fullname; } mysql_free_result($result); ?>
Example 20.39. mysql_fetch_object
example
<?php class foo { public $name; } mysql_connect('hostname', 'user', 'password'); mysql_select_db('mydb'); $result = mysql_query('select name from mytable limit 1'); $obj = mysql_fetch_object($result, 'foo'); var_dump($obj); ?>
Notes
PerformanceSpeed-wise, the function is identical to mysql_fetch_array
, and almost as quick as mysql_fetch_row
(the difference is insignificant).Note
mysql-fetch-object
is similar to mysql_fetch_array
, with one difference - an object is returned, instead of an array. Indirectly, that means that you can only access the data by the field names, and not by their offsets (numbers are illegal property names).Note
Field names returned by this function are case-sensitive.Note
This function sets NULL fields to the PHP NULL
value.
See Also
mysql_fetch_array
|
mysql_fetch_assoc
|
mysql_fetch_row
|
mysql_data_seek
|
mysql_query |
mysql_fetch_row
mysql_fetch_row
Get a result row as an enumerated array
Description
array mysql_fetch_row(resource result);
Returns a numerical array that corresponds to the fetched row and moves the internal data pointer ahead.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
.
Return Values
Returns an numerical array of strings that corresponds to the fetched row, or FALSE
if there are no more rows.
mysql_fetch_row
fetches one row of data from the result associated with the specified result identifier. The row is returned as an array. Each result column is stored in an array offset, starting at offset 0.
Examples
Example 20.40. Fetching one row with mysql_fetch_row
<?php $result = mysql_query('SELECT id,email FROM people WHERE id = '42''); if (!$result) { echo 'Could not run query: ' . mysql_error(); exit; } $row = mysql_fetch_row($result); echo $row[0]; // 42 echo $row[1]; // the email value ?>
Notes
NoteThis function sets NULL fields to the PHP NULL
value.
See Also
mysql_fetch_array
|
mysql_fetch_assoc
|
mysql_fetch_object
|
mysql_data_seek
|
mysql_fetch_lengths
|
mysql_result |
mysql_field_flags
mysql_field_flags
Get the flags associated with the specified field in a result
Description
string mysql_field_flags(resource result,
int field_offset);
mysql_field_flags
returns the field flags of the specified field. The flags are reported as a single word per flag separated by a single space, so that you can split the returned value using explode
.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. field_offset
-
The numerical field offset. The
field_offset
starts at0
. Iffield_offset
does not exist, an error of levelE_WARNING
is also issued.
Return Values
Returns a string of flags associated with the result or FALSE
on failure.
The following flags are reported, if your version of MariaDB is current enough to support them: 'not_null'
, 'primary_key'
, 'unique_key'
, 'multiple_key'
, 'blob'
, 'unsigned'
, 'zerofill'
, 'binary'
, 'enum'
, 'auto_increment'
and 'timestamp'
.
Examples
Example 20.41. A mysql_field_flags
example
<?php $result = mysql_query('SELECT id,email FROM people WHERE id = '42''); if (!$result) { echo 'Could not run query: ' . mysql_error(); exit; } $flags = mysql_field_flags($result, 0); echo $flags; print_r(explode(' ', $flags)); ?>
The above example will output something similar to:
not_null primary_key auto_increment Array ( [0] => not_null [1] => primary_key [2] => auto_increment )
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_fieldflags
See Also
mysql_field_type
|
mysql_field_len |
mysql_field_len
mysql_field_len
Returns the length of the specified field
Description
int mysql_field_len(resource result,
int field_offset);
mysql_field_len
returns the length of the specified field.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. field_offset
-
The numerical field offset. The
field_offset
starts at0
. Iffield_offset
does not exist, an error of levelE_WARNING
is also issued.
Return Values
The length of the specified field index on success or FALSE
on failure.
Examples
Example 20.42. mysql_field_len
example
<?php $result = mysql_query('SELECT id,email FROM people WHERE id = '42''); if (!$result) { echo 'Could not run query: ' . mysql_error(); exit; } // Will get the length of the id field as specified in the database // schema. $length = mysql_field_len($result, 0); echo $length; ?>
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_fieldlen
See Also
mysql_fetch_lengths
|
strlen |
mysql_field_name
mysql_field_name
Get the name of the specified field in a result
Description
string mysql_field_name(resource result,
int field_offset);
mysql_field_name
returns the name of the specified field index.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. field_offset
-
The numerical field offset. The
field_offset
starts at0
. Iffield_offset
does not exist, an error of levelE_WARNING
is also issued.
Return Values
The name of the specified field index on success or FALSE
on failure.
Examples
Example 20.43. mysql_field_name
example
<?php /* The users table consists of three fields: * user_id * username * password. */ $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect to MariaDB server: ' . mysql_error()); } $dbname = 'mydb'; $db_selected = mysql_select_db($dbname, $link); if (!$db_selected) { die('Could not set $dbname: ' . mysql_error()); } $res = mysql_query('select * from users', $link); echo mysql_field_name($res, 0) . '\n'; echo mysql_field_name($res, 2); ?>
The above example will output:
user_id password
Notes
NoteField names returned by this function are case-sensitive.Note
For backward compatibility, the following deprecated alias may be used: mysql_fieldname
See Also
mysql_field_type
|
mysql_field_len |
mysql_field_seek
mysql_field_seek
Set result pointer to a specified field offset
Description
bool mysql_field_seek(resource result,
int field_offset);
Seeks to the specified field offset. If the next call to mysql_fetch_field
doesn't include a field offset, the field offset specified in mysql_field_seek
will be returned.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. field_offset
-
The numerical field offset. The
field_offset
starts at0
. Iffield_offset
does not exist, an error of levelE_WARNING
is also issued.
Return Values
Returns TRUE
on success or FALSE
on failure.
See Also
mysql_fetch_field |
mysql_field_table
mysql_field_table
Get name of the table the specified field is in
Description
string mysql_field_table(resource result,
int field_offset);
Returns the name of the table that the specified field is in.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. field_offset
-
The numerical field offset. The
field_offset
starts at0
. Iffield_offset
does not exist, an error of levelE_WARNING
is also issued.
Return Values
The name of the table on success.
Examples
Example 20.44. A mysql_field_table
example
<?php $query = 'SELECT account.*, country.* FROM account, country WHERE country.name = 'Portugal' AND account.country_id = country.id'; // get the result from the DB $result = mysql_query($query); // Lists the table name and then the field name for ($i = 0; $i < mysql_num_fields($result); ++$i) { $table = mysql_field_table($result, $i); $field = mysql_field_name($result, $i); echo '$table: $field\n'; } ?>
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_fieldtable
See Also
mysql_list_tables |
mysql_field_type
mysql_field_type
Get the type of the specified field in a result
Description
string mysql_field_type(resource result,
int field_offset);
mysql-field-type
is similar to the mysql_field_name
function. The arguments are identical, but the field type is returned instead.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. field_offset
-
The numerical field offset. The
field_offset
starts at0
. Iffield_offset
does not exist, an error of levelE_WARNING
is also issued.
Return Values
The returned field type will be one of 'int'
, 'real'
, 'string'
, 'blob'
, and others as detailed in the MySQL documentation.
Examples
Example 20.45. mysql_field_type
example
<?php mysql_connect('localhost', 'mysql_username', 'mysql_password'); mysql_select_db('mysql'); $result = mysql_query('SELECT * FROM func'); $fields = mysql_num_fields($result); $rows = mysql_num_rows($result); $table = mysql_field_table($result, 0); echo 'Your '' . $table . '' table has ' . $fields . ' fields and ' . $rows . ' record(s)\n'; echo 'The table has the following fields:\n'; for ($i=0; $i < $fields; $i++) { $type = mysql_field_type($result, $i); $name = mysql_field_name($result, $i); $len = mysql_field_len($result, $i); $flags = mysql_field_flags($result, $i); echo $type . ' ' . $name . ' ' . $len . ' ' . $flags . '\n'; } mysql_free_result($result); mysql_close(); ?>
The above example will output something similar to:
Your 'func' table has 4 fields and 1 record(s) The table has the following fields: string name 64 not_null primary_key binary int ret 1 not_null string dl 128 not_null string type 9 not_null enum
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_fieldtype
See Also
mysql_field_name
|
mysql_field_len |
mysql_free_result
mysql_free_result
Free result memory
Description
bool mysql_free_result(resource result);
mysql_free_result
will free all memory associated with the result identifier result
.
mysql_free_result
only needs to be called if you are concerned about how much memory is being used for queries that return large result sets. All associated result memory is automatically freed at the end of the script's execution.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
.
Return Values
Returns TRUE
on success or FALSE
on failure.
If a non-resource is used for the result
, an error of level E_WARNING will be emitted. It's worth noting that mysql_query
only returns a resource for SELECT, SHOW, EXPLAIN, and DESCRIBE queries.
Examples
Example 20.46. A mysql_free_result
example
<?php $result = mysql_query('SELECT id,email FROM people WHERE id = '42''); if (!$result) { echo 'Could not run query: ' . mysql_error(); exit; } /* Use the result, assuming we're done with it afterwards */ $row = mysql_fetch_assoc($result); /* Now we free up the result and continue on with our script */ mysql_free_result($result); echo $row['id']; echo $row['email']; ?>
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_freeresult
See Also
mysql_query
|
is_resource |
mysql_get_client_info
mysql_get_client_info
Get MariaDB client info
Description
string mysql_get_client_info();
mysql_get_client_info
returns a string that represents the client library version.
Return Values
The MariaDB client version.
Examples
Example 20.47. mysql_get_client_info
example
<?php printf('MySQL client info: %s\n', mysql_get_client_info()); ?>
The above example will output something similar to:
MySQL client info: 3.23.39
See Also
mysql_get_host_info
|
mysql_get_proto_info
|
mysql_get_server_info |
mysql_get_host_info
mysql_get_host_info
Get MariaDB host info
Description
string mysql_get_host_info(resource link_identifier= =NULL);
Describes the type of connection in use for the connection, including the server host name.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns a string describing the type of MariaDB connection in use for the connection or FALSE
on failure.
Examples
Example 20.48. mysql_get_host_info
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } printf('MySQL host info: %s\n', mysql_get_host_info()); ?>
The above example will output something similar to:
MySQL host info: Localhost via UNIX socket
See Also
mysql_get_client_info
|
mysql_get_proto_info
|
mysql_get_server_info |
mysql_get_proto_info
mysql_get_proto_info
Get MariaDB protocol info
Description
int mysql_get_proto_info(resource link_identifier= =NULL);
Retrieves the MariaDB protocol.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns the MariaDB protocol on success or FALSE
on failure.
Examples
Example 20.49. mysql_get_proto_info
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } printf('MySQL protocol version: %s\n', mysql_get_proto_info()); ?>
The above example will output something similar to:
MySQL protocol version: 10
See Also
mysql_get_client_info
|
mysql_get_host_info
|
mysql_get_server_info |
mysql_get_server_info
mysql_get_server_info
Get MariaDB server info
Description
string mysql_get_server_info(resource link_identifier= =NULL);
Retrieves the MariaDB server version.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns the MariaDB server version on success or FALSE
on failure.
Examples
Example 20.50. mysql_get_server_info
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } printf('MySQL server version: %s\n', mysql_get_server_info()); ?>
The above example will output something similar to:
MySQL server version: 4.0.1-alpha
See Also
mysql_get_client_info
|
mysql_get_host_info
|
mysql_get_proto_info
|
phpversion |
mysql_info
mysql_info
Get information about the most recent query
Description
string mysql_info(resource link_identifier= =NULL);
Returns detailed information about the last query.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns information about the statement on success, or FALSE
on failure. See the example below for which statements provide information, and what the returned value may look like. Statements that are not listed will return FALSE
.
Examples
Example 20.51. Relevant MariaDB Statements
Statements that return string values. The numbers are only for illustrating purpose; their values will correspond to the query.
INSERT INTO ... SELECT ... String format: Records: 23 Duplicates: 0 Warnings: 0 INSERT INTO ... VALUES (...),(...),(...)... String format: Records: 37 Duplicates: 0 Warnings: 0 LOAD DATA INFILE ... String format: Records: 42 Deleted: 0 Skipped: 0 Warnings: 0 ALTER TABLE String format: Records: 60 Duplicates: 0 Warnings: 0 UPDATE String format: Rows matched: 65 Changed: 65 Warnings: 0
Notes
Notemysql_info
returns a non- FALSE
value for the INSERT ... VALUES statement only if multiple value lists are specified in the statement.
See Also
mysql_affected_rows
|
mysql_insert_id
|
mysql_stat |
mysql_insert_id
mysql_insert_id
Get the ID generated in the last query
Description
int mysql_insert_id(resource link_identifier= =NULL);
Retrieves the ID generated for an AUTO_INCREMENT column by the previous query (usually INSERT).
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
The ID generated for an AUTO_INCREMENT column by the previous query on success, 0
if the previous query does not generate an AUTO_INCREMENT value, or FALSE
if no MariaDB connection was established.
Examples
Example 20.52. mysql_insert_id
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } mysql_select_db('mydb'); mysql_query('INSERT INTO mytable (product) values ('kossu')'); printf('Last inserted record has id %d\n', mysql_insert_id()); ?>
Notes
Cautionmysql_insert_id
will convert the return type of the native MariaDB C API function mysql_insert_id()
to a type of long
(named int in PHP). If your AUTO_INCREMENT column has a column type of BIGINT (64 bits) the conversion may result in an incorrect value. Instead, use the internal MariaDB SQL function LAST_INSERT_ID() in an SQL query. For more information about PHP's maximum integer values, please see the integer documentation.Note
Because mysql_insert_id
acts on the last performed query, be sure to call mysql_insert_id
immediately after the query that generates the value.Note
The value of the MariaDB SQL function LAST_INSERT_ID()
always contains the most recently generated AUTO_INCREMENT value, and is not reset between queries.
See Also
mysql_query
|
mysql_info |
mysql_list_dbs
mysql_list_dbs
List databases available on a MariaDB server
Description
resource mysql_list_dbs(resource link_identifier= =NULL);
Returns a result pointer containing the databases available from the current mysql daemon.Warning
This function has been DEPRECATED as of PHP 5.4.0. Relying on this function is highly discouraged.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns a result pointer resource on success, or FALSE
on failure. Use the mysql_tablename
function to traverse this result pointer, or any function for result tables, such as mysql_fetch_array
.
Examples
Example 20.53. mysql_list_dbs
example
<?php // Usage without mysql_list_dbs() $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); $res = mysql_query('SHOW DATABASES'); while ($row = mysql_fetch_assoc($res)) { echo $row['Database'] . '\n'; } // Deprecated as of PHP 5.4.0 $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); $db_list = mysql_list_dbs($link); while ($row = mysql_fetch_object($db_list)) { echo $row->Database . '\n'; } ?>
The above example will output something similar to:
database1 database2 database3
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_listdbs
See Also
mysql_db_name
|
mysql_select_db |
mysql_list_fields
mysql_list_fields
List MariaDB table fields
Description
resource mysql_list_fields(string database_name,
string table_name,
resource link_identifier= =NULL);
Retrieves information about the given table name.
This function is deprecated. It is preferable to use mysql_query
to issue an SQL SHOW COLUMNS FROM table [LIKE 'name']
statement instead.
Parameters
database_name
-
The name of the database that's being queried.
table_name
-
The name of the table that's being queried.
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
A result pointer resource on success, or FALSE
on failure.
The returned result can be used with mysql_field_flags
, mysql_field_len
, mysql_field_name
and mysql_field_type
.
Examples
Example 20.54. Alternate to deprecated mysql_list_fields
<?php $result = mysql_query('SHOW COLUMNS FROM sometable'); if (!$result) { echo 'Could not run query: ' . mysql_error(); exit; } if (mysql_num_rows($result) > 0) { while ($row = mysql_fetch_assoc($result)) { print_r($row); } } ?>
The above example will output something similar to:
Array ( [Field] => id [Type] => int(7) [Null] => [Key] => PRI [Default] => [Extra] => auto_increment ) Array ( [Field] => email [Type] => varchar(100) [Null] => [Key] => [Default] => [Extra] => )
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_listfields
See Also
mysql_field_flags
|
mysql_info |
mysql_list_processes
mysql_list_processes
List MariaDB processes
Description
resource mysql_list_processes(resource link_identifier= =NULL);
Retrieves the current MariaDB server threads.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
A result pointer resource on success or FALSE
on failure.
Examples
Example 20.55. mysql_list_processes
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); $result = mysql_list_processes($link); while ($row = mysql_fetch_assoc($result)){ printf('%s %s %s %s %s\n', $row['Id'], $row['Host'], $row['db'], $row['Command'], $row['Time']); } mysql_free_result($result); ?>
The above example will output something similar to:
1 localhost test Processlist 0 4 localhost mysql sleep 5
See Also
mysql_thread_id
|
mysql_stat |
mysql_list_tables
mysql_list_tables
List tables in a MariaDB database
Description
resource mysql_list_tables(string database,
resource link_identifier= =NULL);
Retrieves a list of table names from a MariaDB database.
This function is deprecated. It is preferable to use mysql_query
to issue an SQL SHOW TABLES [FROM db_name] [LIKE 'pattern']
statement instead.
Parameters
database
-
The name of the database
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
A result pointer resource on success or FALSE
on failure.
Use the mysql_tablename
function to traverse this result pointer, or any function for result tables, such as mysql_fetch_array
.
Changelog
Version | Description |
---|---|
4.3.7 | This function became deprecated. |
Examples
Example 20.56. mysql_list_tables
alternative example
<?php $dbname = 'mysql_dbname'; if (!mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) { echo 'Could not connect to mysql'; exit; } $sql = 'SHOW TABLES FROM $dbname'; $result = mysql_query($sql); if (!$result) { echo 'DB Error, could not list tables\n'; echo 'MySQL Error: ' . mysql_error(); exit; } while ($row = mysql_fetch_row($result)) { echo 'Table: {$row[0]}\n'; } mysql_free_result($result); ?>
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_listtables
See Also
mysql_list_dbs
|
mysql_tablename |
mysql_num_fields
mysql_num_fields
Get number of fields in result
Description
int mysql_num_fields(resource result);
Retrieves the number of fields from a query.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
.
Return Values
Returns the number of fields in the result set resource on success or FALSE
on failure.
Examples
Example 20.57. A mysql_num_fields
example
<?php $result = mysql_query('SELECT id,email FROM people WHERE id = '42''); if (!$result) { echo 'Could not run query: ' . mysql_error(); exit; } /* returns 2 because id,email === two fields */ echo mysql_num_fields($result); ?>
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_numfields
See Also
mysql_select_db
|
mysql_query
|
mysql_fetch_field
|
mysql_num_rows |
mysql_num_rows
mysql_num_rows
Get number of rows in result
Description
int mysql_num_rows(resource result);
Retrieves the number of rows from a result set. This command is only valid for statements like SELECT or SHOW that return an actual result set. To retrieve the number of rows affected by a INSERT, UPDATE, REPLACE or DELETE query, use mysql_affected_rows
.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
.
Return Values
The number of rows in a result set on success or FALSE
on failure.
Examples
Example 20.58. mysql_num_rows
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); mysql_select_db('database', $link); $result = mysql_query('SELECT * FROM table1', $link); $num_rows = mysql_num_rows($result); echo '$num_rows Rows\n'; ?>
Notes
NoteIf you use mysql_unbuffered_query
, mysql_num_rows
will not return the correct value until all the rows in the result set have been retrieved.Note
For backward compatibility, the following deprecated alias may be used: mysql_numrows
See Also
mysql_affected_rows
|
mysql_connect
|
mysql_data_seek
|
mysql_select_db
|
mysql_query |
mysql_pconnect
mysql_pconnect
Open a persistent connection to a MariaDB server
Description
resource mysql_pconnect(string server= =ini_get('mysql.default_host'),
string username= =ini_get('mysql.default_user'),
string password= =ini_get('mysql.default_password'),
int client_flags= =0);
Establishes a persistent connection to a MariaDB server.
mysql-pconnect
acts very much like mysql_connect
with two major differences.
First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, username and password. If one is found, an identifier for it will be returned instead of opening a new connection.
Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (mysql_close
will not close links established by mysql_pconnect
).
This type of link is therefore called 'persistent'.
Parameters
server
-
The MariaDB server. It can also include a port number. e.g. 'hostname:port' or a path to a local socket e.g. ':/path/to/socket' for the localhost.
If the PHP directive mysql.default_host is undefined (default), then the default value is 'localhost:3306'
username
-
The username. Default value is the name of the user that owns the server process.
password
-
The password. Default value is an empty password.
client_flags
-
The
client_flags
parameter can be a combination of the following constants: 128 (enableLOAD DATA LOCAL
handling),MYSQL_CLIENT_SSL
,MYSQL_CLIENT_COMPRESS
,MYSQL_CLIENT_IGNORE_SPACE
orMYSQL_CLIENT_INTERACTIVE
.
Return Values
Returns a MariaDB persistent link identifier on success, or FALSE
on failure.
Changelog
Version | Description |
---|---|
4.3.0 | Added the client_flags parameter. |
Notes
NoteNote, that these kind of links only work if you are using a module version of PHP. See the Persistent Database Connections section for more information.Warning
Using persistent connections can require a bit of tuning of your Apache and MariaDB configurations to ensure that you do not exceed the number of connections allowed by MySQL.Note
You can suppress the error message on failure by prepending a @ to the function name.
See Also
mysql_connect
|
Persistent Database Connections |
mysql_ping
mysql_ping
Ping a server connection or reconnect if there is no connection
Description
bool mysql_ping(resource link_identifier= =NULL);
Checks whether or not the connection to the server is working. If it has gone down, an automatic reconnection is attempted. This function can be used by scripts that remain idle for a long while, to check whether or not the server has closed the connection and reconnect if necessary.Note
Automatic reconnection is disabled by default in versions of MariaDB >= 5.0.3.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns TRUE
if the connection to the server MariaDB server is working, otherwise FALSE
.
Examples
Example 20.59. A mysql_ping
example
<?php set_time_limit(0); $conn = mysql_connect('localhost', 'mysqluser', 'mypass'); $db = mysql_select_db('mydb'); /* Assuming this query will take a long time */ $result = mysql_query($sql); if (!$result) { echo 'Query #1 failed, exiting.'; exit; } /* Make sure the connection is still alive, if not, try to reconnect */ if (!mysql_ping($conn)) { echo 'Lost connection, exiting after query #1'; exit; } mysql_free_result($result); /* So the connection is still alive, let's run another query */ $result2 = mysql_query($sql2); ?>
See Also
mysql_thread_id
|
mysql_list_processes |
mysql_query
mysql_query
Send a MariaDB query
Description
resource mysql_query(string query,
resource link_identifier= =NULL);
mysql_query
sends a unique query (multiple queries are not supported) to the currently active database on the server that's associated with the specified link_identifier
.
Parameters
query
-
An SQL query
The query string should not end with a semicolon. Data inside the query should be properly escaped.
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
For SELECT, SHOW, DESCRIBE, EXPLAIN and other statements returning resultset, mysql_query
returns a resource on success, or FALSE
on error.
For other type of SQL statements, INSERT, UPDATE, DELETE, DROP, etc, mysql_query
returns TRUE
on success or FALSE
on error.
The returned result resource should be passed to mysql_fetch_array
, and other functions for dealing with result tables, to access the returned data.
Use mysql_num_rows
to find out how many rows were returned for a SELECT statement or mysql_affected_rows
to find out how many rows were affected by a DELETE, INSERT, REPLACE, or UPDATE statement.
mysql_query
will also fail and return FALSE
if the user does not have permission to access the table(s) referenced by the query.
Examples
Example 20.60. Invalid Query
The following query is syntactically invalid, so mysql_query
fails and returns FALSE
.
<?php $result = mysql_query('SELECT * WHERE 1=1'); if (!$result) { die('Invalid query: ' . mysql_error()); } ?>
Example 20.61. Valid Query
The following query is valid, so mysql_query
returns a resource.
<?php // This could be supplied by a user, for example $firstname = 'fred'; $lastname = 'fox'; // Formulate Query // This is the best way to perform an SQL query // For more examples, see mysql_real_escape_string() $query = sprintf('SELECT firstname, lastname, address, age FROM friends WHERE firstname="%s" AND lastname="%s"', mysql_real_escape_string($firstname), mysql_real_escape_string($lastname)); // Perform Query $result = mysql_query($query); // Check result // This shows the actual query sent to MySQL, and the error. Useful for debugging. if (!$result) { $message = 'Invalid query: ' . mysql_error() . '\n'; $message .= 'Whole query: ' . $query; die($message); } // Use result // Attempting to print $result won't allow access to information in the resource // One of the mysql result functions must be used // See also mysql_result(), mysql_fetch_array(), mysql_fetch_row(), etc. while ($row = mysql_fetch_assoc($result)) { echo $row['firstname']; echo $row['lastname']; echo $row['address']; echo $row['age']; } // Free the resources associated with the result set // This is done automatically at the end of the script mysql_free_result($result); ?>
See Also
mysql_connect
|
mysql_error
|
mysql_real_escape_string
|
mysql_result
|
mysql_fetch_assoc
|
mysql_unbuffered_query |
mysql_real_escape_string
mysql_real_escape_string
Escapes special characters in a string for use in an SQL statement
Description
string mysql_real_escape_string(string unescaped_string,
resource link_identifier= =NULL);
Escapes special characters in the unescaped_string
, taking into account the current character set of the connection so that it is safe to place it in a mysql_query
. If binary data is to be inserted, this function must be used.
mysql_real_escape_string
calls MySQL's library function mysql_real_escape_string, which prepends backslashes to the following characters: \x00
, \n
, \r
, \
, '
, '
and \x1a
.
This function must always (with few exceptions) be used to make data safe before sending a query to MariaDB.
Parameters
unescaped_string
-
The string that is to be escaped.
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns the escaped string, or FALSE
on error.
Examples
Example 20.62. Simple mysql_real_escape_string
example
<?php // Connect $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password') OR die(mysql_error()); // Query $query = sprintf('SELECT * FROM users WHERE user="%s" AND password="%s"', mysql_real_escape_string($user), mysql_real_escape_string($password)); ?>
Example 20.63. An example SQL Injection Attack
<?php // We didn't check $_POST['password'], it could be anything the user wanted! For example: $_POST['username'] = 'aidan'; $_POST['password'] = '' OR ''=''; // Query database to check if there are any matching users $query = 'SELECT * FROM users WHERE user="{$_POST["username']}' AND password="{$_POST["password']}''; mysql_query($query); // This means the query sent to MariaDB would be: echo $query; ?>
The query sent to MySQL:
SELECT * FROM users WHERE user="aidan" AND password="" OR ''=''
This would allow anyone to log in without a valid password.
Notes
NoteA MariaDB connection is required before using mysql_real_escape_string
otherwise an error of level E_WARNING
is generated, and FALSE
is returned. If link_identifier
isn't defined, the last MariaDB connection is used.Note
If magic_quotes_gpc is enabled, first apply stripslashes
to the data. Using this function on data which has already been escaped will escape the data twice.Note
If this function is not used to escape data, the query is vulnerable to SQL Injection Attacks.Note
mysql_real_escape_string
does not escape %
and _
. These are wildcards in MariaDB if combined with LIKE
, GRANT
, or REVOKE
.
See Also
mysql_client_encoding
|
addslashes
|
stripslashes
|
The magic_quotes_gpc directive |
The magic_quotes_runtime directive |
mysql_result
mysql_result
Get result data
Description
string mysql_result(resource result,
int row,
mixed field= =0);
Retrieves the contents of one cell from a MariaDB result set.
When working on large result sets, you should consider using one of the functions that fetch an entire row (specified below). As these functions return the contents of multiple cells in one function call, they're MUCH quicker than mysql_result
. Also, note that specifying a numeric offset for the field argument is much quicker than specifying a fieldname or tablename.fieldname argument.
Parameters
result
-
The result resource that is being evaluated. This result comes from a call to
mysql_query
. row
-
The row number from the result that's being retrieved. Row numbers start at
0
. field
-
The name or offset of the field being retrieved.
It can be the field's offset, the field's name, or the field's table dot field name (tablename.fieldname). If the column name has been aliased ('select foo as bar from...'), use the alias instead of the column name. If undefined, the first field is retrieved.
Return Values
The contents of one cell from a MariaDB result set on success, or FALSE
on failure.
Examples
Example 20.64. mysql_result
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Could not connect: ' . mysql_error()); } if (!mysql_select_db('database_name')) { die('Could not select database: ' . mysql_error()); } $result = mysql_query('SELECT name FROM work.employee'); if (!$result) { die('Could not query:' . mysql_error()); } echo mysql_result($result, 2); // outputs third employee's name mysql_close($link); ?>
Notes
NoteCalls to mysql_result
should not be mixed with calls to other functions that deal with the result set.
See Also
mysql_fetch_row
|
mysql_fetch_array
|
mysql_fetch_assoc
|
mysql_fetch_object |
mysql_select_db
mysql_select_db
Select a MariaDB database
Description
bool mysql_select_db(string database_name,
resource link_identifier= =NULL);
Sets the current active database on the server that's associated with the specified link identifier. Every subsequent call to mysql_query
will be made on the active database.
Parameters
database_name
-
The name of the database that is to be selected.
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.65. mysql_select_db
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); if (!$link) { die('Not connected : ' . mysql_error()); } // make foo the current db $db_selected = mysql_select_db('foo', $link); if (!$db_selected) { die ('Can\'t use foo : ' . mysql_error()); } ?>
Notes
NoteFor backward compatibility, the following deprecated alias may be used: mysql_selectdb
See Also
mysql_connect
|
mysql_pconnect
|
mysql_query |
mysql_set_charset
mysql_set_charset
Sets the client character set
Description
bool mysql_set_charset(string charset,
resource link_identifier= =NULL);
Sets the default character set for the current connection.
Parameters
charset
-
A valid character set name.
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns TRUE
on success or FALSE
on failure.
Notes
NoteThis function requires MariaDB 5.0.7 or later.Note
This is the preferred way to change the charset. Using mysql_query
to execute SET NAMES ..
is not recommended.
See Also
mysql_client_encoding
|
List of character sets that MariaDB supports |
mysql_stat
mysql_stat
Get current system status
Description
string mysql_stat(resource link_identifier= =NULL);
mysql_stat
returns the current server status.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
Returns a string with the status for uptime, threads, queries, open tables, flush tables and queries per second. For a complete list of other status variables, you have to use the SHOW STATUS
SQL command. If link_identifier
is invalid, NULL
is returned.
Examples
Example 20.66. mysql_stat
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); $status = explode(' ', mysql_stat($link)); print_r($status); ?>
The above example will output something similar to:
Array ( [0] => Uptime: 5380 [1] => Threads: 2 [2] => Questions: 1321299 [3] => Slow queries: 0 [4] => Opens: 26 [5] => Flush tables: 1 [6] => Open tables: 17 [7] => Queries per second avg: 245.595 )
Example 20.67. Alternative mysql_stat
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); $result = mysql_query('SHOW STATUS', $link); while ($row = mysql_fetch_assoc($result)) { echo $row['Variable_name'] . ' = ' . $row['Value'] . '\n'; } ?>
The above example will output something similar to:
back_log = 50 basedir = /usr/local/ bdb_cache_size = 8388600 bdb_log_buffer_size = 32768 bdb_home = /var/db/mysql/ bdb_max_lock = 10000 bdb_logdir = bdb_shared_data = OFF bdb_tmpdir = /var/tmp/ ...
See Also
mysql_get_server_info
|
mysql_list_processes |
mysql_tablename
mysql_tablename
Get table name of field
Description
string mysql_tablename(resource result,
int i);
Retrieves the table name from a result
.
This function is deprecated. It is preferable to use mysql_query
to issue an SQL SHOW TABLES [FROM db_name] [LIKE 'pattern']
statement instead.
Parameters
result
-
A result pointer resource that's returned from
mysql_list_tables
. i
-
The integer index (row/table number)
Return Values
The name of the table on success or FALSE
on failure.
Use the mysql_tablename
function to traverse this result pointer, or any function for result tables, such as mysql_fetch_array
.
Examples
Example 20.68. mysql_tablename
example
<?php mysql_connect('localhost', 'mysql_user', 'mysql_password'); $result = mysql_list_tables('mydb'); $num_rows = mysql_num_rows($result); for ($i = 0; $i < $num_rows; $i++) { echo 'Table: ', mysql_tablename($result, $i), '\n'; } mysql_free_result($result); ?>
Notes
NoteThe mysql_num_rows
function may be used to determine the number of tables in the result pointer.
See Also
mysql_list_tables
|
mysql_field_table
|
mysql_db_name |
mysql_thread_id
mysql_thread_id
Return the current thread ID
Description
int mysql_thread_id(resource link_identifier= =NULL);
Retrieves the current thread ID. If the connection is lost, and a reconnect with mysql_ping
is executed, the thread ID will change. This means only retrieve the thread ID when needed.
Parameters
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
The thread ID on success or FALSE
on failure.
Examples
Example 20.69. mysql_thread_id
example
<?php $link = mysql_connect('localhost', 'mysql_user', 'mysql_password'); $thread_id = mysql_thread_id($link); if ($thread_id){ printf('current thread id is %d\n', $thread_id); } ?>
The above example will output something similar to:
current thread id is 73
See Also
mysql_ping
|
mysql_list_processes |
mysql_unbuffered_query
mysql_unbuffered_query
Send an SQL query to MariaDB without fetching and buffering the result rows.
Description
resource mysql_unbuffered_query(string query,
resource link_identifier= =NULL);
mysql_unbuffered_query
sends the SQL query query
to MariaDB without automatically fetching and buffering the result rows as mysql_query
does. This saves a considerable amount of memory with SQL queries that produce large result sets, and you can start working on the result set immediately after the first row has been retrieved as you don't have to wait until the complete SQL query has been performed. To use mysql_unbuffered_query
while multiple database connections are open, you must specify the optional parameter link_identifier
to identify which connection you want to use.
Parameters
query
-
The SQL query to execute.
Data inside the query should be properly escaped.
link_identifier
-
The MariaDB connection. If the link identifier is not specified, the last link opened by
mysql_connect
is assumed. If no such link is found, it will try to create one as ifmysql_connect
was called with no arguments. If no connection is found or established, anE_WARNING
level error is generated.
Return Values
For SELECT, SHOW, DESCRIBE or EXPLAIN statements, mysql_unbuffered_query
returns a resource on success, or FALSE
on error.
For other type of SQL statements, UPDATE, DELETE, DROP, etc, mysql_unbuffered_query
returns TRUE
on success or FALSE
on error.
Notes
NoteThe benefits of mysql_unbuffered_query
come at a cost: you cannot use mysql_num_rows
and mysql_data_seek
on a result set returned from mysql_unbuffered_query
, until all rows are fetched. You also have to fetch all result rows from an unbuffered SQL query before you can send a new SQL query to MySQL, using the same link_identifier
.
See Also
mysql_query |
MySQL Improved Extension (Mysqli
)
- Examples
- Overview
- Quick start guide
- Installing/Configuring
- The mysqli Extension and Persistent Connections
- Predefined Constants
- Notes
- The MySQLi Extension Function Summary
- The mysqli class (
mysqli
)- The mysqli_stmt class (
mysqli_stmt
)- The mysqli_result class (
mysqli_result
)- The mysqli_driver class (
mysqli_driver
)- The mysqli_warning class (
mysqli_warning
)- The mysqli_sql_exception class (
mysqli_sql_exception
)- Aliases and deprecated Mysqli Functions
- Overview
The mysqli
extension allows you to access the functionality provided by MariaDB and above. More information about the MariaDB Database server can be found at http://www.mysql.com/
An overview of software available for using MariaDB from PHP can be found at , "Overview"
Documentation for MariaDB can be found at http://dev.mysql.com/doc/.
Parts of this documentation included from MariaDB manual with permissions of Oracle Corporation.
Examples
All examples in the mysqli
documentation use the world database. The world database can be found at http://downloads.mysql.com/docs/world.sql.gz
Overview
This section provides an introduction to the options available to you when developing a PHP application that needs to interact with a MariaDB database.
What is an API?
An Application Programming Interface, or API, defines the classes, methods, functions and variables that your application will need to call in order to carry out its desired task. In the case of PHP applications that need to communicate with databases the necessary APIs are usually exposed via PHP extensions.
APIs can be procedural or object-oriented. With a procedural API you call functions to carry out tasks, with the object-oriented API you instantiate classes and then call methods on the resulting objects. Of the two the latter is usually the preferred interface, as it is more modern and leads to better organised code.
When writing PHP applications that need to connect to the MariaDB server there are several API options available. This document discusses what is available and how to select the best solution for your application.
What is a Connector?
In the MariaDB documentation, the term connector refers to a piece of software that allows your application to connect to the MariaDB database server. MariaDB provides connectors for a variety of languages, including PHP.
If your PHP application needs to communicate with a database server you will need to write PHP code to perform such activities as connecting to the database server, querying the database and other database-related functions. Software is required to provide the API that your PHP application will use, and also handle the communication between your application and the database server, possibly using other intermediate libraries where necessary. This software is known generically as a connector, as it allows your application to connect to a database server.
What is a Driver?
A driver is a piece of software designed to communicate with a specific type of database server. The driver may also call a library, such as the MariaDB Client Library or the MariaDB Native Driver. These libraries implement the low-level protocol used to communicate with the MariaDB database server.
By way of an example, the PHP Data Objects (PDO) database abstraction layer may use one of several database-specific drivers. One of the drivers it has available is the PDO MYSQL driver, which allows it to interface with the MariaDB server.
Sometimes people use the terms connector and driver interchangeably, this can be confusing. In the MySQL-related documentation the term "driver" is reserved for software that provides the database-specific part of a connector package.
What is an Extension?
In the PHP documentation you will come across another term - extension. The PHP code consists of a core, with optional extensions to the core functionality. PHP's MySQL-related extensions, such as the mysqli
extension, and the MariaDB
extension, are implemented using the PHP extension framework.
An extension typically exposes an API to the PHP programmer, to allow its facilities to be used programmatically. However, some extensions which use the PHP extension framework do not expose an API to the PHP programmer.
The PDO MariaDB driver extension, for example, does not expose an API to the PHP programmer, but provides an interface to the PDO layer above it.
The terms API and extension should not be taken to mean the same thing, as an extension may not necessarily expose an API to the programmer.
What are the main PHP API offerings for using MySQL?
There are three main API options when considering connecting to a MariaDB database server:
- PHP's MariaDB Extension
- PHP's mysqli Extension
- PHP Data Objects (PDO)
Each has its own advantages and disadvantages. The following discussion aims to give a brief introduction to the key aspects of each API.
What is PHP's MariaDB Extension?
This is the original extension designed to allow you to develop PHP applications that interact with a MariaDB database. The MariaDB
extension provides a procedural interface and is intended for use only with MariaDB versions older than 4.1.3. This extension can be used with versions of MariaDB 4.1.3 or newer, but not all of the latest MariaDB server features will be available.Note
If you are using MariaDB versions 4.1.3 or later it is strongly recommended that you use the mysqli
extension instead.
The MariaDB
extension source code is located in the PHP extension directory ext/mysql
.
For further information on the MariaDB
extension, see , "Original MariaDB API (MariaDB
)".
What is PHP's mysqli Extension?
The mysqli
extension, or as it is sometimes known, the MariaDB improved extension, was developed to take advantage of new features found in MariaDB systems versions 4.1.3 and newer. The mysqli
extension is included with PHP versions 5 and later.
The mysqli
extension has a number of benefits, the key enhancements over the MariaDB
extension being:
- Object-oriented interface
- Support for Prepared Statements
- Support for Multiple Statements
- Support for Transactions
- Enhanced debugging capabilities
- Embedded server support
If you are using MariaDB versions 4.1.3 or later it is strongly recommended that you use this extension.
As well as the object-oriented interface the extension also provides a procedural interface.
The mysqli
extension is built using the PHP extension framework, its source code is located in the directory ext/mysqli
.
For further information on the mysqli
extension, see , "MySQL Improved Extension (Mysqli
)".
What is PDO?
PHP Data Objects, or PDO, is a database abstraction layer specifically for PHP applications. PDO provides a consistent API for your PHP application regardless of the type of database server your application will connect to. In theory, if you are using the PDO API, you could switch the database server you used, from say Firebird to MySQL, and only need to make minor changes to your PHP code.
Other examples of database abstraction layers include JDBC for Java applications and DBI for Perl.
While PDO has its advantages, such as a clean, simple, portable API, its main disadvantage is that it doesn't allow you to use all of the advanced features that are available in the latest versions of MariaDB server. For example, PDO does not allow you to use MySQL's support for Multiple Statements.
PDO is implemented using the PHP extension framework, its source code is located in the directory ext/pdo
.
For further information on PDO, see the http://www.php.net/book.pdo.
What is the PDO MYSQL driver?
The PDO MYSQL driver is not an API as such, at least from the PHP programmer's perspective. In fact the PDO MYSQL driver sits in the layer below PDO itself and provides MySQL-specific functionality. The programmer still calls the PDO API, but PDO uses the PDO MYSQL driver to carry out communication with the MariaDB server.
The PDO MYSQL driver is one of several available PDO drivers. Other PDO drivers available include those for the Firebird and PostgreSQL database servers.
The PDO MYSQL driver is implemented using the PHP extension framework. Its source code is located in the directory ext/pdo_mysql
. It does not expose an API to the PHP programmer.
For further information on the PDO MYSQL driver, see , "MySQL Functions (PDO_MYSQL) (MySQL (PDO)
)".
What is PHP's MariaDB Native Driver?
In order to communicate with the MariaDB database server the MariaDB
extension, mysqli
and the PDO MYSQL driver each use a low-level library that implements the required protocol. In the past, the only available library was the MariaDB Client Library, otherwise known as libmysql
.
However, the interface presented by libmysql
was not optimized for communication with PHP applications, as libmysql
was originally designed with C applications in mind. For this reason the MariaDB Native Driver, mysqlnd
, was developed as an alternative to libmysql
for PHP applications.
The MariaDB
extension, the mysqli
extension and the PDO MariaDB driver can each be individually configured to use either libmysql
or mysqlnd
. As mysqlnd
is designed specifically to be utilised in the PHP system it has numerous memory and speed enhancements over libmysql
. You are strongly encouraged to take advantage of these improvements.Note
The MariaDB Native Driver can only be used with MariaDB server versions 4.1.3 and later.
The MariaDB Native Driver is implemented using the PHP extension framework. The source code is located in ext/mysqlnd
. It does not expose an API to the PHP programmer.
Comparison of Features
The following table compares the functionality of the three main methods of connecting to MariaDB from PHP:
PHP's mysqli Extension | PDO (Using PDO MariaDB Driver and MariaDB Native Driver) | PHP's MariaDB Extension | |
---|---|---|---|
PHP version introduced | 5.0 | 5.0 | Prior to 3.0 |
Included with PHP 5.x | yes | yes | Yes |
MySQL development status | Active development | Active development as of PHP 5.3 | Maintenance only |
Recommended by MariaDB for new projects | Yes - preferred option | Yes | No |
API supports Charsets | Yes | Yes | No |
API supports server-side Prepared Statements | Yes | Yes | No |
API supports client-side Prepared Statements | No | Yes | No |
API supports Stored Procedures | Yes | Yes | No |
API supports Multiple Statements | Yes | Most | No |
Supports all MariaDB 4.1+ functionality | Yes | Most | No |
Quick start guide
- Dual procedural and object-oriented interface
- Connections
- Executing statements
- Prepared Statements
- Stored Procedures
- Multiple Statements
- API support for transactions
- Metadata
- Connections
This quick start guide will help with choosing and gaining familiarity with the PHP MariaDB API.
This quick start gives an overview on the mysqli extension. Code examples are provided for all major aspects of the API. Database concepts are explained to the degree needed for presenting concepts specific to MariaDB.
Required: A familiarity with the PHP programming language, the SQL language, and basic knowledge of the MariaDB server.
Dual procedural and object-oriented interface
The mysqli extension features a dual interface. It supports the procedural and object-oriented programming paradigm.
Users migrating from the old mysql extension may prefer the procedural interface. The procedural interface is similar to that of the old mysql extension. In many cases, the function names differ only by prefix. Some mysqli functions take a connection handle as their first argument, whereas matching functions in the old mysql interface take it as an optional last argument.
Example 20.70. Easy migration from the old mysql extension
<?php $mysqli = mysqli_connect('example.com', 'user', 'password', 'database'); $res = mysqli_query($mysqli, 'SELECT 'Please, do not use ' AS _msg FROM DUAL'); $row = mysqli_fetch_assoc($res); echo $row['_msg']; $mysql = mysql_connect('localhost', 'root', ''); mysql_select_db('test'); $res = mysql_query('SELECT 'the mysql extension for new developments.' AS _msg FROM DUAL', $mysql); $row = mysql_fetch_assoc($res); echo $row['_msg']; ?>
The above example will output:
Please, do not use the mysql extension for new developments.
The object-oriented interface
In addition to the classical procedural interface, users can choose to use the object-oriented interface. The documentation is organized using the object-oriented interface. The object-oriented interface shows functions grouped by their purpose, making it easier to get started. The reference section gives examples for both syntax variants.
There are no significant performance differences between the two interfaces. Users can base their choice on personal preference.
Example 20.71. Object-oriented and procedural interface
<?php $mysqli = mysqli_connect('example.com', 'user', 'password', 'database'); if (mysqli_connect_errno($mysqli)) { echo 'Failed to connect to MySQL: ' . mysqli_connect_error(); } $res = mysqli_query($mysqli, 'SELECT 'A world full of ' AS _msg FROM DUAL'); $row = mysqli_fetch_assoc($res); echo $row['_msg']; $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: ' . $mysqli->connect_error; } $res = $mysqli->query('SELECT 'choices to please everybody,' AS _msg FROM DUAL'); $row = $res->fetch_assoc(); echo $row['_msg']; ?>
The above example will output:
A world full of choices to please everybody.
The object oriented interface is used for the quickstart because the reference section is organized that way.
Mixing styles
It is possible to switch between styles at any time. Mixing both styles is not recommended for code clarity and coding style reasons.
Example 20.72. Bad coding style
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: ' . $mysqli->connect_error; } $res = mysqli_query($mysqli, 'SELECT 'Possible but bad style.' AS _msg FROM DUAL'); if (!$res) { echo 'Failed to run query: (' . $mysqli->errno . ') ' . $mysqli->error; } if ($row = $res->fetch_assoc()) { echo $row['_msg']; } ?>
The above example will output:
Possible but bad style.
See also
mysqli::__construct
|
mysqli::query
|
mysqli_result::fetch_assoc
|
$mysqli::connect_errno |
$mysqli::connect_error |
$mysqli::errno |
$mysqli::error |
The MySQLi Extension Function Summary |
Connections
The MariaDB server supports the use of different transport layers for connections. Connections use TCP/IP, Unix domain sockets or Windows named pipes.
The hostname localhost
has a special meaning. It is bound to the use of Unix domain sockets. It is not possible to open a TCP/IP connection using the hostname localhost
you must use 127.0.0.1
instead.
Example 20.73. Special meaning of localhost
<?php $mysqli = new mysqli('localhost', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } echo $mysqli->host_info . '\n'; $mysqli = new mysqli('127.0.0.1', 'user', 'password', 'database', 3306); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } echo $mysqli->host_info . '\n'; ?>
The above example will output:
Localhost via UNIX socket 127.0.0.1 via TCP/IP
Connection parameter defaults
Depending on the connection function used, assorted parameters can be omitted. If a parameter is not provided, then the extension attempts to use the default values that are set in the PHP configuration file.
Example 20.74. Setting defaults
mysqli.default_host=192.168.2.27 mysqli.default_user=root mysqli.default_pw='' mysqli.default_port=3306 mysqli.default_socket=/tmp/mysql.sock
The resulting parameter values are then passed to the client library that is used by the extension. If the client library detects empty or unset parameters, then it may default to the library built-in values.
Built-in connection library defaults
If the host value is unset or empty, then the client library will default to a Unix socket connection on localhost
. If socket is unset or empty, and a Unix socket connection is requested, then a connection to the default socket on /tmp/mysql.sock
is attempted.
On Windows systems, the host name .
is interpreted by the client library as an attempt to open a Windows named pipe based connection. In this case the socket parameter is interpreted as the pipe name. If not given or empty, then the socket (pipe name) defaults to \\.\pipe\MySQL
.
If neither a Unix domain socket based not a Windows named pipe based connection is to be be established and the port parameter value is unset, the library will default to port 3306
.
The mysqlnd library and the MariaDB Client Library (libmysql) implement the same logic for determining defaults.
Connection options
Connection options are available to, for example, set init commands which are executed upon connect, or for requesting use of a certain charset. Connection options must be set before a network connection is established.
For setting a connection option, the connect operation has to be performed in three steps: creating a connection handle with mysqli_init
, setting the requested options using mysqli_options
, and establishing the network connection with mysqli_real_connect
.
Connection pooling
The mysqli extension supports persistent database connections, which are a special kind of pooled connections. By default, every database connection opened by a script is either explicitly closed by the user during runtime or released automatically at the end of the script. A persistent connection is not. Instead it is put into a pool for later reuse, if a connection to the same server using the same username, password, socket, port and default database is opened. Reuse saves connection overhead.
Every PHP process is using its own mysqli connection pool. Depending on the web server deployment model, a PHP process may serve one or multiple requests. Therefore, a pooled connection may be used by one or more scripts subsequently.
Persistent connection
If a unused persistent connection for a given combination of host, username, password, socket, port and default database can not be found in the connection pool, then mysqli opens a new connection. The use of persistent connections can be enabled and disabled using the PHP directive mysqli.allow_persistent. The total number of connections opened by a script can be limited with mysqli.max_links. The maximum number of persistent connections per PHP process can be restricted with mysqli.max_persistent. Please note, that the web server may spawn many PHP processes.
A common complain about persistent connections is that their state is not reset before reuse. For example, open and unfinished transactions are not automatically rolled back. But also, authorization changes which happened in the time between putting the connection into the pool and reusing it are not reflected. This may be seen as an unwanted side-effect. On the contrary, the name persistent
may be understood as a promise that the state is persisted.
The mysqli extension supports both interpretations of a persistent connection: state persisted, and state reset before reuse. The default is reset. Before a persistent connection is reused, the mysqli extension implicitly calls mysqli_change_user
to reset the state. The persistent connection appears to the user as if it was just opened. No artifacts from previous usages are visible.
The mysqli_change_user
function is an expensive operation. For best performance, users may want to recompile the extension with the compile flag MYSQLI_NO_CHANGE_USER_ON_PCONNECT
being set.
It is left to the user to choose between safe behavior and best performance. Both are valid optimization goals. For ease of use, the safe behavior has been made the default at the expense of maximum performance.
See also
mysqli::__construct
|
mysqli::init
|
mysqli::options
|
mysqli::real_connect
|
mysqli::change_user
|
$mysqli::host_info |
MySQLi Configuration Options |
Persistent Database Connections |
Executing statements
Statements can be executed with the mysqli-query
, mysqli_real_query
and mysqli_multi_query
functions. The mysqli_query
function is the most common, and combines the executing statement with a buffered fetch of its result set, if any, in one call. Calling mysqli_query
is identical to calling mysqli_real_query
followed by mysqli_store_result
.
The mysqli_multi_query
function is used with multiple statements.
Example 20.75. Bad coding style
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT)') || !$mysqli->query('INSERT INTO test(id) VALUES (1)')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } ?>
Buffered result sets
After statement execution results can be retrieved at once to be buffered by the client or by read row by row. Client-side result set buffering allows the server to free resources associated with the statement results as early as possible. Generally speaking, clients are slow consuming result sets. Therefore, it is recommended to use buffered result sets. mysqli_query
combines statement execution and result set buffering.
PHP applications can navigate freely through buffered results. Navigation is fast because the result sets are held in client memory. Please, keep in mind that it is often easier to scale by client than it is to scale the server.
Example 20.76. Navigation through buffered results
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT)') || !$mysqli->query('INSERT INTO test(id) VALUES (1), (2), (3)')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } $res = $mysqli->query('SELECT id FROM test ORDER BY id ASC'); echo 'Reverse order...\n'; for ($row_no = $res->num_rows - 1; $row_no >= 0; $row_no--) { $res->data_seek($row_no); $row = $res->fetch_assoc(); echo ' id = ' . $row['id'] . '\n'; } echo 'Result set order...\n'; $res->data_seek(0); while ($row = $res->fetch_assoc()) { echo ' id = ' . $row['id'] . '\n'; } ?>
The above example will output:
Reverse order... id = 3 id = 2 id = 1 Result set order... id = 1 id = 2 id = 3
Unbuffered result sets
If client memory is a short resource and freeing server resources as early as possible to keep server load low is not needed, unbuffered results can be used. Scrolling through unbuffered results is not possible before all rows have been read.
Example 20.77. Navigation through buffered results
<?php $mysqli->real_query('SELECT id FROM test ORDER BY id ASC'); $res = $mysqli->use_result(); echo 'Result set order...\n'; while ($row = $res->fetch_assoc()) { echo ' id = ' . $row['id'] . '\n'; } ?>
Result set values data types
The mysqli-query
, mysqli_real_query
and mysqli_multi_query
functions are used to execute non-prepared statements. At the level of the MariaDB Client Server Protocol, the command COM_QUERY
and the text protocol are used for statement execution. With the text protocol, the MariaDB server converts all data of a result sets into strings before sending. This conversion is done regardless of the SQL result set column data type. The mysql client libraries receive all column values as strings. No further client-side casting is done to convert columns back to their native types. Instead, all values are provided as PHP strings.
Example 20.78. Text protocol returns strings by default
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT, label CHAR(1))') || !$mysqli->query('INSERT INTO test(id, label) VALUES (1, 'a')')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } $res = $mysqli->query('SELECT id, label FROM test WHERE id = 1'); $row = $res->fetch_assoc(); printf('id = %s (%s)\n', $row['id'], gettype($row['id'])); printf('label = %s (%s)\n', $row['label'], gettype($row['label'])); ?>
The above example will output:
id = 1 (string) label = a (string)
It is possible to convert integer and float columns back to PHP numbers by setting the MYSQLI_OPT_INT_AND_FLOAT_NATIVE
connection option, if using the mysqlnd library. If set, the mysqlnd library will check the result set meta data column types and convert numeric SQL columns to PHP numbers, if the PHP data type value range allows for it. This way, for example, SQL INT columns are returned as integers.
Example 20.79. Native data types with mysqlnd and connection option
<?php $mysqli = mysqli_init(); $mysqli->options(MYSQLI_OPT_INT_AND_FLOAT_NATIVE, 1); $mysqli->real_connect('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT, label CHAR(1))') || !$mysqli->query('INSERT INTO test(id, label) VALUES (1, 'a')')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } $res = $mysqli->query('SELECT id, label FROM test WHERE id = 1'); $row = $res->fetch_assoc(); printf('id = %s (%s)\n', $row['id'], gettype($row['id'])); printf('label = %s (%s)\n', $row['label'], gettype($row['label'])); ?>
The above example will output:
id = 1 (integer) label = a (string)
See also
mysqli::__construct
|
mysqli::init
|
mysqli::options
|
mysqli::real_connect
|
mysqli::query
|
mysqli::multi_query
|
mysqli::use_result
|
mysqli::store_result
|
mysqli_result::free |
Prepared Statements
The MariaDB database supports prepared statements. A prepared statement or a parameterized statement is used to execute the same statement repeatedly with high efficiency.
Basic workflow
The prepared statement execution consists of two stages: prepare and execute. At the prepare stage a statement template is send to the database server. The server performs a syntax check and initializes server internal resources for later use.
The MariaDB server supports using anonymous, positional placeholder with ?
.
Example 20.80. First stage: prepare
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } /* Non-prepared statement */ if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT)')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } /* Prepared statement, stage 1: prepare */ if (!($stmt = $mysqli->prepare('INSERT INTO test(id) VALUES (?)'))) { echo 'Prepare failed: (' . $mysqli->errno . ') ' . $mysqli->error; } ?>
Prepare is followed by execute. During execute the client binds parameter values and sends them to the server. The server creates a statement from the statement template and the bound values to execute it using the previously created internal resources.
Example 20.81. Second stage: bind and execute
<?php /* Prepared statement, stage 2: bind and execute */ $id = 1; if (!$stmt->bind_param('i', $id)) { echo 'Binding parameters failed: (' . $stmt->errno . ') ' . $stmt->error; } if (!$stmt->execute()) { echo 'Execute failed: (' . $stmt->errno . ') ' . $stmt->error; } ?>
Repeated execution
A prepared statement can be executed repeatedly. Upon every execution the current value of the bound variable is evaluated and send to the server. The statement is not parsed again. The statement template is not transferred to the server again.
Example 20.82. INSERT prepared once, executed multiple times
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } /* Non-prepared statement */ if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT)')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } /* Prepared statement, stage 1: prepare */ if (!($stmt = $mysqli->prepare('INSERT INTO test(id) VALUES (?)'))) { echo 'Prepare failed: (' . $mysqli->errno . ') ' . $mysqli->error; } /* Prepared statement, stage 2: bind and execute */ $id = 1; if (!$stmt->bind_param('i', $id)) { echo 'Binding parameters failed: (' . $stmt->errno . ') ' . $stmt->error; } if (!$stmt->execute()) { echo 'Execute failed: (' . $stmt->errno . ') ' . $stmt->error; } /* Prepared statement: repeated execution, only data transferred from client to server */ for ($id = 2; $id < 5; $id++) { if (!$stmt->execute()) { echo 'Execute failed: (' . $stmt->errno . ') ' . $stmt->error; } } /* explicit close recommended */ $stmt->close(); /* Non-prepared statement */ $res = $mysqli->query('SELECT id FROM test'); var_dump($res->fetch_all()); ?>
The above example will output:
array(4) { [0]=> array(1) { [0]=> string(1) '1' } [1]=> array(1) { [0]=> string(1) '2' } [2]=> array(1) { [0]=> string(1) '3' } [3]=> array(1) { [0]=> string(1) '4' } }
Every prepared statement occupies server resources. Statements should be closed explicitly immediately after use. If not done explicitly, the statement will be closed when the statement handle is freed by PHP.
Using a prepared statement is not always the most efficient way of executing a statement. A prepared statement executed only once causes more client-server round-trips than a non-prepared statement. This is why the SELECT
is not run as a prepared statement above.
Also, consider the use of the MariaDB multi-INSERT SQL syntax for INSERTs. For the example, multi-INSERT requires less round-trips between the server and client than the prepared statement shown above.
Example 20.83. Less round trips using multi-INSERT SQL
<?php if (!$mysqli->query('INSERT INTO test(id) VALUES (1), (2), (3), (4)')) { echo 'Multi-INSERT failed: (' . $mysqli->errno . ') ' . $mysqli->error; } ?>
Result set values data types
The MariaDB Client Server Protocol defines a different data transfer protocol for prepared statements and non-prepared statements. Prepared statements are using the so called binary protocol. The MariaDB server sends result set data 'as is' in binary format. Results are not serialized into strings before sending. The client libraries do not receive strings only. Instead, they will receive binary data and try to convert the values into appropriate PHP data types. For example, results from an SQL INT
column will be provided as PHP integer variables.
Example 20.84. Native datatypes
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT, label CHAR(1))') || !$mysqli->query('INSERT INTO test(id, label) VALUES (1, 'a')')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } $stmt = $mysqli->prepare('SELECT id, label FROM test WHERE id = 1'); $stmt->execute(); $res = $stmt->get_result(); $row = $res->fetch_assoc(); printf('id = %s (%s)\n', $row['id'], gettype($row['id'])); printf('label = %s (%s)\n', $row['label'], gettype($row['label'])); ?>
The above example will output:
id = 1 (integer) label = a (string)
This behavior differs from non-prepared statements. By default, non-prepared statements return all results as strings. This default can be changed using a connection option. If the connection option is used, there are no differences.
Fetching results using bound variables
Results from prepared statements can either be retrieved by binding output variables, or by requesting a mysqli_result
object.
Output variables must be bound after statement execution. One variable must be bound for every column of the statements result set.
Example 20.85. Output variable binding
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT, label CHAR(1))') || !$mysqli->query('INSERT INTO test(id, label) VALUES (1, 'a')')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!($stmt = $mysqli->prepare('SELECT id, label FROM test'))) { echo 'Prepare failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$stmt->execute()) { echo 'Execute failed: (' . $mysqli->errno . ') ' . $mysqli->error; } $out_id = NULL; $out_label = NULL; if (!$stmt->bind_result($out_id, $out_label)) { echo 'Binding output parameters failed: (' . $stmt->errno . ') ' . $stmt->error; } while ($stmt->fetch()) { printf('id = %s (%s), label = %s (%s)\n', $out_id, gettype($out_id), $out_label, gettype($out_label)); } ?>
The above example will output:
id = 1 (integer), label = a (string)
Prepared statements return unbuffered result sets by default. The results of the statement are not implicitly fetched and transferred from the server to the client for client-side buffering. The result set takes server resources until all results have been fetched by the client. Thus it is recommended to consume results timely. If a client fails to fetch all results or the client closes the statement before having fetched all data, the data has to be fetched implicitly by mysqli
.
It is also possible to buffer the results of a prepared statement using mysqli_stmt_store_result
.
Fetching results using mysqli_result interface
Instead of using bound results, results can also be retrieved through the mysqli_result interface. mysqli_stmt_get_result
returns a buffered result set.
Example 20.86. Using mysqli_result to fetch results
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT, label CHAR(1))') || !$mysqli->query('INSERT INTO test(id, label) VALUES (1, 'a')')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!($stmt = $mysqli->prepare('SELECT id, label FROM test ORDER BY id ASC'))) { echo 'Prepare failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$stmt->execute()) { echo 'Execute failed: (' . $stmt->errno . ') ' . $stmt->error; } if (!($res = $stmt->get_result())) { echo 'Getting result set failed: (' . $stmt->errno . ') ' . $stmt->error; } var_dump($res->fetch_all()); ?>
The above example will output:
array(1) { [0]=> array(2) { [0]=> int(1) [1]=> string(1) 'a' } }
Using the mysqli_result interface
offers the additional benefit of flexible client-side result set navigation.
Example 20.87. Buffered result set for flexible read out
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT, label CHAR(1))') || !$mysqli->query('INSERT INTO test(id, label) VALUES (1, 'a'), (2, 'b'), (3, 'c')')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!($stmt = $mysqli->prepare('SELECT id, label FROM test'))) { echo 'Prepare failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$stmt->execute()) { echo 'Execute failed: (' . $stmt->errno . ') ' . $stmt->error; } if (!($res = $stmt->get_result())) { echo 'Getting result set failed: (' . $stmt->errno . ') ' . $stmt->error; } for ($row_no = ($res->num_rows - 1); $row_no >= 0; $row_no--) { $res->data_seek($row_no); var_dump($res->fetch_assoc()); } $res->close(); ?>
The above example will output:
array(2) { ['id']=> int(3) ['label']=> string(1) 'c' } array(2) { ['id']=> int(2) ['label']=> string(1) 'b' } array(2) { ['id']=> int(1) ['label']=> string(1) 'a' }
Escaping and SQL injection
Bound variables will be escaped automatically by the server. The server inserts their escaped values at the appropriate places into the statement template before execution. A hint must be provided to the server for the type of bound variable, to create an appropriate conversion. See the mysqli_stmt_bind_param
function for more information.
The automatic escaping of values within the server is sometimes considered a security feature to prevent SQL injection. The same degree of security can be achieved with non-prepared statements, if input values are escaped correctly.
Client-side prepared statement emulation
The API does not include emulation for client-side prepared statement emulation.
Quick prepared - non-prepared statement comparison
The table below compares server-side prepared and non-prepared statements.
Prepared Statement | Non-prepared statement | |
---|---|---|
Client-server round trips, SELECT, single execution | 2 | 1 |
Statement string transferred from client to server | 1 | 1 |
Client-server round trips, SELECT, repeated (n) execution | 1 + n | n |
Statement string transferred from client to server | 1 template, n times bound parameter, if any | n times together with parameter, if any |
Input parameter binding API | Yes, automatic input escaping | No, manual input escaping |
Output variable binding API | Yes | No |
Supports use of mysqli_result API | Yes, use mysqli_stmt_get_result
| Yes |
Buffered result sets | Yes, use mysqli_stmt_get_result or binding with mysqli_stmt_store_result
| Yes, default of mysqli_query
|
Unbuffered result sets | Yes, use output binding API | Yes, use mysqli_real_query with mysqli_use_result
|
MySQL Client Server protocol data transfer flavor | Binary protocol | Text protocol |
Result set values SQL data types | Preserved when fetching | Converted to string or preserved when fetching |
Supports all SQL statements | Recent MariaDB versions support most but not all | Yes |
See also
mysqli::__construct
|
mysqli::query
|
mysqli::prepare
|
mysqli_stmt::prepare
|
mysqli_stmt::execute
|
mysqli_stmt::bind_param
|
mysqli_stmt::bind_result |
Stored Procedures
The MariaDB database supports stored procedures. A stored procedure is a subroutine stored in the database catalog. Applications can call and execute the stored procedure. The CALL
SQL statement is used to execute a stored procedure.
Parameter
Stored procedures can have IN
, INOUT
and OUT
parameters, depending on the MariaDB version. The mysqli interface has no special notion for the different kinds of parameters.
IN parameter
Input parameters are provided with the CALL
statement. Please, make sure values are escaped correctly.
Example 20.88. Calling a stored procedure
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT)')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$mysqli->query('DROP PROCEDURE IF EXISTS p') || !$mysqli->query('CREATE PROCEDURE p(IN id_val INT) BEGIN INSERT INTO test(id) VALUES(id_val); END;')) { echo 'Stored procedure creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$mysqli->query('CALL p(1)')) { echo 'CALL failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!($res = $mysqli->query('SELECT id FROM test'))) { echo 'SELECT failed: (' . $mysqli->errno . ') ' . $mysqli->error; } var_dump($res->fetch_assoc()); ?>
The above example will output:
array(1) { ['id']=> string(1) '1' }
INOUT/OUT parameter
The values of INOUT
/OUT
parameters are accessed using session variables.
Example 20.89. Using session variables
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP PROCEDURE IF EXISTS p') || !$mysqli->query('CREATE PROCEDURE p(OUT msg VARCHAR(50)) BEGIN SELECT 'Hi!' INTO msg; END;')) { echo 'Stored procedure creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$mysqli->query('SET @msg = ''') || !$mysqli->query('CALL p(@msg)')) { echo 'CALL failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!($res = $mysqli->query('SELECT @msg as _p_out'))) { echo 'Fetch failed: (' . $mysqli->errno . ') ' . $mysqli->error; } $row = $res->fetch_assoc(); echo $row['_p_out']; ?>
The above example will output:
Hi!
Application and framework developers may be able to provide a more convenient API using a mix of session variables and databased catalog inspection. However, please note the possible performance impact of a custom solution based on catalog inspection.
Handling result sets
Stored procedures can return result sets. Result sets returned from a stored procedure cannot be fetched correctly using mysqli_query
. The mysqli_query
function combines statement execution and fetching the first result set into a buffered result set, if any. However, there are additional stored procedure result sets hidden from the user which cause mysqli_query
to fail returning the user expected result sets.
Result sets returned from a stored procedure are fetched using mysqli_real_query
or mysqli_multi_query
. Both functions allow fetching any number of result sets returned by a statement, such as CALL
. Failing to fetch all result sets returned by a stored procedure causes an error.
Example 20.90. Fetching results from stored procedures
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT)') || !$mysqli->query('INSERT INTO test(id) VALUES (1), (2), (3)')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$mysqli->query('DROP PROCEDURE IF EXISTS p') || !$mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;')) { echo 'Stored procedure creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$mysqli->multi_query('CALL p()')) { echo 'CALL failed: (' . $mysqli->errno . ') ' . $mysqli->error; } do { if ($res = $mysqli->store_result()) { printf('---\n'); var_dump($res->fetch_all()); $res->free(); } else { if ($mysqli->errno) { echo 'Store failed: (' . $mysqli->errno . ') ' . $mysqli->error; } } } while ($mysqli->more_results() && $mysqli->next_result()); ?>
The above example will output:
--- array(3) { [0]=> array(1) { [0]=> string(1) '1' } [1]=> array(1) { [0]=> string(1) '2' } [2]=> array(1) { [0]=> string(1) '3' } } --- array(3) { [0]=> array(1) { [0]=> string(1) '2' } [1]=> array(1) { [0]=> string(1) '3' } [2]=> array(1) { [0]=> string(1) '4' } }
Use of prepared statements
No special handling is required when using the prepared statement interface for fetching results from the same stored procedure as above. The prepared statement and non-prepared statement interfaces are similar. Please note, that not every MYSQL server version may support preparing the CALL
SQL statement.
Example 20.91. Stored Procedures and Prepared Statements
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT)') || !$mysqli->query('INSERT INTO test(id) VALUES (1), (2), (3)')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$mysqli->query('DROP PROCEDURE IF EXISTS p') || !$mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;')) { echo 'Stored procedure creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!($stmt = $mysqli->prepare('CALL p()'))) { echo 'Prepare failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$stmt->execute()) { echo 'Execute failed: (' . $stmt->errno . ') ' . $stmt->error; } do { if ($res = $stmt->get_result()) { printf('---\n'); var_dump(mysqli_fetch_all($res)); mysqli_free_result($res); } else { if ($stmt->errno) { echo 'Store failed: (' . $stmt->errno . ') ' . $stmt->error; } } } while ($stmt->more_results() && $stmt->next_result()); ?>
Of course, use of the bind API for fetching is supported as well.
Example 20.92. Stored Procedures and Prepared Statements using bind API
<?php if (!($stmt = $mysqli->prepare('CALL p()'))) { echo 'Prepare failed: (' . $mysqli->errno . ') ' . $mysqli->error; } if (!$stmt->execute()) { echo 'Execute failed: (' . $stmt->errno . ') ' . $stmt->error; } do { $id_out = NULL; if (!$stmt->bind_result($id_out)) { echo 'Bind failed: (' . $stmt->errno . ') ' . $stmt->error; } while ($stmt->fetch()) { echo 'id = $id_out\n'; } } while ($stmt->more_results() && $stmt->next_result()); ?>
See also
mysqli::query
|
mysqli::multi_query
|
mysqli_result::next-result
|
mysqli_result::more-results |
Multiple Statements
MySQL optionally allows having multiple statements in one statement string. Sending multiple statements at once reduces client-server round trips but requires special handling.
Multiple statements or multi queries must be executed with mysqli_multi_query
. The individual statements of the statement string are separated by semicolon. Then, all result sets returned by the executed statements must be fetched.
The MariaDB server allows having statements that do return result sets and statements that do not return result sets in one multiple statement.
Example 20.93. Multiple Statements
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } if (!$mysqli->query('DROP TABLE IF EXISTS test') || !$mysqli->query('CREATE TABLE test(id INT)')) { echo 'Table creation failed: (' . $mysqli->errno . ') ' . $mysqli->error; } $sql = 'SELECT COUNT(*) AS _num FROM test; '; $sql.= 'INSERT INTO test(id) VALUES (1); '; $sql.= 'SELECT COUNT(*) AS _num FROM test; '; if (!$mysqli->multi_query($sql)) { echo 'Multi query failed: (' . $mysqli->errno . ') ' . $mysqli->error; } do { if ($res = $mysqli->store_result()) { var_dump($res->fetch_all(MYSQLI_ASSOC)); $res->free(); } } while ($mysqli->more_results() && $mysqli->next_result()); ?>
The above example will output:
array(1) { [0]=> array(1) { ['_num']=> string(1) '0' } } array(1) { [0]=> array(1) { ['_num']=> string(1) '1' } }
Security considerations
The API functions mysqli-query
and mysqli_real_query
do not set a connection flag necessary for activating multi queries in the server. An extra API call is used for multiple statements to reduce the likeliness of accidental SQL injection attacks. An attacker may try to add statements such as ; DROP DATABASE mysql
or ; SELECT SLEEP(999)
. If the attacker succeeds in adding SQL to the statement string but mysqli_multi_query
is not used, the server will not execute the second, injected and malicious SQL statement.
Example 20.94. SQL Injection
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); $res = $mysqli->query('SELECT 1; DROP TABLE mysql.user'); if (!$res) { echo 'Error executing query: (' . $mysqli->errno . ') ' . $mysqli->error; } ?>
The above example will output:
Error executing query: (1064) You have an error in your SQL syntax; check the manual that corresponds to your MariaDB server version for the right syntax to use near 'DROP TABLE mysql.user' at line 1
Prepared statements
Use of the multiple statement with prepared statements is not supported.
See also
mysqli::query
|
mysqli::multi_query
|
mysqli_result::next-result
|
mysqli_result::more-results |
API support for transactions
The MariaDB server supports transactions depending on the storage engine used. Since MariaDB 5.5, the default storage engine is InnoDB. InnoDB has full ACID transaction support.
Transactions can either be controlled using SQL or API calls. It is recommended to use API calls for enabling and disabling the auto commit mode and for committing and rolling back transactions.
Example 20.95. Setting auto commit mode with SQL and through the API
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } /* Recommended: using API to control transactional settings */ $mysqli->autocommit(false); /* Won't be monitored and recognized by the replication and the load balancing plugin */ if (!$mysqli->query('SET AUTOCOMMIT = 0')) { echo 'Query failed: (' . $mysqli->errno . ') ' . $mysqli->error; } ?>
Optional feature packages, such as the replication and load balancing plugin, can easily monitor API calls. The replication plugin offers transaction aware load balancing, if transactions are controlled with API calls. Transaction aware load balancing is not available if SQL statements are used for setting auto commit mode, committing or rolling back a transaction.
Example 20.96. Commit and rollback
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); $mysqli->autocommit(false); $mysqli->query('INSERT INTO test(id) VALUES (1)'); $mysqli->rollback(); $mysqli->query('INSERT INTO test(id) VALUES (2)'); $mysqli->commit(); ?>
Please note, that the MariaDB server cannot roll back all statements. Some statements cause am implicit commit.
See also
mysqli::autocommit
|
mysqli_result::commit
|
mysqli_result::rollback |
Metadata
A MariaDB result set contains metadata. The metadata describes the columns found in the result set. All metadata send by MariaDB is accessible through the mysqli
interface. The extension performs no or negligible changes to the information it receives. Differences between MariaDB server versions are not aligned.
Meta data is access through the mysqli_result
interface.
Example 20.97. Accessing result set meta data
<?php $mysqli = new mysqli('example.com', 'user', 'password', 'database'); if ($mysqli->connect_errno) { echo 'Failed to connect to MySQL: (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error; } $res = $mysqli->query('SELECT 1 AS _one, 'Hello' AS _two FROM DUAL'); var_dump($res->fetch_fields()); ?>
The above example will output:
array(2) { [0]=> object(stdClass)#3 (13) { ['name']=> string(4) '_one' ['orgname']=> string(0) '' ['table']=> string(0) '' ['orgtable']=> string(0) '' ['def']=> string(0) '' ['db']=> string(0) '' ['catalog']=> string(3) 'def' ['max_length']=> int(1) ['length']=> int(1) ['charsetnr']=> int(63) ['flags']=> int(32897) ['type']=> int(8) ['decimals']=> int(0) } [1]=> object(stdClass)#4 (13) { ['name']=> string(4) '_two' ['orgname']=> string(0) '' ['table']=> string(0) '' ['orgtable']=> string(0) '' ['def']=> string(0) '' ['db']=> string(0) '' ['catalog']=> string(3) 'def' ['max_length']=> int(5) ['length']=> int(5) ['charsetnr']=> int(8) ['flags']=> int(1) ['type']=> int(253) ['decimals']=> int(31) } }
Prepared statements
Meta data of result sets created using prepared statements are accessed the same way. A suitable mysqli_result
handle is returned by mysqli_stmt_result_metadata
.
Example 20.98. Prepared statements metadata
<?php $stmt = $mysqli->prepare('SELECT 1 AS _one, 'Hello' AS _two FROM DUAL'); $stmt->execute(); $res = $stmt->result_metadata(); var_dump($res->fetch_fields()); ?>
See also
mysqli::query
|
mysqli_result::fetch_fields |
Installing/Configuring
Requirements
In order to have these functions available, you must compile PHP with support for the mysqli extension.Note
The mysqli extension is designed to work with MariaDB version 4.1.13 or newer, or 5.0.7 or newer. For previous versions, please see the MySQL extension documentation.
Installation
The mysqli
extension was introduced with PHP version 5.0.0. The MariaDB Native Driver was included in PHP version 5.3.0.
Installation on Linux
The common Unix distributions include binary versions of PHP that can be installed. Although these binary versions are typically built with support for MariaDB extensions enabled, the extension libraries themselves may need to be installed using an additional package. Check the package manager than comes with your chosen distribution for availability.
Unless your Unix distribution comes with a binary package of PHP with the mysqli
extension available, you will need to build PHP from source code. Building PHP from source allows you to specify the MariaDB extensions you want to use, as well as your choice of client library for each extension.
The MariaDB Native Driver is the recommended option, as it results in improved performance and gives access to features not available when using the MariaDB Client Library. Refer to What is PHP's MariaDB Native Driver? for a brief overview of the advantages of MariaDB Native Driver.
The /path/to/mysql_config
represents the location of the mysql_config
program that comes with MariaDB Server.
Table 20.12. mysqli compile time support matrix
PHP Version | Default | Configure Options: mysqlnd | Configure Options: libmysql
| Changelog |
---|---|---|---|---|
5.0.x, 5.1.x, 5.2.x | libmysql | Not Available | --with-mysqli=/path/to/mysql_config
| |
5.3.x | libmysql | --with-mysqli=mysqlnd
| --with-mysqli=/path/to/mysql_config
| mysqlnd is now supported |
5.4.x | mysqlnd | --with-mysqli
| --with-mysqli=/path/to/mysql_config
| mysqlnd is now the default |
Note that it is possible to freely mix MariaDB extensions and client libraries. For example, it is possible to enable the MariaDB extension to use the MariaDB Client Library (libmysql), while configuring the mysqli
extension to use the MariaDB Native Driver. However, all permutations of extension and client library are possible.
The following example builds the MariaDB extension to use the MariaDB Client Library, and the mysqli
and PDO MYSQL extensions to use the MariaDB Native Driver:
./configure --with-mysql=/usr/bin/mysql_config \ --with-mysqli=mysqlnd \ --with-pdo-mysql=mysqlnd [other options]
Installation on Windows Systems
On Windows, PHP is most commonly installed using the binary installer.
PHP 5.0, 5.1, 5.2
Once PHP has been installed, some configuration is required to enable mysqli
and specify the client library you want it to use.
The mysqli
extension is not enabled by default, so the php_mysqli.dll
DLL must be enabled inside of php.ini
. In order to do this you need to find the php.ini
file (typically located in c:\php
), and make sure you remove the comment (semi-colon) from the start of the line extension=php_mysqli.dll
, in the section marked [PHP_MYSQLI]
.
Also, if you want to use the MariaDB Client Library with mysqli
, you need to make sure PHP can access the client library file. The MariaDB Client Library is included as a file named libmysql.dll
in the Windows PHP distribution. This file needs to be available in the Windows system's PATH
environment variable, so that it can be successfully loaded. See the FAQ titled 'How do I add my PHP directory to the PATH on Windows' for information on how to do this. Copying libmysql.dll
to the Windows system directory (typically c:\Windows\system
) also works, as the system directory is by default in the system's PATH
. However, this practice is strongly discouraged.
As with enabling any PHP extension (such as php_mysqli.dll
), the PHP directive extension_dir should be set to the directory where the PHP extensions are located. See also the Manual Windows Installation Instructions. An example extension_dir
value for PHP 5 is c:\php\ext
.Note
If when starting the web server an error similar to the following occurs: 'Unable to load dynamic library './php_mysqli.dll''
, this is because php_mysqli.dll
and/or libmysql.dll
cannot be found by the system.
PHP 5.3.0+
On Windows, for PHP versions 5.3 and newer, the mysqli
extension is enabled and uses the MariaDB Native Driver by default. This means you don't need to worry about configuring access to libmysql.dll
.
Runtime Configuration
The behaviour of these functions is affected by settings in php.ini
.
Table 20.13. MySQLi Configuration Options
Name | Default | Changeable | Changelog |
---|---|---|---|
mysqli.allow_local_infile | '1' | PHP_INI_SYSTEM | Available since PHP 5.2.4. |
mysqli.allow_persistent | '1' | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
mysqli.max_persistent | '-1' | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
mysqli.max_links | '-1' | PHP_INI_SYSTEM | Available since PHP 5.0.0. |
mysqli.default_port | '3306' | PHP_INI_ALL | Available since PHP 5.0.0. |
mysqli.default_socket | NULL | PHP_INI_ALL | Available since PHP 5.0.0. |
mysqli.default_host | NULL | PHP_INI_ALL | Available since PHP 5.0.0. |
mysqli.default_user | NULL | PHP_INI_ALL | Available since PHP 5.0.0. |
mysqli.default_pw | NULL | PHP_INI_ALL | Available since PHP 5.0.0. |
mysqli.reconnect | '0' | PHP_INI_SYSTEM | Available since PHP 4.3.5. |
mysqli.cache_size | '2000' | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
For further details and definitions of the preceding PHP_INI_* constants, see the chapter on configuration changes.
Here's a short explanation of the configuration directives.
mysqli.allow_local_infile
integer-
Allow accessing, from PHP's perspective, local files with LOAD DATA statements
mysqli.allow_persistent
integer-
Enable the ability to create persistent connections using
mysqli_connect
. mysqli.max_persistent
integer-
Maximum of persistent connections that can be made. Set to 0 for unlimited.
mysqli.max_links
integer-
The maximum number of MariaDB connections per process.
mysqli.default_port
integer-
The default TCP port number to use when connecting to the database server if no other port is specified. If no default is specified, the port will be obtained from the
MYSQL_TCP_PORT
environment variable, themysql-tcp
entry in/etc/services
or the compile-timeMYSQL_PORT
constant, in that order. Win32 will only use theMYSQL_PORT
constant. mysqli.default_socket
string-
The default socket name to use when connecting to a local database server if no other socket name is specified.
mysqli.default_host
string-
The default server host to use when connecting to the database server if no other host is specified. Doesn't apply in safe mode.
mysqli.default_user
string-
The default user name to use when connecting to the database server if no other name is specified. Doesn't apply in safe mode.
mysqli.default_pw
string-
The default password to use when connecting to the database server if no other password is specified. Doesn't apply in safe mode.
mysqli.reconnect
integer-
Automatically reconnect if the connection was lost.
mysqli.cache_size
integer-
Available only with mysqlnd.
Users cannot set MYSQL_OPT_READ_TIMEOUT
through an API call or runtime configuration setting. Note that if it were possible there would be differences between how libmysql
and streams would interpret the value of MYSQL_OPT_READ_TIMEOUT
.
Resource Types
This extension has no resource types defined.
The mysqli Extension and Persistent Connections
Persistent connection support was introduced in PHP 5.3 for the mysqli
extension. Support was already present in PDO MYSQL and ext/mysql. The idea behind persistent connections is that a connection between a client process and a database can be reused by a client process, rather than being created and destroyed multiple times. This reduces the overhead of creating fresh connections every time one is required, as unused connections are cached and ready to be reused.
Unlike the mysql extension, mysqli does not provide a separate function for opening persistent connections. To open a persistent connection you must prepend p:
to the hostname when connecting.
The problem with persistent connections is that they can be left in unpredictable states by clients. For example, a table lock might be activated before a client terminates unexpectedly. A new client process reusing this persistent connection will get the connection "as is". Any cleanup would need to be done by the new client process before it could make good use of the persistent connection, increasing the burden on the programmer.
The persistent connection of the mysqli
extension however provides built-in cleanup handling code. The cleanup carried out by mysqli
includes:
- Rollback active transactions
- Close and drop temporary tables
- Unlock tables
- Reset session variables
- Close prepared statements (always happens with PHP)
- Close handler
- Release locks acquired with
GET_LOCK
This ensures that persistent connections are in a clean state on return from the connection pool, before the client process uses them.
The mysqli
extension does this cleanup by automatically calling the C-API function mysql_change_user()
.
The automatic cleanup feature has advantages and disadvantages though. The advantage is that the programmer no longer needs to worry about adding cleanup code, as it is called automatically. However, the disadvantage is that the code could potentially be a little slower, as the code to perform the cleanup needs to run each time a connection is returned from the connection pool.
It is possible to switch off the automatic cleanup code, by compiling PHP with MYSQLI_NO_CHANGE_USER_ON_PCONNECT
defined.Note
The mysqli
extension supports persistent connections when using either MariaDB Native Driver or MariaDB Client Library.
Predefined Constants
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
MYSQLI_READ_DEFAULT_GROUP
-
Read options from the named group from
my.cnf
or the file specified withMYSQLI_READ_DEFAULT_FILE
MYSQLI_READ_DEFAULT_FILE
-
Read options from the named option file instead of from
my.cnf
MYSQLI_OPT_CONNECT_TIMEOUT
-
Connect timeout in seconds
MYSQLI_OPT_LOCAL_INFILE
-
Enables command
LOAD LOCAL INFILE
MYSQLI_INIT_COMMAND
-
Command to execute when connecting to MariaDB server. Will automatically be re-executed when reconnecting.
MYSQLI_CLIENT_SSL
-
Use SSL (encrypted protocol). This option should not be set by application programs; it is set internally in the MariaDB client library
MYSQLI_CLIENT_COMPRESS
-
Use compression protocol
MYSQLI_CLIENT_INTERACTIVE
-
Allow
interactive_timeout
seconds (instead ofwait_timeout
seconds) of inactivity before closing the connection. The client's sessionwait_timeout
variable will be set to the value of the sessioninteractive_timeout
variable. MYSQLI_CLIENT_IGNORE_SPACE
-
Allow spaces after function names. Makes all functions names reserved words.
MYSQLI_CLIENT_NO_SCHEMA
-
Don't allow the
db_name.tbl_name.col_name
syntax. MYSQLI_CLIENT_MULTI_QUERIES
-
Allows multiple semicolon-delimited queries in a single
mysqli_query
call. MYSQLI_STORE_RESULT
-
For using buffered resultsets
MYSQLI_USE_RESULT
-
For using unbuffered resultsets
MYSQLI_ASSOC
-
Columns are returned into the array having the fieldname as the array index.
MYSQLI_NUM
-
Columns are returned into the array having an enumerated index.
MYSQLI_BOTH
-
Columns are returned into the array having both a numerical index and the fieldname as the associative index.
MYSQLI_NOT_NULL_FLAG
-
Indicates that a field is defined as
NOT NULL
MYSQLI_PRI_KEY_FLAG
-
Field is part of a primary index
MYSQLI_UNIQUE_KEY_FLAG
-
Field is part of a unique index.
MYSQLI_MULTIPLE_KEY_FLAG
-
Field is part of an index.
MYSQLI_BLOB_FLAG
-
Field is defined as
BLOB
MYSQLI_UNSIGNED_FLAG
-
Field is defined as
UNSIGNED
MYSQLI_ZEROFILL_FLAG
-
Field is defined as
ZEROFILL
MYSQLI_AUTO_INCREMENT_FLAG
-
Field is defined as
AUTO_INCREMENT
MYSQLI_TIMESTAMP_FLAG
-
Field is defined as
TIMESTAMP
MYSQLI_SET_FLAG
-
Field is defined as
SET
MYSQLI_NUM_FLAG
-
Field is defined as
NUMERIC
MYSQLI_PART_KEY_FLAG
-
Field is part of an multi-index
MYSQLI_GROUP_FLAG
-
Field is part of
GROUP BY
MYSQLI_TYPE_DECIMAL
-
Field is defined as
DECIMAL
MYSQLI_TYPE_NEWDECIMAL
-
Precision math
DECIMAL
orNUMERIC
field (MySQL 5.0.3 and up) MYSQLI_TYPE_BIT
-
Field is defined as
BIT
(MySQL 5.0.3 and up) MYSQLI_TYPE_TINY
-
Field is defined as
TINYINT
MYSQLI_TYPE_SHORT
-
Field is defined as
SMALLINT
MYSQLI_TYPE_LONG
-
Field is defined as
INT
MYSQLI_TYPE_FLOAT
-
Field is defined as
FLOAT
MYSQLI_TYPE_DOUBLE
-
Field is defined as
DOUBLE
MYSQLI_TYPE_NULL
-
Field is defined as
DEFAULT NULL
MYSQLI_TYPE_TIMESTAMP
-
Field is defined as
TIMESTAMP
MYSQLI_TYPE_LONGLONG
-
Field is defined as
BIGINT
MYSQLI_TYPE_INT24
-
Field is defined as
MEDIUMINT
MYSQLI_TYPE_DATE
-
Field is defined as
DATE
MYSQLI_TYPE_TIME
-
Field is defined as
TIME
MYSQLI_TYPE_DATETIME
-
Field is defined as
DATETIME
MYSQLI_TYPE_YEAR
-
Field is defined as
YEAR
MYSQLI_TYPE_NEWDATE
-
Field is defined as
DATE
MYSQLI_TYPE_INTERVAL
-
Field is defined as
INTERVAL
MYSQLI_TYPE_ENUM
-
Field is defined as
ENUM
MYSQLI_TYPE_SET
-
Field is defined as
SET
MYSQLI_TYPE_TINY_BLOB
-
Field is defined as
TINYBLOB
MYSQLI_TYPE_MEDIUM_BLOB
-
Field is defined as
MEDIUMBLOB
MYSQLI_TYPE_LONG_BLOB
-
Field is defined as
LONGBLOB
MYSQLI_TYPE_BLOB
-
Field is defined as
BLOB
MYSQLI_TYPE_VAR_STRING
-
Field is defined as
VARCHAR
MYSQLI_TYPE_STRING
-
Field is defined as
STRING
MYSQLI_TYPE_CHAR
-
Field is defined as
CHAR
MYSQLI_TYPE_GEOMETRY
-
Field is defined as
GEOMETRY
MYSQLI_NEED_DATA
-
More data available for bind variable
MYSQLI_NO_DATA
-
No more data available for bind variable
MYSQLI_DATA_TRUNCATED
-
Data truncation occurred. Available since PHP 5.1.0 and MariaDB 5.0.5.
MYSQLI_ENUM_FLAG
-
Field is defined as
ENUM
. Available since PHP 5.3.0. MYSQLI_CURSOR_TYPE_FOR_UPDATE
MYSQLI_CURSOR_TYPE_NO_CURSOR
MYSQLI_CURSOR_TYPE_READ_ONLY
MYSQLI_CURSOR_TYPE_SCROLLABLE
MYSQLI_STMT_ATTR_CURSOR_TYPE
MYSQLI_STMT_ATTR_PREFETCH_ROWS
MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH
MYSQLI_SET_CHARSET_NAME
MYSQLI_REPORT_INDEX
-
Report if no index or bad index was used in a query.
MYSQLI_REPORT_ERROR
-
Report errors from mysqli function calls.
MYSQLI_REPORT_STRICT
-
Throw a
mysqli_sql_exception
for errors instead of warnings. MYSQLI_REPORT_ALL
-
Set all options on (report all).
MYSQLI_REPORT_OFF
-
Turns reporting off.
MYSQLI_DEBUG_TRACE_ENABLED
-
Is set to 1 if
mysqli_debug
functionality is enabled. MYSQLI_SERVER_QUERY_NO_GOOD_INDEX_USED
MYSQLI_SERVER_QUERY_NO_INDEX_USED
MYSQLI_REFRESH_GRANT
-
Refreshes the grant tables.
MYSQLI_REFRESH_LOG
-
Flushes the logs, like executing the
FLUSH LOGS
SQL statement. MYSQLI_REFRESH_TABLES
-
Flushes the table cache, like executing the
FLUSH TABLES
SQL statement. MYSQLI_REFRESH_HOSTS
-
Flushes the host cache, like executing the
FLUSH HOSTS
SQL statement. MYSQLI_REFRESH_STATUS
-
Reset the status variables, like executing the
FLUSH STATUS
SQL statement. MYSQLI_REFRESH_THREADS
-
Flushes the thread cache.
MYSQLI_REFRESH_SLAVE
-
On a slave replication server: resets the master server information, and restarts the slave. Like executing the
RESET SLAVE
SQL statement. MYSQLI_REFRESH_MASTER
-
On a master replication server: removes the binary log files listed in the binary log index, and truncates the index file. Like executing the
RESET MASTER
SQL statement.
Notes
Some implementation notes:
- Support was added for
MYSQL_TYPE_GEOMETRY
to the MySQLi extension in PHP 5.3. - Note there are different internal implementations within
libmysql
andmysqlnd
for handling columns of typeMYSQL_TYPE_GEOMETRY
. Generally speaking,mysqlnd
will allocate significantly less memory. For example, if there is aPOINT
column in a result set,libmysql
may pre-allocate up to 4GB of RAM although less than 50 bytes are needed for holding aPOINT
column in memory. Memory allocation is much lower, less than 50 bytes, if usingmysqlnd
.
The MySQLi Extension Function Summary
mysqli Class | |||
---|---|---|---|
OOP Interface | Procedural Interface | Alias (Do not use) | Description |
Properties | |||
$mysqli::affected_rows | mysqli_affected_rows
| N/A | Gets the number of affected rows in a previous MariaDB operation |
$mysqli::client_info | mysqli_get_client_info
| N/A | Returns the MariaDB client version as a string |
$mysqli::client_version | mysqli_get_client_version
| N/A | Returns MariaDB client version info as an integer |
$mysqli::connect_errno | mysqli_connect_errno
| N/A | Returns the error code from last connect call |
$mysqli::connect_error | mysqli_connect_error
| N/A | Returns a string description of the last connect error |
$mysqli::errno | mysqli_errno
| N/A | Returns the error code for the most recent function call |
$mysqli::error | mysqli_error
| N/A | Returns a string description of the last error |
$mysqli::field_count | mysqli_field_count
| N/A | Returns the number of columns for the most recent query |
$mysqli::host_info | mysqli_get_host_info
| N/A | Returns a string representing the type of connection used |
$mysqli::protocol_version | mysqli_get_proto_info
| N/A | Returns the version of the MariaDB protocol used |
$mysqli::server_info | mysqli_get_server_info
| N/A | Returns the version of the MariaDB server |
$mysqli::server_version | mysqli_get_server_version
| N/A | Returns the version of the MariaDB server as an integer |
$mysqli::info | mysqli_info
| N/A | Retrieves information about the most recently executed query |
$mysqli::insert_id | mysqli_insert_id
| N/A | Returns the auto generated id used in the last query |
$mysqli::sqlstate | mysqli_sqlstate
| N/A | Returns the SQLSTATE error from previous MariaDB operation |
$mysqli::warning_count | mysqli_warning_count
| N/A | Returns the number of warnings from the last query for the given link |
Methods | |||
mysqli::autocommit
| mysqli_autocommit
| N/A | Turns on or off auto-commiting database modifications |
mysqli::change_user
| mysqli_change_user
| N/A | Changes the user of the specified database connection |
mysqli::character_set_name , mysqli::client_encoding
| mysqli_character_set_name
| mysqli_client_encoding
| Returns the default character set for the database connection |
mysqli::close
| mysqli_close
| N/A | Closes a previously opened database connection |
mysqli::commit
| mysqli_commit
| N/A | Commits the current transaction |
mysqli::__construct
| mysqli_connect
| N/A | Open a new connection to the MariaDB server [Note: static (i.e. class) method] |
mysqli::debug
| mysqli_debug
| N/A | Performs debugging operations |
mysqli::dump_debug_info
| mysqli_dump_debug_info
| N/A | Dump debugging information into the log |
mysqli::get_charset
| mysqli_get_charset
| N/A | Returns a character set object |
mysqli::get_connection_stats
| mysqli_get_connection_stats
| N/A | Returns client connection statistics. Available only with mysqlnd. |
mysqli::get_client_info
| mysqli_get_client_info
| N/A | Returns the MariaDB client version as a string |
mysqli::get_client_stats
| mysqli_get_client_stats
| N/A | Returns client per-process statistics. Available only with mysqlnd. |
mysqli::get_cache_stats
| mysqli_get_cache_stats
| N/A | Returns client Zval cache statistics. Available only with mysqlnd. |
mysqli::get_server_info
| mysqli_get_server_info
| N/A | NOT DOCUMENTED |
mysqli::get_warnings
| mysqli_get_warnings
| N/A | NOT DOCUMENTED |
mysqli::init
| mysqli_init
| N/A | Initializes MySQLi and returns a resource for use with mysqli_real_connect. [Not called on an object, as it returns a $mysqli object.] |
mysqli::kill
| mysqli_kill
| N/A | Asks the server to kill a MariaDB thread |
mysqli::more_results
| mysqli_more_results
| N/A | Check if there are any more query results from a multi query |
mysqli::multi_query
| mysqli_multi_query
| N/A | Performs a query on the database |
mysqli::next_result
| mysqli_next_result
| N/A | Prepare next result from multi_query |
mysqli::options
| mysqli_options
| mysqli_set_opt
| Set options |
mysqli::ping
| mysqli_ping
| N/A | Pings a server connection, or tries to reconnect if the connection has gone down |
mysqli::prepare
| mysqli_prepare
| N/A | Prepare an SQL statement for execution |
mysqli::query
| mysqli_query
| N/A | Performs a query on the database |
mysqli::real_connect
| mysqli_real_connect
| N/A | Opens a connection to a mysql server |
mysqli::real_escape_string , mysqli::escape_string
| mysqli_real_escape_string
| mysqli_escape_string
| Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection |
mysqli::real_query
| mysqli_real_query
| N/A | Execute an SQL query |
mysqli::refresh
| mysqli_refresh
| N/A | Flushes tables or caches, or resets the replication server information |
mysqli::rollback
| mysqli_rollback
| N/A | Rolls back current transaction |
mysqli::select_db
| mysqli_select_db
| N/A | Selects the default database for database queries |
mysqli::set_charset
| mysqli_set_charset
| N/A | Sets the default client character set |
mysqli::set_local_infile_default
| mysqli_set_local_infile_default
| N/A | Unsets user defined handler for load local infile command |
mysqli::set_local_infile_handler
| mysqli_set_local_infile_handler
| N/A | Set callback function for LOAD DATA LOCAL INFILE command |
mysqli::ssl_set
| mysqli_ssl_set
| N/A | Used for establishing secure connections using SSL |
mysqli::stat
| mysqli_stat
| N/A | Gets the current system status |
mysqli::stmt_init
| mysqli_stmt_init
| N/A | Initializes a statement and returns an object for use with mysqli_stmt_prepare |
mysqli::store_result
| mysqli_store_result
| N/A | Transfers a result set from the last query |
mysqli::thread_id
| mysqli_thread_id
| N/A | Returns the thread ID for the current connection |
mysqli::thread_safe
| mysqli_thread_safe
| N/A | Returns whether thread safety is given or not |
mysqli::use_result
| mysqli_use_result
| N/A | Initiate a result set retrieval |
MySQL_STMT | |||
---|---|---|---|
OOP Interface | Procedural Interface | Alias (Do not use) | Description |
Properties | |||
$mysqli_stmt::affected_rows | mysqli_stmt_affected_rows
| N/A | Returns the total number of rows changed, deleted, or inserted by the last executed statement |
$mysqli_stmt::errno | mysqli_stmt_errno
| N/A | Returns the error code for the most recent statement call |
$mysqli_stmt::error | mysqli_stmt_error
| N/A | Returns a string description for last statement error |
$mysqli_stmt::field_count | mysqli_stmt_field_count
| N/A | Returns the number of field in the given statement - not documented |
$mysqli_stmt::insert_id | mysqli_stmt_insert_id
| N/A | Get the ID generated from the previous INSERT operation |
$mysqli_stmt::num_rows | mysqli_stmt_num_rows
| N/A | Return the number of rows in statements result set |
$mysqli_stmt::param_count | mysqli_stmt_param_count
| mysqli_param_count
| Returns the number of parameter for the given statement |
$mysqli_stmt::sqlstate | mysqli_stmt_sqlstate
| N/A | Returns SQLSTATE error from previous statement operation |
Methods | |||
mysqli_stmt::attr_get
| mysqli_stmt_attr_get
| N/A | Used to get the current value of a statement attribute |
mysqli_stmt::attr_set
| mysqli_stmt_attr_set
| N/A | Used to modify the behavior of a prepared statement |
mysqli_stmt::bind_param
| mysqli_stmt_bind_param
| mysqli_bind_param
| Binds variables to a prepared statement as parameters |
mysqli_stmt::bind_result
| mysqli_stmt_bind_result
| mysqli_bind_result
| Binds variables to a prepared statement for result storage |
mysqli_stmt::close
| mysqli_stmt_close
| N/A | Closes a prepared statement |
mysqli_stmt::data_seek
| mysqli_stmt_data_seek
| N/A | Seeks to an arbitrary row in statement result set |
mysqli_stmt::execute
| mysqli_stmt_execute
| mysqli_execute
| Executes a prepared Query |
mysqli_stmt::fetch
| mysqli_stmt_fetch
| mysqli_fetch
| Fetch results from a prepared statement into the bound variables |
mysqli_stmt::free_result
| mysqli_stmt_free_result
| N/A | Frees stored result memory for the given statement handle |
mysqli_stmt::get_result
| mysqli_stmt_get_result
| N/A | Gets a result set from a prepared statement. Available only with mysqlnd. |
mysqli_stmt::get_warnings
| mysqli_stmt_get_warnings
| N/A | NOT DOCUMENTED |
$mysqli_stmt::more_results() | mysqli_stmt_more_results() | N/A | NOT DOCUMENTED Available only with mysqlnd. |
$mysqli_stmt::next_result() | mysqli_stmt_next_result() | N/A | NOT DOCUMENTED Available only with mysqlnd. |
mysqli_stmt::num_rows
| mysqli_stmt_num_rows
| N/A | See also property $mysqli_stmt::num_rows |
mysqli_stmt::prepare
| mysqli_stmt_prepare
| N/A | Prepare an SQL statement for execution |
mysqli_stmt::reset
| mysqli_stmt_reset
| N/A | Resets a prepared statement |
mysqli_stmt::result_metadata
| mysqli_stmt_result_metadata
| mysqli_get_metadata
| Returns result set metadata from a prepared statement |
mysqli_stmt::send_long_data
| mysqli_stmt_send_long_data
| mysqli_send_long_data
| Send data in blocks |
mysqli_stmt::store_result
| mysqli_stmt_store_result
| N/A | Transfers a result set from a prepared statement |
mysqli_result | |||
---|---|---|---|
OOP Interface | Procedural Interface | Alias (Do not use) | Description |
Properties | |||
$mysqli_result::current_field | mysqli_field_tell
| N/A | Get current field offset of a result pointer |
$mysqli_result::field_count | mysqli_num_fields
| N/A | Get the number of fields in a result |
$mysqli_result::lengths | mysqli_fetch_lengths
| N/A | Returns the lengths of the columns of the current row in the result set |
$mysqli_result::num_rows | mysqli_num_rows
| N/A | Gets the number of rows in a result |
Methods | |||
mysqli_result::data_seek
| mysqli_data_seek
| N/A | Adjusts the result pointer to an arbitary row in the result |
mysqli_result::fetch_all
| mysqli_fetch_all
| N/A | Fetches all result rows and returns the result set as an associative array, a numeric array, or both. Available only with mysqlnd. |
mysqli_result::fetch_array
| mysqli_fetch_array
| N/A | Fetch a result row as an associative, a numeric array, or both |
mysqli_result::fetch_assoc
| mysqli_fetch_assoc
| N/A | Fetch a result row as an associative array |
mysqli_result::fetch_field_direct
| mysqli_fetch_field_direct
| N/A | Fetch meta-data for a single field |
mysqli_result::fetch_field
| mysqli_fetch_field
| N/A | Returns the next field in the result set |
mysqli_result::fetch_fields
| mysqli_fetch_fields
| N/A | Returns an array of objects representing the fields in a result set |
mysqli_result::fetch_object
| mysqli_fetch_object
| N/A | Returns the current row of a result set as an object |
mysqli_result::fetch_row
| mysqli_fetch_row
| N/A | Get a result row as an enumerated array |
mysqli_result::field_seek
| mysqli_field_seek
| N/A | Set result pointer to a specified field offset |
mysqli_result::free , mysqli_result::close, mysqli_result::free_result
| mysqli_free_result
| N/A | Frees the memory associated with a result |
MySQL_Driver | |||
---|---|---|---|
OOP Interface | Procedural Interface | Alias (Do not use) | Description |
Properties | |||
N/A | |||
Methods | |||
mysqli_driver::embedded_server_end
| mysqli_embedded_server_end
| N/A | NOT DOCUMENTED |
mysqli_driver::embedded_server_start
| mysqli_embedded_server_start
| N/A | NOT DOCUMENTED |
Alias functions are provided for backward compatibility purposes only. Do not use them in new projects.
The mysqli class (mysqli
)
mysqli::$affected_rows
,mysqli_affected_rows
mysqli::autocommit
,mysqli_autocommit
mysqli::change_user
,mysqli_change_user
mysqli::character_set_name
,mysqli_character_set_name
mysqli::$client_info
,mysqli_get_client_info
mysqli::$client_version
,mysqli_get_client_version
mysqli::close
,mysqli_close
mysqli::commit
,mysqli_commit
mysqli::$connect_errno
,mysqli_connect_errno
mysqli::$connect_error
,mysqli_connect_error
mysqli::__construct
,mysqli_connect
mysqli::debug
,mysqli_debug
mysqli::disable_reads_from_master
,mysqli_disable_reads_from_master
mysqli::dump_debug_info
,mysqli_dump_debug_info
mysqli::$errno
,mysqli_errno
mysqli::$error_list
,mysqli_error_list
mysqli::$error
,mysqli_error
mysqli::$field_count
,mysqli_field_count
mysqli::get_charset
,mysqli_get_charset
mysqli::get_client_info
,mysqli_get_client_info
mysqli_get_client_stats
mysqli::$client_version
,mysqli_get_client_version
mysqli::get_connection_stats
,mysqli_get_connection_stats
mysqli::$host_info
,mysqli_get_host_info
mysqli::$protocol_version
,mysqli_get_proto_info
mysqli::$server_info
,mysqli_get_server_info
mysqli::$server_version
,mysqli_get_server_version
mysqli::get_warnings
,mysqli_get_warnings
mysqli::$info
,mysqli_info
mysqli::init
,mysqli_init
mysqli::$insert_id
,mysqli_insert_id
mysqli::kill
,mysqli_kill
mysqli::more_results
,mysqli_more_results
mysqli::multi_query
,mysqli_multi_query
mysqli::next_result
,mysqli_next_result
mysqli::options
,mysqli_options
mysqli::ping
,mysqli_ping
mysqli::poll
,mysqli_poll
mysqli::prepare
,mysqli_prepare
mysqli::query
,mysqli_query
mysqli::real_connect
,mysqli_real_connect
mysqli::real_escape_string
,mysqli_real_escape_string
mysqli::real_query
,mysqli_real_query
mysqli::reap_async_query
,mysqli_reap_async_query
mysqli::refresh
,mysqli_refresh
mysqli::rollback
,mysqli_rollback
mysqli::rpl_query_type
,mysqli_rpl_query_type
mysqli::select_db
,mysqli_select_db
mysqli::send_query
,mysqli_send_query
mysqli::set_charset
,mysqli_set_charset
mysqli::set_local_infile_default
,mysqli_set_local_infile_default
mysqli::set_local_infile_handler
,mysqli_set_local_infile_handler
mysqli::$sqlstate
,mysqli_sqlstate
mysqli::ssl_set
,mysqli_ssl_set
mysqli::stat
,mysqli_stat
mysqli::stmt_init
,mysqli_stmt_init
mysqli::store_result
,mysqli_store_result
mysqli::$thread_id
,mysqli_thread_id
mysqli::thread_safe
,mysqli_thread_safe
mysqli::use_result
,mysqli_use_result
mysqli::$warning_count
,mysqli_warning_count
Represents a connection between PHP and a MariaDB database.
mysqli {
mysqli Propertiesint mysqli->affected_rows ;
string mysqli->client_info ;
int mysqli->client_version ;
string mysqli->connect_errno ;
string mysqli->connect_error ;
int mysqli->errno ;
array mysqli->error_list ;
string mysqli->error ;
int mysqli->field_count ;
int mysqli->client_version ;
string mysqli->host_info ;
string mysqli->protocol_version ;
string mysqli->server_info ;
int mysqli->server_version ;
string mysqli->info ;
mixed mysqli->insert_id ;
string mysqli->sqlstate ;
int mysqli->thread_id ;
int mysqli->warning_count ;
Methodsbool mysqli::autocommit(bool mode);
bool mysqli::change_user(string user,
string password,
string database);
string mysqli::character_set_name();
bool mysqli::close();
bool mysqli::commit();
bool mysqli::debug(string message);
void mysqli::disable_reads_from_master();
bool mysqli::dump_debug_info();
object mysqli::get_charset();
string mysqli::get_client_info();
bool mysqli::get_connection_stats();
mysqli_warning mysqli::get_warnings();
mysqli mysqli::init();
bool mysqli::kill(int processid);
bool mysqli::more_results();
bool mysqli::multi_query(string query);
bool mysqli::next_result();
bool mysqli::options(int option,
mixed value);
bool mysqli::ping();
public int mysqli::poll(array read,
array error,
array reject,
int sec,
int usec);
mysqli_stmt mysqli::prepare(string query);
mixed mysqli::query(string query,
int resultmode= =MYSQLI_STORE_RESULT);
bool mysqli::real_connect(string host,
string username,
string passwd,
string dbname,
int port,
string socket,
int flags);
string mysqli::escape_string(string escapestr);
bool mysqli::real_query(string query);
public mysqli_result mysqli::reap_async_query();
public bool mysqli::refresh(int options);
bool mysqli::rollback();
int mysqli::rpl_query_type(string query);
bool mysqli::select_db(string dbname);
bool mysqli::send_query(string query);
bool mysqli::set_charset(string charset);
bool mysqli::set_local_infile_handler(mysqli link,
callable read_func);
bool mysqli::ssl_set(string key,
string cert,
string ca,
string capath,
string cipher);
string mysqli::stat();
mysqli_stmt mysqli::stmt_init();
mysqli_result mysqli::store_result();
mysqli_result mysqli::use_result();
}
mysqli::$affected_rows
, mysqli_affected_rows
mysqli::$affected_rows
mysqli_affected_rows
Gets the number of affected rows in a previous MariaDB operation
Description
Object oriented styleint mysqli->affected_rows ;
Procedural styleint mysqli_affected_rows(mysqli link);
Returns the number of rows affected by the last INSERT
, UPDATE
, REPLACE
or DELETE
query.
For SELECT statements mysqli_affected_rows
works like mysqli_num_rows
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records where updated for an UPDATE statement, no rows matched the WHERE
clause in the query or that no query has yet been executed. -1 indicates that the query returned an error.Note
If the number of affected rows is greater than maximal int value, the number of affected rows will be returned as a string.
Examples
Example 20.99. $mysqli->affected_rows
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* Insert rows */ $mysqli->query('CREATE TABLE Language SELECT * from CountryLanguage'); printf('Affected rows (INSERT): %d\n', $mysqli->affected_rows); $mysqli->query('ALTER TABLE Language ADD Status int default 0'); /* update rows */ $mysqli->query('UPDATE Language SET Status=1 WHERE Percentage > 50'); printf('Affected rows (UPDATE): %d\n', $mysqli->affected_rows); /* delete rows */ $mysqli->query('DELETE FROM Language WHERE Percentage < 50'); printf('Affected rows (DELETE): %d\n', $mysqli->affected_rows); /* select all rows */ $result = $mysqli->query('SELECT CountryCode FROM Language'); printf('Affected rows (SELECT): %d\n', $mysqli->affected_rows); $result->close(); /* Delete table Language */ $mysqli->query('DROP TABLE Language'); /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); if (!$link) { printf('Can't connect to localhost. Error: %s\n', mysqli_connect_error()); exit(); } /* Insert rows */ mysqli_query($link, 'CREATE TABLE Language SELECT * from CountryLanguage'); printf('Affected rows (INSERT): %d\n', mysqli_affected_rows($link)); mysqli_query($link, 'ALTER TABLE Language ADD Status int default 0'); /* update rows */ mysqli_query($link, 'UPDATE Language SET Status=1 WHERE Percentage > 50'); printf('Affected rows (UPDATE): %d\n', mysqli_affected_rows($link)); /* delete rows */ mysqli_query($link, 'DELETE FROM Language WHERE Percentage < 50'); printf('Affected rows (DELETE): %d\n', mysqli_affected_rows($link)); /* select all rows */ $result = mysqli_query($link, 'SELECT CountryCode FROM Language'); printf('Affected rows (SELECT): %d\n', mysqli_affected_rows($link)); mysqli_free_result($result); /* Delete table Language */ mysqli_query($link, 'DROP TABLE Language'); /* close connection */ mysqli_close($link); ?>
The above examples will output:
Affected rows (INSERT): 984 Affected rows (UPDATE): 168 Affected rows (DELETE): 815 Affected rows (SELECT): 169
See Also
mysqli_num_rows
|
mysqli_info |
mysqli::autocommit
, mysqli_autocommit
mysqli::autocommit
mysqli_autocommit
Turns on or off auto-commiting database modifications
Description
Object oriented stylebool mysqli::autocommit(bool mode);
Procedural stylebool mysqli_autocommit(mysqli link,
bool mode);
Turns on or off auto-commit mode on queries for the database connection.
To determine the current state of autocommit use the SQL command SELECT @@autocommit
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
mode
-
Whether to turn on auto-commit or not.
Return Values
Returns TRUE
on success or FALSE
on failure.
Notes
NoteThis function doesn't work with non transactional table types (like MyISAM or ISAM).
Examples
Example 20.100. mysqli::autocommit
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* turn autocommit on */ $mysqli->autocommit(TRUE); if ($result = $mysqli->query('SELECT @@autocommit')) { $row = $result->fetch_row(); printf('Autocommit is %s\n', $row[0]); $result->free(); } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); if (!$link) { printf('Can't connect to localhost. Error: %s\n', mysqli_connect_error()); exit(); } /* turn autocommit on */ mysqli_autocommit($link, TRUE); if ($result = mysqli_query($link, 'SELECT @@autocommit')) { $row = mysqli_fetch_row($result); printf('Autocommit is %s\n', $row[0]); mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Autocommit is 1
See Also
mysqli_commit
|
mysqli_rollback |
mysqli::change_user
, mysqli_change_user
mysqli::change_user
mysqli_change_user
Changes the user of the specified database connection
Description
Object oriented stylebool mysqli::change_user(string user,
string password,
string database);
Procedural stylebool mysqli_change_user(mysqli link,
string user,
string password,
string database);
Changes the user of the specified database connection and sets the current database.
In order to successfully change users a valid username
and password
parameters 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.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
user
-
The MariaDB user name.
password
-
The MariaDB password.
database
-
The database to change to.
If desired, the
NULL
value may be passed resulting in only changing the user and not selecting a database. To select a database in this case use themysqli_select_db
function.
Return Values
Returns TRUE
on success or FALSE
on failure.
Notes
NoteUsing this command will always cause the current database connection to behave as if was a completely new database connection, regardless of if the operation was completed successfully. This reset includes performing a rollback on any active transactions, closing all temporary tables, and unlocking all locked tables.
Examples
Example 20.101. mysqli::change_user
example
Object oriented style
<?php /* connect database test */ $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'test'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* Set Variable a */ $mysqli->query('SET @a:=1'); /* reset all and select a new database */ $mysqli->change_user('my_user', 'my_password', 'world'); if ($result = $mysqli->query('SELECT DATABASE()')) { $row = $result->fetch_row(); printf('Default database: %s\n', $row[0]); $result->close(); } if ($result = $mysqli->query('SELECT @a')) { $row = $result->fetch_row(); if ($row[0] === NULL) { printf('Value of variable a is NULL\n'); } $result->close(); } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php /* connect database test */ $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test'); /* check connection */ if (!$link) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* Set Variable a */ mysqli_query($link, 'SET @a:=1'); /* reset all and select a new database */ mysqli_change_user($link, 'my_user', 'my_password', 'world'); if ($result = mysqli_query($link, 'SELECT DATABASE()')) { $row = mysqli_fetch_row($result); printf('Default database: %s\n', $row[0]); mysqli_free_result($result); } if ($result = mysqli_query($link, 'SELECT @a')) { $row = mysqli_fetch_row($result); if ($row[0] === NULL) { printf('Value of variable a is NULL\n'); } mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Default database: world Value of variable a is NULL
See Also
mysqli_connect
|
mysqli_select_db |
mysqli::character_set_name
, mysqli_character_set_name
mysqli::character_set_name
mysqli_character_set_name
Returns the default character set for the database connection
Description
Object oriented stylestring mysqli::character_set_name();
Procedural stylestring mysqli_character_set_name(mysqli link);
Returns the current character set for the database connection.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
The default character set for the current connection
Examples
Example 20.102. mysqli::character_set_name
example
Object oriented style
<?php /* Open a connection */ $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* Print current character set */ $charset = $mysqli->character_set_name(); printf ('Current character set is %s\n', $charset); $mysqli->close(); ?>
Procedural style
<?php /* Open a connection */ $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (!$link) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* Print current character set */ $charset = mysqli_character_set_name($link); printf ('Current character set is %s\n',$charset); /* close connection */ mysqli_close($link); ?>
The above examples will output:
Current character set is latin1_swedish_ci
See Also
mysqli_client_encoding
|
mysqli_real_escape_string |
mysqli::$client_info
, mysqli_get_client_info
mysqli::$client_info
mysqli_get_client_info
Returns the MariaDB client version as a string
Description
Object oriented stylestring mysqli->client_info ;
Procedural stylestring mysqli_get_client_info(mysqli link);
Returns a string that represents the MariaDB client library version.
Return Values
A string that represents the MariaDB client library version
Examples
Example 20.103. mysqli_get_client_info
<?php /* We don't need a connection to determine the version of mysql client library */ printf('Client library version: %s\n', mysqli_get_client_info()); ?>
See Also
mysqli_get_client_version
|
mysqli_get_server_info
|
mysqli_get_server_version |
mysqli::$client_version
, mysqli_get_client_version
mysqli::$client_version
mysqli_get_client_version
Get MariaDB client info
Description
Object oriented styleint mysqli->client_version ;
Procedural styleint mysqli_get_client_version(mysqli link);
Returns client version number as an integer.
Return Values
A number that represents the MariaDB client library version in format: main_version*10000 + minor_version *100 + sub_version
. For example, 4.1.0 is returned as 40100.
This is useful to quickly determine the version of the client library to know if some capability exists.
Examples
Example 20.104. mysqli_get_client_version
<?php /* We don't need a connection to determine the version of mysql client library */ printf('Client library version: %d\n', mysqli_get_client_version()); ?>
See Also
mysqli_get_client_info
|
mysqli_get_server_info
|
mysqli_get_server_version |
mysqli::close
, mysqli_close
mysqli::close
mysqli_close
Closes a previously opened database connection
Description
Object oriented stylebool mysqli::close();
Procedural stylebool mysqli_close(mysqli link);
Closes a previously opened database connection.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
See mysqli_connect
.
See Also
mysqli_connect
|
mysqli_init
|
mysqli_real_connect |
mysqli::commit
, mysqli_commit
mysqli::commit
mysqli_commit
Commits the current transaction
Description
Object oriented stylebool mysqli::commit();
Procedural stylebool mysqli_commit(mysqli link);
Commits the current transaction for the database connection.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.105. mysqli::commit
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $mysqli->query('CREATE TABLE Language LIKE CountryLanguage'); /* set autocommit to off */ $mysqli->autocommit(FALSE); /* Insert some values */ $mysqli->query('INSERT INTO Language VALUES ('DEU', 'Bavarian', 'F', 11.2)'); $mysqli->query('INSERT INTO Language VALUES ('DEU', 'Swabian', 'F', 9.4)'); /* commit transaction */ $mysqli->commit(); /* drop table */ $mysqli->query('DROP TABLE Language'); /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test'); /* check connection */ if (!$link) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* set autocommit to off */ mysqli_autocommit($link, FALSE); mysqli_query($link, 'CREATE TABLE Language LIKE CountryLanguage'); /* Insert some values */ mysqli_query($link, 'INSERT INTO Language VALUES ('DEU', 'Bavarian', 'F', 11.2)'); mysqli_query($link, 'INSERT INTO Language VALUES ('DEU', 'Swabian', 'F', 9.4)'); /* commit transaction */ mysqli_commit($link); /* close connection */ mysqli_close($link); ?>
See Also
mysqli_autocommit
|
mysqli_rollback |
mysqli::$connect_errno
, mysqli_connect_errno
mysqli::$connect_errno
mysqli_connect_errno
Returns the error code from last connect call
Description
Object oriented stylestring mysqli->connect_errno ;
Procedural styleint mysqli_connect_errno();
Returns the last error code number from the last call to mysqli_connect
.Note
Client error message numbers are listed in the MariaDB errmsg.h
header file, server error message numbers are listed in mysqld_error.h
. In the MariaDB source distribution you can find a complete list of error messages and error numbers in the file Docs/mysqld_error.txt
.
Return Values
An error code value for the last call to mysqli_connect
, if it failed. zero means no error occurred.
Examples
Example 20.106. $mysqli->connect_errno
example
Object oriented style
<?php $mysqli = @new mysqli('localhost', 'fake_user', 'my_password', 'my_db'); if ($mysqli->connect_errno) { die('Connect Error: ' . $mysqli->connect_errno); } ?>
Procedural style
<?php $link = @mysqli_connect('localhost', 'fake_user', 'my_password', 'my_db'); if (!$link) { die('Connect Error: ' . mysqli_connect_errno()); } ?>
The above examples will output:
Connect Error: 1045
See Also
mysqli_connect
|
mysqli_connect_error
|
mysqli_errno
|
mysqli_error
|
mysqli_sqlstate |
mysqli::$connect_error
, mysqli_connect_error
mysqli::$connect_error
mysqli_connect_error
Returns a string description of the last connect error
Description
Object oriented stylestring mysqli->connect_error ;
Procedural stylestring mysqli_connect_error();
Returns the last error message string from the last call to mysqli_connect
.
Return Values
A string that describes the error. NULL
is returned if no error occurred.
Examples
Example 20.107. $mysqli->connect_error
example
Object oriented style
<?php $mysqli = @new mysqli('localhost', 'fake_user', 'my_password', 'my_db'); // Works as of PHP 5.2.9 and 5.3.0. if ($mysqli->connect_error) { die('Connect Error: ' . $mysqli->connect_error); } ?>
Procedural style
<?php $link = @mysqli_connect('localhost', 'fake_user', 'my_password', 'my_db'); if (!$link) { die('Connect Error: ' . mysqli_connect_error()); } ?>
The above examples will output:
Connect Error: Access denied for user 'fake_user'@'localhost' (using password: YES)
Notes
WarningThe mysqli->connect_error property only works properly as of PHP versions 5.2.9 and 5.3.0. Use the mysqli_connect_error
function if compatibility with earlier PHP versions is required.
See Also
mysqli_connect
|
mysqli_connect_errno
|
mysqli_errno
|
mysqli_error
|
mysqli_sqlstate |
mysqli::__construct
, mysqli_connect
mysqli::__construct
mysqli_connect
Open a new connection to the MariaDB server
Description
Object oriented stylemysqli::__construct(string host= =ini_get('mysqli.default_host'),
string username= =ini_get('mysqli.default_user'),
string passwd= =ini_get('mysqli.default_pw'),
string dbname= ='',
int port= =ini_get('mysqli.default_port'),
string socket= =ini_get('mysqli.default_socket'));
Procedural stylemysqli mysqli_connect(string host= =ini_get('mysqli.default_host'),
string username= =ini_get('mysqli.default_user'),
string passwd= =ini_get('mysqli.default_pw'),
string dbname= ='',
int port= =ini_get('mysqli.default_port'),
string socket= =ini_get('mysqli.default_socket'));
Opens a connection to the MariaDB Server running on.
Parameters
host
-
Can be either a host name or an IP address. Passing the
NULL
value or the string 'localhost' to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol.Prepending host by
p:
opens a persistent connection.mysqli_change_user
is automatically called on connections opened from the connection pool. username
-
The MariaDB user name.
passwd
-
If not provided or
NULL
, the MariaDB server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password as provided or not). dbname
-
If provided will specify the default database to be used when performing queries.
port
-
Specifies the port number to attempt to connect to the MariaDB server.
socket
-
Specifies the socket or named pipe that should be used.Note
Specifying the
socket
parameter will not explicitly determine the type of connection to be used when connecting to the MariaDB server. How the connection is made to the MariaDB database is determined by thehost
parameter.
Return Values
Returns an object which represents the connection to a MariaDB Server.
Changelog
Version | Description |
---|---|
5.3.0 | Added the ability of persistent connections. |
Examples
Example 20.108. mysqli::__construct
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db'); /* * This is the 'official' OO way to do it, * BUT $connect_error was broken until PHP 5.2.9 and 5.3.0. */ if ($mysqli->connect_error) { die('Connect Error (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error); } /* * Use this instead of $connect_error if you need to ensure * compatibility with PHP versions prior to 5.2.9 and 5.3.0. */ if (mysqli_connect_error()) { die('Connect Error (' . mysqli_connect_errno() . ') ' . mysqli_connect_error()); } echo 'Success... ' . $mysqli->host_info . '\n'; $mysqli->close(); ?>
Object oriented style when extending mysqli class
<?php class foo_mysqli extends mysqli { public function __construct($host, $user, $pass, $db) { parent::__construct($host, $user, $pass, $db); if (mysqli_connect_error()) { die('Connect Error (' . mysqli_connect_errno() . ') ' . mysqli_connect_error()); } } } $db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db'); echo 'Success... ' . $db->host_info . '\n'; $db->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db'); if (!$link) { die('Connect Error (' . mysqli_connect_errno() . ') ' . mysqli_connect_error()); } echo 'Success... ' . mysqli_get_host_info($link) . '\n'; mysqli_close($link); ?>
The above examples will output:
Success... MariaDB host info: localhost via TCP/IP
Notes
NoteMySQLnd always assumes the server default charset. This charset is sent during connection hand-shake/authentication, which mysqlnd will use.
Libmysql uses the default charset set in the my.cnf
or by an explicit call to mysqli_options
prior to calling mysqli_real_connect
, but after mysqli_init
.Note
OO syntax only: If a connection fails an object is still returned. To check if the connection failed then use either the mysqli_connect_error
function or the mysqli->connect_error property as in the preceding examples.Note
If it is necessary to set options, such as the connection timeout, mysqli_real_connect
must be used instead.Note
Calling the constructor with no parameters is the same as calling mysqli_init
.Note
Error 'Can't create TCP/IP socket (10106)' usually means that the variables_order configure directive doesn't contain character E
. On Windows, if the environment is not copied the SYSTEMROOT
environment variable won't be available and PHP will have problems loading Winsock.
See Also
mysqli_real_connect
|
mysqli_options
|
mysqli_connect_errno
|
mysqli_connect_error
|
mysqli_close |
mysqli::debug
, mysqli_debug
mysqli::debug
mysqli_debug
Performs debugging operations
Description
Object oriented stylebool mysqli::debug(string message);
Procedural stylebool mysqli_debug(string message);
Performs debugging operations using the Fred Fish debugging library.
Parameters
message
-
A string representing the debugging operation to perform
Return Values
Returns TRUE
.
Notes
NoteTo use the mysqli_debug
function you must compile the MariaDB client library to support debugging.
Examples
Example 20.109. Generating a Trace File
<?php /* Create a trace file in '/tmp/client.trace' on the local (client) machine: */ mysqli_debug('d:t:o,/tmp/client.trace'); ?>
See Also
mysqli_dump_debug_info
|
mysqli_report |
mysqli::disable_reads_from_master
, mysqli_disable_reads_from_master
mysqli::disable_reads_from_master
mysqli_disable_reads_from_master
Disable reads from master
Description
Object oriented stylevoid mysqli::disable_reads_from_master();
Procedural stylebool mysqli_disable_reads_from_master(mysqli link);
Warning
This function is currently not documented; only its argument list is available.Warning
This function has been DEPRECATED and REMOVED as of PHP 5.3.0.
mysqli::dump_debug_info
, mysqli_dump_debug_info
mysqli::dump_debug_info
mysqli_dump_debug_info
Dump debugging information into the log
Description
Object oriented stylebool mysqli::dump_debug_info();
Procedural stylebool mysqli_dump_debug_info(mysqli link);
This function is designed to be executed by an user with the SUPER privilege and is used to dump debugging information into the log for the MariaDB Server relating to the connection.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns TRUE
on success or FALSE
on failure.
See Also
mysqli_debug |
mysqli::$errno
, mysqli_errno
mysqli::$errno
mysqli_errno
Returns the error code for the most recent function call
Description
Object oriented styleint mysqli->errno ;
Procedural styleint mysqli_errno(mysqli link);
Returns the last error code for the most recent MySQLi function call that can succeed or fail.
Client error message numbers are listed in the MariaDB errmsg.h
header file, server error message numbers are listed in mysqld_error.h
. In the MariaDB source distribution you can find a complete list of error messages and error numbers in the file Docs/mysqld_error.txt
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
An error code value for the last call, if it failed. zero means no error occurred.
Examples
Example 20.110. $mysqli->errno
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if (!$mysqli->query('SET a=1')) { printf('Errorcode: %d\n', $mysqli->errno); } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if (!mysqli_query($link, 'SET a=1')) { printf('Errorcode: %d\n', mysqli_errno($link)); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Errorcode: 1193
See Also
mysqli_connect_errno
|
mysqli_connect_error
|
mysqli_error
|
mysqli_sqlstate |
mysqli::$error_list
, mysqli_error_list
mysqli::$error_list
mysqli_error_list
Returns a list of errors from the last command executed
Description
Object oriented stylearray mysqli->error_list ;
Procedural stylearray mysqli_error_list(mysqli link);
Returns a array of errors for the most recent MySQLi function call that can succeed or fail.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
A list of errors, each as an associative array containing the errno, error, and sqlstate.
Examples
Example 20.111. $mysqli->error_list
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'nobody', ''); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if (!$mysqli->query('SET a=1')) { print_r($mysqli->error_list); } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if (!mysqli_query($link, 'SET a=1')) { print_r(mysqli_error_list($link)); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Array ( [0] => Array ( [errno] => 1193 [sqlstate] => HY000 [error] => Unknown system variable 'a' ) )
See Also
mysqli_connect_errno
|
mysqli_connect_error
|
mysqli_error
|
mysqli_sqlstate |
mysqli::$error
, mysqli_error
mysqli::$error
mysqli_error
Returns a string description of the last error
Description
Object oriented stylestring mysqli->error ;
Procedural stylestring mysqli_error(mysqli link);
Returns the last error message for the most recent MySQLi function call that can succeed or fail.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
A string that describes the error. An empty string if no error occurred.
Examples
Example 20.112. $mysqli->error
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if (!$mysqli->query('SET a=1')) { printf('Errormessage: %s\n', $mysqli->error); } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if (!mysqli_query($link, 'SET a=1')) { printf('Errormessage: %s\n', mysqli_error($link)); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Errormessage: Unknown system variable 'a'
See Also
mysqli_connect_errno
|
mysqli_connect_error
|
mysqli_errno
|
mysqli_sqlstate |
mysqli::$field_count
, mysqli_field_count
mysqli::$field_count
mysqli_field_count
Returns the number of columns for the most recent query
Description
Object oriented styleint mysqli->field_count ;
Procedural styleint mysqli_field_count(mysqli link);
Returns the number of columns for the most recent query on the connection represented by the link
parameter. This function can be useful when using the mysqli_store_result
function to determine if the query should have produced a non-empty result set or not without knowing the nature of the query.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
An integer representing the number of fields in a result set.
Examples
Example 20.113. $mysqli->field_count
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'test'); $mysqli->query( 'DROP TABLE IF EXISTS friends'); $mysqli->query( 'CREATE TABLE friends (id int, name varchar(20))'); $mysqli->query( 'INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')'); $mysqli->real_query('SELECT * FROM friends'); if ($mysqli->field_count) { /* this was a select/show or describe query */ $result = $mysqli->store_result(); /* process resultset */ $row = $result->fetch_row(); /* free resultset */ $result->close(); } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test'); mysqli_query($link, 'DROP TABLE IF EXISTS friends'); mysqli_query($link, 'CREATE TABLE friends (id int, name varchar(20))'); mysqli_query($link, 'INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')'); mysqli_real_query($link, 'SELECT * FROM friends'); if (mysqli_field_count($link)) { /* this was a select/show or describe query */ $result = mysqli_store_result($link); /* process resultset */ $row = mysqli_fetch_row($result); /* free resultset */ mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
mysqli::get_charset
, mysqli_get_charset
mysqli::get_charset
mysqli_get_charset
Returns a character set object
Description
Object oriented styleobject mysqli::get_charset();
Procedural styleobject mysqli_get_charset(mysqli link);
Returns a character set object providing several properties of the current active character set.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
The function returns a character set object with the following properties:
charset
-
Character set name
collation
-
Collation name
dir
-
Directory the charset description was fetched from (?) or '' for built-in character sets
min_length
-
Minimum character length in bytes
max_length
-
Maximum character length in bytes
number
-
Internal character set number
state
-
Character set status (?)
Examples
Example 20.114. mysqli::get_charset
example
Object oriented style
<?php $db = mysqli_init(); $db->real_connect('localhost','root','','test'); var_dump($db->get_charset()); ?>
Procedural style
<?php $db = mysqli_init(); mysqli_real_connect($db, 'localhost','root','','test'); var_dump($db->get_charset()); ?>
The above examples will output:
object(stdClass)#2 (7) { ['charset']=> string(6) 'latin1' ['collation']=> string(17) 'latin1_swedish_ci' ['dir']=> string(0) '' ['min_length']=> int(1) ['max_length']=> int(1) ['number']=> int(8) ['state']=> int(801) }
See Also
mysqli_character_set_name
|
mysqli_set_charset |
mysqli::get_client_info
, mysqli_get_client_info
mysqli::get_client_info
mysqli_get_client_info
Returns the MariaDB client version as a string
Description
Object oriented stylestring mysqli::get_client_info();
Procedural stylestring mysqli_get_client_info(mysqli link);
Returns a string that represents the MariaDB client library version.
Return Values
A string that represents the MariaDB client library version
Examples
Example 20.115. mysqli_get_client_info
<?php /* We don't need a connection to determine the version of mysql client library */ printf('Client library version: %s\n', mysqli_get_client_info()); ?>
See Also
mysqli_get_client_version
|
mysqli_get_server_info
|
mysqli_get_server_version |
mysqli_get_client_stats
mysqli_get_client_stats
Returns client per-process statistics
Description
array mysqli_get_client_stats();
Returns client per-process statistics. Available only with mysqlnd.
Parameters
Return Values
Returns an array with client stats if success, FALSE
otherwise.
Examples
Example 20.116. A mysqli_get_client_stats
example
<?php $link = mysqli_connect(); print_r(mysqli_get_client_stats()); ?>
The above example will output something similar to:
Array ( [bytes_sent] => 43 [bytes_received] => 80 [packets_sent] => 1 [packets_received] => 2 [protocol_overhead_in] => 8 [protocol_overhead_out] => 4 [bytes_received_ok_packet] => 11 [bytes_received_eof_packet] => 0 [bytes_received_rset_header_packet] => 0 [bytes_received_rset_field_meta_packet] => 0 [bytes_received_rset_row_packet] => 0 [bytes_received_prepare_response_packet] => 0 [bytes_received_change_user_packet] => 0 [packets_sent_command] => 0 [packets_received_ok] => 1 [packets_received_eof] => 0 [packets_received_rset_header] => 0 [packets_received_rset_field_meta] => 0 [packets_received_rset_row] => 0 [packets_received_prepare_response] => 0 [packets_received_change_user] => 0 [result_set_queries] => 0 [non_result_set_queries] => 0 [no_index_used] => 0 [bad_index_used] => 0 [slow_queries] => 0 [buffered_sets] => 0 [unbuffered_sets] => 0 [ps_buffered_sets] => 0 [ps_unbuffered_sets] => 0 [flushed_normal_sets] => 0 [flushed_ps_sets] => 0 [ps_prepared_never_executed] => 0 [ps_prepared_once_executed] => 0 [rows_fetched_from_server_normal] => 0 [rows_fetched_from_server_ps] => 0 [rows_buffered_from_client_normal] => 0 [rows_buffered_from_client_ps] => 0 [rows_fetched_from_client_normal_buffered] => 0 [rows_fetched_from_client_normal_unbuffered] => 0 [rows_fetched_from_client_ps_buffered] => 0 [rows_fetched_from_client_ps_unbuffered] => 0 [rows_fetched_from_client_ps_cursor] => 0 [rows_skipped_normal] => 0 [rows_skipped_ps] => 0 [copy_on_write_saved] => 0 [copy_on_write_performed] => 0 [command_buffer_too_small] => 0 [connect_success] => 1 [connect_failure] => 0 [connection_reused] => 0 [reconnect] => 0 [pconnect_success] => 0 [active_connections] => 1 [active_persistent_connections] => 0 [explicit_close] => 0 [implicit_close] => 0 [disconnect_close] => 0 [in_middle_of_command_close] => 0 [explicit_free_result] => 0 [implicit_free_result] => 0 [explicit_stmt_close] => 0 [implicit_stmt_close] => 0 [mem_emalloc_count] => 0 [mem_emalloc_ammount] => 0 [mem_ecalloc_count] => 0 [mem_ecalloc_ammount] => 0 [mem_erealloc_count] => 0 [mem_erealloc_ammount] => 0 [mem_efree_count] => 0 [mem_malloc_count] => 0 [mem_malloc_ammount] => 0 [mem_calloc_count] => 0 [mem_calloc_ammount] => 0 [mem_realloc_count] => 0 [mem_realloc_ammount] => 0 [mem_free_count] => 0 [proto_text_fetched_null] => 0 [proto_text_fetched_bit] => 0 [proto_text_fetched_tinyint] => 0 [proto_text_fetched_short] => 0 [proto_text_fetched_int24] => 0 [proto_text_fetched_int] => 0 [proto_text_fetched_bigint] => 0 [proto_text_fetched_decimal] => 0 [proto_text_fetched_float] => 0 [proto_text_fetched_double] => 0 [proto_text_fetched_date] => 0 [proto_text_fetched_year] => 0 [proto_text_fetched_time] => 0 [proto_text_fetched_datetime] => 0 [proto_text_fetched_timestamp] => 0 [proto_text_fetched_string] => 0 [proto_text_fetched_blob] => 0 [proto_text_fetched_enum] => 0 [proto_text_fetched_set] => 0 [proto_text_fetched_geometry] => 0 [proto_text_fetched_other] => 0 [proto_binary_fetched_null] => 0 [proto_binary_fetched_bit] => 0 [proto_binary_fetched_tinyint] => 0 [proto_binary_fetched_short] => 0 [proto_binary_fetched_int24] => 0 [proto_binary_fetched_int] => 0 [proto_binary_fetched_bigint] => 0 [proto_binary_fetched_decimal] => 0 [proto_binary_fetched_float] => 0 [proto_binary_fetched_double] => 0 [proto_binary_fetched_date] => 0 [proto_binary_fetched_year] => 0 [proto_binary_fetched_time] => 0 [proto_binary_fetched_datetime] => 0 [proto_binary_fetched_timestamp] => 0 [proto_binary_fetched_string] => 0 [proto_binary_fetched_blob] => 0 [proto_binary_fetched_enum] => 0 [proto_binary_fetched_set] => 0 [proto_binary_fetched_geometry] => 0 [proto_binary_fetched_other] => 0 )
See Also
Stats description |
mysqli::$client_version
, mysqli_get_client_version
mysqli::$client_version
mysqli_get_client_version
Get MariaDB client info
Description
Object oriented styleint mysqli->client_version ;
Procedural styleint mysqli_get_client_version(mysqli link);
Returns client version number as an integer.
Return Values
A number that represents the MariaDB client library version in format: main_version*10000 + minor_version *100 + sub_version
. For example, 4.1.0 is returned as 40100.
This is useful to quickly determine the version of the client library to know if some capability exits.
Examples
Example 20.117. mysqli_get_client_version
<?php /* We don't need a connection to determine the version of mysql client library */ printf('Client library version: %d\n', mysqli_get_client_version()); ?>
See Also
mysqli_get_client_info
|
mysqli_get_server_info
|
mysqli_get_server_version |
mysqli::get_connection_stats
, mysqli_get_connection_stats
mysqli::get_connection_stats
mysqli_get_connection_stats
Returns statistics about the client connection
Description
Object oriented stylebool mysqli::get_connection_stats();
Procedural stylearray mysqli_get_connection_stats(mysqli link);
Returns statistics about the client connection. Available only with mysqlnd.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns an array with connection stats if success, FALSE
otherwise.
Examples
Example 20.118. A mysqli_get_connection_stats
example
<?php $link = mysqli_connect(); print_r(mysqli_get_connection_stats($link)); ?>
The above example will output something similar to:
Array ( [bytes_sent] => 43 [bytes_received] => 80 [packets_sent] => 1 [packets_received] => 2 [protocol_overhead_in] => 8 [protocol_overhead_out] => 4 [bytes_received_ok_packet] => 11 [bytes_received_eof_packet] => 0 [bytes_received_rset_header_packet] => 0 [bytes_received_rset_field_meta_packet] => 0 [bytes_received_rset_row_packet] => 0 [bytes_received_prepare_response_packet] => 0 [bytes_received_change_user_packet] => 0 [packets_sent_command] => 0 [packets_received_ok] => 1 [packets_received_eof] => 0 [packets_received_rset_header] => 0 [packets_received_rset_field_meta] => 0 [packets_received_rset_row] => 0 [packets_received_prepare_response] => 0 [packets_received_change_user] => 0 [result_set_queries] => 0 [non_result_set_queries] => 0 [no_index_used] => 0 [bad_index_used] => 0 [slow_queries] => 0 [buffered_sets] => 0 [unbuffered_sets] => 0 [ps_buffered_sets] => 0 [ps_unbuffered_sets] => 0 [flushed_normal_sets] => 0 [flushed_ps_sets] => 0 [ps_prepared_never_executed] => 0 [ps_prepared_once_executed] => 0 [rows_fetched_from_server_normal] => 0 [rows_fetched_from_server_ps] => 0 [rows_buffered_from_client_normal] => 0 [rows_buffered_from_client_ps] => 0 [rows_fetched_from_client_normal_buffered] => 0 [rows_fetched_from_client_normal_unbuffered] => 0 [rows_fetched_from_client_ps_buffered] => 0 [rows_fetched_from_client_ps_unbuffered] => 0 [rows_fetched_from_client_ps_cursor] => 0 [rows_skipped_normal] => 0 [rows_skipped_ps] => 0 [copy_on_write_saved] => 0 [copy_on_write_performed] => 0 [command_buffer_too_small] => 0 [connect_success] => 1 [connect_failure] => 0 [connection_reused] => 0 [reconnect] => 0 [pconnect_success] => 0 [active_connections] => 1 [active_persistent_connections] => 0 [explicit_close] => 0 [implicit_close] => 0 [disconnect_close] => 0 [in_middle_of_command_close] => 0 [explicit_free_result] => 0 [implicit_free_result] => 0 [explicit_stmt_close] => 0 [implicit_stmt_close] => 0 [mem_emalloc_count] => 0 [mem_emalloc_ammount] => 0 [mem_ecalloc_count] => 0 [mem_ecalloc_ammount] => 0 [mem_erealloc_count] => 0 [mem_erealloc_ammount] => 0 [mem_efree_count] => 0 [mem_malloc_count] => 0 [mem_malloc_ammount] => 0 [mem_calloc_count] => 0 [mem_calloc_ammount] => 0 [mem_realloc_count] => 0 [mem_realloc_ammount] => 0 [mem_free_count] => 0 [proto_text_fetched_null] => 0 [proto_text_fetched_bit] => 0 [proto_text_fetched_tinyint] => 0 [proto_text_fetched_short] => 0 [proto_text_fetched_int24] => 0 [proto_text_fetched_int] => 0 [proto_text_fetched_bigint] => 0 [proto_text_fetched_decimal] => 0 [proto_text_fetched_float] => 0 [proto_text_fetched_double] => 0 [proto_text_fetched_date] => 0 [proto_text_fetched_year] => 0 [proto_text_fetched_time] => 0 [proto_text_fetched_datetime] => 0 [proto_text_fetched_timestamp] => 0 [proto_text_fetched_string] => 0 [proto_text_fetched_blob] => 0 [proto_text_fetched_enum] => 0 [proto_text_fetched_set] => 0 [proto_text_fetched_geometry] => 0 [proto_text_fetched_other] => 0 [proto_binary_fetched_null] => 0 [proto_binary_fetched_bit] => 0 [proto_binary_fetched_tinyint] => 0 [proto_binary_fetched_short] => 0 [proto_binary_fetched_int24] => 0 [proto_binary_fetched_int] => 0 [proto_binary_fetched_bigint] => 0 [proto_binary_fetched_decimal] => 0 [proto_binary_fetched_float] => 0 [proto_binary_fetched_double] => 0 [proto_binary_fetched_date] => 0 [proto_binary_fetched_year] => 0 [proto_binary_fetched_time] => 0 [proto_binary_fetched_datetime] => 0 [proto_binary_fetched_timestamp] => 0 [proto_binary_fetched_string] => 0 [proto_binary_fetched_blob] => 0 [proto_binary_fetched_enum] => 0 [proto_binary_fetched_set] => 0 [proto_binary_fetched_geometry] => 0 [proto_binary_fetched_other] => 0 )
See Also
Stats description |
mysqli::$host_info
, mysqli_get_host_info
mysqli::$host_info
mysqli_get_host_info
Returns a string representing the type of connection used
Description
Object oriented stylestring mysqli->host_info ;
Procedural stylestring mysqli_get_host_info(mysqli link);
Returns a string describing the connection represented by the link
parameter (including the server host name).
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
A character string representing the server hostname and the connection type.
Examples
Example 20.119. $mysqli->host_info
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* print host information */ printf('Host info: %s\n', $mysqli->host_info); /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* print host information */ printf('Host info: %s\n', mysqli_get_host_info($link)); /* close connection */ mysqli_close($link); ?>
The above examples will output:
Host info: Localhost via UNIX socket
See Also
mysqli_get_proto_info |
mysqli::$protocol_version
, mysqli_get_proto_info
mysqli::$protocol_version
mysqli_get_proto_info
Returns the version of the MariaDB protocol used
Description
Object oriented stylestring mysqli->protocol_version ;
Procedural styleint mysqli_get_proto_info(mysqli link);
Returns an integer representing the MariaDB protocol version used by the connection represented by the link
parameter.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns an integer representing the protocol version.
Examples
Example 20.120. $mysqli->protocol_version
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* print protocol version */ printf('Protocol version: %d\n', $mysqli->protocol_version); /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* print protocol version */ printf('Protocol version: %d\n', mysqli_get_proto_info($link)); /* close connection */ mysqli_close($link); ?>
The above examples will output:
Protocol version: 10
See Also
mysqli_get_host_info |
mysqli::$server_info
, mysqli_get_server_info
mysqli::$server_info
mysqli_get_server_info
Returns the version of the MariaDB server
Description
Object oriented stylestring mysqli->server_info ;
Procedural stylestring mysqli_get_server_info(mysqli link);
Returns a string representing the version of the MariaDB server that the MySQLi extension is connected to.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
A character string representing the server version.
Examples
Example 20.121. $mysqli->server_info
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* print server version */ printf('Server version: %s\n', $mysqli->server_info); /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* print server version */ printf('Server version: %s\n', mysqli_get_server_info($link)); /* close connection */ mysqli_close($link); ?>
The above examples will output:
Server version: 4.1.2-alpha-debug
See Also
mysqli_get_client_info
|
mysqli_get_client_version
|
mysqli_get_server_version |
mysqli::$server_version
, mysqli_get_server_version
mysqli::$server_version
mysqli_get_server_version
Returns the version of the MariaDB server as an integer
Description
Object oriented styleint mysqli->server_version ;
Procedural styleint mysqli_get_server_version(mysqli link);
The mysqli_get_server_version
function returns the version of the server connected to (represented by the link
parameter) as an integer.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
An integer representing the server version.
The form of this version number is main_version * 10000 + minor_version * 100 + sub_version
(i.e. version 4.1.0 is 40100).
Examples
Example 20.122. $mysqli->server_version
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* print server version */ printf('Server version: %d\n', $mysqli->server_version); /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* print server version */ printf('Server version: %d\n', mysqli_get_server_version($link)); /* close connection */ mysqli_close($link); ?>
The above examples will output:
Server version: 40102
See Also
mysqli_get_client_info
|
mysqli_get_client_version
|
mysqli_get_server_info |
mysqli::get_warnings
, mysqli_get_warnings
mysqli::get_warnings
mysqli_get_warnings
Get result of SHOW WARNINGS
Description
Object oriented stylemysqli_warning mysqli::get_warnings();
Procedural stylemysqli_warning mysqli_get_warnings(mysqli link);
Warning
This function is currently not documented; only its argument list is available.
mysqli::$info
, mysqli_info
mysqli::$info
mysqli_info
Retrieves information about the most recently executed query
Description
Object oriented stylestring mysqli->info ;
Procedural stylestring mysqli_info(mysqli link);
The mysqli_info
function returns a string providing information about the last query executed. The nature of this string is provided below:
Table 20.14. Possible mysqli_info return values
Query type | Example result string |
---|---|
INSERT INTO...SELECT... | Records: 100 Duplicates: 0 Warnings: 0 |
INSERT INTO...VALUES (...),(...),(...) | Records: 3 Duplicates: 0 Warnings: 0 |
LOAD DATA INFILE ... | Records: 1 Deleted: 0 Skipped: 0 Warnings: 0 |
ALTER TABLE ... | Records: 3 Duplicates: 0 Warnings: 0 |
UPDATE ... | Rows matched: 40 Changed: 40 Warnings: 0 |
Queries which do not fall into one of the preceding formats are not supported. In these situations, mysqli_info
will return an empty string.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
A character string representing additional information about the most recently executed query.
Examples
Example 20.123. $mysqli->info
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $mysqli->query('CREATE TEMPORARY TABLE t1 LIKE City'); /* INSERT INTO .. SELECT */ $mysqli->query('INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150'); printf('%s\n', $mysqli->info); /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } mysqli_query($link, 'CREATE TEMPORARY TABLE t1 LIKE City'); /* INSERT INTO .. SELECT */ mysqli_query($link, 'INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150'); printf('%s\n', mysqli_info($link)); /* close connection */ mysqli_close($link); ?>
The above examples will output:
Records: 150 Duplicates: 0 Warnings: 0
See Also
mysqli_affected_rows
|
mysqli_warning_count
|
mysqli_num_rows |
mysqli::init
, mysqli_init
mysqli::init
mysqli_init
Initializes MySQLi and returns a resource for use with mysqli_real_connect()
Description
Object oriented stylemysqli mysqli::init();
Procedural stylemysqli mysqli_init();
Allocates or initializes a MYSQL object suitable for mysqli_options
and mysqli_real_connect
.Note
Any subsequent calls to any mysqli function (except mysqli_options
) will fail until mysqli_real_connect
was called.
Return Values
Returns an object.
Examples
See mysqli_real_connect
.
See Also
mysqli_options
|
mysqli_close
|
mysqli_real_connect
|
mysqli_connect |
mysqli::$insert_id
, mysqli_insert_id
mysqli::$insert_id
mysqli_insert_id
Returns the auto generated id used in the last query
Description
Object oriented stylemixed mysqli->insert_id ;
Procedural stylemixed mysqli_insert_id(mysqli link);
The mysqli_insert_id
function returns the ID generated by a query on a table with a column having the AUTO_INCREMENT attribute. If the last query wasn't an INSERT or UPDATE statement or if the modified table does not have a column with the AUTO_INCREMENT attribute, this function will return zero.Note
Performing an INSERT or UPDATE statement using the LAST_INSERT_ID() function will also modify the value returned by the mysqli_insert_id
function.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
The value of the AUTO_INCREMENT
field that was updated by the previous query. Returns zero if there was no previous query on the connection or if the query did not update an AUTO_INCREMENT
value.Note
If the number is greater than maximal int value, mysqli_insert_id
will return a string.
Examples
Example 20.124. $mysqli->insert_id
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $mysqli->query('CREATE TABLE myCity LIKE City'); $query = 'INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)'; $mysqli->query($query); printf ('New Record has id %d.\n', $mysqli->insert_id); /* drop table */ $mysqli->query('DROP TABLE myCity'); /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } mysqli_query($link, 'CREATE TABLE myCity LIKE City'); $query = 'INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)'; mysqli_query($link, $query); printf ('New Record has id %d.\n', mysqli_insert_id($link)); /* drop table */ mysqli_query($link, 'DROP TABLE myCity'); /* close connection */ mysqli_close($link); ?>
The above examples will output:
New Record has id 1.
mysqli::kill
, mysqli_kill
mysqli::kill
mysqli_kill
Asks the server to kill a MariaDB thread
Description
Object oriented stylebool mysqli::kill(int processid);
Procedural stylebool mysqli_kill(mysqli link,
int processid);
This function is used to ask the server to kill a MariaDB thread specified by the processid
parameter. This value must be retrieved by calling the mysqli_thread_id
function.
To stop a running query you should use the SQL command KILL QUERY processid
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.125. mysqli::kill
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* determine our thread id */ $thread_id = $mysqli->thread_id; /* Kill connection */ $mysqli->kill($thread_id); /* This should produce an error */ if (!$mysqli->query('CREATE TABLE myCity LIKE City')) { printf('Error: %s\n', $mysqli->error); exit; } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* determine our thread id */ $thread_id = mysqli_thread_id($link); /* Kill connection */ mysqli_kill($link, $thread_id); /* This should produce an error */ if (!mysqli_query($link, 'CREATE TABLE myCity LIKE City')) { printf('Error: %s\n', mysqli_error($link)); exit; } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Error: MariaDB server has gone away
See Also
mysqli_thread_id |
mysqli::more_results
, mysqli_more_results
mysqli::more_results
mysqli_more_results
Check if there are any more query results from a multi query
Description
Object oriented stylebool mysqli::more_results();
Procedural stylebool mysqli_more_results(mysqli link);
Indicates if one or more result sets are available from a previous call to mysqli_multi_query
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
See mysqli_multi_query
.
See Also
mysqli_multi_query
|
mysqli_next_result
|
mysqli_store_result
|
mysqli_use_result |
mysqli::multi_query
, mysqli_multi_query
mysqli::multi_query
mysqli_multi_query
Performs a query on the database
Description
Object oriented stylebool mysqli::multi_query(string query);
Procedural stylebool mysqli_multi_query(mysqli link,
string query);
Executes one or multiple queries which are concatenated by a semicolon.
To retrieve the resultset from the first query you can use mysqli_use_result
or mysqli_store_result
. All subsequent query results can be processed using mysqli_more_results
and mysqli_next_result
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
query
-
The query, as a string.
Data inside the query should be properly escaped.
Return Values
Returns FALSE
if the first statement failed. To retrieve subsequent errors from other statements you have to call mysqli_next_result
first.
Examples
Example 20.126. mysqli::multi_query
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT CURRENT_USER();'; $query .= 'SELECT Name FROM City ORDER BY ID LIMIT 20, 5'; /* execute multi query */ if ($mysqli->multi_query($query)) { do { /* store first result set */ if ($result = $mysqli->store_result()) { while ($row = $result->fetch_row()) { printf('%s\n', $row[0]); } $result->free(); } /* print divider */ if ($mysqli->more_results()) { printf('-----------------\n'); } } while ($mysqli->next_result()); } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT CURRENT_USER();'; $query .= 'SELECT Name FROM City ORDER BY ID LIMIT 20, 5'; /* execute multi query */ if (mysqli_multi_query($link, $query)) { do { /* store first result set */ if ($result = mysqli_store_result($link)) { while ($row = mysqli_fetch_row($result)) { printf('%s\n', $row[0]); } mysqli_free_result($result); } /* print divider */ if (mysqli_more_results($link)) { printf('-----------------\n'); } } while (mysqli_next_result($link)); } /* close connection */ mysqli_close($link); ?>
The above examples will output something similar to:
my_user@localhost ----------------- Amersfoort Maastricht Dordrecht Leiden Haarlemmermeer
See Also
mysqli_use_result
|
mysqli_store_result
|
mysqli_next_result
|
mysqli_more_results |
mysqli::next_result
, mysqli_next_result
mysqli::next_result
mysqli_next_result
Prepare next result from multi_query
Description
Object oriented stylebool mysqli::next_result();
Procedural stylebool mysqli_next_result(mysqli link);
Prepares next result set from a previous call to mysqli_multi_query
which can be retrieved by mysqli_store_result
or mysqli_use_result
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
See mysqli_multi_query
.
See Also
mysqli_multi_query
|
mysqli_more_results
|
mysqli_store_result
|
mysqli_use_result |
mysqli::options
, mysqli_options
mysqli::options
mysqli_options
Set options
Description
Object oriented stylebool mysqli::options(int option,
mixed value);
Procedural stylebool mysqli_options(mysqli link,
int option,
mixed value);
Used to set extra connect options and affect behavior for a connection.
This function may be called multiple times to set several options.
mysqli-options
should be called after mysqli_init
and before mysqli_real_connect
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
option
-
The option that you want to set. It can be one of the following values:
Table 20.15. Valid options
Name Description MYSQLI_OPT_CONNECT_TIMEOUT
connection timeout in seconds (supported on Windows with TCP/IP since PHP 5.3.1) MYSQLI_OPT_LOCAL_INFILE
enable/disable use of LOAD LOCAL INFILE
MYSQLI_INIT_COMMAND
command to execute after when connecting to MariaDB server MYSQLI_READ_DEFAULT_FILE
Read options from named option file instead of my.cnf
MYSQLI_READ_DEFAULT_GROUP
Read options from the named group from my.cnf
or the file specified withMYSQL_READ_DEFAULT_FILE
. value
-
The value for the option.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
See mysqli_real_connect
.
Notes
NoteMySQLnd always assumes the server default charset. This charset is sent during connection hand-shake/authentication, which mysqlnd will use.
Libmysql uses the default charset set in the my.cnf
or by an explicit call to mysqli_options
prior to calling mysqli_real_connect
, but after mysqli_init
.
See Also
mysqli_init
|
mysqli_real_connect |
mysqli::ping
, mysqli_ping
mysqli::ping
mysqli_ping
Pings a server connection, or tries to reconnect if the connection has gone down
Description
Object oriented stylebool mysqli::ping();
Procedural stylebool mysqli_ping(mysqli link);
Checks whether the connection to the server is working. If it has gone down, and global option mysqli.reconnect is enabled an automatic reconnection is attempted.
This function can be used by clients that remain idle for a long while, to check whether the server has closed the connection and reconnect if necessary.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.127. mysqli::ping
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* check if server is alive */ if ($mysqli->ping()) { printf ('Our connection is ok!\n'); } else { printf ('Error: %s\n', $mysqli->error); } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* check if server is alive */ if (mysqli_ping($link)) { printf ('Our connection is ok!\n'); } else { printf ('Error: %s\n', mysqli_error($link)); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Our connection is ok!
mysqli::poll
, mysqli_poll
mysqli::poll
mysqli_poll
Poll connections
Description
Object oriented stylepublic int mysqli::poll(array read,
array error,
array reject,
int sec,
int usec);
Procedural styleint mysqli_poll(array read,
Warning
array error,
array reject,
int sec,
int usec);
This function is currently not documented; only its argument list is available.
Poll connections. Available only with mysqlnd.
Parameters
read
error
reject
sec
-
Number of seconds to wait, must be non-negative.
usec
-
Number of microseconds to wait, must be non-negative.
Return Values
Returns number of ready connections in success, FALSE
otherwise.
Examples
Example 20.128. A mysqli_poll
example
<?php $link1 = mysqli_connect(); $link1->query('SELECT 'test'', MYSQLI_ASYNC); $all_links = array($link1); $processed = 0; do { $links = $errors = $reject = array(); foreach ($all_links as $link) { $links[] = $errors[] = $reject[] = $link; } if (!mysqli_poll($links, $errors, $reject, 1)) { continue; } foreach ($links as $link) { if ($result = $link->reap_async_query()) { print_r($result->fetch_row()); mysqli_free_result($result); $processed++; } } } while ($processed < count($all_links)); ?>
The above example will output:
Array ( [0] => test )
See Also
mysqli_query
|
mysqli_reap_async_query |
mysqli::prepare
, mysqli_prepare
mysqli::prepare
mysqli_prepare
Prepare an SQL statement for execution
Description
Object oriented stylemysqli_stmt mysqli::prepare(string query);
Procedural stylemysqli_stmt mysqli_prepare(mysqli link,
string query);
Prepares the SQL query, and returns a statement handle to be used for further operations on the statement. The query must consist of a single SQL statement.
The parameter markers must be bound to application variables using mysqli_stmt_bind_param
and/or mysqli_stmt_bind_result
before executing the statement or fetching rows.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
query
-
The query, as a string.Note
You should not add a terminating semicolon or
\g
to the statement.This parameter can include one or more parameter markers in the SQL statement by embedding question mark (
?
) characters at the appropriate positions.NoteThe markers are legal only in certain places in SQL statements. For example, they are allowed in the
VALUES()
list of anINSERT
statement (to specify column values for a row), or in a comparison with a column in aWHERE
clause to specify a comparison value.However, they are not allowed for identifiers (such as table or column names), in the select list that names the columns to be returned by a
SELECT
statement, or to specify both operands of a binary operator such as the=
equal sign. The latter restriction is necessary because it would be impossible to determine the parameter type. It's not allowed to compare marker withNULL
by? IS NULL
too. In general, parameters are legal only in Data Manipulation Language (DML) statements, and not in Data Definition Language (DDL) statements.
Return Values
mysqli_prepare
returns a statement object or FALSE
if an error occurred.
Examples
Example 20.129. mysqli::prepare
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $city = 'Amersfoort'; /* create a prepared statement */ if ($stmt = $mysqli->prepare('SELECT District FROM City WHERE Name=?')) { /* bind parameters for markers */ $stmt->bind_param('s', $city); /* execute query */ $stmt->execute(); /* bind result variables */ $stmt->bind_result($district); /* fetch value */ $stmt->fetch(); printf('%s is in district %s\n', $city, $district); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $city = 'Amersfoort'; /* create a prepared statement */ if ($stmt = mysqli_prepare($link, 'SELECT District FROM City WHERE Name=?')) { /* bind parameters for markers */ mysqli_stmt_bind_param($stmt, 's', $city); /* execute query */ mysqli_stmt_execute($stmt); /* bind result variables */ mysqli_stmt_bind_result($stmt, $district); /* fetch value */ mysqli_stmt_fetch($stmt); printf('%s is in district %s\n', $city, $district); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Amersfoort is in district Utrecht
See Also
mysqli_stmt_execute
|
mysqli_stmt_fetch
|
mysqli_stmt_bind_param
|
mysqli_stmt_bind_result
|
mysqli_stmt_close |
mysqli::query
, mysqli_query
mysqli::query
mysqli_query
Performs a query on the database
Description
Object oriented stylemixed mysqli::query(string query,
int resultmode= =MYSQLI_STORE_RESULT);
Procedural stylemixed mysqli_query(mysqli link,
string query,
int resultmode= =MYSQLI_STORE_RESULT);
Performs a query
against the database.
Functionally, using this function is identical to calling mysqli_real_query
followed either by mysqli_use_result
or mysqli_store_result
.Note
In the case where you pass a statement to mysqli_query
that is longer than max_allowed_packet
of the server, the returned error codes are different depending on whether you are using MariaDB Native Driver (mysqlnd
) or MariaDB Client Library (libmysql
). The behavior is as follows:
mysqlnd
on Linux returns an error code of 1153. The error message means "got a packet bigger thanmax_allowed_packet
bytes".mysqlnd
on Windows returns an error code 2006. This error message means "server has gone away".libmysql
on all platforms returns an error code 2006. This error message means "server has gone away".
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
query
-
The query string.
Data inside the query should be properly escaped.
resultmode
-
Either the constant
MYSQLI_USE_RESULT
orMYSQLI_STORE_RESULT
depending on the desired behavior. By default,MYSQLI_STORE_RESULT
is used.If you use
MYSQLI_USE_RESULT
all subsequent calls will return errorCommands out of sync
unless you callmysqli_free_result
With
MYSQLI_ASYNC
(available with mysqlnd), it is possible to perform query asynchronously.mysqli_poll
is then used to get results from such queries.
Return Values
Returns FALSE
on failure. For successful SELECT, SHOW, DESCRIBE
or EXPLAIN
queries mysqli_query
will return a mysqli_result
object. For other successful queries mysqli_query
will return TRUE
.
Changelog
Version | Description |
---|---|
5.3.0 | Added the ability of async queries. |
Examples
Example 20.130. mysqli::query
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if ($mysqli->connect_errno) { printf('Connect failed: %s\n', $mysqli->connect_error); exit(); } /* Create table doesn't return a resultset */ if ($mysqli->query('CREATE TEMPORARY TABLE myCity LIKE City') === TRUE) { printf('Table myCity successfully created.\n'); } /* Select queries return a resultset */ if ($result = $mysqli->query('SELECT Name FROM City LIMIT 10')) { printf('Select returned %d rows.\n', $result->num_rows); /* free result set */ $result->close(); } /* If we have to retrieve large amount of data we use MYSQLI_USE_RESULT */ if ($result = $mysqli->query('SELECT * FROM City', MYSQLI_USE_RESULT)) { /* Note, that we can't execute any functions which interact with the server until result set was closed. All calls will return an 'out of sync' error */ if (!$mysqli->query('SET @a:='this will not work'')) { printf('Error: %s\n', $mysqli->error); } $result->close(); } $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* Create table doesn't return a resultset */ if (mysqli_query($link, 'CREATE TEMPORARY TABLE myCity LIKE City') === TRUE) { printf('Table myCity successfully created.\n'); } /* Select queries return a resultset */ if ($result = mysqli_query($link, 'SELECT Name FROM City LIMIT 10')) { printf('Select returned %d rows.\n', mysqli_num_rows($result)); /* free result set */ mysqli_free_result($result); } /* If we have to retrieve large amount of data we use MYSQLI_USE_RESULT */ if ($result = mysqli_query($link, 'SELECT * FROM City', MYSQLI_USE_RESULT)) { /* Note, that we can't execute any functions which interact with the server until result set was closed. All calls will return an 'out of sync' error */ if (!mysqli_query($link, 'SET @a:='this will not work'')) { printf('Error: %s\n', mysqli_error($link)); } mysqli_free_result($result); } mysqli_close($link); ?>
The above examples will output:
Table myCity successfully created. Select returned 10 rows. Error: Commands out of sync; You can't run this command now
See Also
mysqli_real_query
|
mysqli_multi_query
|
mysqli_free_result |
mysqli::real_connect
, mysqli_real_connect
mysqli::real_connect
mysqli_real_connect
Opens a connection to a mysql server
Description
Object oriented stylebool mysqli::real_connect(string host,
string username,
string passwd,
string dbname,
int port,
string socket,
int flags);
Procedural stylebool mysqli_real_connect(mysqli link,
string host,
string username,
string passwd,
string dbname,
int port,
string socket,
int flags);
Establish a connection to a MariaDB database engine.
This function differs from mysqli_connect
:
mysqli_real_connect
needs a valid object which has to be created by functionmysqli_init
.- With the
mysqli_options
function you can set various options for connection. - There is a
flags
parameter.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
host
-
Can be either a host name or an IP address. Passing the
NULL
value or the string 'localhost' to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol. username
-
The MariaDB user name.
passwd
-
If provided or
NULL
, the MariaDB server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password as provided or not). dbname
-
If provided will specify the default database to be used when performing queries.
port
-
Specifies the port number to attempt to connect to the MariaDB server.
socket
-
Specifies the socket or named pipe that should be used.Note
Specifying the
socket
parameter will not explicitly determine the type of connection to be used when connecting to the MariaDB server. How the connection is made to the MariaDB database is determined by thehost
parameter. flags
-
With the parameter
flags
you can set different connection options:Table 20.16. Supported flags
Name Description MYSQLI_CLIENT_COMPRESS
Use compression protocol MYSQLI_CLIENT_FOUND_ROWS
return number of matched rows, not the number of affected rows MYSQLI_CLIENT_IGNORE_SPACE
Allow spaces after function names. Makes all function names reserved words. MYSQLI_CLIENT_INTERACTIVE
Allow interactive_timeout
seconds (instead ofwait_timeout
seconds) of inactivity before closing the connectionMYSQLI_CLIENT_SSL
Use SSL (encryption) For security reasons the
MULTI_STATEMENT
flag is not supported in PHP. If you want to execute multiple queries use themysqli_multi_query
function.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.131. mysqli::real_connect
example
Object oriented style
<?php $mysqli = mysqli_init(); if (!$mysqli) { die('mysqli_init failed'); } if (!$mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) { die('Setting MYSQLI_INIT_COMMAND failed'); } if (!$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5)) { die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed'); } if (!$mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db')) { die('Connect Error (' . mysqli_connect_errno() . ') ' . mysqli_connect_error()); } echo 'Success... ' . $mysqli->host_info . '\n'; $mysqli->close(); ?>
Object oriented style when extending mysqli class
<?php class foo_mysqli extends mysqli { public function __construct($host, $user, $pass, $db) { parent::init(); if (!parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) { die('Setting MYSQLI_INIT_COMMAND failed'); } if (!parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5)) { die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed'); } if (!parent::real_connect($host, $user, $pass, $db)) { die('Connect Error (' . mysqli_connect_errno() . ') ' . mysqli_connect_error()); } } } $db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db'); echo 'Success... ' . $db->host_info . '\n'; $db->close(); ?>
Procedural style
<?php $link = mysqli_init(); if (!$link) { die('mysqli_init failed'); } if (!mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) { die('Setting MYSQLI_INIT_COMMAND failed'); } if (!mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5)) { die('Setting MYSQLI_OPT_CONNECT_TIMEOUT failed'); } if (!mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db')) { die('Connect Error (' . mysqli_connect_errno() . ') ' . mysqli_connect_error()); } echo 'Success... ' . mysqli_get_host_info($link) . '\n'; mysqli_close($link); ?>
The above examples will output:
Success... MariaDB host info: localhost via TCP/IP
Notes
NoteMySQLnd always assumes the server default charset. This charset is sent during connection hand-shake/authentication, which mysqlnd will use.
Libmysql uses the default charset set in the my.cnf
or by an explicit call to mysqli_options
prior to calling mysqli_real_connect
, but after mysqli_init
.
See Also
mysqli_connect
|
mysqli_init
|
mysqli_options
|
mysqli_ssl_set
|
mysqli_close |
mysqli::real_escape_string
, mysqli_real_escape_string
mysqli::real_escape_string
mysqli_real_escape_string
Escapes special characters in a string for use in an SQL statement, taking into account the current charset of the connection
Description
Object oriented stylestring mysqli::escape_string(string escapestr);
string mysqli::real_escape_string(string escapestr);
Procedural stylestring mysqli_real_escape_string(mysqli link,
string escapestr);
This function is used to create a legal SQL string that you can use in an SQL statement. The given string is encoded to an escaped SQL string, taking into account the current character set of the connection.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
escapestr
-
The string to be escaped.
Characters encoded are
NUL (ASCII 0), \n, \r, \, ', ', and Control-Z
.
Return Values
Returns an escaped string.
Examples
Example 20.132. mysqli::real_escape_string
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $mysqli->query('CREATE TEMPORARY TABLE myCity LIKE City'); $city = ''s Hertogenbosch'; /* this query will fail, cause we didn't escape $city */ if (!$mysqli->query('INSERT into myCity (Name) VALUES ('$city')')) { printf('Error: %s\n', $mysqli->sqlstate); } $city = $mysqli->real_escape_string($city); /* this query with escaped $city will work */ if ($mysqli->query('INSERT into myCity (Name) VALUES ('$city')')) { printf('%d Row inserted.\n', $mysqli->affected_rows); } $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } mysqli_query($link, 'CREATE TEMPORARY TABLE myCity LIKE City'); $city = ''s Hertogenbosch'; /* this query will fail, cause we didn't escape $city */ if (!mysqli_query($link, 'INSERT into myCity (Name) VALUES ('$city')')) { printf('Error: %s\n', mysqli_sqlstate($link)); } $city = mysqli_real_escape_string($link, $city); /* this query with escaped $city will work */ if (mysqli_query($link, 'INSERT into myCity (Name) VALUES ('$city')')) { printf('%d Row inserted.\n', mysqli_affected_rows($link)); } mysqli_close($link); ?>
The above examples will output:
Error: 42000 1 Row inserted.
Notes
NoteFor those accustomed to using mysql_real_escape_string
, note that the arguments of mysqli_real_escape_string
differ from what mysql_real_escape_string
expects. The link
identifier comes first in mysqli_real_escape_string
, whereas the string to be escaped comes first in mysql_real_escape_string
.
See Also
mysqli_character_set_name |
mysqli::real_query
, mysqli_real_query
mysqli::real_query
mysqli_real_query
Execute an SQL query
Description
Object oriented stylebool mysqli::real_query(string query);
Procedural stylebool mysqli_real_query(mysqli link,
string query);
Executes a single query against the database whose result can then be retrieved or stored using the mysqli_store_result
or mysqli_use_result
functions.
In order to determine if a given query should return a result set or not, see mysqli_field_count
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
query
-
The query, as a string.
Data inside the query should be properly escaped.
Return Values
Returns TRUE
on success or FALSE
on failure.
See Also
mysqli_query
|
mysqli_store_result
|
mysqli_use_result |
mysqli::reap_async_query
, mysqli_reap_async_query
mysqli::reap_async_query
mysqli_reap_async_query
Get result from async query
Description
Object oriented stylepublic mysqli_result mysqli::reap_async_query();
Procedural stylemysqli_result mysqli_reap_async_query(mysql link);
Warning
This function is currently not documented; only its argument list is available.
Get result from async query. Available only with mysqlnd.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns mysqli_result
in success, FALSE
otherwise.
See Also
mysqli_poll |
mysqli::refresh
, mysqli_refresh
mysqli::refresh
mysqli_refresh
Refreshes
Description
Object oriented stylepublic bool mysqli::refresh(int options);
Procedural styleint mysqli_refresh(resource link,
int options);
Flushes tables or caches, or resets the replication server information.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
options
-
The options to refresh, using the MYSQLI_REFRESH_* constants as documented within the MySQLi constants documentation.
See also the official MySQL Refresh documentation.
Return Values
TRUE
if the refresh was a success, otherwise FALSE
See Also
mysqli_poll |
mysqli::rollback
, mysqli_rollback
mysqli::rollback
mysqli_rollback
Rolls back current transaction
Description
Object oriented stylebool mysqli::rollback();
Procedural stylebool mysqli_rollback(mysqli link);
Rollbacks the current transaction for the database.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.133. mysqli::rollback
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* disable autocommit */ $mysqli->autocommit(FALSE); $mysqli->query('CREATE TABLE myCity LIKE City'); $mysqli->query('ALTER TABLE myCity Type=InnoDB'); $mysqli->query('INSERT INTO myCity SELECT * FROM City LIMIT 50'); /* commit insert */ $mysqli->commit(); /* delete all rows */ $mysqli->query('DELETE FROM myCity'); if ($result = $mysqli->query('SELECT COUNT(*) FROM myCity')) { $row = $result->fetch_row(); printf('%d rows in table myCity.\n', $row[0]); /* Free result */ $result->close(); } /* Rollback */ $mysqli->rollback(); if ($result = $mysqli->query('SELECT COUNT(*) FROM myCity')) { $row = $result->fetch_row(); printf('%d rows in table myCity (after rollback).\n', $row[0]); /* Free result */ $result->close(); } /* Drop table myCity */ $mysqli->query('DROP TABLE myCity'); $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* disable autocommit */ mysqli_autocommit($link, FALSE); mysqli_query($link, 'CREATE TABLE myCity LIKE City'); mysqli_query($link, 'ALTER TABLE myCity Type=InnoDB'); mysqli_query($link, 'INSERT INTO myCity SELECT * FROM City LIMIT 50'); /* commit insert */ mysqli_commit($link); /* delete all rows */ mysqli_query($link, 'DELETE FROM myCity'); if ($result = mysqli_query($link, 'SELECT COUNT(*) FROM myCity')) { $row = mysqli_fetch_row($result); printf('%d rows in table myCity.\n', $row[0]); /* Free result */ mysqli_free_result($result); } /* Rollback */ mysqli_rollback($link); if ($result = mysqli_query($link, 'SELECT COUNT(*) FROM myCity')) { $row = mysqli_fetch_row($result); printf('%d rows in table myCity (after rollback).\n', $row[0]); /* Free result */ mysqli_free_result($result); } /* Drop table myCity */ mysqli_query($link, 'DROP TABLE myCity'); mysqli_close($link); ?>
The above examples will output:
0 rows in table myCity. 50 rows in table myCity (after rollback).
See Also
mysqli_commit
|
mysqli_autocommit |
mysqli::rpl_query_type
, mysqli_rpl_query_type
mysqli::rpl_query_type
mysqli_rpl_query_type
Returns RPL query type
Description
Object oriented styleint mysqli::rpl_query_type(string query);
Procedural styleint mysqli_rpl_query_type(mysqli link,
string query);
Returns MYSQLI_RPL_MASTER
, MYSQLI_RPL_SLAVE
or MYSQLI_RPL_ADMIN
depending on a query type. INSERT
, UPDATE
and similar are master queries, SELECT
is slave, and FLUSH
, REPAIR
and similar are admin.Warning
This function is currently not documented; only its argument list is available.Warning
This function has been DEPRECATED and REMOVED as of PHP 5.3.0.
mysqli::select_db
, mysqli_select_db
mysqli::select_db
mysqli_select_db
Selects the default database for database queries
Description
Object oriented stylebool mysqli::select_db(string dbname);
Procedural stylebool mysqli_select_db(mysqli link,
string dbname);
Selects the default database to be used when performing queries against the database connection.Note
This function should only be used to change the default database for the connection. You can select the default database with 4th parameter in mysqli_connect
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
dbname
-
The database name.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.134. mysqli::select_db
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'test'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* return name of current default database */ if ($result = $mysqli->query('SELECT DATABASE()')) { $row = $result->fetch_row(); printf('Default database is %s.\n', $row[0]); $result->close(); } /* change db to world db */ $mysqli->select_db('world'); /* return name of current default database */ if ($result = $mysqli->query('SELECT DATABASE()')) { $row = $result->fetch_row(); printf('Default database is %s.\n', $row[0]); $result->close(); } $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* return name of current default database */ if ($result = mysqli_query($link, 'SELECT DATABASE()')) { $row = mysqli_fetch_row($result); printf('Default database is %s.\n', $row[0]); mysqli_free_result($result); } /* change db to world db */ mysqli_select_db($link, 'world'); /* return name of current default database */ if ($result = mysqli_query($link, 'SELECT DATABASE()')) { $row = mysqli_fetch_row($result); printf('Default database is %s.\n', $row[0]); mysqli_free_result($result); } mysqli_close($link); ?>
The above examples will output:
Default database is test. Default database is world.
See Also
mysqli_connect
|
mysqli_real_connect |
mysqli::send_query
, mysqli_send_query
mysqli::send_query
mysqli_send_query
Send the query and return
Description
Object oriented stylebool mysqli::send_query(string query);
Procedural stylebool mysqli_send_query(mysqli link,
Warning
string query);
This function is currently not documented; only its argument list is available.Warning
This function has been DEPRECATED and REMOVED as of PHP 5.3.0.
mysqli::set_charset
, mysqli_set_charset
mysqli::set_charset
mysqli_set_charset
Sets the default client character set
Description
Object oriented stylebool mysqli::set_charset(string charset);
Procedural stylebool mysqli_set_charset(mysqli link,
string charset);
Sets the default character set to be used when sending data from and to the database server.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
charset
-
The charset to be set as default.
Return Values
Returns TRUE
on success or FALSE
on failure.
Notes
NoteTo use this function on a Windows platform you need MariaDB client library version 4.1.11 or above (for MariaDB 5.0 you need 5.0.6 or above).Note
This is the preferred way to change the charset. Using mysqli::query
to execute SET NAMES ..
is not recommended.
Examples
Example 20.135. mysqli::set_charset
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'test'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* change character set to utf8 */ if (!$mysqli->set_charset('utf8')) { printf('Error loading character set utf8: %s\n', $mysqli->error); } else { printf('Current character set: %s\n', $mysqli->character_set_name()); } $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* change character set to utf8 */ if (!mysqli_set_charset($link, 'utf8')) { printf('Error loading character set utf8: %s\n', mysqli_error($link)); } else { printf('Current character set: %s\n', mysqli_character_set_name($link)); } mysqli_close($link); ?>
The above examples will output:
Current character set: utf8
See Also
mysqli_character_set_name
|
mysqli_real_escape_string
|
List of character sets that MariaDB supports |
mysqli::set_local_infile_default
, mysqli_set_local_infile_default
mysqli::set_local_infile_default
mysqli_set_local_infile_default
Unsets user defined handler for load local infile command
Description
void mysqli_set_local_infile_default(mysqli link);
Deactivates a LOAD DATA INFILE LOCAL
handler previously set with mysqli_set_local_infile_handler
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
No value is returned.
Examples
See mysqli_set_local_infile_handler
examples
See Also
mysqli_set_local_infile_handler |
mysqli::set_local_infile_handler
, mysqli_set_local_infile_handler
mysqli::set_local_infile_handler
mysqli_set_local_infile_handler
Set callback function for LOAD DATA LOCAL INFILE command
Description
Object oriented stylebool mysqli::set_local_infile_handler(mysqli link,
callable read_func);
Procedural stylebool mysqli_set_local_infile_handler(mysqli link,
callable read_func);
Set callback function for LOAD DATA LOCAL INFILE command
The callbacks task is to read input from the file specified in the LOAD DATA LOCAL INFILE
and to reformat it into the format understood by LOAD DATA INFILE
.
The returned data needs to match the format specified in the LOAD DATA
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
read_func
-
A callback function or object method taking the following parameters:
stream
-
A PHP stream associated with the SQL commands INFILE
&buffer
-
A string buffer to store the rewritten input into
buflen
-
The maximum number of characters to be stored in the buffer
&errormsg
-
If an error occurs you can store an error message in here
The callback function should return the number of characters stored in the buffer
or a negative value if an error occurred.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.136. mysqli::set_local_infile_handler
example
Object oriented style
<?php $db = mysqli_init(); $db->real_connect('localhost','root','','test'); function callme($stream, &$buffer, $buflen, &$errmsg) { $buffer = fgets($stream); echo $buffer; // convert to upper case and replace ',' delimiter with [TAB] $buffer = strtoupper(str_replace(',', '\t', $buffer)); return strlen($buffer); } echo 'Input:\n'; $db->set_local_infile_handler('callme'); $db->query('LOAD DATA LOCAL INFILE 'input.txt' INTO TABLE t1'); $db->set_local_infile_default(); $res = $db->query('SELECT * FROM t1'); echo '\nResult:\n'; while ($row = $res->fetch_assoc()) { echo join(',', $row).'\n'; } ?>
Procedural style
<?php $db = mysqli_init(); mysqli_real_connect($db, 'localhost','root','','test'); function callme($stream, &$buffer, $buflen, &$errmsg) { $buffer = fgets($stream); echo $buffer; // convert to upper case and replace ',' delimiter with [TAB] $buffer = strtoupper(str_replace(',', '\t', $buffer)); return strlen($buffer); } echo 'Input:\n'; mysqli_set_local_infile_handler($db, 'callme'); mysqli_query($db, 'LOAD DATA LOCAL INFILE 'input.txt' INTO TABLE t1'); mysqli_set_local_infile_default($db); $res = mysqli_query($db, 'SELECT * FROM t1'); echo '\nResult:\n'; while ($row = mysqli_fetch_assoc($res)) { echo join(',', $row).'\n'; } ?>
The above examples will output:
Input: 23,foo 42,bar Output: 23,FOO 42,BAR
See Also
mysqli_set_local_infile_default |
mysqli::$sqlstate
, mysqli_sqlstate
mysqli::$sqlstate
mysqli_sqlstate
Returns the SQLSTATE error from previous MariaDB operation
Description
Object oriented stylestring mysqli->sqlstate ;
Procedural stylestring mysqli_sqlstate(mysqli link);
Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000'
means no error. The values are specified by ANSI SQL and ODBC. For a list of possible values, see http://dev.mysql.com/doc/mysql/en/error-handling.html.Note
Note that not all MariaDB errors are yet mapped to SQLSTATE's. The value HY000
(general error) is used for unmapped errors.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000'
means no error.
Examples
Example 20.137. $mysqli->sqlstate
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* Table City already exists, so we should get an error */ if (!$mysqli->query('CREATE TABLE City (ID INT, Name VARCHAR(30))')) { printf('Error - SQLSTATE %s.\n', $mysqli->sqlstate); } $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* Table City already exists, so we should get an error */ if (!mysqli_query($link, 'CREATE TABLE City (ID INT, Name VARCHAR(30))')) { printf('Error - SQLSTATE %s.\n', mysqli_sqlstate($link)); } mysqli_close($link); ?>
The above examples will output:
Error - SQLSTATE 42S01.
See Also
mysqli_errno
|
mysqli_error |
mysqli::ssl_set
, mysqli_ssl_set
mysqli::ssl_set
mysqli_ssl_set
Used for establishing secure connections using SSL
Description
Object oriented stylebool mysqli::ssl_set(string key,
string cert,
string ca,
string capath,
string cipher);
Procedural stylebool mysqli_ssl_set(mysqli link,
string key,
string cert,
string ca,
string capath,
string cipher);
Used for establishing secure connections using SSL. It must be called before mysqli_real_connect
. This function does nothing unless OpenSSL support is enabled.
Note that MariaDB Native Driver does not support SSL before PHP 5.3.3, so calling this function when using MariaDB Native Driver will result in an error. MariaDB Native Driver is enabled by default on Microsoft Windows from PHP version 5.3 onwards.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
key
-
The path name to the key file.
cert
-
The path name to the certificate file.
ca
-
The path name to the certificate authority file.
capath
-
The pathname to a directory that contains trusted SSL CA certificates in PEM format.
cipher
-
A list of allowable ciphers to use for SSL encryption.
Any unused SSL parameters may be given as NULL
Return Values
This function always returns TRUE
value. If SSL setup is incorrect mysqli_real_connect
will return an error when you attempt to connect.
See Also
mysqli_options
|
mysqli_real_connect |
mysqli::stat
, mysqli_stat
mysqli::stat
mysqli_stat
Gets the current system status
Description
Object oriented stylestring mysqli::stat();
Procedural stylestring mysqli_stat(mysqli link);
mysqli_stat
returns a string containing information similar to that provided by the 'mysqladmin status' command. This includes uptime in seconds and the number of running threads, questions, reloads, and open tables.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
A string describing the server status. FALSE
if an error occurred.
Examples
Example 20.138. mysqli::stat
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } printf ('System status: %s\n', $mysqli->stat()); $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } printf('System status: %s\n', mysqli_stat($link)); mysqli_close($link); ?>
The above examples will output:
System status: Uptime: 272 Threads: 1 Questions: 5340 Slow queries: 0 Opens: 13 Flush tables: 1 Open tables: 0 Queries per second avg: 19.632 Memory in use: 8496K Max memory used: 8560K
See Also
mysqli_get_server_info |
mysqli::stmt_init
, mysqli_stmt_init
mysqli::stmt_init
mysqli_stmt_init
Initializes a statement and returns an object for use with mysqli_stmt_prepare
Description
Object oriented stylemysqli_stmt mysqli::stmt_init();
Procedural stylemysqli_stmt mysqli_stmt_init(mysqli link);
Allocates and initializes a statement object suitable for mysqli_stmt_prepare
.Note
Any subsequent calls to any mysqli_stmt function will fail until mysqli_stmt_prepare
was called.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns an object.
See Also
mysqli_stmt_prepare |
mysqli::store_result
, mysqli_store_result
mysqli::store_result
mysqli_store_result
Transfers a result set from the last query
Description
Object oriented stylemysqli_result mysqli::store_result();
Procedural stylemysqli_result mysqli_store_result(mysqli link);
Transfers the result set from the last query on the database connection represented by the link
parameter to be used with the mysqli_data_seek
function.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns a buffered result object or FALSE
if an error occurred.Note
mysqli_store_result
returns FALSE
in case the query didn't return a result set (if the query was, for example an INSERT statement). This function also returns FALSE
if the reading of the result set failed. You can check if you have got an error by checking if mysqli_error
doesn't return an empty string, if mysqli_errno
returns a non zero value, or if mysqli_field_count
returns a non zero value. Also possible reason for this function returning FALSE
after successful call to mysqli_query
can be too large result set (memory for it cannot be allocated). If mysqli_field_count
returns a non-zero value, the statement should have produced a non-empty result set.
Notes
NoteAlthough it is always good practice to free the memory used by the result of a query using the mysqli_free_result
function, when transferring large result sets using the mysqli_store_result
this becomes particularly important.
Examples
See mysqli_multi_query
.
See Also
mysqli_real_query
|
mysqli_use_result |
mysqli::$thread_id
, mysqli_thread_id
mysqli::$thread_id
mysqli_thread_id
Returns the thread ID for the current connection
Description
Object oriented styleint mysqli->thread_id ;
Procedural styleint mysqli_thread_id(mysqli link);
The mysqli_thread_id
function returns the thread ID for the current connection which can then be killed using the mysqli_kill
function. If the connection is lost and you reconnect with mysqli_ping
, the thread ID will be other. Therefore you should get the thread ID only when you need it.Note
The thread ID is assigned on a connection-by-connection basis. Hence, if the connection is broken and then re-established a new thread ID will be assigned.
To kill a running query you can use the SQL command KILL QUERY processid
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Returns the Thread ID for the current connection.
Examples
Example 20.139. $mysqli->thread_id
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* determine our thread id */ $thread_id = $mysqli->thread_id; /* Kill connection */ $mysqli->kill($thread_id); /* This should produce an error */ if (!$mysqli->query('CREATE TABLE myCity LIKE City')) { printf('Error: %s\n', $mysqli->error); exit; } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* determine our thread id */ $thread_id = mysqli_thread_id($link); /* Kill connection */ mysqli_kill($link, $thread_id); /* This should produce an error */ if (!mysqli_query($link, 'CREATE TABLE myCity LIKE City')) { printf('Error: %s\n', mysqli_error($link)); exit; } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Error: MariaDB server has gone away
See Also
mysqli_kill |
mysqli::thread_safe
, mysqli_thread_safe
mysqli::thread_safe
mysqli_thread_safe
Returns whether thread safety is given or not
Description
Procedural stylebool mysqli_thread_safe();
Tells whether the client library is compiled as thread-safe.
Return Values
TRUE
if the client library is thread-safe, otherwise FALSE
.
mysqli::use_result
, mysqli_use_result
mysqli::use_result
mysqli_use_result
Initiate a result set retrieval
Description
Object oriented stylemysqli_result mysqli::use_result();
Procedural stylemysqli_result mysqli_use_result(mysqli link);
Used to initiate the retrieval of a result set from the last query executed using the mysqli_real_query
function on the database connection.
Either this or the mysqli_store_result
function must be called before the results of a query can be retrieved, and one or the other must be called to prevent the next query on that database connection from failing.Note
The mysqli_use_result
function does not transfer the entire result set from the database and hence cannot be used functions such as mysqli_data_seek
to move to a particular row within the set. To use this functionality, the result set must be stored using mysqli_store_result
. One should not use mysqli_use_result
if a lot of processing on the client side is performed, since this will tie up the server and prevent other threads from updating any tables from which the data is being fetched.
Return Values
Returns an unbuffered result object or FALSE
if an error occurred.
Examples
Example 20.140. mysqli::use_result
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT CURRENT_USER();'; $query .= 'SELECT Name FROM City ORDER BY ID LIMIT 20, 5'; /* execute multi query */ if ($mysqli->multi_query($query)) { do { /* store first result set */ if ($result = $mysqli->use_result()) { while ($row = $result->fetch_row()) { printf('%s\n', $row[0]); } $result->close(); } /* print divider */ if ($mysqli->more_results()) { printf('-----------------\n'); } } while ($mysqli->next_result()); } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT CURRENT_USER();'; $query .= 'SELECT Name FROM City ORDER BY ID LIMIT 20, 5'; /* execute multi query */ if (mysqli_multi_query($link, $query)) { do { /* store first result set */ if ($result = mysqli_use_result($link)) { while ($row = mysqli_fetch_row($result)) { printf('%s\n', $row[0]); } mysqli_free_result($result); } /* print divider */ if (mysqli_more_results($link)) { printf('-----------------\n'); } } while (mysqli_next_result($link)); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
my_user@localhost ----------------- Amersfoort Maastricht Dordrecht Leiden Haarlemmermeer
See Also
mysqli_real_query
|
mysqli_store_result |
mysqli::$warning_count
, mysqli_warning_count
mysqli::$warning_count
mysqli_warning_count
Returns the number of warnings from the last query for the given link
Description
Object oriented styleint mysqli->warning_count ;
Procedural styleint mysqli_warning_count(mysqli link);
Returns the number of warnings from the last query in the connection.Note
For retrieving warning messages you can use the SQL command SHOW WARNINGS [limit row_count]
.
Parameters
link
-
Procedural style only: A link identifier returned by
mysqli_connect
ormysqli_init
Return Values
Number of warnings or zero if there are no warnings.
Examples
Example 20.141. $mysqli->warning_count
example
Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $mysqli->query('CREATE TABLE myCity LIKE City'); /* a remarkable city in Wales */ $query = 'INSERT INTO myCity (CountryCode, Name) VALUES('GBR', 'Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch')'; $mysqli->query($query); if ($mysqli->warning_count) { if ($result = $mysqli->query('SHOW WARNINGS')) { $row = $result->fetch_row(); printf('%s (%d): %s\n', $row[0], $row[1], $row[2]); $result->close(); } } /* close connection */ $mysqli->close(); ?>
Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } mysqli_query($link, 'CREATE TABLE myCity LIKE City'); /* a remarkable long city name in Wales */ $query = 'INSERT INTO myCity (CountryCode, Name) VALUES('GBR', 'Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch')'; mysqli_query($link, $query); if (mysqli_warning_count($link)) { if ($result = mysqli_query($link, 'SHOW WARNINGS')) { $row = mysqli_fetch_row($result); printf('%s (%d): %s\n', $row[0], $row[1], $row[2]); mysqli_free_result($result); } } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Warning (1264): Data truncated for column 'Name' at row 1
See Also
mysqli_errno
|
mysqli_error
|
mysqli_sqlstate |
The mysqli_stmt class (mysqli_stmt
)
mysqli_stmt::$affected_rows
,mysqli_stmt_affected_rows
mysqli_stmt::attr_get
,mysqli_stmt_attr_get
mysqli_stmt::attr_set
,mysqli_stmt_attr_set
mysqli_stmt::bind_param
,mysqli_stmt_bind_param
mysqli_stmt::bind_result
,mysqli_stmt_bind_result
mysqli_stmt::close
,mysqli_stmt_close
mysqli_stmt::data_seek
,mysqli_stmt_data_seek
mysqli_stmt::$errno
,mysqli_stmt_errno
mysqli_stmt::$error_list
,mysqli_stmt_error_list
mysqli_stmt::$error
,mysqli_stmt_error
mysqli_stmt::execute
,mysqli_stmt_execute
mysqli_stmt::fetch
,mysqli_stmt_fetch
mysqli_stmt::$field_count
,mysqli_stmt_field_count
mysqli_stmt::free_result
,mysqli_stmt_free_result
mysqli_stmt::get_result
,mysqli_stmt_get_result
mysqli_stmt::get_warnings
,mysqli_stmt_get_warnings
mysqli_stmt::$insert_id
,mysqli_stmt_insert_id
mysqli_stmt::more_results
,mysqli_stmt_more_results
mysqli_stmt::next_result
,mysqli_stmt_next_result
mysqli_stmt::$num_rows
,mysqli_stmt_num_rows
mysqli_stmt::$param_count
,mysqli_stmt_param_count
mysqli_stmt::prepare
,mysqli_stmt_prepare
mysqli_stmt::reset
,mysqli_stmt_reset
mysqli_stmt::result_metadata
,mysqli_stmt_result_metadata
mysqli_stmt::send_long_data
,mysqli_stmt_send_long_data
mysqli_stmt::$sqlstate
,mysqli_stmt_sqlstate
mysqli_stmt::store_result
,mysqli_stmt_store_result
Represents a prepared statement.
mysqli_stmt {
mysqli_stmt Propertiesint mysqli_stmt->affected_rows ;
int mysqli_stmt->errno ;
string mysqli_stmt->error_list ;
string mysqli_stmt->error ;
int mysqli_stmt->field_count ;
int mysqli_stmt->insert_id ;
int mysqli_stmt->num_rows ;
int mysqli_stmt->param_count ;
string mysqli_stmt->sqlstate ;
Methodsint mysqli_stmt::attr_get(int attr);
bool mysqli_stmt::attr_set(int attr,
int mode);
bool mysqli_stmt::bind_param(string types,
mixed var1,
mixed ...);
bool mysqli_stmt::bind_result(mixed var1,
mixed ...);
bool mysqli_stmt::close();
void mysqli_stmt::data_seek(int offset);
bool mysqli_stmt::execute();
bool mysqli_stmt::fetch();
void mysqli_stmt::free_result();
mysqli_result mysqli_stmt::get_result();
object mysqli_stmt::get_warnings(mysqli_stmt stmt);
mixed mysqli_stmt::prepare(string query);
bool mysqli_stmt::reset();
mysqli_result mysqli_stmt::result_metadata();
bool mysqli_stmt::send_long_data(int param_nr,
string data);
bool mysqli_stmt::store_result();
}
mysqli_stmt::$affected_rows
, mysqli_stmt_affected_rows
mysqli_stmt::$affected_rows
mysqli_stmt_affected_rows
Returns the total number of rows changed, deleted, or inserted by the last executed statement
Description
Object oriented styleint mysqli_stmt->affected_rows ;
Procedural styleint mysqli_stmt_affected_rows(mysqli_stmt stmt);
Returns the number of rows affected by INSERT
, UPDATE
, or DELETE
query.
This function only works with queries which update a table. In order to get the number of rows from a SELECT query, use mysqli_stmt_num_rows
instead.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records where updated for an UPDATE/DELETE statement, no rows matched the WHERE clause in the query or that no query has yet been executed. -1 indicates that the query has returned an error. NULL indicates an invalid argument was supplied to the function.Note
If the number of affected rows is greater than maximal PHP int value, the number of affected rows will be returned as a string value.
Examples
Example 20.142. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* create temp table */ $mysqli->query('CREATE TEMPORARY TABLE myCountry LIKE Country'); $query = 'INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?'; /* prepare statement */ if ($stmt = $mysqli->prepare($query)) { /* Bind variable for placeholder */ $code = 'A%'; $stmt->bind_param('s', $code); /* execute statement */ $stmt->execute(); printf('rows inserted: %d\n', $stmt->affected_rows); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.143. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* create temp table */ mysqli_query($link, 'CREATE TEMPORARY TABLE myCountry LIKE Country'); $query = 'INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?'; /* prepare statement */ if ($stmt = mysqli_prepare($link, $query)) { /* Bind variable for placeholder */ $code = 'A%'; mysqli_stmt_bind_param($stmt, 's', $code); /* execute statement */ mysqli_stmt_execute($stmt); printf('rows inserted: %d\n', mysqli_stmt_affected_rows($stmt)); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
rows inserted: 17
See Also
mysqli_stmt_num_rows
|
mysqli_prepare |
mysqli_stmt::attr_get
, mysqli_stmt_attr_get
mysqli_stmt::attr_get
mysqli_stmt_attr_get
Used to get the current value of a statement attribute
Description
Object oriented styleint mysqli_stmt::attr_get(int attr);
Procedural styleint mysqli_stmt_attr_get(mysqli_stmt stmt,
int attr);
Gets the current value of a statement attribute.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
. attr
-
The attribute that you want to get.
Return Values
Returns FALSE
if the attribute is not found, otherwise returns the value of the attribute.
mysqli_stmt::attr_set
, mysqli_stmt_attr_set
mysqli_stmt::attr_set
mysqli_stmt_attr_set
Used to modify the behavior of a prepared statement
Description
Object oriented stylebool mysqli_stmt::attr_set(int attr,
int mode);
Procedural stylebool mysqli_stmt_attr_set(mysqli_stmt stmt,
int attr,
int mode);
Used to modify the behavior of a prepared statement. This function may be called multiple times to set several attributes.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
. attr
-
The attribute that you want to set. It can have one of the following values:
Table 20.17. Attribute values
Character Description MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH If set to 1, causes mysqli_stmt_store_result
to update the metadataMYSQL_FIELD->max_length
value.MYSQLI_STMT_ATTR_CURSOR_TYPE Type of cursor to open for statement when mysqli_stmt_execute
is invoked.mode
can beMYSQLI_CURSOR_TYPE_NO_CURSOR
(the default) orMYSQLI_CURSOR_TYPE_READ_ONLY
.MYSQLI_STMT_ATTR_PREFETCH_ROWS Number of rows to fetch from server at a time when using a cursor. mode
can be in the range from 1 to the maximum value of unsigned long. The default is 1.If you use the
MYSQLI_STMT_ATTR_CURSOR_TYPE
option withMYSQLI_CURSOR_TYPE_READ_ONLY
, a cursor is opened for the statement when you invokemysqli_stmt_execute
. If there is already an open cursor from a previousmysqli_stmt_execute
call, it closes the cursor before opening a new one.mysqli_stmt_reset
also closes any open cursor before preparing the statement for re-execution.mysqli_stmt_free_result
closes any open cursor.If you open a cursor for a prepared statement,
mysqli_stmt_store_result
is unnecessary. mode
-
The value to assign to the attribute.
mysqli_stmt::bind_param
, mysqli_stmt_bind_param
mysqli_stmt::bind_param
mysqli_stmt_bind_param
Binds variables to a prepared statement as parameters
Description
Object oriented stylebool mysqli_stmt::bind_param(string types,
mixed var1,
mixed ...);
Procedural stylebool mysqli_stmt_bind_param(mysqli_stmt stmt,
string types,
mixed var1,
mixed ...);
Bind variables for the parameter markers in the SQL statement that was passed to mysqli_prepare
.Note
If data size of a variable exceeds max. allowed packet size (max_allowed_packet), you have to specify b
in types
and use mysqli_stmt_send_long_data
to send the data in packets.Note
Care must be taken when using mysqli_stmt_bind_param
in conjunction with call_user_func_array
. Note that mysqli_stmt_bind_param
requires parameters to be passed by reference, whereas call_user_func_array
can accept as a parameter a list of variables that can represent references or values.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
. types
-
A string that contains one or more characters which specify the types for the corresponding bind variables:
Table 20.18. Type specification chars
Character Description i corresponding variable has type integer d corresponding variable has type double s corresponding variable has type string b corresponding variable is a blob and will be sent in packets var1
-
The number of variables and length of string
types
must match the parameters in the statement.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.144. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $stmt = $mysqli->prepare('INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)'); $stmt->bind_param('sssd', $code, $language, $official, $percent); $code = 'DEU'; $language = 'Bavarian'; $official = 'F'; $percent = 11.2; /* execute prepared statement */ $stmt->execute(); printf('%d Row inserted.\n', $stmt->affected_rows); /* close statement and connection */ $stmt->close(); /* Clean up table CountryLanguage */ $mysqli->query('DELETE FROM CountryLanguage WHERE Language="Bavarian"'); printf('%d Row deleted.\n', $mysqli->affected_rows); /* close connection */ $mysqli->close(); ?>
Example 20.145. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (!$link) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $stmt = mysqli_prepare($link, 'INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)'); mysqli_stmt_bind_param($stmt, 'sssd', $code, $language, $official, $percent); $code = 'DEU'; $language = 'Bavarian'; $official = 'F'; $percent = 11.2; /* execute prepared statement */ mysqli_stmt_execute($stmt); printf('%d Row inserted.\n', mysqli_stmt_affected_rows($stmt)); /* close statement and connection */ mysqli_stmt_close($stmt); /* Clean up table CountryLanguage */ mysqli_query($link, 'DELETE FROM CountryLanguage WHERE Language="Bavarian"'); printf('%d Row deleted.\n', mysqli_affected_rows($link)); /* close connection */ mysqli_close($link); ?>
The above examples will output:
1 Row inserted. 1 Row deleted.
See Also
mysqli_stmt_bind_result
|
mysqli_stmt_execute
|
mysqli_stmt_fetch
|
mysqli_prepare
|
mysqli_stmt_send_long_data
|
mysqli_stmt_errno
|
mysqli_stmt_error |
mysqli_stmt::bind_result
, mysqli_stmt_bind_result
mysqli_stmt::bind_result
mysqli_stmt_bind_result
Binds variables to a prepared statement for result storage
Description
Object oriented stylebool mysqli_stmt::bind_result(mixed var1,
mixed ...);
Procedural stylebool mysqli_stmt_bind_result(mysqli_stmt stmt,
mixed var1,
mixed ...);
Binds columns in the result set to variables.
When mysqli_stmt_fetch
is called to fetch data, the MariaDB client/server protocol places the data for the bound columns into the specified variables var1, ...
.Note
Note that all columns must be bound after mysqli_stmt_execute
and prior to calling mysqli_stmt_fetch
. Depending on column types bound variables can silently change to the corresponding PHP type.
A column can be bound or rebound at any time, even after a result set has been partially retrieved. The new binding takes effect the next time mysqli_stmt_fetch
is called.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
. var1
-
The variable to be bound.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.146. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* prepare statement */ if ($stmt = $mysqli->prepare('SELECT Code, Name FROM Country ORDER BY Name LIMIT 5')) { $stmt->execute(); /* bind variables to prepared statement */ $stmt->bind_result($col1, $col2); /* fetch values */ while ($stmt->fetch()) { printf('%s %s\n', $col1, $col2); } /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.147. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (!$link) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* prepare statement */ if ($stmt = mysqli_prepare($link, 'SELECT Code, Name FROM Country ORDER BY Name LIMIT 5')) { mysqli_stmt_execute($stmt); /* bind variables to prepared statement */ mysqli_stmt_bind_result($stmt, $col1, $col2); /* fetch values */ while (mysqli_stmt_fetch($stmt)) { printf('%s %s\n', $col1, $col2); } /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
AFG Afghanistan ALB Albania DZA Algeria ASM American Samoa AND Andorra
See Also
mysqli_stmt_bind_param
|
mysqli_stmt_execute
|
mysqli_stmt_fetch
|
mysqli_prepare
|
mysqli_stmt_prepare
|
mysqli_stmt_init
|
mysqli_stmt_errno
|
mysqli_stmt_error |
mysqli_stmt::close
, mysqli_stmt_close
mysqli_stmt::close
mysqli_stmt_close
Closes a prepared statement
Description
Object oriented stylebool mysqli_stmt::close();
Procedural stylebool mysqli_stmt_close(mysqli_stmt stmt);
Closes a prepared statement. mysqli_stmt_close
also deallocates the statement handle. If the current statement has pending or unread results, this function cancels them so that the next query can be executed.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Returns TRUE
on success or FALSE
on failure.
See Also
mysqli_prepare |
mysqli_stmt::data_seek
, mysqli_stmt_data_seek
mysqli_stmt::data_seek
mysqli_stmt_data_seek
Seeks to an arbitrary row in statement result set
Description
Object oriented stylevoid mysqli_stmt::data_seek(int offset);
Procedural stylevoid mysqli_stmt_data_seek(mysqli_stmt stmt,
int offset);
Seeks to an arbitrary result pointer in the statement result set.
mysqli_stmt_store_result
must be called prior to mysqli_stmt_data_seek
.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
. offset
-
Must be between zero and the total number of rows minus one (0..
mysqli_stmt_num_rows
- 1).
Return Values
No value is returned.
Examples
Example 20.148. Object oriented style
<?php /* Open a connection */ $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER BY Name'; if ($stmt = $mysqli->prepare($query)) { /* execute query */ $stmt->execute(); /* bind result variables */ $stmt->bind_result($name, $code); /* store result */ $stmt->store_result(); /* seek to row no. 400 */ $stmt->data_seek(399); /* fetch values */ $stmt->fetch(); printf ('City: %s Countrycode: %s\n', $name, $code); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.149. Procedural style
<?php /* Open a connection */ $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER BY Name'; if ($stmt = mysqli_prepare($link, $query)) { /* execute query */ mysqli_stmt_execute($stmt); /* bind result variables */ mysqli_stmt_bind_result($stmt, $name, $code); /* store result */ mysqli_stmt_store_result($stmt); /* seek to row no. 400 */ mysqli_stmt_data_seek($stmt, 399); /* fetch values */ mysqli_stmt_fetch($stmt); printf ('City: %s Countrycode: %s\n', $name, $code); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
City: Benin City Countrycode: NGA
See Also
mysqli_prepare |
mysqli_stmt::$errno
, mysqli_stmt_errno
mysqli_stmt::$errno
mysqli_stmt_errno
Returns the error code for the most recent statement call
Description
Object oriented styleint mysqli_stmt->errno ;
Procedural styleint mysqli_stmt_errno(mysqli_stmt stmt);
Returns the error code for the most recently invoked statement function that can succeed or fail.
Client error message numbers are listed in the MariaDB errmsg.h
header file, server error message numbers are listed in mysqld_error.h
. In the MariaDB source distribution you can find a complete list of error messages and error numbers in the file Docs/mysqld_error.txt
.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
An error code value. Zero means no error occurred.
Examples
Example 20.150. Object oriented style
<?php /* Open a connection */ $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $mysqli->query('CREATE TABLE myCountry LIKE Country'); $mysqli->query('INSERT INTO myCountry SELECT * FROM Country'); $query = 'SELECT Name, Code FROM myCountry ORDER BY Name'; if ($stmt = $mysqli->prepare($query)) { /* drop table */ $mysqli->query('DROP TABLE myCountry'); /* execute query */ $stmt->execute(); printf('Error: %d.\n', $stmt->errno); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.151. Procedural style
<?php /* Open a connection */ $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } mysqli_query($link, 'CREATE TABLE myCountry LIKE Country'); mysqli_query($link, 'INSERT INTO myCountry SELECT * FROM Country'); $query = 'SELECT Name, Code FROM myCountry ORDER BY Name'; if ($stmt = mysqli_prepare($link, $query)) { /* drop table */ mysqli_query($link, 'DROP TABLE myCountry'); /* execute query */ mysqli_stmt_execute($stmt); printf('Error: %d.\n', mysqli_stmt_errno($stmt)); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Error: 1146.
See Also
mysqli_stmt_error
|
mysqli_stmt_sqlstate |
mysqli_stmt::$error_list
, mysqli_stmt_error_list
mysqli_stmt::$error_list
mysqli_stmt_error_list
Returns a list of errors from the last statement executed
Description
Object oriented stylestring mysqli_stmt->error_list ;
Procedural stylestring mysqli_stmt_error_list(mysqli_stmt stmt);
Returns an array of errors for the most recently invoked statement function that can succeed or fail.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
A list of errors, each as an associative array containing the errno, error, and sqlstate.
Examples
Example 20.152. Object oriented style
<?php /* Open a connection */ $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $mysqli->query('CREATE TABLE myCountry LIKE Country'); $mysqli->query('INSERT INTO myCountry SELECT * FROM Country'); $query = 'SELECT Name, Code FROM myCountry ORDER BY Name'; if ($stmt = $mysqli->prepare($query)) { /* drop table */ $mysqli->query('DROP TABLE myCountry'); /* execute query */ $stmt->execute(); echo 'Error:\n'; print_r($stmt->error_list); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.153. Procedural style
<?php /* Open a connection */ $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } mysqli_query($link, 'CREATE TABLE myCountry LIKE Country'); mysqli_query($link, 'INSERT INTO myCountry SELECT * FROM Country'); $query = 'SELECT Name, Code FROM myCountry ORDER BY Name'; if ($stmt = mysqli_prepare($link, $query)) { /* drop table */ mysqli_query($link, 'DROP TABLE myCountry'); /* execute query */ mysqli_stmt_execute($stmt); echo 'Error:\n'; print_r(mysql_stmt_error_list($stmt)); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Array ( [0] => Array ( [errno] => 1146 [sqlstate] => 42S02 [error] => Table 'world.myCountry' doesn't exist ) )
See Also
mysqli_stmt_error
|
mysqli_stmt_errno
|
mysqli_stmt_sqlstate |
mysqli_stmt::$error
, mysqli_stmt_error
mysqli_stmt::$error
mysqli_stmt_error
Returns a string description for last statement error
Description
Object oriented stylestring mysqli_stmt->error ;
Procedural stylestring mysqli_stmt_error(mysqli_stmt stmt);
Returns a containing the error message for the most recently invoked statement function that can succeed or fail.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
A string that describes the error. An empty string if no error occurred.
Examples
Example 20.154. Object oriented style
<?php /* Open a connection */ $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $mysqli->query('CREATE TABLE myCountry LIKE Country'); $mysqli->query('INSERT INTO myCountry SELECT * FROM Country'); $query = 'SELECT Name, Code FROM myCountry ORDER BY Name'; if ($stmt = $mysqli->prepare($query)) { /* drop table */ $mysqli->query('DROP TABLE myCountry'); /* execute query */ $stmt->execute(); printf('Error: %s.\n', $stmt->error); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.155. Procedural style
<?php /* Open a connection */ $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } mysqli_query($link, 'CREATE TABLE myCountry LIKE Country'); mysqli_query($link, 'INSERT INTO myCountry SELECT * FROM Country'); $query = 'SELECT Name, Code FROM myCountry ORDER BY Name'; if ($stmt = mysqli_prepare($link, $query)) { /* drop table */ mysqli_query($link, 'DROP TABLE myCountry'); /* execute query */ mysqli_stmt_execute($stmt); printf('Error: %s.\n', mysqli_stmt_error($stmt)); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Error: Table 'world.myCountry' doesn't exist.
See Also
mysqli_stmt_errno
|
mysqli_stmt_sqlstate |
mysqli_stmt::execute
, mysqli_stmt_execute
mysqli_stmt::execute
mysqli_stmt_execute
Executes a prepared Query
Description
Object oriented stylebool mysqli_stmt::execute();
Procedural stylebool mysqli_stmt_execute(mysqli_stmt stmt);
Executes a query that has been previously prepared using the mysqli_prepare
function. When executed any parameter markers which exist will automatically be replaced with the appropriate data.
If the statement is UPDATE
, DELETE
, or INSERT
, the total number of affected rows can be determined by using the mysqli_stmt_affected_rows
function. Likewise, if the query yields a result set the mysqli_stmt_fetch
function is used.Note
When using mysqli_stmt_execute
, the mysqli_stmt_fetch
function must be used to fetch the data prior to performing any additional queries.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.156. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $mysqli->query('CREATE TABLE myCity LIKE City'); /* Prepare an insert statement */ $query = 'INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)'; $stmt = $mysqli->prepare($query); $stmt->bind_param('sss', $val1, $val2, $val3); $val1 = 'Stuttgart'; $val2 = 'DEU'; $val3 = 'Baden-Wuerttemberg'; /* Execute the statement */ $stmt->execute(); $val1 = 'Bordeaux'; $val2 = 'FRA'; $val3 = 'Aquitaine'; /* Execute the statement */ $stmt->execute(); /* close statement */ $stmt->close(); /* retrieve all rows from myCity */ $query = 'SELECT Name, CountryCode, District FROM myCity'; if ($result = $mysqli->query($query)) { while ($row = $result->fetch_row()) { printf('%s (%s,%s)\n', $row[0], $row[1], $row[2]); } /* free result set */ $result->close(); } /* remove table */ $mysqli->query('DROP TABLE myCity'); /* close connection */ $mysqli->close(); ?>
Example 20.157. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } mysqli_query($link, 'CREATE TABLE myCity LIKE City'); /* Prepare an insert statement */ $query = 'INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)'; $stmt = mysqli_prepare($link, $query); mysqli_stmt_bind_param($stmt, 'sss', $val1, $val2, $val3); $val1 = 'Stuttgart'; $val2 = 'DEU'; $val3 = 'Baden-Wuerttemberg'; /* Execute the statement */ mysqli_stmt_execute($stmt); $val1 = 'Bordeaux'; $val2 = 'FRA'; $val3 = 'Aquitaine'; /* Execute the statement */ mysqli_stmt_execute($stmt); /* close statement */ mysqli_stmt_close($stmt); /* retrieve all rows from myCity */ $query = 'SELECT Name, CountryCode, District FROM myCity'; if ($result = mysqli_query($link, $query)) { while ($row = mysqli_fetch_row($result)) { printf('%s (%s,%s)\n', $row[0], $row[1], $row[2]); } /* free result set */ mysqli_free_result($result); } /* remove table */ mysqli_query($link, 'DROP TABLE myCity'); /* close connection */ mysqli_close($link); ?>
The above examples will output:
Stuttgart (DEU,Baden-Wuerttemberg) Bordeaux (FRA,Aquitaine)
See Also
mysqli_prepare
|
mysqli_stmt_bind_param |
mysqli_stmt::fetch
, mysqli_stmt_fetch
mysqli_stmt::fetch
mysqli_stmt_fetch
Fetch results from a prepared statement into the bound variables
Description
Object oriented stylebool mysqli_stmt::fetch();
Procedural stylebool mysqli_stmt_fetch(mysqli_stmt stmt);
Fetch the result from a prepared statement into the variables bound by mysqli_stmt_bind_result
.Note
Note that all columns must be bound by the application before calling mysqli_stmt_fetch
.Note
Data are transferred unbuffered without calling mysqli_stmt_store_result
which can decrease performance (but reduces memory cost).
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Table 20.19. Return Values
Value | Description |
---|---|
TRUE
| Success. Data has been fetched |
FALSE
| Error occurred |
NULL
| No more rows/data exists or data truncation occurred |
Examples
Example 20.158. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5'; if ($stmt = $mysqli->prepare($query)) { /* execute statement */ $stmt->execute(); /* bind result variables */ $stmt->bind_result($name, $code); /* fetch values */ while ($stmt->fetch()) { printf ('%s (%s)\n', $name, $code); } /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.159. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5'; if ($stmt = mysqli_prepare($link, $query)) { /* execute statement */ mysqli_stmt_execute($stmt); /* bind result variables */ mysqli_stmt_bind_result($stmt, $name, $code); /* fetch values */ while (mysqli_stmt_fetch($stmt)) { printf ('%s (%s)\n', $name, $code); } /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Rockford (USA) Tallahassee (USA) Salinas (USA) Santa Clarita (USA) Springfield (USA)
See Also
mysqli_prepare
|
mysqli_stmt_errno
|
mysqli_stmt_error
|
mysqli_stmt_bind_result |
mysqli_stmt::$field_count
, mysqli_stmt_field_count
mysqli_stmt::$field_count
mysqli_stmt_field_count
Returns the number of field in the given statement
Description
Object oriented styleint mysqli_stmt->field_count ;
Procedural styleint mysqli_stmt_field_count(mysqli_stmt stmt);
Warning
This function is currently not documented; only its argument list is available.
mysqli_stmt::free_result
, mysqli_stmt_free_result
mysqli_stmt::free_result
mysqli_stmt_free_result
Frees stored result memory for the given statement handle
Description
Object oriented stylevoid mysqli_stmt::free_result();
Procedural stylevoid mysqli_stmt_free_result(mysqli_stmt stmt);
Frees the result memory associated with the statement, which was allocated by mysqli_stmt_store_result
.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
No value is returned.
See Also
mysqli_stmt_store_result |
mysqli_stmt::get_result
, mysqli_stmt_get_result
mysqli_stmt::get_result
mysqli_stmt_get_result
Gets a result set from a prepared statement
Description
Object oriented stylemysqli_result mysqli_stmt::get_result();
Procedural stylemysqli_result mysqli_stmt_get_result(mysqli_stmt stmt);
Call to return a result set from a prepared statement query.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Returns a resultset or FALSE
on failure.
MySQL Native Driver Only
Available only with mysqlnd.
Examples
Example 20.160. Object oriented style
<?php $mysqli = new mysqli('127.0.0.1', 'user', 'password', 'world'); if($mysqli->connect_error) { die('$mysqli->connect_errno: $myslqi->connect_error'); } $query = 'SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1'; $stmt = $mysqli->stmt_init(); if(!$stmt->prepare($query)) { print 'Failed to prepare statement\n'; } else { $stmt->bind_param('s', $continent); $continent_array = array('Europe','Africa','Asia','North America'); foreach($continent_array as $continent) { $stmt->execute(); $result = $stmt->get_result(); while ($row = $result->fetch_array(MYSQLI_NUM)) { foreach ($row as $r) { print '$r '; } print '\n'; } } } $stmt->close(); $mysqli->close(); ?>
Example 20.161. Procedural style
<?php $link = mysqli_connect('127.0.0.1', 'user', 'password', 'world'); if (!$link) { $error = mysqli_connect_error(); $errno = mysqli_connect_errno(); print '$errno: $error\n'; exit(); } $query = 'SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1'; $stmt = mysqli_stmt_init($link); if(!mysqli_stmt_prepare($stmt, $query)) { print 'Failed to prepare statement\n'; } else { mysqli_stmt_bind_param($stmt, 's', $continent); $continent_array = array('Europe','Africa','Asia','North America'); foreach($continent_array as $continent) { mysqli_stmt_execute($stmt); $result = mysqli_stmt_get_result($stmt); while ($row = mysqli_fetch_array($result, MYSQLI_NUM)) { foreach ($row as $r) { print '$r '; } print '\n'; } } } mysqli_stmt_close($stmt); mysqli_close($link); ?>
The above examples will output:
Albania 3401200 Europe Algeria 31471000 Africa Afghanistan 22720000 Asia Anguilla 8000 North America
See Also
mysqli_prepare
|
mysqli_stmt_result_metadata
|
mysqli_stmt_fetch
|
mysqli_fetch_array
|
mysqli_stmt_store_result |
mysqli_stmt::get_warnings
, mysqli_stmt_get_warnings
mysqli_stmt::get_warnings
mysqli_stmt_get_warnings
Get result of SHOW WARNINGS
Description
Object oriented styleobject mysqli_stmt::get_warnings(mysqli_stmt stmt);
Procedural styleobject mysqli_stmt_get_warnings(mysqli_stmt stmt);
Warning
This function is currently not documented; only its argument list is available.
mysqli_stmt::$insert_id
, mysqli_stmt_insert_id
mysqli_stmt::$insert_id
mysqli_stmt_insert_id
Get the ID generated from the previous INSERT operation
Description
Object oriented styleint mysqli_stmt->insert_id ;
Procedural stylemixed mysqli_stmt_insert_id(mysqli_stmt stmt);
Warning
This function is currently not documented; only its argument list is available.
mysqli_stmt::more_results
, mysqli_stmt_more_results
mysqli_stmt::more_results
mysqli_stmt_more_results
Check if there are more query results from a multiple query
Description
Object oriented style (method):public bool mysqli_stmt::more_results();
Procedural style:bool mysqli_stmt_more_results(mysql_stmt stmt);
Checks if there are more query results from a multiple query.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Returns TRUE
if more results exist, otherwise FALSE
.
See Also
mysqli_stmt::next_result
|
mysqli::multi_query |
mysqli_stmt::next_result
, mysqli_stmt_next_result
mysqli_stmt::next_result
mysqli_stmt_next_result
Reads the next result from a multiple query
Description
Object oriented style (method):public bool mysqli_stmt::next_result();
Procedural style:bool mysqli_stmt_next_result(mysql_stmt stmt);
Reads the next result from a multiple query.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Returns TRUE
on success or FALSE
on failure.
Errors/Exceptions
Emits an E_STRICT
level error if a result set does not exist, and suggests using mysqli_stmt::more_results
in these cases, before calling mysqli_stmt::next_result
.
See Also
mysqli_stmt::more_results
|
mysqli::multi_query |
mysqli_stmt::$num_rows
, mysqli_stmt_num_rows
mysqli_stmt::$num_rows
mysqli_stmt_num_rows
Return the number of rows in statements result set
Description
Object oriented styleint mysqli_stmt->num_rows ;
Procedural styleint mysqli_stmt_num_rows(mysqli_stmt stmt);
Returns the number of rows in the result set. The use of mysqli_stmt_num_rows
depends on whether or not you used mysqli_stmt_store_result
to buffer the entire result set in the statement handle.
If you use mysqli_stmt_store_result
, mysqli_stmt_num_rows
may be called immediately.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
An integer representing the number of rows in result set.
Examples
Example 20.162. Object oriented style
<?php /* Open a connection */ $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20'; if ($stmt = $mysqli->prepare($query)) { /* execute query */ $stmt->execute(); /* store result */ $stmt->store_result(); printf('Number of rows: %d.\n', $stmt->num_rows); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.163. Procedural style
<?php /* Open a connection */ $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20'; if ($stmt = mysqli_prepare($link, $query)) { /* execute query */ mysqli_stmt_execute($stmt); /* store result */ mysqli_stmt_store_result($stmt); printf('Number of rows: %d.\n', mysqli_stmt_num_rows($stmt)); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Number of rows: 20.
See Also
mysqli_stmt_affected_rows
|
mysqli_prepare
|
mysqli_stmt_store_result |
mysqli_stmt::$param_count
, mysqli_stmt_param_count
mysqli_stmt::$param_count
mysqli_stmt_param_count
Returns the number of parameter for the given statement
Description
Object oriented styleint mysqli_stmt->param_count ;
Procedural styleint mysqli_stmt_param_count(mysqli_stmt stmt);
Returns the number of parameter markers present in the prepared statement.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Returns an integer representing the number of parameters.
Examples
Example 20.164. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if ($stmt = $mysqli->prepare('SELECT Name FROM Country WHERE Name=? OR Code=?')) { $marker = $stmt->param_count; printf('Statement has %d markers.\n', $marker); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.165. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if ($stmt = mysqli_prepare($link, 'SELECT Name FROM Country WHERE Name=? OR Code=?')) { $marker = mysqli_stmt_param_count($stmt); printf('Statement has %d markers.\n', $marker); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Statement has 2 markers.
See Also
mysqli_prepare |
mysqli_stmt::prepare
, mysqli_stmt_prepare
mysqli_stmt::prepare
mysqli_stmt_prepare
Prepare an SQL statement for execution
Description
Object oriented stylemixed mysqli_stmt::prepare(string query);
Procedural stylebool mysqli_stmt_prepare(mysqli_stmt stmt,
string query);
Prepares the SQL query pointed to by the null-terminated string query.
The parameter markers must be bound to application variables using mysqli_stmt_bind_param
and/or mysqli_stmt_bind_result
before executing the statement or fetching rows.Note
In the case where you pass a statement to mysqli_stmt_prepare
that is longer than max_allowed_packet
of the server, the returned error codes are different depending on whether you are using MariaDB Native Driver (mysqlnd
) or MariaDB Client Library (libmysql
). The behavior is as follows:
mysqlnd
on Linux returns an error code of 1153. The error message means "got a packet bigger thanmax_allowed_packet
bytes".mysqlnd
on Windows returns an error code 2006. This error message means "server has gone away".libmysql
on all platforms returns an error code 2006. This error message means "server has gone away".
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
. query
-
The query, as a string. It must consist of a single SQL statement.
You can include one or more parameter markers in the SQL statement by embedding question mark (
?
) characters at the appropriate positions.NoteYou should not add a terminating semicolon or
\g
to the statement.NoteThe markers are legal only in certain places in SQL statements. For example, they are allowed in the VALUES() list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value.
However, they are not allowed for identifiers (such as table or column names), in the select list that names the columns to be returned by a SELECT statement), or to specify both operands of a binary operator such as the
=
equal sign. The latter restriction is necessary because it would be impossible to determine the parameter type. In general, parameters are legal only in Data Manipulation Language (DML) statements, and not in Data Definition Language (DDL) statements.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.166. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $city = 'Amersfoort'; /* create a prepared statement */ $stmt = $mysqli->stmt_init(); if ($stmt->prepare('SELECT District FROM City WHERE Name=?')) { /* bind parameters for markers */ $stmt->bind_param('s', $city); /* execute query */ $stmt->execute(); /* bind result variables */ $stmt->bind_result($district); /* fetch value */ $stmt->fetch(); printf('%s is in district %s\n', $city, $district); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.167. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $city = 'Amersfoort'; /* create a prepared statement */ $stmt = mysqli_stmt_init($link); if (mysqli_stmt_prepare($stmt, 'SELECT District FROM City WHERE Name=?')) { /* bind parameters for markers */ mysqli_stmt_bind_param($stmt, 's', $city); /* execute query */ mysqli_stmt_execute($stmt); /* bind result variables */ mysqli_stmt_bind_result($stmt, $district); /* fetch value */ mysqli_stmt_fetch($stmt); printf('%s is in district %s\n', $city, $district); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Amersfoort is in district Utrecht
See Also
mysqli_stmt_init
|
mysqli_stmt_execute
|
mysqli_stmt_fetch
|
mysqli_stmt_bind_param
|
mysqli_stmt_bind_result
|
mysqli_stmt_close |
mysqli_stmt::reset
, mysqli_stmt_reset
mysqli_stmt::reset
mysqli_stmt_reset
Resets a prepared statement
Description
Object oriented stylebool mysqli_stmt::reset();
Procedural stylebool mysqli_stmt_reset(mysqli_stmt stmt);
Resets a prepared statement on client and server to state after prepare.
It resets the statement on the server, data sent using mysqli_stmt_send_long_data
, unbuffered result sets and current errors. It does not clear bindings or stored result sets. Stored result sets will be cleared when executing the prepared statement (or closing it).
To prepare a statement with another query use function mysqli_stmt_prepare
.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Returns TRUE
on success or FALSE
on failure.
See Also
mysqli_prepare |
mysqli_stmt::result_metadata
, mysqli_stmt_result_metadata
mysqli_stmt::result_metadata
mysqli_stmt_result_metadata
Returns result set metadata from a prepared statement
Description
Object oriented stylemysqli_result mysqli_stmt::result_metadata();
Procedural stylemysqli_result mysqli_stmt_result_metadata(mysqli_stmt stmt);
If a statement passed to mysqli_prepare
is one that produces a result set, mysqli_stmt_result_metadata
returns the result object that can be used to process the meta information such as total number of fields and individual field information.Note
This result set pointer can be passed as an argument to any of the field-based functions that process result set metadata, such as:
mysqli_num_fields
mysqli_fetch_field
mysqli_fetch_field_direct
mysqli_fetch_fields
mysqli_field_count
mysqli_field_seek
mysqli_field_tell
mysqli_free_result
The result set structure should be freed when you are done with it, which you can do by passing it to mysqli_free_result
Note
The result set returned by mysqli_stmt_result_metadata
contains only metadata. It does not contain any row results. The rows are obtained by using the statement handle with mysqli_stmt_fetch
.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Returns a result object or FALSE
if an error occurred.
Examples
Example 20.168. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'test'); $mysqli->query('DROP TABLE IF EXISTS friends'); $mysqli->query('CREATE TABLE friends (id int, name varchar(20))'); $mysqli->query('INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')'); $stmt = $mysqli->prepare('SELECT id, name FROM friends'); $stmt->execute(); /* get resultset for metadata */ $result = $stmt->result_metadata(); /* retrieve field information from metadata result set */ $field = $result->fetch_field(); printf('Fieldname: %s\n', $field->name); /* close resultset */ $result->close(); /* close connection */ $mysqli->close(); ?>
Example 20.169. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test'); mysqli_query($link, 'DROP TABLE IF EXISTS friends'); mysqli_query($link, 'CREATE TABLE friends (id int, name varchar(20))'); mysqli_query($link, 'INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')'); $stmt = mysqli_prepare($link, 'SELECT id, name FROM friends'); mysqli_stmt_execute($stmt); /* get resultset for metadata */ $result = mysqli_stmt_result_metadata($stmt); /* retrieve field information from metadata result set */ $field = mysqli_fetch_field($result); printf('Fieldname: %s\n', $field->name); /* close resultset */ mysqli_free_result($result); /* close connection */ mysqli_close($link); ?>
See Also
mysqli_prepare
|
mysqli_free_result |
mysqli_stmt::send_long_data
, mysqli_stmt_send_long_data
mysqli_stmt::send_long_data
mysqli_stmt_send_long_data
Send data in blocks
Description
Object oriented stylebool mysqli_stmt::send_long_data(int param_nr,
string data);
Procedural stylebool mysqli_stmt_send_long_data(mysqli_stmt stmt,
int param_nr,
string data);
Allows to send parameter data to the server in pieces (or chunks), e.g. if the size of a blob exceeds the size of max_allowed_packet
. This function can be called multiple times to send the parts of a character or binary data value for a column, which must be one of the TEXT or BLOB datatypes.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
. param_nr
-
Indicates which parameter to associate the data with. Parameters are numbered beginning with 0.
data
-
A string containing data to be sent.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.170. Object oriented style
<?php $stmt = $mysqli->prepare('INSERT INTO messages (message) VALUES (?)'); $null = NULL; $stmt->bind_param('b', $null); $fp = fopen('messages.txt', 'r'); while (!feof($fp)) { $stmt->send_long_data(0, fread($fp, 8192)); } fclose($fp); $stmt->execute(); ?>
See Also
mysqli_prepare
|
mysqli_stmt_bind_param |
mysqli_stmt::$sqlstate
, mysqli_stmt_sqlstate
mysqli_stmt::$sqlstate
mysqli_stmt_sqlstate
Returns SQLSTATE error from previous statement operation
Description
Object oriented stylestring mysqli_stmt->sqlstate ;
Procedural stylestring mysqli_stmt_sqlstate(mysqli_stmt stmt);
Returns a string containing the SQLSTATE error code for the most recently invoked prepared statement function that can succeed or fail. The error code consists of five characters. '00000'
means no error. The values are specified by ANSI SQL and ODBC. For a list of possible values, see http://dev.mysql.com/doc/mysql/en/error-handling.html.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000'
means no error.
Notes
NoteNote that not all MariaDB errors are yet mapped to SQLSTATE's. The value HY000
(general error) is used for unmapped errors.
Examples
Example 20.171. Object oriented style
<?php /* Open a connection */ $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $mysqli->query('CREATE TABLE myCountry LIKE Country'); $mysqli->query('INSERT INTO myCountry SELECT * FROM Country'); $query = 'SELECT Name, Code FROM myCountry ORDER BY Name'; if ($stmt = $mysqli->prepare($query)) { /* drop table */ $mysqli->query('DROP TABLE myCountry'); /* execute query */ $stmt->execute(); printf('Error: %s.\n', $stmt->sqlstate); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.172. Procedural style
<?php /* Open a connection */ $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } mysqli_query($link, 'CREATE TABLE myCountry LIKE Country'); mysqli_query($link, 'INSERT INTO myCountry SELECT * FROM Country'); $query = 'SELECT Name, Code FROM myCountry ORDER BY Name'; if ($stmt = mysqli_prepare($link, $query)) { /* drop table */ mysqli_query($link, 'DROP TABLE myCountry'); /* execute query */ mysqli_stmt_execute($stmt); printf('Error: %s.\n', mysqli_stmt_sqlstate($stmt)); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Error: 42S02.
See Also
mysqli_stmt_errno
|
mysqli_stmt_error |
mysqli_stmt::store_result
, mysqli_stmt_store_result
mysqli_stmt::store_result
mysqli_stmt_store_result
Transfers a result set from a prepared statement
Description
Object oriented stylebool mysqli_stmt::store_result();
Procedural stylebool mysqli_stmt_store_result(mysqli_stmt stmt);
You must call mysqli_stmt_store_result
for every query that successfully produces a result set (SELECT, SHOW, DESCRIBE, EXPLAIN
), and only if you want to buffer the complete result set by the client, so that the subsequent mysqli_stmt_fetch
call returns buffered data.Note
It is unnecessary to call mysqli_stmt_store_result
for other queries, but if you do, it will not harm or cause any notable performance in all cases. You can detect whether the query produced a result set by checking if mysqli_stmt_result_metadata
returns NULL.
Parameters
stmt
-
Procedural style only: A statement identifier returned by
mysqli_stmt_init
.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.173. Object oriented style
<?php /* Open a connection */ $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20'; if ($stmt = $mysqli->prepare($query)) { /* execute query */ $stmt->execute(); /* store result */ $stmt->store_result(); printf('Number of rows: %d.\n', $stmt->num_rows); /* free result */ $stmt->free_result(); /* close statement */ $stmt->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.174. Procedural style
<?php /* Open a connection */ $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20'; if ($stmt = mysqli_prepare($link, $query)) { /* execute query */ mysqli_stmt_execute($stmt); /* store result */ mysqli_stmt_store_result($stmt); printf('Number of rows: %d.\n', mysqli_stmt_num_rows($stmt)); /* free result */ mysqli_stmt_free_result($stmt); /* close statement */ mysqli_stmt_close($stmt); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Number of rows: 20.
See Also
mysqli_prepare
|
mysqli_stmt_result_metadata
|
mysqli_stmt_fetch |
The mysqli_result class (mysqli_result
)
mysqli_result::$current_field
,mysqli_field_tell
mysqli_result::data_seek
,mysqli_data_seek
mysqli_result::fetch_all
,mysqli_fetch_all
mysqli_result::fetch_array
,mysqli_fetch_array
mysqli_result::fetch_assoc
,mysqli_fetch_assoc
mysqli_result::fetch_field_direct
,mysqli_fetch_field_direct
mysqli_result::fetch_field
,mysqli_fetch_field
mysqli_result::fetch_fields
,mysqli_fetch_fields
mysqli_result::fetch_object
,mysqli_fetch_object
mysqli_result::fetch_row
,mysqli_fetch_row
mysqli_result::$field_count
,mysqli_num_fields
mysqli_result::field_seek
,mysqli_field_seek
mysqli_result::free
,mysqli_free_result
mysqli_result::$lengths
,mysqli_fetch_lengths
mysqli_result::$num_rows
,mysqli_num_rows
Represents the result set obtained from a query against the database.
Changelog
Table 20.20. Changelog
Version | Description |
---|---|
5.4.0 | Iterator support was added, as mysqli_result now implements Traversable . |
mysqli_result {
mysqli_result , Traversable Propertiesint mysqli_result->current_field ;
int mysqli_result->field_count ;
array mysqli_result->lengths ;
int mysqli_result->num_rows ;
Methodsbool mysqli_result::data_seek(int offset);
mixed mysqli_result::fetch_all(int resulttype= =MYSQLI_NUM);
mixed mysqli_result::fetch_array(int resulttype= =MYSQLI_BOTH);
array mysqli_result::fetch_assoc();
object mysqli_result::fetch_field_direct(int fieldnr);
object mysqli_result::fetch_field();
array mysqli_result::fetch_fields();
object mysqli_result::fetch_object(string class_name,
array params);
mixed mysqli_result::fetch_row();
bool mysqli_result::field_seek(int fieldnr);
void mysqli_result::free();
}
mysqli_result::$current_field
, mysqli_field_tell
mysqli_result::$current_field
mysqli_field_tell
Get current field offset of a result pointer
Description
Object oriented styleint mysqli_result->current_field ;
Procedural styleint mysqli_field_tell(mysqli_result result);
Returns the position of the field cursor used for the last mysqli_fetch_field
call. This value can be used as an argument to mysqli_field_seek
.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
.
Return Values
Returns current offset of field cursor.
Examples
Example 20.175. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5'; if ($result = $mysqli->query($query)) { /* Get field information for all columns */ while ($finfo = $result->fetch_field()) { /* get fieldpointer offset */ $currentfield = $result->current_field; printf('Column %d:\n', $currentfield); printf('Name: %s\n', $finfo->name); printf('Table: %s\n', $finfo->table); printf('max. Len: %d\n', $finfo->max_length); printf('Flags: %d\n', $finfo->flags); printf('Type: %d\n\n', $finfo->type); } $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.176. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5'; if ($result = mysqli_query($link, $query)) { /* Get field information for all fields */ while ($finfo = mysqli_fetch_field($result)) { /* get fieldpointer offset */ $currentfield = mysqli_field_tell($result); printf('Column %d:\n', $currentfield); printf('Name: %s\n', $finfo->name); printf('Table: %s\n', $finfo->table); printf('max. Len: %d\n', $finfo->max_length); printf('Flags: %d\n', $finfo->flags); printf('Type: %d\n\n', $finfo->type); } mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Column 1: Name: Name Table: Country max. Len: 11 Flags: 1 Type: 254 Column 2: Name: SurfaceArea Table: Country max. Len: 10 Flags: 32769 Type: 4
See Also
mysqli_fetch_field
|
mysqli_field_seek |
mysqli_result::data_seek
, mysqli_data_seek
mysqli_result::data_seek
mysqli_data_seek
Adjusts the result pointer to an arbitary row in the result
Description
Object oriented stylebool mysqli_result::data_seek(int offset);
Procedural stylebool mysqli_data_seek(mysqli_result result,
int offset);
The mysqli_data_seek
function seeks to an arbitrary result pointer specified by the offset
in the result set.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
. offset
-
The field offset. Must be between zero and the total number of rows minus one (0..
mysqli_num_rows
- 1).
Return Values
Returns TRUE
on success or FALSE
on failure.
Notes
NoteThis function can only be used with buffered results attained from the use of the mysqli_store_result
or mysqli_query
functions.
Examples
Example 20.177. Object oriented style
<?php /* Open a connection */ $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER BY Name'; if ($result = $mysqli->query( $query)) { /* seek to row no. 400 */ $result->data_seek(399); /* fetch row */ $row = $result->fetch_row(); printf ('City: %s Countrycode: %s\n', $row[0], $row[1]); /* free result set*/ $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.178. Procedural style
<?php /* Open a connection */ $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (!$link) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER BY Name'; if ($result = mysqli_query($link, $query)) { /* seek to row no. 400 */ mysqli_data_seek($result, 399); /* fetch row */ $row = mysqli_fetch_row($result); printf ('City: %s Countrycode: %s\n', $row[0], $row[1]); /* free result set*/ mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
City: Benin City Countrycode: NGA
See Also
mysqli_store_result
|
mysqli_fetch_row
|
mysqli_fetch_array
|
mysqli_fetch_assoc
|
mysqli_fetch_object
|
mysqli_query
|
mysqli_num_rows |
mysqli_result::fetch_all
, mysqli_fetch_all
mysqli_result::fetch_all
mysqli_fetch_all
Fetches all result rows as an associative array, a numeric array, or both
Description
Object oriented stylemixed mysqli_result::fetch_all(int resulttype= =MYSQLI_NUM);
Procedural stylemixed mysqli_fetch_all(mysqli_result result,
int resulttype= =MYSQLI_NUM);
mysqli_fetch_all
fetches all result rows and returns the result set as an associative array, a numeric array, or both.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
. resulttype
-
This optional parameter is a constant indicating what type of array should be produced from the current row data. The possible values for this parameter are the constants
MYSQLI_ASSOC
,MYSQLI_NUM
, orMYSQLI_BOTH
.
Return Values
Returns an array of associative or numeric arrays holding result rows.
MySQL Native Driver Only
Available only with mysqlnd.
As mysqli_fetch_all
returns all the rows as an array in a single step, it may consume more memory than some similar functions such as mysqli_fetch_array
, which only returns one row at a time from the result set. Further, if you need to iterate over the result set, you will need a looping construct that will further impact performance. For these reasons mysqli_fetch_all
should only be used in those situations where the fetched result set will be sent to another layer for processing.
See Also
mysqli_fetch_array
|
mysqli_query |
mysqli_result::fetch_array
, mysqli_fetch_array
mysqli_result::fetch_array
mysqli_fetch_array
Fetch a result row as an associative, a numeric array, or both
Description
Object oriented stylemixed mysqli_result::fetch_array(int resulttype= =MYSQLI_BOTH);
Procedural stylemixed mysqli_fetch_array(mysqli_result result,
int resulttype= =MYSQLI_BOTH);
Returns an array that corresponds to the fetched row or NULL
if there are no more rows for the resultset represented by the result
parameter.
mysqli_fetch_array
is an extended version of the mysqli_fetch_row
function. In addition to storing the data in the numeric indices of the result array, the mysqli_fetch_array
function can also store the data in associative indices, using the field names of the result set as keys.Note
Field names returned by this function are case-sensitive.Note
This function sets NULL fields to the PHP NULL
value.
If two or more columns of the result have the same field names, the last column will take precedence and overwrite the earlier data. In order to access multiple columns with the same name, the numerically indexed version of the row must be used.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
. resulttype
-
This optional parameter is a constant indicating what type of array should be produced from the current row data. The possible values for this parameter are the constants
MYSQLI_ASSOC
,MYSQLI_NUM
, orMYSQLI_BOTH
.By using the
MYSQLI_ASSOC
constant this function will behave identically to themysqli_fetch_assoc
, whileMYSQLI_NUM
will behave identically to themysqli_fetch_row
function. The final optionMYSQLI_BOTH
will create a single array with the attributes of both.
Return Values
Returns an array of strings that corresponds to the fetched row or NULL
if there are no more rows in resultset.
Examples
Example 20.179. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3'; $result = $mysqli->query($query); /* numeric array */ $row = $result->fetch_array(MYSQLI_NUM); printf ('%s (%s)\n', $row[0], $row[1]); /* associative array */ $row = $result->fetch_array(MYSQLI_ASSOC); printf ('%s (%s)\n', $row['Name'], $row['CountryCode']); /* associative and numeric array */ $row = $result->fetch_array(MYSQLI_BOTH); printf ('%s (%s)\n', $row[0], $row['CountryCode']); /* free result set */ $result->close(); /* close connection */ $mysqli->close(); ?>
Example 20.180. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3'; $result = mysqli_query($link, $query); /* numeric array */ $row = mysqli_fetch_array($result, MYSQLI_NUM); printf ('%s (%s)\n', $row[0], $row[1]); /* associative array */ $row = mysqli_fetch_array($result, MYSQLI_ASSOC); printf ('%s (%s)\n', $row['Name'], $row['CountryCode']); /* associative and numeric array */ $row = mysqli_fetch_array($result, MYSQLI_BOTH); printf ('%s (%s)\n', $row[0], $row['CountryCode']); /* free result set */ mysqli_free_result($result); /* close connection */ mysqli_close($link); ?>
The above examples will output:
Kabul (AFG) Qandahar (AFG) Herat (AFG)
See Also
mysqli_fetch_assoc
|
mysqli_fetch_row
|
mysqli_fetch_object
|
mysqli_query
|
mysqli_data_seek |
mysqli_result::fetch_assoc
, mysqli_fetch_assoc
mysqli_result::fetch_assoc
mysqli_fetch_assoc
Fetch a result row as an associative array
Description
Object oriented stylearray mysqli_result::fetch_assoc();
Procedural stylearray mysqli_fetch_assoc(mysqli_result result);
Returns an associative array that corresponds to the fetched row or NULL
if there are no more rows.Note
Field names returned by this function are case-sensitive.Note
This function sets NULL fields to the PHP NULL
value.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
.
Return Values
Returns an associative array of strings representing the fetched row in the result set, where each key in the array represents the name of one of the result set's columns or NULL
if there are no more rows in resultset.
If two or more columns of the result have the same field names, the last column will take precedence. To access the other column(s) of the same name, you either need to access the result with numeric indices by using mysqli_fetch_row
or add alias names.
Examples
Example 20.181. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5'; if ($result = $mysqli->query($query)) { /* fetch associative array */ while ($row = $result->fetch_assoc()) { printf ('%s (%s)\n', $row['Name'], $row['CountryCode']); } /* free result set */ $result->free(); } /* close connection */ $mysqli->close(); ?>
Example 20.182. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5'; if ($result = mysqli_query($link, $query)) { /* fetch associative array */ while ($row = mysqli_fetch_assoc($result)) { printf ('%s (%s)\n', $row['Name'], $row['CountryCode']); } /* free result set */ mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Pueblo (USA) Arvada (USA) Cape Coral (USA) Green Bay (USA) Santa Clara (USA)
Example 20.183. A mysqli_result
example comparing iterator
usage
<?php $c = mysqli_connect('127.0.0.1','user', 'pass'); // Using iterators (support was added with PHP 5.4) foreach ( $c->query('SELECT user,host FROM mysql.user') as $row ) { printf(''%s'@'%s'\n', $row['user'], $row['host']); } echo '\n==================\n'; // Not using iterators $result = $c->query('SELECT user,host FROM mysql.user'); while ($row = $result->fetch_assoc()) { printf(''%s'@'%s'\n', $row['user'], $row['host']); } ?>
The above example will output something similar to:
'root'@'192.168.1.1' 'root'@'127.0.0.1' 'dude'@'localhost' 'lebowski'@'localhost' ================== 'root'@'192.168.1.1' 'root'@'127.0.0.1' 'dude'@'localhost' 'lebowski'@'localhost'
See Also
mysqli_fetch_array
|
mysqli_fetch_row
|
mysqli_fetch_object
|
mysqli_query
|
mysqli_data_seek |
mysqli_result::fetch_field_direct
, mysqli_fetch_field_direct
mysqli_result::fetch_field_direct
mysqli_fetch_field_direct
Fetch meta-data for a single field
Description
Object oriented styleobject mysqli_result::fetch_field_direct(int fieldnr);
Procedural styleobject mysqli_fetch_field_direct(mysqli_result result,
int fieldnr);
Returns an object which contains field definition information from the specified result set.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
. fieldnr
-
The field number. This value must be in the range from
0
tonumber of fields - 1
.
Return Values
Returns an object which contains field definition information or FALSE
if no field information for specified fieldnr
is available.
Table 20.21. Object attributes
Attribute | Description |
---|---|
name | The name of the column |
orgname | Original column name if an alias was specified |
table | The name of the table this field belongs to (if not calculated) |
orgtable | Original table name if an alias was specified |
def | The default value for this field, represented as a string |
max_length | The maximum width of the field for the result set. |
length | The width of the field, as specified in the table definition. |
charsetnr | The character set number for the field. |
flags | An integer representing the bit-flags for the field. |
type | The data type used for this field |
decimals | The number of decimals used (for integer fields) |
Examples
Example 20.184. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5'; if ($result = $mysqli->query($query)) { /* Get field information for column 'SurfaceArea' */ $finfo = $result->fetch_field_direct(1); printf('Name: %s\n', $finfo->name); printf('Table: %s\n', $finfo->table); printf('max. Len: %d\n', $finfo->max_length); printf('Flags: %d\n', $finfo->flags); printf('Type: %d\n', $finfo->type); $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.185. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5'; if ($result = mysqli_query($link, $query)) { /* Get field information for column 'SurfaceArea' */ $finfo = mysqli_fetch_field_direct($result, 1); printf('Name: %s\n', $finfo->name); printf('Table: %s\n', $finfo->table); printf('max. Len: %d\n', $finfo->max_length); printf('Flags: %d\n', $finfo->flags); printf('Type: %d\n', $finfo->type); mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Name: SurfaceArea Table: Country max. Len: 10 Flags: 32769 Type: 4
See Also
mysqli_num_fields
|
mysqli_fetch_field
|
mysqli_fetch_fields |
mysqli_result::fetch_field
, mysqli_fetch_field
mysqli_result::fetch_field
mysqli_fetch_field
Returns the next field in the result set
Description
Object oriented styleobject mysqli_result::fetch_field();
Procedural styleobject mysqli_fetch_field(mysqli_result result);
Returns the definition of one column of a result set as an object. Call this function repeatedly to retrieve information about all columns in the result set.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
.
Return Values
Returns an object which contains field definition information or FALSE
if no field information is available.
Table 20.22. Object properties
Property | Description |
---|---|
name | The name of the column |
orgname | Original column name if an alias was specified |
table | The name of the table this field belongs to (if not calculated) |
orgtable | Original table name if an alias was specified |
def | Reserved for default value, currently always '' |
db | Database (since PHP 5.3.6) |
catalog | The catalog name, always 'def' (since PHP 5.3.6) |
max_length | The maximum width of the field for the result set. |
length | The width of the field, as specified in the table definition. |
charsetnr | The character set number for the field. |
flags | An integer representing the bit-flags for the field. |
type | The data type used for this field |
decimals | The number of decimals used (for integer fields) |
Examples
Example 20.186. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5'; if ($result = $mysqli->query($query)) { /* Get field information for all columns */ while ($finfo = $result->fetch_field()) { printf('Name: %s\n', $finfo->name); printf('Table: %s\n', $finfo->table); printf('max. Len: %d\n', $finfo->max_length); printf('Flags: %d\n', $finfo->flags); printf('Type: %d\n\n', $finfo->type); } $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.187. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5'; if ($result = mysqli_query($link, $query)) { /* Get field information for all fields */ while ($finfo = mysqli_fetch_field($result)) { printf('Name: %s\n', $finfo->name); printf('Table: %s\n', $finfo->table); printf('max. Len: %d\n', $finfo->max_length); printf('Flags: %d\n', $finfo->flags); printf('Type: %d\n\n', $finfo->type); } mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Name: Name Table: Country max. Len: 11 Flags: 1 Type: 254 Name: SurfaceArea Table: Country max. Len: 10 Flags: 32769 Type: 4
See Also
mysqli_num_fields
|
mysqli_fetch_field_direct
|
mysqli_fetch_fields
|
mysqli_field_seek |
mysqli_result::fetch_fields
, mysqli_fetch_fields
mysqli_result::fetch_fields
mysqli_fetch_fields
Returns an array of objects representing the fields in a result set
Description
Object oriented stylearray mysqli_result::fetch_fields();
Procedural stylearray mysqli_fetch_fields(mysqli_result result);
This function serves an identical purpose to the mysqli_fetch_field
function with the single difference that, instead of returning one object at a time for each field, the columns are returned as an array of objects.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
.
Return Values
Returns an array of objects which contains field definition information or FALSE
if no field information is available.
Table 20.23. Object properties
Property | Description |
---|---|
name | The name of the column |
orgname | Original column name if an alias was specified |
table | The name of the table this field belongs to (if not calculated) |
orgtable | Original table name if an alias was specified |
max_length | The maximum width of the field for the result set. |
length | The width of the field, as specified in the table definition. |
charsetnr | The character set number for the field. |
flags | An integer representing the bit-flags for the field. |
type | The data type used for this field |
decimals | The number of decimals used (for integer fields) |
Examples
Example 20.188. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5'; if ($result = $mysqli->query($query)) { /* Get field information for all columns */ $finfo = $result->fetch_fields(); foreach ($finfo as $val) { printf('Name: %s\n', $val->name); printf('Table: %s\n', $val->table); printf('max. Len: %d\n', $val->max_length); printf('Flags: %d\n', $val->flags); printf('Type: %d\n\n', $val->type); } $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.189. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5'; if ($result = mysqli_query($link, $query)) { /* Get field information for all columns */ $finfo = mysqli_fetch_fields($result); foreach ($finfo as $val) { printf('Name: %s\n', $val->name); printf('Table: %s\n', $val->table); printf('max. Len: %d\n', $val->max_length); printf('Flags: %d\n', $val->flags); printf('Type: %d\n\n', $val->type); } mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Name: Name Table: Country max. Len: 11 Flags: 1 Type: 254 Name: SurfaceArea Table: Country max. Len: 10 Flags: 32769 Type: 4
See Also
mysqli_num_fields
|
mysqli_fetch_field_direct
|
mysqli_fetch_field |
mysqli_result::fetch_object
, mysqli_fetch_object
mysqli_result::fetch_object
mysqli_fetch_object
Returns the current row of a result set as an object
Description
Object oriented styleobject mysqli_result::fetch_object(string class_name,
array params);
Procedural styleobject mysqli_fetch_object(mysqli_result result,
string class_name,
array params);
The mysqli_fetch_object
will return the current row result set as an object where the attributes of the object represent the names of the fields found within the result set.
Note that mysqli_fetch_object
sets the properties of the object before calling the object constructor.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
. class_name
-
The name of the class to instantiate, set the properties of and return. If not specified, a
stdClass
object is returned. params
-
An optional array of parameters to pass to the constructor for
class_name
objects.
Return Values
Returns an object with string properties that corresponds to the fetched row or NULL
if there are no more rows in resultset.Note
Field names returned by this function are case-sensitive.Note
This function sets NULL fields to the PHP NULL
value.
Changelog
Version | Description |
---|---|
5.0.0 | Added the ability to return as a different object. |
Examples
Example 20.190. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5'; if ($result = $mysqli->query($query)) { /* fetch object array */ while ($obj = $result->fetch_object()) { printf ('%s (%s)\n', $obj->Name, $obj->CountryCode); } /* free result set */ $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.191. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5'; if ($result = mysqli_query($link, $query)) { /* fetch associative array */ while ($obj = mysqli_fetch_object($result)) { printf ('%s (%s)\n', $obj->Name, $obj->CountryCode); } /* free result set */ mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Pueblo (USA) Arvada (USA) Cape Coral (USA) Green Bay (USA) Santa Clara (USA)
See Also
mysqli_fetch_array
|
mysqli_fetch_assoc
|
mysqli_fetch_row
|
mysqli_query
|
mysqli_data_seek |
mysqli_result::fetch_row
, mysqli_fetch_row
mysqli_result::fetch_row
mysqli_fetch_row
Get a result row as an enumerated array
Description
Object oriented stylemixed mysqli_result::fetch_row();
Procedural stylemixed mysqli_fetch_row(mysqli_result result);
Fetches one row of data from the result set and returns it as an enumerated array, where each column is stored in an array offset starting from 0 (zero). Each subsequent call to this function will return the next row within the result set, or NULL
if there are no more rows.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
.
Return Values
mysqli_fetch_row
returns an array of strings that corresponds to the fetched row or NULL
if there are no more rows in result set.Note
This function sets NULL fields to the PHP NULL
value.
Examples
Example 20.192. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5'; if ($result = $mysqli->query($query)) { /* fetch object array */ while ($row = $result->fetch_row()) { printf ('%s (%s)\n', $row[0], $row[1]); } /* free result set */ $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.193. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 50,5'; if ($result = mysqli_query($link, $query)) { /* fetch associative array */ while ($row = mysqli_fetch_row($result)) { printf ('%s (%s)\n', $row[0], $row[1]); } /* free result set */ mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Pueblo (USA) Arvada (USA) Cape Coral (USA) Green Bay (USA) Santa Clara (USA)
See Also
mysqli_fetch_array
|
mysqli_fetch_assoc
|
mysqli_fetch_object
|
mysqli_query
|
mysqli_data_seek |
mysqli_result::$field_count
, mysqli_num_fields
mysqli_result::$field_count
mysqli_num_fields
Get the number of fields in a result
Description
Object oriented styleint mysqli_result->field_count ;
Procedural styleint mysqli_num_fields(mysqli_result result);
Returns the number of fields from specified result set.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
.
Return Values
The number of fields from a result set.
Examples
Example 20.194. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if ($result = $mysqli->query('SELECT * FROM City ORDER BY ID LIMIT 1')) { /* determine number of fields in result set */ $field_cnt = $result->field_count; printf('Result set has %d fields.\n', $field_cnt); /* close result set */ $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.195. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if ($result = mysqli_query($link, 'SELECT * FROM City ORDER BY ID LIMIT 1')) { /* determine number of fields in result set */ $field_cnt = mysqli_num_fields($result); printf('Result set has %d fields.\n', $field_cnt); /* close result set */ mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Result set has 5 fields.
See Also
mysqli_fetch_field |
mysqli_result::field_seek
, mysqli_field_seek
mysqli_result::field_seek
mysqli_field_seek
Set result pointer to a specified field offset
Description
Object oriented stylebool mysqli_result::field_seek(int fieldnr);
Procedural stylebool mysqli_field_seek(mysqli_result result,
int fieldnr);
Sets the field cursor to the given offset. The next call to mysqli_fetch_field
will retrieve the field definition of the column associated with that offset.Note
To seek to the beginning of a row, pass an offset value of zero.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
. fieldnr
-
The field number. This value must be in the range from
0
tonumber of fields - 1
.
Return Values
Returns TRUE
on success or FALSE
on failure.
Examples
Example 20.196. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5'; if ($result = $mysqli->query($query)) { /* Get field information for 2nd column */ $result->field_seek(1); $finfo = $result->fetch_field(); printf('Name: %s\n', $finfo->name); printf('Table: %s\n', $finfo->table); printf('max. Len: %d\n', $finfo->max_length); printf('Flags: %d\n', $finfo->flags); printf('Type: %d\n\n', $finfo->type); $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.197. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5'; if ($result = mysqli_query($link, $query)) { /* Get field information for 2nd column */ mysqli_field_seek($result, 1); $finfo = mysqli_fetch_field($result); printf('Name: %s\n', $finfo->name); printf('Table: %s\n', $finfo->table); printf('max. Len: %d\n', $finfo->max_length); printf('Flags: %d\n', $finfo->flags); printf('Type: %d\n\n', $finfo->type); mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Name: SurfaceArea Table: Country max. Len: 10 Flags: 32769 Type: 4
See Also
mysqli_fetch_field |
mysqli_result::free
, mysqli_free_result
mysqli_result::free
mysqli_free_result
Frees the memory associated with a result
Description
Object oriented stylevoid mysqli_result::free();
void mysqli_result::close();
void mysqli_result::free_result();
Procedural stylevoid mysqli_free_result(mysqli_result result);
Frees the memory associated with the result.Note
You should always free your result with mysqli_free_result
, when your result object is not needed anymore.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
.
Return Values
No value is returned.
See Also
mysqli_query
|
mysqli_stmt_store_result
|
mysqli_store_result
|
mysqli_use_result |
mysqli_result::$lengths
, mysqli_fetch_lengths
mysqli_result::$lengths
mysqli_fetch_lengths
Returns the lengths of the columns of the current row in the result set
Description
Object oriented stylearray mysqli_result->lengths ;
Procedural stylearray mysqli_fetch_lengths(mysqli_result result);
The mysqli_fetch_lengths
function returns an array containing the lengths of every column of the current row within the result set.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
.
Return Values
An array of integers representing the size of each column (not including any terminating null characters). FALSE
if an error occurred.
mysqli_fetch_lengths
is valid only for the current row of the result set. It returns FALSE
if you call it before calling mysqli_fetch_row/array/object or after retrieving all rows in the result.
Examples
Example 20.198. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT * from Country ORDER BY Code LIMIT 1'; if ($result = $mysqli->query($query)) { $row = $result->fetch_row(); /* display column lengths */ foreach ($result->lengths as $i => $val) { printf('Field %2d has Length %2d\n', $i+1, $val); } $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.199. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } $query = 'SELECT * from Country ORDER BY Code LIMIT 1'; if ($result = mysqli_query($link, $query)) { $row = mysqli_fetch_row($result); /* display column lengths */ foreach (mysqli_fetch_lengths($result) as $i => $val) { printf('Field %2d has Length %2d\n', $i+1, $val); } mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Field 1 has Length 3 Field 2 has Length 5 Field 3 has Length 13 Field 4 has Length 9 Field 5 has Length 6 Field 6 has Length 1 Field 7 has Length 6 Field 8 has Length 4 Field 9 has Length 6 Field 10 has Length 6 Field 11 has Length 5 Field 12 has Length 44 Field 13 has Length 7 Field 14 has Length 3 Field 15 has Length 2
mysqli_result::$num_rows
, mysqli_num_rows
mysqli_result::$num_rows
mysqli_num_rows
Gets the number of rows in a result
Description
Object oriented styleint mysqli_result->num_rows ;
Procedural styleint mysqli_num_rows(mysqli_result result);
Returns the number of rows in the result set.
The behaviour of mysqli_num_rows
depends on whether buffered or unbuffered result sets are being used. For unbuffered result sets, mysqli_num_rows
will not return the correct number of rows until all the rows in the result have been retrieved.
Parameters
result
-
Procedural style only: A result set identifier returned by
mysqli_query
,mysqli_store_result
ormysqli_use_result
.
Return Values
Returns number of rows in the result set.Note
If the number of rows is greater than MAXINT
, the number will be returned as a string.
Examples
Example 20.200. Object oriented style
<?php $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if ($result = $mysqli->query('SELECT Code, Name FROM Country ORDER BY Name')) { /* determine number of rows result set */ $row_cnt = $result->num_rows; printf('Result set has %d rows.\n', $row_cnt); /* close result set */ $result->close(); } /* close connection */ $mysqli->close(); ?>
Example 20.201. Procedural style
<?php $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } if ($result = mysqli_query($link, 'SELECT Code, Name FROM Country ORDER BY Name')) { /* determine number of rows result set */ $row_cnt = mysqli_num_rows($result); printf('Result set has %d rows.\n', $row_cnt); /* close result set */ mysqli_free_result($result); } /* close connection */ mysqli_close($link); ?>
The above examples will output:
Result set has 239 rows.
See Also
mysqli_affected_rows
|
mysqli_store_result
|
mysqli_use_result
|
mysqli_query |
The mysqli_driver class (mysqli_driver
)
mysqli_driver::embedded_server_end
,mysqli_embedded_server_end
mysqli_driver::embedded_server_start
,mysqli_embedded_server_start
MySQLi Driver.
mysqli_driver {
mysqli_driver Propertiespublic readonly string client_info ;
public readonly string client_version ;
public readonly string driver_version ;
public readonly string embedded ;
public bool reconnect ;
public int report_mode ;
Methodsvoid mysqli_driver::embedded_server_end();
bool mysqli_driver::embedded_server_start(bool start,
array arguments,
array groups);
}
client_info
-
The Client API header version
client_version
-
The Client version
driver_version
-
The MySQLi Driver version
embedded
-
Whether MySQLi Embedded support is enabled
reconnect
-
Allow or prevent reconnect (see the mysqli.reconnect INI directive)
report_mode
-
Set to
MYSQLI_REPORT_OFF
,MYSQLI_REPORT_ALL
or any combination ofMYSQLI_REPORT_STRICT
(throw Exceptions for errors),MYSQLI_REPORT_ERROR
(report errors) andMYSQLI_REPORT_INDEX
(errors regarding indexes). See alsomysqli_report
.
mysqli_driver::embedded_server_end
, mysqli_embedded_server_end
mysqli_driver::embedded_server_end
mysqli_embedded_server_end
Stop embedded server
Description
Object oriented stylevoid mysqli_driver::embedded_server_end();
Procedural stylevoid mysqli_embedded_server_end();
Warning
This function is currently not documented; only its argument list is available.
mysqli_driver::embedded_server_start
, mysqli_embedded_server_start
mysqli_driver::embedded_server_start
mysqli_embedded_server_start
Initialize and start embedded server
Description
Object oriented stylebool mysqli_driver::embedded_server_start(bool start,
array arguments,
array groups);
Procedural stylebool mysqli_embedded_server_start(bool start,
Warning
array arguments,
array groups);
This function is currently not documented; only its argument list is available.
The mysqli_warning class (mysqli_warning
)
Represents a MariaDB warning.
mysqli_warning {
mysqli_warning Propertiespublic message ;
public sqlstate ;
public errno ;
Methodspublic mysqli_warning::__construct();
public void mysqli_warning::next();
}
message
-
Message string
sqlstate
-
SQL state
errno
-
Error number
mysqli_warning::__construct
mysqli_warning::__construct
The __construct purpose
Description
public mysqli_warning::__construct();
Warning
This function is currently not documented; only its argument list is available.
Parameters
This function has no parameters.
Return Values
mysqli_warning::next
mysqli_warning::next
The next purpose
Description
public void mysqli_warning::next();
Warning
This function is currently not documented; only its argument list is available.
Parameters
This function has no parameters.
Return Values
The mysqli_sql_exception class (mysqli_sql_exception
)
The mysqli exception handling class.
mysqli_sql_exception {
mysqli_sql_exception, extends RuntimeException Propertiesprotected code ;
protected sqlstate ;
}
message
-
The error message.
file
-
The file with the error.
line
-
The line with the error.
code
-
The code causing the error.
sqlstate
-
The sql state with the error.
Aliases and deprecated Mysqli Functions
mysqli_bind_param
mysqli_bind_result
mysqli_client_encoding
mysqli_connect
mysqli_disable_rpl_parse
mysqli_enable_reads_from_master
mysqli_enable_rpl_parse
mysqli_escape_string
mysqli_execute
mysqli_fetch
mysqli_get_cache_stats
mysqli_get_metadata
mysqli_master_query
mysqli_param_count
mysqli_report
mysqli_rpl_parse_enabled
mysqli_rpl_probe
mysqli_send_long_data
mysqli_set_opt
mysqli_slave_query
mysqli_bind_param
mysqli_bind_param
Alias for
mysqli_stmt_bind_param
Description
This function is an alias of mysqli_stmt_bind_param
.
Notes
Notemysqli_bind_param
is deprecated and will be removed.
See Also
mysqli_stmt_bind_param |
mysqli_bind_result
mysqli_bind_result
Alias for
mysqli_stmt_bind_result
Description
This function is an alias of mysqli_stmt_bind_result
.
Notes
Notemysqli_bind_result
is deprecated and will be removed.
See Also
mysqli_stmt_bind_result |
mysqli_client_encoding
mysqli_client_encoding
Alias of
mysqli_character_set_name
Description
This function is an alias of mysqli_character_set_name
.
See Also
mysqli_real_escape_string |
mysqli_connect
mysqli_connect
Alias of
mysqli::__construct
Description
This function is an alias of: mysqli::__construct
mysqli_disable_rpl_parse
mysqli_disable_rpl_parse
Disable RPL parse
Description
bool mysqli_disable_rpl_parse(mysqli link);
Warning
This function is currently not documented; only its argument list is available.Warning
This function has been DEPRECATED and REMOVED as of PHP 5.3.0.
mysqli_enable_reads_from_master
mysqli_enable_reads_from_master
Enable reads from master
Description
bool mysqli_enable_reads_from_master(mysqli link);
Warning
This function is currently not documented; only its argument list is available.Warning
This function has been DEPRECATED and REMOVED as of PHP 5.3.0.
mysqli_enable_rpl_parse
mysqli_enable_rpl_parse
Enable RPL parse
Description
bool mysqli_enable_rpl_parse(mysqli link);
Warning
This function is currently not documented; only its argument list is available.Warning
This function has been DEPRECATED and REMOVED as of PHP 5.3.0.
mysqli_escape_string
mysqli_escape_string
Alias of
mysqli_real_escape_string
Description
This function is an alias of: mysqli_real_escape_string
.
mysqli_execute
mysqli_execute
Alias for
mysqli_stmt_execute
Description
This function is an alias of mysqli_stmt_execute
.
Notes
Notemysqli_execute
is deprecated and will be removed.
See Also
mysqli_stmt_execute |
mysqli_fetch
mysqli_fetch
Alias for
mysqli_stmt_fetch
Description
This function is an alias of mysqli_stmt_fetch
.
Notes
Notemysqli_fetch
is deprecated and will be removed.
See Also
mysqli_stmt_fetch |
mysqli_get_cache_stats
mysqli_get_cache_stats
Returns client Zval cache statistics
Description
array mysqli_get_cache_stats();
Warning
This function is currently not documented; only its argument list is available.
Returns client Zval cache statistics. Available only with mysqlnd.
Parameters
Return Values
Returns an array with client Zval cache stats if success, FALSE
otherwise.
Examples
Example 20.202. A mysqli_get_cache_stats
example
<?php $link = mysqli_connect(); print_r(mysqli_get_cache_stats()); ?>
The above example will output something similar to:
Array ( [bytes_sent] => 43 [bytes_received] => 80 [packets_sent] => 1 [packets_received] => 2 [protocol_overhead_in] => 8 [protocol_overhead_out] => 4 [bytes_received_ok_packet] => 11 [bytes_received_eof_packet] => 0 [bytes_received_rset_header_packet] => 0 [bytes_received_rset_field_meta_packet] => 0 [bytes_received_rset_row_packet] => 0 [bytes_received_prepare_response_packet] => 0 [bytes_received_change_user_packet] => 0 [packets_sent_command] => 0 [packets_received_ok] => 1 [packets_received_eof] => 0 [packets_received_rset_header] => 0 [packets_received_rset_field_meta] => 0 [packets_received_rset_row] => 0 [packets_received_prepare_response] => 0 [packets_received_change_user] => 0 [result_set_queries] => 0 [non_result_set_queries] => 0 [no_index_used] => 0 [bad_index_used] => 0 [slow_queries] => 0 [buffered_sets] => 0 [unbuffered_sets] => 0 [ps_buffered_sets] => 0 [ps_unbuffered_sets] => 0 [flushed_normal_sets] => 0 [flushed_ps_sets] => 0 [ps_prepared_never_executed] => 0 [ps_prepared_once_executed] => 0 [rows_fetched_from_server_normal] => 0 [rows_fetched_from_server_ps] => 0 [rows_buffered_from_client_normal] => 0 [rows_buffered_from_client_ps] => 0 [rows_fetched_from_client_normal_buffered] => 0 [rows_fetched_from_client_normal_unbuffered] => 0 [rows_fetched_from_client_ps_buffered] => 0 [rows_fetched_from_client_ps_unbuffered] => 0 [rows_fetched_from_client_ps_cursor] => 0 [rows_skipped_normal] => 0 [rows_skipped_ps] => 0 [copy_on_write_saved] => 0 [copy_on_write_performed] => 0 [command_buffer_too_small] => 0 [connect_success] => 1 [connect_failure] => 0 [connection_reused] => 0 [reconnect] => 0 [pconnect_success] => 0 [active_connections] => 1 [active_persistent_connections] => 0 [explicit_close] => 0 [implicit_close] => 0 [disconnect_close] => 0 [in_middle_of_command_close] => 0 [explicit_free_result] => 0 [implicit_free_result] => 0 [explicit_stmt_close] => 0 [implicit_stmt_close] => 0 [mem_emalloc_count] => 0 [mem_emalloc_ammount] => 0 [mem_ecalloc_count] => 0 [mem_ecalloc_ammount] => 0 [mem_erealloc_count] => 0 [mem_erealloc_ammount] => 0 [mem_efree_count] => 0 [mem_malloc_count] => 0 [mem_malloc_ammount] => 0 [mem_calloc_count] => 0 [mem_calloc_ammount] => 0 [mem_realloc_count] => 0 [mem_realloc_ammount] => 0 [mem_free_count] => 0 [proto_text_fetched_null] => 0 [proto_text_fetched_bit] => 0 [proto_text_fetched_tinyint] => 0 [proto_text_fetched_short] => 0 [proto_text_fetched_int24] => 0 [proto_text_fetched_int] => 0 [proto_text_fetched_bigint] => 0 [proto_text_fetched_decimal] => 0 [proto_text_fetched_float] => 0 [proto_text_fetched_double] => 0 [proto_text_fetched_date] => 0 [proto_text_fetched_year] => 0 [proto_text_fetched_time] => 0 [proto_text_fetched_datetime] => 0 [proto_text_fetched_timestamp] => 0 [proto_text_fetched_string] => 0 [proto_text_fetched_blob] => 0 [proto_text_fetched_enum] => 0 [proto_text_fetched_set] => 0 [proto_text_fetched_geometry] => 0 [proto_text_fetched_other] => 0 [proto_binary_fetched_null] => 0 [proto_binary_fetched_bit] => 0 [proto_binary_fetched_tinyint] => 0 [proto_binary_fetched_short] => 0 [proto_binary_fetched_int24] => 0 [proto_binary_fetched_int] => 0 [proto_binary_fetched_bigint] => 0 [proto_binary_fetched_decimal] => 0 [proto_binary_fetched_float] => 0 [proto_binary_fetched_double] => 0 [proto_binary_fetched_date] => 0 [proto_binary_fetched_year] => 0 [proto_binary_fetched_time] => 0 [proto_binary_fetched_datetime] => 0 [proto_binary_fetched_timestamp] => 0 [proto_binary_fetched_string] => 0 [proto_binary_fetched_blob] => 0 [proto_binary_fetched_enum] => 0 [proto_binary_fetched_set] => 0 [proto_binary_fetched_geometry] => 0 [proto_binary_fetched_other] => 0 )
See Also
Stats description |
mysqli_get_metadata
mysqli_get_metadata
Alias for
mysqli_stmt_result_metadata
Description
This function is an alias of mysqli_stmt_result_metadata
.
Notes
Notemysqli_get_metadata
is deprecated and will be removed.
See Also
mysqli_stmt_result_metadata |
mysqli_master_query
mysqli_master_query
Enforce execution of a query on the master in a master/slave setup
Description
bool mysqli_master_query(mysqli link,
string query);
Warning
This function is currently not documented; only its argument list is available.Warning
This function has been DEPRECATED and REMOVED as of PHP 5.3.0.
mysqli_param_count
mysqli_param_count
Alias for
mysqli_stmt_param_count
Description
This function is an alias of mysqli_stmt_param_count
.
Notes
Notemysqli_param_count
is deprecated and will be removed.
See Also
mysqli_stmt_param_count |
mysqli_report
mysqli_report
Enables or disables internal report functions
Description
bool mysqli_report(int flags);
mysqli_report
is a powerful function to improve your queries and code during development and testing phase. Depending on the flags it reports errors from mysqli function calls or queries which don't use an index (or use a bad index).
Parameters
flags
-
Table 20.24. Supported flags
Name Description MYSQLI_REPORT_OFF
Turns reporting off MYSQLI_REPORT_ERROR
Report errors from mysqli function calls MYSQLI_REPORT_STRICT
Throw mysqli_sql_exception
for errors instead of warningsMYSQLI_REPORT_INDEX
Report if no index or bad index was used in a query MYSQLI_REPORT_ALL
Set all options (report all)
Return Values
Returns TRUE
on success or FALSE
on failure.
Changelog
Version | Description |
---|---|
& 5.3.4 | Changing the reporting mode is now be per-request, rather than per-process. |
Examples
Example 20.203. Object oriented style
<?php /* activate reporting */ mysqli_report(MYSQLI_REPORT_ALL); $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world'); /* check connection */ if (mysqli_connect_errno()) { printf('Connect failed: %s\n', mysqli_connect_error()); exit(); } /* this query should report an error */ $result = $mysqli->query('SELECT Name FROM Nonexistingtable WHERE population > 50000'); /* this query should report a bad index */ $result = $mysqli->query('SELECT Name FROM City WHERE population > 50000'); $result->close(); $mysqli->close(); ?>
See Also
mysqli_driver::$report_mode |
mysqli_debug
|
mysqli_dump_debug_info |
mysqli_rpl_parse_enabled
mysqli_rpl_parse_enabled
Check if RPL parse is enabled
Description
int mysqli_rpl_parse_enabled(mysqli link);
Warning
This function is currently not documented; only its argument list is available.Warning
This function has been DEPRECATED and REMOVED as of PHP 5.3.0.
mysqli_rpl_probe
mysqli_rpl_probe
RPL probe
Description
bool mysqli_rpl_probe(mysqli link);
Warning
This function is currently not documented; only its argument list is available.Warning
This function has been DEPRECATED and REMOVED as of PHP 5.3.0.
mysqli_send_long_data
mysqli_send_long_data
Alias for
mysqli_stmt_send_long_data
Description
This function is an alias of mysqli_stmt_send_long_data
.
Notes
Notemysqli_send_long_data
is deprecated and will be removed.
See Also
mysqli_stmt_send_long_data |
mysqli_set_opt
mysqli_set_opt
Alias of
mysqli_options
Description
This function is an alias of mysqli_options
.
mysqli_slave_query
mysqli_slave_query
Force execution of a query on a slave in a master/slave setup
Description
bool mysqli_slave_query(mysqli link,
string query);
Warning
This function is currently not documented; only its argument list is available.Warning
This function has been DEPRECATED and REMOVED as of PHP 5.3.0.
MySQL Native Driver (Mysqlnd
)
- Overview
- Installation
- Runtime Configuration
- Persistent Connections
- Statistics
- Notes
- MySQL Native Driver Plugin API
- Installation
MySQL Native Driver is a replacement for the MariaDB Client Library (libmysql). MariaDB Native Driver is part of the official PHP sources as of PHP 5.3.0.
The MariaDB database extensions MariaDB extension, mysqli
and PDO MYSQL all communicate with the MariaDB server. In the past, this was done by the extension using the services provided by the MariaDB Client Library. The extensions were compiled against the MariaDB Client Library in order to use its client-server protocol.
With MariaDB Native Driver there is now an alternative, as the MariaDB database extensions can be compiled to use MariaDB Native Driver instead of the MariaDB Client Library.
MySQL Native Driver is written in C as a PHP extension.
Overview
What it is not
Although MariaDB Native Driver is written as a PHP extension, it is important to note that it does not provide a new API to the PHP programmer. The programmer APIs for MariaDB database connectivity are provided by the MariaDB extension, mysqli
and PDO MYSQL. These extensions can now use the services of MariaDB Native Driver to communicate with the MariaDB Server. Therefore, you should not think of MariaDB Native Driver as an API.
Why use it?
Using the MariaDB Native Driver offers a number of advantages over using the MariaDB Client Library.
The older MariaDB Client Library was written by MariaDB Foundation (now Oracle Corporation) and so was released under the MariaDB license. This ultimately led to MariaDB support being disabled by default in PHP. However, the MariaDB Native Driver has been developed as part of the PHP project, and is therefore released under the PHP license. This removes licensing issues that have been problematic in the past.
Also, in the past, you needed to build the MariaDB database extensions against a copy of the MariaDB Client Library. This typically meant you needed to have MariaDB installed on a machine where you were building the PHP source code. Also, when your PHP application was running, the MariaDB database extensions would call down to the MariaDB Client library file at run time, so the file needed to be installed on your system. With MariaDB Native Driver that is no longer the case as it is included as part of the standard distribution. So you do not need MariaDB installed in order to build PHP or run PHP database applications.
Because MariaDB Native Driver is written as a PHP extension, it is tightly coupled to the workings of PHP. This leads to gains in efficiency, especially when it comes to memory usage, as the driver uses the PHP memory management system. It also supports the PHP memory limit. Using MariaDB Native Driver leads to comparable or better performance than using MariaDB Client Library, it always ensures the most efficient use of memory. One example of the memory efficiency is the fact that when using the MariaDB Client Library, each row is stored in memory twice, whereas with the MariaDB Native Driver each row is only stored once in memory.
Special features
MySQL Native Driver also provides some special features not available when the MariaDB database extensions use MariaDB Client Library. These special features are listed below:
- Improved persistent connections
- The special function
mysqli_fetch_all
- Performance statistics calls:
mysqli_get_cache_stats
,mysqli_get_client_stats
,mysqli_get_connection_stats
The performance statistics facility can prove to be very useful in identifying performance bottlenecks.
MySQL Native Driver also allows for persistent connections when used with the mysqli
extension.
SSL Support
MySQL Native Driver has supported SSL since PHP version 5.3.3
Compressed Protocol Support
As of PHP 5.3.2 MariaDB Native Driver supports the compressed client server protocol. MariaDB Native Driver did not support this in 5.3.0 and 5.3.1. Extensions such as ext/mysql
, ext/mysqli
, that are configured to use MariaDB Native Driver, can also take advantage of this feature. Note that PDO_MYSQL
does NOT support compression when used together with mysqlnd.
Named Pipes Support
Named pipes support for Windows was added in PHP version 5.4.0.
Installation
Changelog
Table 20.25. Changelog
Version | Description |
---|---|
5.3.0 | The MariaDB Native Driver was added, with support for all MariaDB extensions (i.e., mysql, mysqli and PDO_MYSQL). Passing in mysqlnd to the appropriate configure switch enables this support.
|
5.4.0 | The MariaDB Native Driver is now the default for all MariaDB extensions (i.e., mysql, mysqli and PDO_MYSQL). Passing in mysqlnd to configure is now optional. |
Installation on Unix
The MariaDB database extensions must be configured to use the MariaDB Client Library. In order to use the MariaDB Native Driver, PHP needs to be built specifying that the MariaDB database extensions are compiled with MariaDB Native Driver support. This is done through configuration options prior to building the PHP source code.
For example, to build the MariaDB extension, mysqli
and PDO MYSQL using the MariaDB Native Driver, the following command would be given:
./configure --with-mysql=mysqlnd \ --with-mysqli=mysqlnd \ --with-pdo-mysql=mysqlnd \ [other options]
Installation on Windows
In the official PHP Windows distributions from 5.3 onwards, MariaDB Native Driver is enabled by default, so no additional configuration is required to use it. All MariaDB database extensions will use MariaDB Native Driver in this case.
Runtime Configuration
The behaviour of these functions is affected by settings in php.ini
.
Table 20.26. MariaDB Native Driver Configuration Options
Name | Default | Changeable | Changelog |
---|---|---|---|
mysqlnd.collect_statistics | '1' | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
mysqlnd.collect_memory_statistics | '0' | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
mysqlnd.debug | '0' | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
mysqlnd.log_mask | 0 | PHP_INI_ALL | Available since PHP 5.3.0 |
mysqlnd.mempool_default_size | 16000 | PHP_INI_ALL | Available since PHP 5.3.3 |
mysqlnd.net_read_timeout | '31536000' | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
mysqlnd.net_cmd_buffer_size | - '2048', 5.3.1 - '4096' | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
mysqlnd.net_read_buffer_size | '32768' | PHP_INI_SYSTEM | Available since PHP 5.3.0. |
For further details and definitions of the PHP_INI_* modes, see the http://www.php.net/manual/en/configuration.changes.modes.
Here's a short explanation of the configuration directives.
mysqlnd.collect_statistics
boolean-
Enables the collection of various client statistics which can be accessed through
mysqli_get_client_stats
,mysqli_get_connection_stats
,mysqli_get_cache_stats
and are shown inmysqlnd
section of the output of thephpinfo
function as well.This configuration setting enables all MySQL Native Driver statistics except those relating to memory management.
mysqlnd.collect_memory_statistics
boolean-
Enable the collection of various memory statistics which can be accessed through
mysqli_get_client_stats
,mysqli_get_connection_stats
,mysqli_get_cache_stats
and are shown inmysqlnd
section of the output of thephpinfo
function as well.This configuration setting enables the memory management statistics within the overall set of MySQL Native Driver statistics.
mysqlnd.debug
string-
Records communication from all extensions using
mysqlnd
to the specified log file.The format of the directive is
mysqlnd.debug = 'option1[,parameter_option1][:option2[,parameter_option2]]'
.The options for the format string are as follows:
- A[,file] - Appends trace output to specified file. Also ensures that data is written after each write. This is done by closing and reopening the trace file (this is slow). It helps ensure a complete log file should the application crash.
- a[,file] - Appends trace output to the specified file.
- d - Enables output from DBUG_<N> macros for the current state. May be followed by a list of keywords which selects output only for the DBUG macros with that keyword. An empty list of keywords implies output for all macros.
- f[,functions] - Limits debugger actions to the specified list of functions. An empty list of functions implies that all functions are selected.
- F - Marks each debugger output line with the name of the source file containing the macro causing the output.
- i - Marks each debugger output line with the PID of the current process.
- L - Marks each debugger output line with the name of the source file line number of the macro causing the output.
- n - Marks each debugger output line with the current function nesting depth
- o[,file] - Similar to a[,file] but overwrites old file, and does not append.
- O[,file] - Similar to A[,file] but overwrites old file, and does not append.
- t[,N] - Enables function control flow tracing. The maximum nesting depth is specified by N, and defaults to 200.
- x - This option activates profiling.
Example:
d:t:x:O,/tmp/mysqlnd.trace
NoteThis feature is only available with a debug build of PHP. Works on Microsoft Windows if using a debug build of PHP and PHP was built using Microsoft Visual C version 9 and above.
mysqlnd.log_mask
integer-
Defines which queries will be logged. The default 0, which disables logging. Define using an integer, and not with PHP constants. For example, a value of 48 (16 + 32) will log slow queries which either use 'no good index' (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) or no index at all (SERVER_QUERY_NO_INDEX_USED = 32). A value of 2043 (1 + 2 + 8 + ... + 1024) will log all slow query types.
The types are as follows: SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2, SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32, SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256, SERVER_STATUS_NO_BACKSLASH_ESCAPES=512, and SERVER_QUERY_WAS_SLOW=1024.
mysqlnd.mempool_default_size
integer-
Default size of the mysqlnd memory pool, which is used by result sets.
mysqlnd.net_read_timeout
integer-
mysqlnd
and the MariaDB Client Library,libmysql
use different networking APIs.mysqlnd
uses PHP streams, whereaslibmysql
uses its own wrapper around the operating level network calls. PHP, by default, sets a read timeout of 60s for streams. This is set viaphp.ini
,default_socket_timeout
. This default applies to all streams that set no other timeout value.mysqlnd
does not set any other value and therefore connections of long running queries can be disconnected afterdefault_socket_timeout
seconds resulting in an error message "- MariaDB Server has gone away". The MariaDB Client Library sets a default timeout of 365 * 24 * 3600 seconds (1 year) and waits for other timeouts to occur, such as TCP/IP timeouts.mysqlnd
now uses the same very long timeout. The value is configurable through a newphp.ini
setting:mysqlnd.net_read_timeout
.mysqlnd.net_read_timeout
gets used by any extension (ext/mysql
,ext/mysqli
,PDO_MySQL
) that usesmysqlnd
.mysqlnd
tells PHP Streams to usemysqlnd.net_read_timeout
. Please note that there may be subtle differences betweenMYSQL_OPT_READ_TIMEOUT
from the MariaDB Client Library and PHP Streams, for exampleMYSQL_OPT_READ_TIMEOUT
is documented to work only for TCP/IP connections and, prior to MariaDB 5.1.2, only for Windows. PHP streams may not have this limitation. Please check the streams documentation, if in doubt. mysqlnd.net_cmd_buffer_size
long-
mysqlnd
allocates an internal command/network buffer ofmysqlnd.net_cmd_buffer_size
(inphp.ini
) bytes for every connection. If a MariaDB Client Server protocol command, for example,COM_QUERY
("normal" query), does not fit into the buffer,mysqlnd
will grow the buffer to the size required for sending the command. Whenever the buffer gets extended for one connection,command_buffer_too_small
will be incremented by one.If
mysqlnd
has to grow the buffer beyond its initial size ofmysqlnd.net_cmd_buffer_size
bytes for almost every connection, you should consider increasing the default size to avoid re-allocations.The default buffer size is 2048 bytes in PHP 5.3.0. In later versions the default is 4096 bytes. The default can changed either through the
php.ini
settingmysqlnd.net_cmd_buffer_size
or usingmysqli_options(MYSQLI_OPT_NET_CMD_BUFFER_SIZE, int size)
.It is recommended that the buffer size be set to no less than 4096 bytes because
mysqlnd
also uses it when reading certain communication packet from MySQL. In PHP 5.3.0,mysqlnd
will not grow the buffer if MariaDB sends a packet that is larger than the current size of the buffer. As a consequence,mysqlnd
is unable to decode the packet and the client application will get an error. There are only two situations when the packet can be larger than the 2048 bytes default ofmysqlnd.net_cmd_buffer_size
in PHP 5.3.0: the packet transports a very long error message, or the packet holds column meta data fromCOM_LIST_FIELD
(mysql_list_fields()
and the meta data come from a string column with a very long default value (>1900 bytes).As of PHP 5.3.2 mysqlnd does not allow setting buffers smaller than 4096 bytes.
The value can also be set using
mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)
. mysqlnd.net_read_buffer_size
long-
Maximum read chunk size in bytes when reading the body of a MariaDB command packet. The MariaDB client server protocol encapsulates all its commands in packets. The packets consist of a small header and a body with the actual payload. The size of the body is encoded in the header.
mysqlnd
reads the body in chunks ofMIN(header.size, mysqlnd.net_read_buffer_size)
bytes. If a packet body is larger thanmysqlnd.net_read_buffer_size
bytes,mysqlnd
has to callread()
multiple times.The value can also be set using
mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)
.
Persistent Connections
Using Persistent Connections
If mysqli
is used with mysqlnd
, when a persistent connection is created it generates a COM_CHANGE_USER
(mysql_change_user()
) call on the server. This ensures that re-authentication of the connection takes place.
As there is some overhead associated with the COM_CHANGE_USER
call, it is possible to switch this off at compile time. Reusing a persistent connection will then generate a COM_PING
(mysql_ping
) call to simply test the connection is reusable.
Generation of COM_CHANGE_USER
can be switched off with the compile flag MYSQLI_NO_CHANGE_USER_ON_PCONNECT
. For example:
shell# CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" ./configure --with-mysql=/usr/local/mysql/ --with-mysqli=/usr/local/mysql/bin/mysql_config --with-pdo-mysql=/usr/local/mysql/bin/mysql_config --enable-debug && make clean && make -j6
Or alternatively:
shell# export CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" shell# configure --whatever-option shell# make clean shell# make
Note that only mysqli
on mysqlnd
uses COM_CHANGE_USER
. Other extension-driver combinations use COM_PING
on initial use of a persistent connection.
Statistics
Using Statistical Data
MySQL Native Driver contains support for gathering statistics on the communication between the client and the server. The statistics gathered are of three main types:
- Client statistics
- Connection statistics
- Zval cache statistics
If you are using the mysqli
extension, these statistics can be obtained through three API calls:
Statistics are aggregated among all extensions that use MariaDB Native Driver. For example, when compiling both ext/mysql
and ext/mysqli
against MariaDB Native Driver, both function calls of ext/mysql
and ext/mysqli
will change the statistics. There is no way to find out how much a certain API call of any extension that has been compiled against MariaDB Native Driver has impacted a certain statistic. You can configure the PDO MariaDB Driver, ext/mysql
and ext/mysqli
to optionally use the MariaDB Native Driver. When doing so, all three extensions will change the statistics.
Accessing Client Statistics
To access client statistics, you need to call mysqli_get_client_stats
. The function call does not require any parameters.
The function returns an associative array that contains the name of the statistic as the key and the statistical data as the value.
Client statistics can also be accessed by calling the phpinfo
function.
Accessing Connection Statistics
To access connection statistics call mysqli_get_connection_stats
. This takes the database connection handle as the parameter.
The function returns an associative array that contains the name of the statistic as the key and the statistical data as the value.
Accessing Zval Cache Statistics
The MariaDB Native Driver also collects statistics from its internal Zval cache. These statistics can be accessed by calling mysqli_get_cache_stats
.
The Zval cache statistics obtained may lead to a tweaking of php.ini
settings related to the Zval cache, resulting in better performance.
Buffered and Unbuffered Result Sets
Result sets can be buffered or unbuffered. Using default settings, ext/mysql
and ext/mysqli
work with buffered result sets for normal (non prepared statement) queries. Buffered result sets are cached on the client. After the query execution all results are fetched from the MariaDB Server and stored in a cache on the client. The big advantage of buffered result sets is that they allow the server to free all resources allocated to a result set, once the results have been fetched by the client.
Unbuffered result sets on the other hand are kept much longer on the server. If you want to reduce memory consumption on the client, but increase load on the server, use unbuffered results. If you experience a high server load and the figures for unbuffered result sets are high, you should consider moving the load to the clients. Clients typically scale better than servers. "Load" does not only refer to memory buffers - the server also needs to keep other resources open, for example file handles and threads, before a result set can be freed.
Prepared Statements use unbuffered result sets by default. However, you can use mysqli_stmt_store_result
to enable buffered result sets.
Statistics returned by MariaDB Native Driver
The following tables show a list of statistics returned by the mysqli_get_client_stats
, mysqli_get_connection_stats
and mysqli_get_cache_stats
functions.
Network
Statistic | Scope | Description | Notes |
---|---|---|---|
bytes_sent
| Connection | Number of bytes sent from PHP to the MariaDB server | Can be used to check the efficiency of the compression protocol |
bytes_received
| Connection | Number of bytes received from MariaDB server | Can be used to check the efficiency of the compression protocol |
packets_sent
| Connection | Number of MariaDB Client Server protocol packets sent | Used for debugging Client Server protocol implementation |
packets_received
| Connection | Number of MariaDB Client Server protocol packets received | Used for debugging Client Server protocol implementation |
protocol_overhead_in
| Connection | MySQL Client Server protocol overhead in bytes for incoming traffic. Currently only the Packet Header (4 bytes) is considered as overhead. protocol_overhead_in = packets_received * 4 | Used for debugging Client Server protocol implementation |
protocol_overhead_out
| Connection | MySQL Client Server protocol overhead in bytes for outgoing traffic. Currently only the Packet Header (4 bytes) is considered as overhead. protocol_overhead_out = packets_sent * 4 | Used for debugging Client Server protocol implementation |
bytes_received_ok_packet
| Connection | Total size of bytes of MariaDB Client Server protocol OK packets received. OK packets can contain a status message. The length of the status message can vary and thus the size of an OK packet is not fixed. | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
packets_received_ok
| Connection | Number of MariaDB Client Server protocol OK packets received. | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
bytes_received_eof_packet
| Connection | Total size in bytes of MariaDB Client Server protocol EOF packets received. EOF can vary in size depending on the server version. Also, EOF can transport an error message. | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
packets_received_eof
| Connection | Number of MariaDB Client Server protocol EOF packets. Like with other packet statistics the number of packets will be increased even if PHP does not receive the expected packet but, for example, an error message. | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
bytes_received_rset_header_packet
| Connection | Total size in bytes of MariaDB Client Server protocol result set header packets. The size of the packets varies depending on the payload (LOAD LOCAL INFILE , INSERT , UPDATE , SELECT , error message).
| Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
packets_received_rset_header
| Connection | Number of MariaDB Client Server protocol result set header packets. | Used for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
bytes_received_rset_field_meta_packet
| Connection | Total size in bytes of MariaDB Client Server protocol result set meta data (field information) packets. Of course the size varies with the fields in the result set. The packet may also transport an error or an EOF packet in case of COM_LIST_FIELDS. | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
packets_received_rset_field_meta
| Connection | Number of MariaDB Client Server protocol result set meta data (field information) packets. | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
bytes_received_rset_row_packet
| Connection | Total size in bytes of MariaDB Client Server protocol result set row data packets. The packet may also transport an error or an EOF packet. You can reverse engineer the number of error and EOF packets by substracting rows_fetched_from_server_normal and rows_fetched_from_server_ps from bytes_received_rset_row_packet .
| Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
packets_received_rset_row
| Connection | Number of MariaDB Client Server protocol result set row data packets and their total size in bytes. | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
bytes_received_prepare_response_packet
| Connection | Total size in bytes of MariaDB Client Server protocol OK for Prepared Statement Initialization packets (prepared statement init packets). The packet may also transport an error. The packet size depends on the MariaDB version: 9 bytes with MariaDB and 12 bytes from MariaDB 5.0 on. There is no safe way to know how many errors happened. You may be able to guess that an error has occurred if, for example, you always connect to MariaDB 5.0 or newer and, bytes_received_prepare_response_packet != packets_received_prepare_response * 12. See also ps_prepared_never_executed , ps_prepared_once_executed .
| Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
packets_received_prepare_response
| Connection | Number of MariaDB Client Server protocol OK for Prepared Statement Initialization packets (prepared statement init packets). | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
bytes_received_change_user_packet
| Connection | Total size in bytes of MariaDB Client Server protocol COM_CHANGE_USER packets. The packet may also transport an error or EOF. | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
packets_received_change_user
| Connection | Number of MariaDB Client Server protocol COM_CHANGE_USER packets | Only useful for debugging CS protocol implementation. Note that the total size in bytes includes the size of the header packet (4 bytes, see protocol overhead). |
packets_sent_command
| Connection | Number of MariaDB Client Server protocol commands sent from PHP to MariaDB. There is no way to know which specific commands and how many of them have been sent. At its best you can use it to check if PHP has sent any commands to MariaDB to know if you can consider to disable MariaDB support in your PHP binary. There is also no way to reverse engineer the number of errors that may have occurred while sending data to MariaDB. The only error recoded is command_buffer_too_small (see below). | Only useful for debugging CS protocol implementation. |
bytes_received_real_data_normal
| Connection | Number of bytes of payload fetched by the PHP client from mysqlnd using the text protocol.
| This is the size of the actual data contained in result sets that do not originate from prepared statements and which have been fetched by the PHP client. Note that although a full result set may have been pulled from MariaDB by mysqlnd , this statistic only counts actual data pulled from mysqlnd by the PHP client. An example of a code sequence that will increase the value is as follows:
$mysqli = new mysqli(); $res = $mysqli->query('SELECT 'abc''); $res->fetch_assoc(); $res->close(); Every fetch operation will increase the value. The statistic will not be increased if the result set is only buffered on the client, but not fetched, such as in the following example: $mysqli = new mysqli(); $res = $mysqli->query('SELECT 'abc''); $res->close(); This statistic is available as of PHP version 5.3.4. |
bytes_received_real_data_ps
| Connection | Number of bytes of the payload fetched by the PHP client from mysqlnd using the prepared statement protocol.
| This is the size of the actual data contained in result sets that originate from prepared statements and which has been fetched by the PHP client. The value will not be increased if the result set is not subsequently read by the PHP client. Note that although a full result set may have been pulled from MariaDB by mysqlnd , this statistic only counts actual data pulled from mysqlnd by the PHP client. See also bytes_received_real_data_normal . This statistic is available as of PHP version 5.3.4. |
Result Set
Statistic | Scope | Description | Notes |
---|---|---|---|
result_set_queries
| Connection | Number of queries that have generated a result set. Examples of queries that generate a result set: SELECT , SHOW . The statistic will not be incremented if there is an error reading the result set header packet from the line.
| You may use it as an indirect measure for the number of queries PHP has sent to MySQL, for example, to identify a client that causes a high database load. |
non_result_set_queries
| Connection | Number of queries that did not generate a result set. Examples of queries that do not generate a result set: INSERT , UPDATE , LOAD DATA , SHOW . The statistic will not be incremented if there is an error reading the result set header packet from the line.
| You may use it as an indirect measure for the number of queries PHP has sent to MySQL, for example, to identify a client that causes a high database load. |
no_index_used
| Connection | Number of queries that have generated a result set but did not use an index (see also mysqld start option -log-queries-not-using-indexes). If you want these queries to be reported you can use mysqli_report(MYSQLI_REPORT_INDEX) to make ext/mysqli throw an exception. If you prefer a warning instead of an exception use mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT). | |
bad_index_used
| Connection | Number of queries that have generated a result set and did not use a good index (see also mysqld start option -log-slow-queries). | If you want these queries to be reported you can use mysqli_report(MYSQLI_REPORT_INDEX) to make ext/mysqli throw an exception. If you prefer a warning instead of an exception use mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT) |
slow_queries
| Connection | SQL statements that took more than long_query_time seconds to execute and required at least min_examined_row_limit rows to be examined.
| Not reported through mysqli_report
|
buffered_sets
| Connection | Number of buffered result sets returned by "normal" queries. "Normal" means "not prepared statement" in the following notes. | Examples of API calls that will buffer result sets on the client: mysql_query , mysqli_query , mysqli_store_result , mysqli_stmt_get_result . Buffering result sets on the client ensures that server resources are freed as soon as possible and it makes result set scrolling easier. The downside is the additional memory consumption on the client for buffering data. Note that mysqlnd (unlike the MariaDB Client Library) respects the PHP memory limit because it uses PHP internal memory management functions to allocate memory. This is also the reason why memory_get_usage reports a higer memory consumption when using mysqlnd instead of the MariaDB Client Library. memory_get_usage does not measure the memory consumption of the MariaDB Client Library at all because the MariaDB Client Library does not use PHP internal memory management functions monitored by the function!
|
unbuffered_sets
| Connection | Number of unbuffered result sets returned by normal (non prepared statement) queries. | Examples of API calls that will not buffer result sets on the client: mysqli_use_result
|
ps_buffered_sets
| Connection | Number of buffered result sets returned by prepared statements. By default prepared statements are unbuffered. | Examples of API calls that will not buffer result sets on the client: mysqli_stmt_store_result
|
ps_unbuffered_sets
| Connection | Number of unbuffered result sets returned by prepared statements. | By default prepared statements are unbuffered. |
flushed_normal_sets
| Connection | Number of result sets from normal (non prepared statement) queries with unread data which have been flushed silently for you. Flushing happens only with unbuffered result sets. | Unbuffered result sets must be fetched completely before a new query can be run on the connection otherwise MariaDB will throw an error. If the application does not fetch all rows from an unbuffered result set, mysqlnd does implicitly fetch the result set to clear the line. See also rows_skipped_normal , rows_skipped_ps . Some possible causes for an implicit flush:
|
flushed_ps_sets
| Connection | Number of result sets from prepared statements with unread data which have been flushed silently for you. Flushing happens only with unbuffered result sets. | Unbuffered result sets must be fetched completely before a new query can be run on the connection otherwise MariaDB will throw an error. If the application does not fetch all rows from an unbuffered result set, mysqlnd does implicitly fetch the result set to clear the line. See also rows_skipped_normal , rows_skipped_ps . Some possible causes for an implicit flush:
|
ps_prepared_never_executed
| Connection | Number of statements prepared but never executed. | Prepared statements occupy server resources. You should not prepare a statement if you do not plan to execute it. |
ps_prepared_once_executed
| Connection | Number of prepared statements executed only one. | One of the ideas behind prepared statements is that the same query gets executed over and over again (with different parameters) and some parsing and other preparation work can be saved, if statement execution is split up in separate prepare and execute stages. The idea is to prepare once and "cache" results, for example, the parse tree to be reused during multiple statement executions. If you execute a prepared statement only once the two stage processing can be inefficient compared to "normal" queries because all the caching means extra work and it takes (limited) server resources to hold the cached information. Consequently, prepared statements that are executed only once may cause performance hurts. |
rows_fetched_from_server_normal , rows_fetched_from_server_ps
| Connection | Total number of result set rows successfully fetched from MariaDB regardless if the client application has consumed them or not. Some of the rows may not have been fetched by the client application but have been flushed implicitly. | See also packets_received_rset_row
|
rows_buffered_from_client_normal , rows_buffered_from_client_ps
| Connection | Total number of succesfully buffered rows originating from a 'normal' query or a prepared statement. This is the number of rows that have been fetched from MariaDB and buffered on client. Note that there are two distinct statistics on rows that have been buffered (MySQL to mysqlnd internal buffer) and buffered rows that have been fetched by the client application (mysqlnd internal buffer to client application). If the number of buffered rows is higher than the number of fetched buffered rows it can mean that the client application runs queries that cause larger result sets than needed resulting in rows not read by the client. | Examples of queries that will buffer results: mysqli_query , mysqli_store_result
|
rows_fetched_from_client_normal_buffered , rows_fetched_from_client_ps_buffered
| Connection | Total number of rows fetched by the client from a buffered result set created by a normal query or a prepared statement. | |
rows_fetched_from_client_normal_unbuffered , rows_fetched_from_client_ps_unbuffered
| Connection | Total number of rows fetched by the client from a unbuffered result set created by a 'normal' query or a prepared statement. | |
rows_fetched_from_client_ps_cursor
| Connection | Total number of rows fetch by the client from a cursor created by a prepared statement. | |
rows_skipped_normal , rows_skipped_ps
| Connection | Reserved for future use (currently not supported) | |
copy_on_write_saved , copy_on_write_performed
| Process | With mysqlnd, variables returned by the extensions point into mysqlnd internal network result buffers. If you do not change the variables, fetched data will be kept only once in memory. If you change the variables, mysqlnd has to perform a copy-on-write to protect the internal network result buffers from being changed. With the MariaDB Client Library you always hold fetched data twice in memory. Once in the internal MariaDB Client Library buffers and once in the variables returned by the extensions. In theory mysqlnd can save up to 40% memory. However, note that the memory saving cannot be measured using memory_get_usage .
| |
explicit_free_result , implicit_free_result
| Connection, Process (only during prepared statement cleanup) | Total number of freed result sets. | The free is always considered explicit but for result sets created by an init command, for example, mysqli_options(MYSQLI_INIT_COMMAND , ...)
|
proto_text_fetched_null , proto_text_fetched_bit , proto_text_fetched_tinyint proto_text_fetched_short , proto_text_fetched_int24 , proto_text_fetched_int proto_text_fetched_bigint , proto_text_fetched_decimal , proto_text_fetched_float proto_text_fetched_double , proto_text_fetched_date , proto_text_fetched_year proto_text_fetched_time , proto_text_fetched_datetime , proto_text_fetched_timestamp proto_text_fetched_string , proto_text_fetched_blob , proto_text_fetched_enum proto_text_fetched_set , proto_text_fetched_geometry , proto_text_fetched_other
| Connection | Total number of columns of a certain type fetched from a normal query (MySQL text protocol). | Mapping from C API / MariaDB meta data type to statistics name:
Note that the MYSQL_*-type constants may not be associated with the very same SQL column types in every version of MySQL. |
proto_binary_fetched_null , proto_binary_fetched_bit , proto_binary_fetched_tinyint proto_binary_fetched_short , proto_binary_fetched_int24 , proto_binary_fetched_int , proto_binary_fetched_bigint , proto_binary_fetched_decimal , proto_binary_fetched_float , proto_binary_fetched_double , proto_binary_fetched_date , proto_binary_fetched_year , proto_binary_fetched_time , proto_binary_fetched_datetime , proto_binary_fetched_timestamp , proto_binary_fetched_string , proto_binary_fetched_blob , proto_binary_fetched_enum , proto_binary_fetched_set , proto_binary_fetched_geometry , proto_binary_fetched_other
| Connection | Total number of columns of a certain type fetched from a prepared statement (MySQL binary protocol). | For type mapping see proto_text_* described in the preceding text. |
Connection
Statistic | Scope | Description | Notes |
---|---|---|---|
connect_success , connect_failure
| Connection | Total number of successful / failed connection attempt. | Reused connections and all other kinds of connections are included. |
reconnect
| Process | Total number of (real_)connect attempts made on an already opened connection handle. | The code sequence $link = new mysqli(...); $link->real_connect(...) will cause a reconnect. But $link = new mysqli(...); $link->connect(...) will not because $link->connect(...) will explicitly close the existing connection before a new connection is established.
|
pconnect_success
| Connection | Total number of successful persistent connection attempts. | Note that connect_success holds the sum of successful persistent and non-persistent connection attempts. The number of successful non-persistent connection attempts is connect_success - pconnect_success .
|
active_connections
| Connection | Total number of active persistent and non-persistent connections. | |
active_persistent_connections
| Connection | Total number of active persistent connections. | The total number of active non-persistent connections is active_connections - active_persistent_connections .
|
explicit_close
| Connection | Total number of explicitly closed connections (ext/mysqli only). | Examples of code snippets that cause an explicit close :
$link = new mysqli(...); $link->close(...) $link = new mysqli(...); $link->connect(...) |
implicit_close
| Connection | Total number of implicitly closed connections (ext/mysqli only). | Examples of code snippets that cause an implicit close :
|
disconnect_close
| Connection | Connection failures indicated by the C API call mysql_real_connect during an attempt to establish a connection.
| It is called disconnect_close because the connection handle passed to the C API call will be closed.
|
in_middle_of_command_close
| Process | A connection has been closed in the middle of a command execution (outstanding result sets not fetched, after sending a query and before retrieving an answer, while fetching data, while transferring data with LOAD DATA). | Unless you use asynchronous queries this should only happen if your script stops unexpectedly and PHP shuts down the connections for you. |
init_command_executed_count
| Connection | Total number of init command executions, for example, mysqli_options(MYSQLI_INIT_COMMAND , ...) .
| The number of successful executions is init_command_executed_count - init_command_failed_count .
|
init_command_failed_count
| Connection | Total number of failed init commands. |
COM_* Commands
Statistic | Scope | Description | Notes |
---|---|---|---|
com_quit , com_init_db , com_query , com_field_list , com_create_db , com_drop_db , com_refresh , com_shutdown , com_statistics , com_process_info , com_connect , com_process_kill , com_debug , com_ping , com_time , com_delayed_insert , com_change_user , com_binlog_dump , com_table_dump , com_connect_out , com_register_slave , com_stmt_prepare , com_stmt_execute , com_stmt_send_long_data , com_stmt_close , com_stmt_reset , com_stmt_set_option , com_stmt_fetch , com_daemon
| Connection | Total number of attempts to send a certain COM_* command from PHP to MariaDB. | The statistics are incremented after checking the line and immediately before sending the corresponding MariaDB client server protocol packet. If mysqlnd fails to send the packet over the wire the statistics will not be decremented. In case of a failure mysqlnd emits a PHP warning "Error while sending %s packet. PID=%d."
Usage examples:
|
Miscellaneous
Statistic | Scope | Description | Notes |
---|---|---|---|
explicit_stmt_close , implicit_stmt_close
| Process | Total number of close prepared statements. | A close is always considered explicit but for a failed prepare. |
mem_emalloc_count , mem_emalloc_ammount , mem_ecalloc_count , mem_ecalloc_ammount , mem_erealloc_count , mem_erealloc_ammount , mem_efree_count , mem_malloc_count , mem_malloc_ammount , mem_calloc_count , mem_calloc_ammount , mem_realloc_count , mem_realloc_ammount , mem_free_count
| Process | Memory management calls. | Development only. |
command_buffer_too_small
| Connection | Number of network command buffer extensions while sending commands from PHP to MariaDB. | mysqlnd allocates an internal command/network buffer of mysqlnd.net_cmd_buffer_size (php.ini ) bytes for every connection. If a MariaDB Client Server protocol command, for example, COM_QUERY (normal query), does not fit into the buffer, mysqlnd will grow the buffer to what is needed for sending the command. Whenever the buffer gets extended for one connection command_buffer_too_small will be incremented by one.
If mysqlnd has to grow the buffer beyond its initial size of The default buffer size is 2048 bytes in PHP 5.3.0. In future versions the default will be 4kB or larger. The default can changed either through the It is recommended to set the buffer size to no less than 4096 bytes because mysqlnd also uses it when reading certain communication packet from MySQL. In PHP 5.3.0, mysqlnd will not grow the buffer if MariaDB sends a packet that is larger than the current size of the buffer. As a consequence mysqlnd is unable to decode the packet and the client application will get an error. There are only two situations when the packet can be larger than the 2048 bytes default of As of PHP 5.3.2 mysqlnd does not allow setting buffers smaller than 4096 bytes. |
connection_reused
|
Notes
This section provides a collection of miscellaneous notes on MariaDB Native Driver usage.
- Using
mysqlnd
means using PHP streams for underlying connectivity. Formysqlnd
, the PHP streams documentation (http://www.php.net/manual/en/book.stream) should be consulted on such details as timeout settings, not the documentation for the MariaDB Client Library.
MySQL Native Driver Plugin API
- A comparison of mysqlnd plugins with MariaDB Proxy
- Obtaining the mysqlnd plugin API
- MySQL Native Driver Plugin Architecture
- The mysqlnd plugin API
- Getting started building a mysqlnd plugin
- Obtaining the mysqlnd plugin API
The MariaDB Native Driver Plugin API is a feature of MariaDB Native Driver, or mysqlnd
. Mysqlnd
plugins operate in the layer between PHP applications and the MariaDB server. This is comparable to MariaDB Proxy. MariaDB Proxy operates on a layer between any MariaDB client application, for example, a PHP application and, the MariaDB server. Mysqlnd
plugins can undertake typical MariaDB Proxy tasks such as load balancing, monitoring and performance optimizations. Due to the different architecture and location, mysqlnd
plugins do not have some of MariaDB Proxy's disadvantages. For example, with plugins, there is no single point of failure, no dedicated proxy server to deploy, and no new programming language to learn (Lua).
A mysqlnd
plugin can be thought of as an extension to mysqlnd
. Plugins can intercept the majority of mysqlnd
functions. The mysqlnd
functions are called by the PHP MariaDB extensions such as ext/mysql
, ext/mysqli
, and PDO_MYSQL
. As a result, it is possible for a mysqlnd
plugin to intercept all calls made to these extensions from the client application.
Internal mysqlnd
function calls can also be intercepted, or replaced. There are no restrictions on manipulating mysqlnd
internal function tables. It is possible to set things up so that when certain mysqlnd
functions are called by the extensions that use mysqlnd
, the call is directed to the appropriate function in the mysqlnd
plugin. The ability to manipulate mysqlnd
internal function tables in this way allows maximum flexibility for plugins.
Mysqlnd
plugins are in fact PHP Extensions, written in C, that use the mysqlnd
plugin API (which is built into MariaDB Native Driver, mysqlnd
). Plugins can be made 100% transparent to PHP applications. No application changes are needed because plugins operate on a different layer. The mysqlnd
plugin can be thought of as operating in a layer below mysqlnd
.
The following list represents some possible applications of mysqlnd
plugins.
- Load Balancing
- Read/Write Splitting. An example of this is the PECL/mysqlnd_ms (Master Slave) extension. This extension splits read/write queries for a replication setup.
- Failover
- Round-Robin, least loaded
- Monitoring
- Query Logging
- Query Analysis
- Query Auditing. An example of this is the PECL/mysqlnd_sip (SQL Injection Protection) extension. This extension inspects queries and executes only those that are allowed according to a ruleset.
- Performance
- Caching. An example of this is the PECL/mysqlnd_qc (Query Cache) extension.
- Throttling
- Sharding. An example of this is the PECL/mysqlnd_mc (Multi Connect) extension. This extension will attempt to split a SELECT statement into n-parts, using SELECT ... LIMIT part_1, SELECT LIMIT part_n. It sends the queries to distinct MariaDB servers and merges the result at the client.
MySQL Native Driver Plugins Available
There are a number of mysqlnd plugins already available. These include:
- PECL/mysqlnd_mc - Multi Connect plugin.
- PECL/mysqlnd_ms - Master Slave plugin.
- PECL/mysqlnd_qc - Query Cache plugin.
- PECL/mysqlnd_pscache - Prepared Statement Handle Cache plugin.
- PECL/mysqlnd_sip - SQL Injection Protection plugin.
- PECL/mysqlnd_uh - User Handler plugin.
A comparison of mysqlnd plugins with MariaDB Proxy
Mysqlnd
plugins and MariaDB Proxy are different technologies using different approaches. Both are valid tools for solving a variety of common tasks such as load balancing, monitoring, and performance enhancements. An important difference is that MariaDB Proxy works with all MariaDB clients, whereas mysqlnd
plugins are specific to PHP applications.
As a PHP Extension, a mysqlnd
plugin gets installed on the PHP application server, along with the rest of PHP. MariaDB Proxy can either be run on the PHP application server or can be installed on a dedicated machine to handle multiple PHP application servers.
Deploying MariaDB Proxy on the application server has two advantages:
- No single point of failure
- Easy to scale out (horizontal scale out, scale by client)
MySQL Proxy (and mysqlnd
plugins) can solve problems easily which otherwise would have required changes to existing applications.
However, MariaDB Proxy does have some disadvantages:
- MySQL Proxy is a new component and technology to master and deploy.
- MySQL Proxy requires knowledge of the Lua scripting language.
MySQL Proxy can be customized with C and Lua programming. Lua is the preferred scripting language of MariaDB Proxy. For most PHP experts Lua is a new language to learn. A mysqlnd
plugin can be written in C. It is also possible to write plugins in PHP using PECL/mysqlnd_uh.
MySQL Proxy runs as a daemon - a background process. MariaDB Proxy can recall earlier decisions, as all state can be retained. However, a mysqlnd
plugin is bound to the request-based lifecycle of PHP. MariaDB Proxy can also share one-time computed results among multiple application servers. A mysqlnd
plugin would need to store data in a persistent medium to be able to do this. Another daemon would need to be used for this purpose, such as Memcache. This gives MariaDB Proxy an advantage in this case.
MySQL Proxy works on top of the wire protocol. With MariaDB Proxy you have to parse and reverse engineer the MariaDB Client Server Protocol. Actions are limited to those that can be achieved by manipulating the communication protocol. If the wire protocol changes (which happens very rarely) MariaDB Proxy scripts would need to be changed as well.
Mysqlnd
plugins work on top of the C API, which mirrors the libmysql
client and Connector/C APIs. This C API is basically a wrapper around the MariaDB Client Server protocol, or wire protocol, as it is sometimes called. You can intercept all C API calls. PHP makes use of the C API, therefore you can hook all PHP calls, without the need to program at the level of the wire protocol.
Mysqlnd
implements the wire protocol. Plugins can therefore parse, reverse engineer, manipulate and even replace the communication protocol. However, this is usually not required.
As plugins allow you to create implementations that use two levels (C API and wire protocol), they have greater flexibility than MariaDB Proxy. If a mysqlnd
plugin is implemented using the C API, any subsequent changes to the wire protocol do not require changes to the plugin itself.
Obtaining the mysqlnd plugin API
The mysqlnd
plugin API is simply part of the MariaDB Native Driver PHP extension, ext/mysqlnd
. Development started on the mysqlnd
plugin API in December 2009. It is developed as part of the PHP source repository, and as such is available to the public either via SVN, or through source snapshot downloads.
The following table shows PHP versions and the corresponding mysqlnd
version contained within.
PHP Version | MySQL Native Driver version |
---|---|
5.3.0 | 5.0.5 |
5.3.1 | 5.0.5 |
5.3.2 | 5.0.7 |
5.3.3 | 5.0.7 |
5.3.4 | 5.0.7 |
Plugin developers can determine the mysqlnd
version through accessing MYSQLND_VERSION
, which is a string of the format "mysqlnd 5.0.7-dev - 091210 - $Revision: 300535", or through MYSQLND_VERSION_ID
, which is an integer such as 50007. Developers can calculate the version number as follows:
Version (part) | Example |
---|---|
Major*10000 | 5*10000 = 50000 |
Minor*100 | 0*100 = 0 |
Patch | 7 = 7 |
MYSQLND_VERSION_ID | 50007 |
During development, developers should refer to the mysqlnd
version number for compatibility and version tests, as several iterations of mysqlnd
could occur during the lifetime of a PHP development branch with a single PHP version number.
MySQL Native Driver Plugin Architecture
This section provides an overview of the mysqlnd
plugin architecture.
MySQL Native Driver Overview
Before developing mysqlnd
plugins, it is useful to know a little of how mysqlnd
itself is organized. Mysqlnd
consists of the following modules:
Modules Statistics | mysqlnd_statistics.c |
Connection | mysqlnd.c |
Resultset | mysqlnd_result.c |
Resultset Metadata | mysqlnd_result_meta.c |
Statement | mysqlnd_ps.c |
Network | mysqlnd_net.c |
Wire protocol | mysqlnd_wireprotocol.c |
C Object Oriented Paradigm
At the code level, mysqlnd
uses a C pattern for implementing object orientation.
In C you use a struct
to represent an object. Members of the struct represent object properties. Struct members pointing to functions represent methods.
Unlike with other languages such as C++ or Java, there are no fixed rules on inheritance in the C object oriented paradigm. However, there are some conventions that need to be followed that will be discussed later.
The PHP Life Cycle
When considering the PHP life cycle there are two basic cycles:
- PHP engine startup and shutdown cycle
- Request cycle
When the PHP engine starts up it will call the module initialization (MINIT) function of each registered extension. This allows each module to setup variables and allocate resources that will exist for the lifetime of the PHP engine process. When the PHP engine shuts down it will call the module shutdown (MSHUTDOWN) function of each extension.
During the lifetime of the PHP engine it will receive a number of requests. Each request constitutes another life cycle. On each request the PHP engine will call the request initialization function of each extension. The extension can perform any variable setup and resource allocation required for request processing. As the request cycle ends the engine calls the request shutdown (RSHUTDOWN) function of each extension so the extension can perform any cleanup required.
How a plugin works
A mysqlnd
plugin works by intercepting calls made to mysqlnd
by extensions that use mysqlnd
. This is achieved by obtaining the mysqlnd
function table, backing it up, and replacing it by a custom function table, which calls the functions of the plugin as required.
The following code shows how the mysqlnd
function table is replaced:
/* a place to store orginal function table */ struct st_mysqlnd_conn_methods org_methods; void minit_register_hooks(TSRMLS_D) { /* active function table */ struct st_mysqlnd_conn_methods * current_methods = mysqlnd_conn_get_methods(); /* backup original function table */ memcpy(&org_methods, current_methods, sizeof(struct st_mysqlnd_conn_methods); /* install new methods */ current_methods->query = MYSQLND_METHOD(my_conn_class, query); }
Connection function table manipulations must be done during Module Initialization (MINIT). The function table is a global shared resource. In an multi-threaded environment, with a TSRM build, the manipulation of a global shared resource during the request processing will almost certainly result in conflicts.Note
Do not use any fixed-size logic when manipulating the mysqlnd
function table: new methods may be added at the end of the function table. The function table may change at any time in the future.
Calling parent methods
If the original function table entries are backed up, it is still possible to call the original function table entries - the parent methods.
In some cases, such as for Connection::stmt_init()
, it is vital to call the parent method prior to any other activity in the derived method.
MYSQLND_METHOD(my_conn_class, query)(MYSQLND *conn, const char *query, unsigned int query_len TSRMLS_DC) { php_printf('my_conn_class::query(query = %s)\n', query); query = 'SELECT 'query rewritten' FROM DUAL'; query_len = strlen(query); return org_methods.query(conn, query, query_len); /* return with call to parent */ }
Extending properties
A mysqlnd
object is represented by a C struct. It is not possible to add a member to a C struct at run time. Users of mysqlnd
objects cannot simply add properties to the objects.
Arbitrary data (properties) can be added to a mysqlnd
objects using an appropriate function of the mysqlnd_plugin_get_plugin_<object>_data()
family. When allocating an object mysqlnd
reserves space at the end of the object to hold a void *
pointer to arbitrary data. mysqlnd
reserves space for one void *
pointer per plugin.
The following table shows how to calculate the position of the pointer for a specific plugin:
Memory address | Contents |
0 | Beginning of the mysqlnd object C struct |
n | End of the mysqlnd object C struct |
n + (m x sizeof(void*)) | void* to object data of the m-th plugin |
If you plan to subclass any of the mysqlnd
object constructors, which is allowed, you must keep this in mind!
The following code shows extending properties:
/* any data we want to associate */ typedef struct my_conn_properties { unsigned long query_counter; } MY_CONN_PROPERTIES; /* plugin id */ unsigned int my_plugin_id; void minit_register_hooks(TSRMLS_D) { /* obtain unique plugin ID */ my_plugin_id = mysqlnd_plugin_register(); /* snip - see Extending Connection: methods */ } static MY_CONN_PROPERTIES** get_conn_properties(const MYSQLND *conn TSRMLS_DC) { MY_CONN_PROPERTIES** props; props = (MY_CONN_PROPERTIES**)mysqlnd_plugin_get_plugin_connection_data( conn, my_plugin_id); if (!props || !(*props)) { *props = mnd_pecalloc(1, sizeof(MY_CONN_PROPERTIES), conn->persistent); (*props)->query_counter = 0; } return props; }
The plugin developer is responsible for the management of plugin data memory.
Use of the mysqlnd
memory allocator is recommended for plugin data. These functions are named using the convention: mnd_*loc()
. The mysqlnd
allocator has some useful features, such as the ability to use a debug allocator in a non-debug build.
When and how to subclass
When to subclass? | Each instance has its own private function table? | How to subclass? | |
Connection (MYSQLND) | MINIT | No | mysqlnd_conn_get_methods() |
Resultset (MYSQLND_RES) | MINIT or later | Yes | mysqlnd_result_get_methods() or object method function table manipulation |
Resultset Meta (MYSQLND_RES_METADATA) | MINIT | No | mysqlnd_result_metadata_get_methods() |
Statement (MYSQLND_STMT) | MINIT | No | mysqlnd_stmt_get_methods() |
Network (MYSQLND_NET) | MINIT or later | Yes | mysqlnd_net_get_methods() or object method function table manipulation |
Wire protocol (MYSQLND_PROTOCOL) | MINIT or later | Yes | mysqlnd_protocol_get_methods() or object method function table manipulation |
You must not manipulate function tables at any time later than MINIT if it is not allowed according to the above table.
Some classes contain a pointer to the method function table. All instances of such a class will share the same function table. To avoid chaos, in particular in threaded environments, such function tables must only be manipulated during MINIT.
Other classes use copies of a globally shared function table. The class function table copy is created together with the object. Each object uses its own function table. This gives you two options: you can manipulate the default function table of an object at MINIT, and you can additionally refine methods of an object without impacting other instances of the same class.
The advantage of the shared function table approach is performance. There is no need to copy a function table for each and every object.
Constructors
Allocation, construction, reset | Can be modified? | Caller | |
Connection (MYSQLND) | mysqlnd_init() | No | mysqlnd_connect() |
Resultset(MYSQLND_RES) | Allocation:
Reset and re-initialized during:
| Yes, but call parent! |
|
Resultset Meta (MYSQLND_RES_METADATA) | Connection::result_meta_init() | Yes, but call parent! | Result::read_result_metadata() |
Statement (MYSQLND_STMT) | Connection::stmt_init() | Yes, but call parent! | Connection::stmt_init() |
Network (MYSQLND_NET) | mysqlnd_net_init() | No | Connection::init() |
Wire protocol (MYSQLND_PROTOCOL) | mysqlnd_protocol_init() | No | Connection::init() |
It is strongly recommended that you do not entirely replace a constructor. The constructors perform memory allocations. The memory allocations are vital for the mysqlnd
plugin API and the object logic of mysqlnd
. If you do not care about warnings and insist on hooking the constructors, you should at least call the parent constructor before doing anything in your constructor.
Regardless of all warnings, it can be useful to subclass constructors. Constructors are the perfect place for modifying the function tables of objects with non-shared object tables, such as Resultset, Network, Wire Protocol.
Destruction
Derived method must call parent? | Destructor | |
Connection | yes, after method execution | free_contents(), end_psession() |
Resultset | yes, after method execution | free_result() |
Resultset Meta | yes, after method execution | free() |
Statement | yes, after method execution | dtor(), free_stmt_content() |
Network | yes, after method execution | free() |
Wire protocol | yes, after method execution | free() |
The destructors are the appropriate place to free properties, mysqlnd_plugin_get_plugin_
.
<object>
_data()
The listed destructors may not be equivalent to the actual mysqlnd
method freeing the object itself. However, they are the best possible place for you to hook in and free your plugin data. As with constructors you may replace the methods entirely but this is not recommended. If multiple methods are listed in the above table you will need to hook all of the listed methods and free your plugin data in whichever method is called first by mysqlnd
.
The recommended method for plugins is to simply hook the methods, free your memory and call the parent implementation immediately following this.Caution
Due to a bug in PHP versions 5.3.0 to 5.3.3, plugins do not associate plugin data with a persistent connection. This is because ext/mysql
and ext/mysqli
do not trigger all the necessary mysqlnd
end_psession()
method calls and the plugin may therefore leak memory. This has been fixed in PHP 5.3.4.
The mysqlnd plugin API
The following is a list of functions provided in the mysqlnd
plugin API:
- mysqlnd_plugin_register()
- mysqlnd_plugin_count()
- mysqlnd_plugin_get_plugin_connection_data()
- mysqlnd_plugin_get_plugin_result_data()
- mysqlnd_plugin_get_plugin_stmt_data()
- mysqlnd_plugin_get_plugin_net_data()
- mysqlnd_plugin_get_plugin_protocol_data()
- mysqlnd_conn_get_methods()
- mysqlnd_result_get_methods()
- mysqlnd_result_meta_get_methods()
- mysqlnd_stmt_get_methods()
- mysqlnd_net_get_methods()
- mysqlnd_protocol_get_methods()
There is no formal definition of what a plugin is and how a plugin mechanism works.
Components often found in plugins mechanisms are:
- A plugin manager
- A plugin API
- Application services (or modules)
- Application service APIs (or module APIs)
The mysqlnd
plugin concept employs these features, and additionally enjoys an open architecture.
No Restrictions
A plugin has full access to the inner workings of mysqlnd
. There are no security limits or restrictions. Everything can be overwritten to implement friendly or hostile algorithms. It is recommended you only deploy plugins from a trusted source.
As discussed previously, plugins can use pointers freely. These pointers are not restricted in any way, and can point into another plugin's data. Simple offset arithmetic can be used to read another plugin's data.
It is recommended that you write cooperative plugins, and that you always call the parent method. The plugins should always cooperate with mysqlnd
itself.
Issues: an example of chaining and cooperation
Extension | mysqlnd.query() pointer | call stack if calling parent |
ext/mysqlnd | mysqlnd.query() | mysqlnd.query |
ext/mysqlnd_cache | mysqlnd_cache.query() |
|
ext/mysqlnd_monitor | mysqlnd_monitor.query() |
|
In this scenario, a cache (ext/mysqlnd_cache
) and a monitor (ext/mysqlnd_monitor
) plugin are loaded. Both subclass Connection::query()
. Plugin registration happens at MINIT
using the logic shown previously. PHP calls extensions in alphabetical order by default. Plugins are not aware of each other and do not set extension dependencies.
By default the plugins call the parent implementation of the query method in their derived version of the method.
PHP Extension Recap
This is a recap of what happens when using an example plugin, ext/mysqlnd_plugin
, which exposes the mysqlnd
C plugin API to PHP:
- Any PHP MariaDB application tries to establish a connection to 192.168.2.29
- The PHP application will either use
ext/mysql
,ext/mysqli
orPDO_MYSQL
. All three PHP MariaDB extensions usemysqlnd
to establish the connection to 192.168.2.29. Mysqlnd
calls its connect method, which has been subclassed byext/mysqlnd_plugin
.ext/mysqlnd_plugin
calls the userspace hookproxy::connect()
registered by the user.- The userspace hook changes the connection host IP from 192.168.2.29 to 127.0.0.1 and returns the connection established by
parent::connect()
. ext/mysqlnd_plugin
performs the equivalent ofparent::connect(127.0.0.1)
by calling the originalmysqlnd
method for establishing a connection.ext/mysqlnd
establishes a connection and returns toext/mysqlnd_plugin
.ext/mysqlnd_plugin
returns as well.- Whatever PHP MariaDB extension had been used by the application, it receives a connection to 127.0.0.1. The PHP MariaDB extension itself returns to the PHP application. The circle is closed.
Getting started building a mysqlnd plugin
It is important to remember that a mysqlnd
plugin is itself a PHP extension.
The following code shows the basic structure of the MINIT function that will be used in the typical mysqlnd
plugin:
/* my_php_mysqlnd_plugin.c */ static PHP_MINIT_FUNCTION(mysqlnd_plugin) { /* globals, ini entries, resources, classes */ /* register mysqlnd plugin */ mysqlnd_plugin_id = mysqlnd_plugin_register(); conn_m = mysqlnd_get_conn_methods(); memcpy(org_conn_m, conn_m, sizeof(struct st_mysqlnd_conn_methods)); conn_m->query = MYSQLND_METHOD(mysqlnd_plugin_conn, query); conn_m->connect = MYSQLND_METHOD(mysqlnd_plugin_conn, connect); }
/* my_mysqlnd_plugin.c */ enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, query)(/* ... */) { /* ... */ } enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, connect)(/* ... */) { /* ... */ }
Task analysis: from C to userspace
class proxy extends mysqlnd_plugin_connection { public function connect($host, ...) { .. } } mysqlnd_plugin_set_conn_proxy(new proxy());
Process:
- PHP: user registers plugin callback
- PHP: user calls any PHP MariaDB API to connect to MySQL
- C: ext/*mysql* calls mysqlnd method
- C: mysqlnd ends up in ext/mysqlnd_plugin
- C: ext/mysqlnd_plugin
- Calls userspace callback
- Or orginal
mysqlnd
method, if userspace callback not set
You need to carry out the following:
- Write a class 'mysqlnd_plugin_connection' in C
- Accept and register proxy object through 'mysqlnd_plugin_set_conn_proxy()'
- Call userspace proxy methods from C (optimization - zend_interfaces.h)
Userspace object methods can either be called using call_user_function()
or you can operate at a level closer to the Zend Engine and use zend_call_method()
.
Optimization: calling methods from C using zend_call_method
The following code snippet shows the prototype for the zend_call_method
function, taken from zend_interfaces.h
.
ZEND_API zval* zend_call_method( zval **object_pp, zend_class_entry *obj_ce, zend_function **fn_proxy, char *function_name, int function_name_len, zval **retval_ptr_ptr, int param_count, zval* arg1, zval* arg2 TSRMLS_DC );
Zend API supports only two arguments. You may need more, for example:
enum_func_status (*func_mysqlnd_conn__connect)( MYSQLND *conn, const char *host, const char * user, const char * passwd, unsigned int passwd_len, const char * db, unsigned int db_len, unsigned int port, const char * socket, unsigned int mysql_flags TSRMLS_DC );
To get around this problem you will need to make a copy of zend_call_method()
and add a facility for additional parameters. You can do this by creating a set of MY_ZEND_CALL_METHOD_WRAPPER
macros.
Calling PHP userspace
This code snippet shows the optimized method for calling a userspace function from C:
/* my_mysqlnd_plugin.c */ MYSQLND_METHOD(my_conn_class,connect)( MYSQLND *conn, const char *host /* ... */ TSRMLS_DC) { enum_func_status ret = FAIL; zval * global_user_conn_proxy = fetch_userspace_proxy(); if (global_user_conn_proxy) { /* call userspace proxy */ ret = MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, host, /*...*/); } else { /* or original mysqlnd method = do nothing, be transparent */ ret = org_methods.connect(conn, host, user, passwd, passwd_len, db, db_len, port, socket, mysql_flags TSRMLS_CC); } return ret; }
Calling userspace: simple arguments
/* my_mysqlnd_plugin.c */ MYSQLND_METHOD(my_conn_class,connect)( /* ... */, const char *host, /* ...*/) { /* ... */ if (global_user_conn_proxy) { /* ... */ zval* zv_host; MAKE_STD_ZVAL(zv_host); ZVAL_STRING(zv_host, host, 1); MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_host /*, ...*/); zval_ptr_dtor(&zv_host); /* ... */ } /* ... */ }
Calling userspace: structs as arguments
/* my_mysqlnd_plugin.c */ MYSQLND_METHOD(my_conn_class, connect)( MYSQLND *conn, /* ...*/) { /* ... */ if (global_user_conn_proxy) { /* ... */ zval* zv_conn; ZEND_REGISTER_RESOURCE(zv_conn, (void *)conn, le_mysqlnd_plugin_conn); MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_conn, zv_host /*, ...*/); zval_ptr_dtor(&zv_conn); /* ... */ } /* ... */ }
The first argument of many mysqlnd
methods is a C 'object'. For example, the first argument of the connect() method is a pointer to MYSQLND
. The struct MYSQLND represents a mysqlnd
connection object.
The mysqlnd
connection object pointer can be compared to a standard I/O file handle. Like a standard I/O file handle a mysqlnd
connection object shall be linked to the userspace using the PHP resource variable type.
From C to userspace and back
class proxy extends mysqlnd_plugin_connection { public function connect($conn, $host, ...) { /* 'pre' hook */ printf('Connecting to host = '%s'\n', $host); debug_print_backtrace(); return parent::connect($conn); } public function query($conn, $query) { /* 'post' hook */ $ret = parent::query($conn, $query); printf('Query = '%s'\n', $query); return $ret; } } mysqlnd_plugin_set_conn_proxy(new proxy());
PHP users must be able to call the parent implementation of an overwritten method.
As a result of subclassing it is possible to refine only selected methods and you can choose to have 'pre' or 'post' hooks.
Buildin class: mysqlnd_plugin_connection::connect()
/* my_mysqlnd_plugin_classes.c */ PHP_METHOD('mysqlnd_plugin_connection', connect) { /* ... simplified! ... */ zval* mysqlnd_rsrc; MYSQLND* conn; char* host; int host_len; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, 'rs', &mysqlnd_rsrc, &host, &host_len) == FAILURE) { RETURN_NULL(); } ZEND_FETCH_RESOURCE(conn, MYSQLND* conn, &mysqlnd_rsrc, -1, 'Mysqlnd Connection', le_mysqlnd_plugin_conn); if (PASS == org_methods.connect(conn, host, /* simplified! */ TSRMLS_CC)) RETVAL_TRUE; else RETVAL_FALSE; }
MySQL Functions (PDO_MYSQL) (MySQL (PDO)
)
PDO_MYSQL is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to MariaDB 3.x, 4.x and 5.x databases.
PDO_MYSQL will take advantage of native prepared statement support present in MariaDB and higher. If you're using an older version of the mysql client libraries, PDO will emulate them for you.Warning
Beware: Some MariaDB table types (storage engines) do not support transactions. When writing transactional database code using a table type that does not support transactions, MariaDB will pretend that a transaction was initiated successfully. In addition, any DDL queries issued will implicitly commit any pending transactions.
Use --with-pdo-mysql[=DIR]
to install the PDO MariaDB extension, where the optional [=DIR]
is the MariaDB base install directory. If mysqlnd is passed as [=DIR]
, then the MariaDB native driver will be used.
Optionally, the --with-mysql-sock[=DIR]
sets to location to the MariaDB unix socket pointer for all MariaDB extensions, including PDO_MYSQL. If unspecified, the default locations are searched.
Optionally, the --with-zlib-dir[=DIR]
is used to set the path to the libz install prefix.
$ ./configure --with-pdo-mysql --with-mysql-sock=/var/mysql/mysql.sock
SSL support is enabled using the appropriate PDO-MySQL constants, which is equivalent to calling the MySQL C API function mysql_ssl_set(). Also, SSL cannot be enabled with PDO::setAttribute
because the connection already exists. See also the MariaDB documentation about connecting to MariaDB with SSL.
Table 20.27. Changelog
Version | Description |
---|---|
5.4.0 | MySQL client libraries 4.1 and below are no longer supported. |
5.3.9 | Added SSL support with mysqlnd and OpenSSL. |
5.3.7 | Added SSL support with libmysql and OpenSSL. |
The constants below are defined by this driver, and will only be available when the extension has been either compiled into PHP or dynamically loaded at runtime. In addition, these driver-specific constants should only be used if you are using this driver. Using driver-specific attributes with another driver may result in unexpected behaviour. PDO::getAttribute
may be used to obtain the PDO_ATTR_DRIVER_NAME
attribute to check the driver, if your code can run against multiple drivers.
PDO::MYSQL_ATTR_USE_BUFFERED_QUERY
(integer)-
If this attribute is set to
TRUE
on aPDOStatement
, the MariaDB driver will use the buffered versions of the MariaDB API. If you're writing portable code, you should usePDOStatement::fetchAll
instead.Example 20.204. Forcing queries to be buffered in mysql
<?php if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') { $stmt = $db->prepare('select * from foo', array(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => true)); } else { die('my application only works with mysql; I should use \$stmt->fetchAll() instead'); } ?>
PDO::MYSQL_ATTR_LOCAL_INFILE
(integer)-
Enable
LOAD LOCAL INFILE
.Note, this constant can only be used in the
driver_options
array when constructing a new database handle. PDO::MYSQL_ATTR_INIT_COMMAND
(integer)-
Command to execute when connecting to the MariaDB server. Will automatically be re-executed when reconnecting.
Note, this constant can only be used in the
driver_options
array when constructing a new database handle. PDO::MYSQL_ATTR_READ_DEFAULT_FILE
(integer)-
Read options from the named option file instead of from
my.cnf
. This option is not available if mysqlnd is used, because mysqlnd does not read the mysql configuration files. PDO::MYSQL_ATTR_READ_DEFAULT_GROUP
(integer)-
Read options from the named group from
my.cnf
or the file specified withMYSQL_READ_DEFAULT_FILE
. This option is not available if mysqlnd is used, because mysqlnd does not read the mysql configuration files. PDO::MYSQL_ATTR_MAX_BUFFER_SIZE
(integer)-
Maximum buffer size. Defaults to 1 MiB. This constant is not supported when compiled against mysqlnd.
PDO::MYSQL_ATTR_DIRECT_QUERY
(integer)-
Perform direct queries, don't use prepared statements.
PDO::MYSQL_ATTR_FOUND_ROWS
(integer)-
Return the number of found (matched) rows, not the number of changed rows.
PDO::MYSQL_ATTR_IGNORE_SPACE
(integer)-
Permit spaces after function names. Makes all functions names reserved words.
PDO::MYSQL_ATTR_COMPRESS
(integer)-
Enable network communication compression. This is not supported when compiled against mysqlnd.
PDO::MYSQL_ATTR_SSL_CA
(integer)-
The file path to the SSL certificate authority.
This exists as of PHP 5.3.7.
PDO::MYSQL_ATTR_SSL_CAPATH
(integer)-
The file path to the directory that contains the trusted SSL CA certificates, which are stored in PEM format.
This exists as of PHP 5.3.7.
PDO::MYSQL_ATTR_SSL_CERT
(integer)-
The file path to the SSL certificate.
This exists as of PHP 5.3.7.
PDO::MYSQL_ATTR_CIPHER
(integer)-
A list of one or more permissible ciphers to use for SSL encryption, in a format understood by OpenSSL. For example:
DHE-RSA-AES256-SHA:AES128-SHA
This exists as of PHP 5.3.7.
PDO::MYSQL_ATTR_KEY
(integer)-
The file path to the SSL key.
This exists as of PHP 5.3.7.
The behaviour of these functions is affected by settings in php.ini
.
Table 20.28. PDO_MYSQL Configuration Options
Name | Default | Changeable |
---|---|---|
pdo_mysql.default_socket | '/tmp/mysql.sock' | PHP_INI_SYSTEM |
pdo_mysql.debug | NULL | PHP_INI_SYSTEM |
For further details and definitions of the PHP_INI_* modes, see the http://www.php.net/manual/en/configuration.changes.modes.
Here's a short explanation of the configuration directives.
pdo_mysql.default_socket
string-
Sets a Unix domain socket. This value can either be set at compile time if a domain socket is found at configure. This ini setting is Unix only.
pdo_mysql.debug
boolean-
Enables debugging for PDO_MYSQL. This setting is only available when PDO_MYSQL is compiled against mysqlnd and in PDO debug mode.
PDO_MYSQL DSN
PDO_MYSQL DSN
Connecting to MariaDB databases
Description
The PDO_MYSQL Data Source Name (DSN) is composed of the following elements:
- DSN prefix
-
The DSN prefix is
mysql:
. host
-
The hostname on which the database server resides.
port
-
The port number where the database server is listening.
dbname
-
The name of the database.
unix_socket
-
The MariaDB Unix socket (shouldn't be used with
host
orport
). charset
-
The character set.
Prior to PHP 5.3.6, this element was silently ignored. The same behaviour can be partly replicated with the
PDO::MYSQL_ATTR_INIT_COMMAND
driver option, as the following example shows.WarningThe method in the below example can only be used with character sets that share the same lower 7 bit representation as ASCII, such as ISO-8859-1 and UTF-8. Users using character sets that have different representations (such as UTF-16 or Big5) must use the
charset
option provided in PHP 5.3.6 and later versions.Example 20.205. Setting the connection character set to UTF-8 prior to PHP 5.3.6
<?php $dsn = 'mysql:host=localhost;dbname=testdb'; $username = 'username'; $password = 'password'; $options = array( PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8', ); $dbh = new PDO($dsn, $username, $password, $options); ?>
Changelog
Version | Description |
---|---|
5.3.6 | Prior to version 5.3.6, charset was ignored. |
Examples
Example 20.206. PDO_MYSQL DSN examples
The following example shows a PDO_MYSQL DSN for connecting to MariaDB databases:
mysql:host=localhost;dbname=testdb
More complete examples:
mysql:host=localhost;port=3307;dbname=testdb mysql:unix_socket=/tmp/mysql.sock;dbname=testdb
Notes
Unix only:When the host name is set to 'localhost'
, then the connection to the server is made thru a domain socket. If PDO_MYSQL is compiled against libmysql then the location of the socket file is at libmysql's compiled in location. If PDO_MYSQL is compiled against mysqlnd a default socket can be set thru the pdo_mysql.default_socket setting.
Connector/PHP
This documentation, and other publications, sometimes uses the term Connector/PHP
. This term refers to the full set of MariaDB related functionality in PHP, which includes the three APIs that are described above, along with the mysqlnd core library and all of its plugins.
Common Problems with MariaDB and PHP
Error: Maximum Execution Time Exceeded
: This is a PHP limit; go into thephp.ini
file and set the maximum execution time up from 30 seconds to something higher, as needed. It is also not a bad idea to double the RAM allowed per script to 16MB instead of 8MB.Fatal error: Call to unsupported or undefined function mysql_connect() in ...
: This means that your PHP version isn't compiled with MariaDB support. You can either compile a dynamic MariaDB module and load it into PHP or recompile PHP with built-in MariaDB support. This process is described in detail in the PHP manual.Error: Undefined reference to 'uncompress'
: This means that the client library is compiled with support for a compressed client/server protocol. The fix is to add-lz
last when linking with-lmysqlclient
.Error: Client does not support authentication protocol
: This is most often encountered when trying to use the olderMariaDB
extension with MariaDB and later. Possible solutions are: downgrade to MariaDB 4.0; switch to PHP 5 and the newermysqli
extension; or configure the MariaDB server with--old-passwords
. (See "Client does not support authentication protocol
", for more information.)
Enabling Both MariaDB
and mysqli
in PHP
If you're experiencing problems with enabling both the MariaDB
and the mysqli
extension when building PHP on Linux yourself, you should try the following procedure.
- Configure PHP like this:
./configure --with-mysqli=/usr/bin/mysql_config --with-mysql=/usr
- Edit the
Makefile
and search for a line that starts withEXTRA_LIBS
. It might look like this (all on one line):EXTRA_LIBS = -lcrypt -lcrypt -lmysqlclient -lz -lresolv -lm -ldl -lnsl -lxml2 -lz -lm -lxml2 -lz -lm -lmysqlclient -lz -lcrypt -lnsl -lm -lxml2 -lz -lm -lcrypt -lxml2 -lz -lm -lcrypt
Remove all duplicates, so that the line looks like this (all on one line):
EXTRA_LIBS = -lcrypt -lcrypt -lmysqlclient -lz -lresolv -lm -ldl -lnsl -lxml2
- Build and install PHP:
make make install
MySQL Perl API
The Perl DBI
module provides a generic interface for database access. You can write a DBI script that works with many different database engines without change. To use DBI with MySQL, install the following:
- The
DBI
module. - The
DBD::mysql
module. This is the DataBase Driver (DBD) module for Perl. - Optionally, the DBD module for any other type of database server you want to access.
Perl DBI is the recommended Perl interface. It replaces an older interface called mysqlperl
, which should be considered obsolete.
These sections contain information about using Perl with MariaDB and writing MariaDB applications in Perl:
- For installation instructions for Perl DBI support, see , "Perl Installation Notes".
- For an example of reading options from option files, see , "Using Client Programs in a Multiple-Server Environment".
- For secure coding tips, see , "General Security Guidelines".
- For debugging tips, see , "Debugging mysqld under gdb".
- For some Perl-specific environment variables, see , "Environment Variables".
- For considerations for running on Mac OS X, see , "Using the Bundled MariaDB on Mac OS X Server".
- For ways to quote string literals, see , "String Literals".
DBI information is available at the command line, online, or in printed form:
- Once you have the
DBI
andDBD::mysql
modules installed, you can get information about them at the command line with theperldoc
command:
shell>
perldoc DBI
shell>perldoc DBI::FAQ
shell>perldoc DBD::mysql
You can also use
pod2man
,pod2html
, and so on to translate this information into other formats. - For online information about Perl DBI, visit the DBI Web site, http://dbi.perl.org/. That site hosts a general DBI mailing list. Oracle Corporation hosts a list specifically about
DBD::mysql
; see , "MySQL Mailing Lists". - For printed information, the official DBI book is Programming the Perl DBI (Alligator Descartes and Tim Bunce, O'Reilly & Associates, 2000). Information about the book is available at the DBI Web site, http://dbi.perl.org/.
For information that focuses specifically on using DBI with MySQL, see MySQL and Perl for the Web (Paul DuBois, New Riders, 2001). This book's Web site is http://www.kitebird.com/mysql-perl/.
MySQL Python API
MySQLdb
provides MariaDB support for Python, compliant with the Python DB API version 2.0. It can be found at http://sourceforge.net/projects/mysql-python/.
Guidelines for Python Developers
The following guidelines cover aspects of developing MariaDB applications that might not be immediately obvious to developers coming from a Python background:
- For security, do not hardcode the values needed to connect and log into the database in your main script. Python has the convention of a
config.py
module, where you can keep such values separate from the rest of your code. - Python scripts often build up and tear down large data structures in memory, up to the limits of available RAM. Because MariaDB often deals with data sets that are many times larger than available memory, techniques that optimize storage space and disk I/O are especially important. For example, in MariaDB tables, you typically use numeric IDs rather than string-based dictionary keys, so that the key values are compact and have a predictable length. This is especially important for columns that make up the primary key for an
InnoDB
table, because those column values are duplicated within each secondary index. - Any application that accepts input must expect to handle bad data.
The bad data might be accidental, such as out-of-range values or misformatted strings. The application can use server-side checks such as unique constraints and NOT NULL constraints, to keep the bad data from ever reaching the database. On the client side, use techniques such as exception handlers to report any problems and take corrective action.
The bad data might also be deliberate, representing a "SQL injection" attack. For example, input values might contain quotation marks, semicolons,
%
and_
wildcard characters and other characters significant in SQL statements. Validate input values to make sure they have only the expected characters. Escape any special characters that could change the intended behavior when substituted into a SQL statement. Never concatenate a user input value into a SQL statement without doing validation and escaping first. Even when accepting input generated by some other program, expect that the other program could also be hacked and be sending you incorrect or malicious data. - Because the result sets from SQL queries can be very large, use the appropriate method to retrieve items from the result set as you loop through them.
fetchone()
retrieves a single item, when you know the result set contains a single row.fetchall()
retrieves all the items, when you know the result set contains a limited number of rows that can fit comfortably into memory.fetchmany()
is the general-purpose method when you cannot predict the size of the result set: you keep calling it and looping through the returned items, until there are no more results to process. - Since Python already has convenient modules such as
pickle
andcPickle
to read and write data structures on disk, the data that you choose store in MariaDB instead is likely to have special characteristics:- Too large to all fit in memory at one time. You use
SELECT
statements to query only the precise items you need, and aggregate functions to perform calculations across multiple items. - Too complex to be represented by a single data structure. You divide the data between different SQL tables. You can recombine data from multiple tables by using a join query. You make sure that related data is kept in sync between different tables by setting up foreign key relationships.
- Updated frequently, perhaps by multiple users simultaneously. The updates might only affect a small portion of the data, making it wasteful to write the whole structure each time. You use the SQL
INSERT
,UPDATE
, andDELETE
statements to update different items concurrently, writing only the changed values to disk. You useInnoDB
tables and transactions to keep write operations from conflicting with each other, and to return consistent query results even as the underlying data is being updated.
- Too large to all fit in memory at one time. You use
- Issuing SQL statements from Python typically involves declaring very long, possibly multi-line string literals. Because string literals within the SQL statements could be enclosed by single quotation, double quotation marks, or contain either of those characters, for simplicity you can use Python's triple-quoting mechanism to enclose the entire statement. For example,
'''It doesn't matter if this string contains 'single' or 'double' quotes, as long as there aren't 3 in a row.'''
- Many of the secrets to a fast, scalable MariaDB application involve using the right syntax at the very start of your setup procedure, in the
CREATE TABLE
statements. For example, Oracle recommends theENGINE=INNODB
clause for most tables, which enables transactional behavior that helps scalability of read-write workloads and offers automatic crash recovery. A follow-on recommendation is to declare a numeric primary key for each table, which offers the fastest way to look up values and can act as a pointer to associated values in other tables (a foreign key). Also within theCREATE TABLE
statement, using the most compact column data types that meet your application requirements helps performance and scalability, as the database server moves large amounts of data back and forth between memory and disk.
MySQL Ruby APIs
Two APIs are available for Ruby programmers developing MariaDB applications:
- The MySQL/Ruby API is based on the
libmysql
API library. For information on installing and using the MySQL/Ruby API, see , "The MySQL/Ruby API". - The Ruby/MySQL API is written to use the native MariaDB network protocol (a native driver). For information on installing and using the Ruby/MySQL API, see , "The Ruby/MySQL API".
For background and syntax information about the Ruby language, see Ruby Programming Language.
The MySQL/Ruby API
The MySQL/Ruby module provides access to MariaDB databases using Ruby through libmysql
.
For information on installing the module, and the functions exposed, see MySQL/Ruby.
The Ruby/MySQL API
The Ruby/MySQL module provides access to MariaDB databases using Ruby through a native driver interface using the MariaDB network protocol.
For information on installing the module, and the functions exposed, see Ruby/MySQL.
MySQL Tcl API
MySQLtcl
is a simple API for accessing a MariaDB database server from the Tcl programming language. It can be found at http://www.xdobry.de/mysqltcl/.
MySQL Eiffel Wrapper
Eiffel MariaDB is an interface to the MariaDB database server using the Eiffel programming language, written by Michael Ravits. It can be found at http://efsa.sourceforge.net/archive/ravits/mysql.htm.Copyright 1997, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices
Prev | Next | |
MySQL Performance Schema | Home | Chapter 21. Extending MySQL |