This section describes C API data structures other than those used for prepared statements, the asynchronous interface, or the replication stream interface. For information about those, seeSection 6.2, “C API Prepared Statement Data Structures”,Section 7.2, “C API Asynchronous Interface Data Structures”, andSection 10.2, “C API Binary Log Data Structures”.
This structure represents the handler for one database connection. It is used for almost all MySQL functions. Do not try to make a copy of a
MYSQLstructure. There is no guarantee that such a copy will be usable.This structure represents the result of a query that returns rows (
SELECT,SHOW,DESCRIBE,EXPLAIN). The information returned from a query is called theresult set in the remainder of this section.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().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_FIELDstructures for each field by callingmysql_fetch_field()repeatedly. Field values are not part of this structure; they are contained in aMYSQL_ROWstructure.This is a type-safe representation of an offset into a MySQL field list. (Used by
mysql_field_seek().) Offsets are field numbers within a row, beginning at zero.A type used for 64-bit unsigned integers. The
my_ulonglongtype was used before MySQL 8.0.18. As of MySQL 8.0.18, use theuint64_tC type instead.A boolean type, for values that are true (nonzero) or false (zero). The
my_booltype was used before MySQL 8.0. As of MySQL 8.0, use theboolorintC type instead.NoteThe change from
my_booltoboolmeans that themysql.hheader file requires a C++ or C99 compiler to compile.
TheMYSQL_FIELD structure contains the members described in the following list. The definitions apply primarily for columns of result sets such as those produced bySELECT statements.MYSQL_FIELD structures are also used to provide metadata forOUT andINOUT parameters returned from stored procedures executed using preparedCALL statements. For such parameters, some of the structure members have a meaning different from the meaning for column values.
To view theMYSQL_FIELD member values for result sets interactively, start themysql client with the--column-type-info option, then execute some sample queries.
char * nameThe name of the field, as a null-terminated string. If the field was given an alias with an
ASclause, the value ofnameis the alias. For a procedure parameter, the parameter name.char * org_nameThe name of the field, as a null-terminated string. Aliases are ignored. For expressions, the value is an empty string. For a procedure parameter, the parameter name.
char * tableThe name of the table containing this field, if it is not a calculated field. For calculated fields, the
tablevalue is an empty string. If the column is selected from a view,tablenames the view. If the table or view was given an alias with anASclause, the value oftableis the alias. For aUNION, the value is the empty string. For a procedure parameter, the procedure name.char * org_tableThe name of the table, as a null-terminated string. Aliases are ignored. If the column is selected from a view,
org_tablenames the view. If the column is selected from a derived table,org_tablenames the base table. If a derived table wraps a view,org_tablestill names the base table. If the column is an expression,org_tableis the empty string. For aUNION, the value is the empty string. For a procedure parameter, the value is the procedure name.char * dbThe name of the database that the field comes from, as a null-terminated string. If the field is a calculated field,
dbis an empty string. For aUNION, the value is the empty string. For a procedure parameter, the name of the database containing the procedure.char * catalogThe catalog name. This value is always
"def".char * defThe default value of this field, as a null-terminated string. This is set only if you use
mysql_list_fields().unsigned long lengthThe width of the field. This corresponds to the display length, in bytes.
The server determines the
lengthvalue 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.For string columns, the
lengthvalue varies on the connection character set. For example, if the character set islatin1, a single-byte character set, thelengthvalue for aSELECT 'abc'query is 3. If the character set isutf8mb4, a multibyte character set in which characters take up to 4 bytes, thelengthvalue is 12.unsigned long max_lengthThe 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_lengthis the length of the string representation of the values in the result set. For example, if you retrieve aFLOATcolumn and the“widest” value is-12.345,max_lengthis 7 (the length of'-12.345').If you are using prepared statements,
max_lengthis 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. (SeeSection 6.2, “C API Prepared Statement Data Structures”.) If you want themax_lengthvalues anyway, enable theSTMT_ATTR_UPDATE_MAX_LENGTHoption withmysql_stmt_attr_set()and the lengths will be set when you callmysql_stmt_store_result(). (SeeSection 6.4.3, “mysql_stmt_attr_set()”, andSection 6.4.29, “mysql_stmt_store_result()”.)unsigned int name_lengthThe length of
name.unsigned int org_name_lengthThe length of
org_name.unsigned int table_lengthThe length of
table.unsigned int org_table_lengthThe length of
org_table.unsigned int db_lengthThe length of
db.unsigned int catalog_lengthThe length of
catalog.unsigned int def_lengthThe length of
def.unsigned int flagsBit-flags that describe the field. The
flagsvalue may have zero or more of the bits set that are shown in the following table.Flag Value Flag Description NOT_NULL_FLAGField cannot be NULLPRI_KEY_FLAGField is part of a primary key UNIQUE_KEY_FLAGField is part of a unique key MULTIPLE_KEY_FLAGField is part of a nonunique key UNSIGNED_FLAGField has the UNSIGNEDattributeZEROFILL_FLAGField has the ZEROFILLattributeBINARY_FLAGField has the BINARYattributeAUTO_INCREMENT_FLAGField has the AUTO_INCREMENTattributeENUM_FLAGField is an ENUMSET_FLAGField is a SETBLOB_FLAGField is a BLOBorTEXT(deprecated)TIMESTAMP_FLAGField is a TIMESTAMP(deprecated)NUM_FLAGField is numeric; see additional notes following table NO_DEFAULT_VALUE_FLAGField 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 thexxxfield->typemember described later:To check for
BLOBorTIMESTAMPvalues, check whethertypeisMYSQL_TYPE_BLOBorMYSQL_TYPE_TIMESTAMP. (TheBLOB_FLAGandTIMESTAMP_FLAGflags are unneeded.)ENUMandSETvalues are returned as strings. For these, check that thetypevalue isMYSQL_TYPE_STRINGand that theENUM_FLAGorSET_FLAGflag is set in theflagsvalue.
NUM_FLAGindicates 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_FLAGindicates that a column has noDEFAULTclause in its definition. This does not apply toNULLcolumns (because such columns have a default ofNULL), or toAUTO_INCREMENTcolumns (which have an implied default value).The following example illustrates a typical use of the
flagsvalue:if (field->flags & NOT_NULL_FLAG) printf("Field cannot be null\n");You may use the convenience macros shown in the following table to determine the boolean status of the
flagsvalue.unsigned int decimalsThe number of decimals for numeric fields, and the fractional seconds precision for temporal fields.
unsigned int charsetnrAn ID number that indicates the character set/collation pair for the field.
Normally, character values in result sets are converted to the character set indicated by the
character_set_resultssystem variable. In this case,charsetnrcorresponds to the character set indicated by that variable. Character set conversion can be suppressed by settingcharacter_set_resultstoNULL. In this case,charsetnrcorresponds to the character set of the original table column or expression. See alsoConnection Character Sets and Collations.To distinguish between binary and nonbinary data for string data types, check whether the
charsetnrvalue is 63. If so, the character set isbinary, which indicates binary rather than nonbinary data. This enables you to distinguishBINARYfromCHAR,VARBINARYfromVARCHAR, and theBLOBtypes from theTEXTtypes.charsetnrvalues are the same as those displayed in theIdcolumn of theSHOW COLLATIONstatement or theIDcolumn of theINFORMATION_SCHEMACOLLATIONStable. You can use those information sources to see which character set and collation specificcharsetnrvalues 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 typeThe type of the field. The
typevalue may be one of theMYSQL_TYPE_symbols shown in the following table.Type Value Type Description MYSQL_TYPE_TINYTINYINTfieldMYSQL_TYPE_SHORTSMALLINTfieldMYSQL_TYPE_LONGINTEGERfieldMYSQL_TYPE_INT24MEDIUMINTfieldMYSQL_TYPE_LONGLONGBIGINTfieldMYSQL_TYPE_DECIMALDECIMALorNUMERICfieldMYSQL_TYPE_NEWDECIMALPrecision math DECIMALorNUMERICMYSQL_TYPE_FLOATFLOATfieldMYSQL_TYPE_DOUBLEDOUBLEorREALfieldMYSQL_TYPE_BITBITfieldMYSQL_TYPE_TIMESTAMPTIMESTAMPfieldMYSQL_TYPE_DATEDATEfieldMYSQL_TYPE_TIMETIMEfieldMYSQL_TYPE_DATETIMEDATETIMEfieldMYSQL_TYPE_YEARYEARfieldMYSQL_TYPE_STRINGCHARorBINARYfieldMYSQL_TYPE_VAR_STRINGVARCHARorVARBINARYfieldMYSQL_TYPE_BLOBBLOBorTEXTfield (usemax_lengthto determine the maximum length)MYSQL_TYPE_SETSETfieldMYSQL_TYPE_ENUMENUMfieldMYSQL_TYPE_GEOMETRYSpatial field MYSQL_TYPE_NULLNULL-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_TIMESTAMPcodes.You can use the
IS_NUM()macro to test whether a field has a numeric type. Pass thetypevalue toIS_NUM()and it evaluates to TRUE if the field is numeric:if (IS_NUM(field->type)) printf("Field is numeric\n");ENUMandSETvalues are returned as strings. For these, check that thetypevalue isMYSQL_TYPE_STRINGand that theENUM_FLAGorSET_FLAGflag is set in theflagsvalue.