Bug #69627 Documentation indicates some MYSQL_FIELD->flags are deprecated which aren't.
Submitted: 1 Jul 2013 10:40 Modified: 3 Jul 2013 17:49
Reporter: Roland Bouman Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.6.10 OS:Any
Assigned to: Paul Dubois

[1 Jul 2013 10:40] Roland Bouman
Description:
http://dev.mysql.com/doc/refman/5.5/en/c-api-data-structures.html, documentation for MYSQL_FIELD readS:

"
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.
"

In the table we find: 

"
ENUM_FLAG	Field is an ENUM (deprecated)
SET_FLAG	Field is a SET (deprecated)
"

Below the table, we find:

"
ENUM and SET values are returned as strings. For these, check that the type value is MYSQL_TYPE_STRING and that the ENUM_FLAG or SET_FLAG flag is set in the flags value.
"

This information is contradictory. Either the flags are deprecated and the type field unambiguously indicates whether the field is ENUM or SET, or the type field uses a more general type such as MYSQL_TYPE_STRING, in which case the flags are required to determine whether the declared type is ENUM or SET.

I found that at least when using mysql_fetch_field() the type field returns MYSQL_TYPE_STRING. The flags are thus required to figure out the declared type, which means they cannot be deprecated since they convey essential information.

How to repeat:
See Description.

Suggested fix:
Please do not mark ENUM_FLAG and SET_FLAG as deprecated. They aren't.
[1 Jul 2013 11:49] Peter Laursen
Agree with Roland that all the 'metadata flags' in a result set should be preserved.  They are important. It is not always a client or user knows the datatype and special client-side funtionalities for specific datatypes may be implemented in clients.  This not at least applies to SET and ENUM.

This reminds me that there is also no 'metadata flag' for indicating the charset/encoding and/or byte-length of string columns (an old report of mine).
[1 Jul 2013 11:56] Roland Bouman
Peter, 

doesn't the charsetnr member in MYSQL_FIELD provide the charset?

http://dev.mysql.com/doc/refman/5.5/en/c-api-data-structures.html

From there you could work out the number of bytes per character.

I agree the collation would still be a missing item.
[1 Jul 2013 12:10] Peter Laursen
Roland: I would like to be able to decide how many bytes to use in a client application for retrieved string data without executing a new query. Now I will need an additional SHOW or SELECT FROM I_S query to find out what the 'charset_no' actually is (except for its number) and not at least how wide it is.

This was my report: http://bugs.mysql.com/bug.php?id=57709

But maybe the supporter who verified my report overlooked your point? Let them comclude!
[1 Jul 2013 12:23] Umesh Shastry
Hello Roland,

Thank you for the report.

Thanks,
Umesh
[1 Jul 2013 12:54] Roland Bouman
Peter, 

yes, you'll need the additional query to the IS. It would be easier to have it in the MYSQL_FIELD struct. 

That said, if I today were to make an application that relies on that information a lot, I would probably do that query just once (for each distinct connection), and cache the data in the client app, and then use that to do a lookup.
[1 Jul 2013 13:11] Peter Laursen
Worse than that actually .. I will need an additional query *for every string column* in the resultset if I shall be able to 'synthesize' a CREATE TABLE statement that fits the data (or an array or other data structures in a client application that does) without wasting space.  Before MySQL 4.1 you could do with a single query. Metadata sent from the server with a simple SELECT statement had all information required.
[1 Jul 2013 13:54] Roland Bouman
Let's take this discussion to the other bug you opened. It has, IMO, no bearing on whether the ENUM and SET flags should be documented as "deprecated" or not.
[3 Jul 2013 17:40] Paul Dubois
Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.

After some internal discussion: Agreed. Unlike BLOB_FLAG and TIMESTAMP_FLAG (also marked deprecated), there is no other way to get this information. Will remove "deprecated" from ENUM_FLAG and SET_FLAG.
[3 Jul 2013 17:49] Roland Bouman
Paul, thanks!