MySQL Bugs: #69627: Documentation indicates some MYSQL_FIELD->flags are deprecated which aren't.

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	CPU Architecture:	Any

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.

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

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.

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!

Hello Roland,

Thank you for the report.

Thanks,
Umesh

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.

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.

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.

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.

Paul, thanks!