Story of Bug#69627

Roland opened a bug "Documentation indicates some MYSQL_FIELD->flags are deprecated which aren't."

The MySQL protocol uses the string values of ENUM- and SET-fields. To indicate that this string originated from a ENUM- or SET-column the ENUM_FLAG and SET_FLAG are used in the Column Defintion

Same as Roland I wonder why they are deprecated. Is it something new? Something old?

Searching through the history

In an attempt to find out since when ENUMs are sent as MYSQL_TYPE_STRING + ENUM_FLAG I grepped through the oldest MySQL release that can be found in the bzr tree:

mysql-3.23.22-beta$ find . -type f | xargs grep -n ENUM_FLAG
./sql/field.cc:4560:  if (flags & (ENUM_FLAG | SET_FLAG))
./sql/field.h:118:  tmp->flags&= (NOT_NULL_FLAG | BLOB_FLAG | UNSIGNED_FLAG | ZEROFILL_FLAG | BINARY_FLAG | ENUM_FLAG | SET_FLAG);
./sql/field.h:920:      flags|=ENUM_FLAG;
./sql/field.h:957:      flags=(flags & ~ENUM_FLAG) | SET_FLAG;
./Docs/manual.texi:30213:@item @code{ENUM_FLAG}           @tab Field is an @code{ENUM} (deprecated)
./Docs/manual.texi:30218:Use of the @code{BLOB_FLAG}, @code{ENUM_FLAG} and @code{TIMESTAMP_FLAG} flags
./include/mysql_com.h:60:#define ENUM_FLAG  256     /* field is an enum */

... and stumbled over:

./Docs/manual.texi:30213:@item @code{ENUM_FLAG}           @tab Field is an @code{ENUM} (deprecated)

A further look at revision 2 shows:

Use of the @code{BLOB_FLAG}, @code{ENUM_FLAG} and @code{TIMESTAMP_FLAG} flags
is deprecated because they indicate the type of a field rather than an
attribute of its type.  It is preferable to test @code{field->type} against
@code{FIELD_TYPE_BLOB}, @code{FIELD_TYPE_ENUM} or @code{FIELD_TYPE_TIMESTAMP}
instead.

Checking the code of Field_enum you see that:

class Field_enum {
  Field_enum(...) {
  ...
    flags |= ENUM_FLAG;
  ...
  enum_field_types type() const { return FIELD_TYPE_STRING; }
}

This code snippet is the same in 5.7.

If the code is the same from 3.32.22 to 5.7 since when are the docs and the code out of sync?

The answer can only be found the old source-tar's of the times before bazaar and bitkeeper.

To the attic

After removing some dust from tar's running the above find-grep shows:

• 3.21.0 introduces ENUM support and the ENUM_FLAG (not documented)

When the ENUM_FLAG was introduced there was no way to send it to the client. Back then field for this in the column definition was only 1-byte long and ENUM_FLAG has the value of 256 ... and was always cut off.

• 3.21.20 introduces support for a wider flags field with the CLIENT_LONG_FLAG capability.

From now on new clients could distinguish strings from ENUMs.

• 3.21.23 comment around ENUM_FLAG in mysql_com.h changed from Not sent to client to field is an enum to describe that.

• 3.22.5 adds documentation for the C-API including its field types and flags (including ENUM_FLAG)

• 3.22.6 deprecates ENUM_FLAG, BLOB_FLAG and TIMESTAMP_FLAG as seen in the text-snippet above

• 3.22.17 marks the table entry for ENUM_FLAG as (deprecated) in the manual (which is what #69627 is about)

Why?

Judging from the documentation snippet and the history ENUM_FLAG was deprecated because:

• it was not supported by clients before 3.21.20
• only ENUM and its brother SET are sent as MYSQL_TYPE_STRING + a flag

When the C-API section was updated in 3.22.6 I guess this was seen, discussed and moved to the stack of things to clean up. It was still a alpha release.

That was in 1998. Years later the documentation was adjusted to follow the code to say:

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.

... and now even the (deprecated) tag is removed.