Documentation Home
MySQL 9.1 C API Developer Guide
Download this Manual
PDF (US Ltr) - 1.4Mb
PDF (A4) - 1.4Mb


5.4.59 mysql_real_connect_dns_srv()

MYSQL *
mysql_real_connect_dns_srv(MYSQL *mysql,
                           const char *dns_srv_name,
                           const char *user,
                           const char *passwd,
                           const char *db,
                           unsigned long client_flag)

Description

Note

mysql_real_connect_dns_srv() is a synchronous function. Unlike mysql_real_connect(), it has no asynchronous counterpart.

mysql_real_connect_dns_srv() is similar to mysql_real_connect(), except that the argument list does not specify the particular host of the MySQL server to connect to. Instead, it names a DNS SRV record that specifies a group of servers. For information about DNS SRV support in MySQL, see Connecting to the Server Using DNS SRV Records.

The dns_srv_name argument for mysql_real_connect_dns_srv() takes the place of the host, port, and unix_socket arguments for mysql_real_connect(). The dns_srv_name argument names a DNS SRV record that determines the candidate hosts to use for establishing a connection to a MySQL server.

The mysql, user, passwd, db, and client_flag arguments to mysql_real_connect_dns_srv() have the same meanings as for mysql_real_connect(). For descriptions of their meanings, see Section 5.4.58, “mysql_real_connect()”.

Suppose that DNS is configured with this SRV information for the example.com domain:

Name                     TTL   Class   Priority Weight Port Target
_mysql._tcp.example.com. 86400 IN SRV  0        5      3306 host1.example.com
_mysql._tcp.example.com. 86400 IN SRV  0        10     3306 host2.example.com
_mysql._tcp.example.com. 86400 IN SRV  10       5      3306 host3.example.com
_mysql._tcp.example.com. 86400 IN SRV  20       5      3306 host4.example.com

To use that DNS SRV record, pass "_mysql._tcp.example.com" as the dns_srv_name argument to mysql_real_connect_dns_srv(), which then attempts a connection to each server in the group until a successful connection is established. A failure to connect occurs only if a connection cannot be established to any of the servers. The priority and weight values in the DNS SRV record determine the order in which servers should be tried.

mysql_real_connect_dns_srv() attempts to establish TCP connections only.

The client library performs a DNS SRV lookup for each call to mysql_real_connect_dns_srv(). The client library does no caching of lookup results.

Return Values

A MYSQL* connection handler if the connection was successful, NULL if the connection was unsuccessful. For a successful connection, the return value is the same as the value of the first argument.

Errors

The same that you can get from mysql_real_connect(), plus:

Example

The following example uses the name of the DNS SRV record shown previously as the source of candidate servers for establishing a connection.

MYSQL mysql;
const char *dns_srv_name = "_mysql._tcp.example.com";

mysql_init(&mysql);
if (!mysql_real_connect_dns_srv(&mysql,dns_srv_name,"user","passwd","database",0))
{
    fprintf(stderr, "Failed to connect to database: Error: %s\n",
          mysql_error(&mysql));
}