MySQL Bugs: #12121: C-API: mysql_real_connect documentation is not exact

Bug #12121	C-API: mysql_real_connect documentation is not exact
Submitted:	22 Jul 2005 18:57	Modified:	9 Sep 2005 17:30
Reporter:	Ingo Krabbe	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:		OS:
Assigned to:	Paul DuBois	CPU Architecture:	Any

Description:
The documenation of mysql_real_connect is not exact in some quite annoying behaviour, that passwords are

          * not used if password=""  (empty string)
          * read from my.cnf group or somewhere else if possible if password=NULL

please be exact in the examples and the parameter descriptions, otherwise the useage of your API depends on trial and false agony.

It took me about an hour to find out about this strict behaviour.  This is anyway no good design. But please document it well at least.

How to repeat:
try the example from mysql_real_connect example

Suggested fix:
document or make interface more intelligent

Hi!

This is from our manual:

"The passwd parameter contains the password for user. If passwd is NULL, only entries in the user table for the user that have a blank (empty) password field are checked for a match. This allows the database administrator to set up the MySQL privilege system in such a way that users get different privileges depending on whether or not they have specified a password. 

Note: Do not attempt to encrypt the password before calling mysql_real_connect(); password encryption is handled automatically by the client API. "

I'm not sure what part is unclear to you.  Also, the password in my.cnf is used only if mysql_options() is set in your code.

I'm a software developer using your C-API.  So I work in a mathematical correct, well defined and well ordered environment, else I would make much errors.

"If passwd is NULL, only entries in the user table for the user that have a blank
(empty) password field are checked for a match."

This sentence can be used for following WRONG conclusions:
            - a passwd that is NULL is equal to an (empty) password field ("" empty string).
            - "if the password is NULL" defines the "user has/hasn't specified a password" setting.
            - the my.cnf option file will be taken into account in any case, is only mysql_options()              
               has been set
            - "if the password it NULL" we won't use a password to connect to the database.

Right is:
          - if the passwd is the empty (C) string "" (not NULL!) the connect will be made with
            "use password = NO"
          - the passwd in my.cnf is  USED  only if passwd is NULL

AND the 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));
}

fails anyway since passwd="passwd" and not read from the [your_program_name] group.

Also passwd="" will fail since this would also choose not to use [your_program_name].  This will connect with "using passwd"=NO as the log says !

Finally passwd=NULL is the only working combination that uses the password from [your_program_name].

So your documentation is not only incorrect its truly wrong and leads on the wrong path in choosing the passwd argument for mysql_real_connect

You should at least say there, that the arguments of mysql_real_connect are preferred over the my.cnf arguments, if the mysql_real_connect argument is NOT NULL (or 0 for integer values).

You should also say that the useage of MYSQL_READ_DEFAULT_GROUP will use [client] overwritten by [your_program_name] parameters.  You cannot have more than one default group.

For host parameter this problem is also true:

"If host is NULL or the string "localhost", a connection to the local host is assumed. " 

This is simply wrong since if host is NULL the my.cnf parameters from the default group is taken into account, if the string is "localhost" the connection to the local host is assumed ( as well as I estimate if the string is empty ("") )

YOU HAVE TO MAKE A DIFFERENCE BETWEEN EMPTY STRINGS AND NULL.  YOU HAVE TO SAY SOMEWHERE THAT THE COMMUNICATION PARAMETERS ARE TAKEN FROM THE DEFAULT GROUPS IN THE DEFAULT FILES SOMEWHERE AND MIGHT THEN BE OVERWRITTEN BY THE PARAMETERS TO REAL CONNECT.

Anyway this is bad style since NULL is no string.  NULL is a wrong string state.  An undefined string state is better expressed by "", which is actually a string of length 1 in C, since it contains the terminating '\0'.

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
product(s).

Additional info:

Some of the conclusions that you've drawn about the meaning of
password values (with respect to NULL versus the empty string) are
incorrect.  Probably this is a result of our not being explicit
about how to override mysql_real_connect() parameters in option
files.  I'll try to clarify the manual page as follows.  (Note that
mysql_options() is *necessary* if you want options to be taken from
an option file.)

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 of NULL or the empty string.

- For user, specify a value of NULL or the empty string.

- For passwd, specify a value of NULL.  (For the password, a value
  of the empty string in the mysql_real_connect() call cannot be
  overridden in an option file, because the empty string indicates
  explicitly that the MySQL account must have an empty password.)

- For db, specify a value of NULL or the empty string.

- For port, specify a value of 0.

- For unix_socket, specify a value of NULL.

If a parameter is not found in the option file, its default value
is used as indicated in the descriptions found earlier in this
section.

Also:
I'm not sure what to make of your statement that an undefined string
is better expressed by the empty string than by NULL.  For passwords,
the empty string cannot represent an undefined string, because it
is an explicit password value and has the specific meaning that the
MySQL account you're using must have an empty password.