mysql_real_connect(3)

💖 mysql_real_connect — MariaDB Connector/C 💖

okay bestie, listen. this is mysql_real_connect(3) from the MariaDB Connector/C manual, and it's literally the moment your code stops being lonely and actually talks to a database server. it's giving first-day-of-school energy. let's get into it 🫶

---

✨ Name ✨

mysql_real_connect — establishes a connection to a MariaDB database server. that's the whole vibe. that's the job. no notes. 💅

---

🌸 Synopsis 🌸

MYSQL * mysql_real_connect(MYSQL *mysql,
                           const char *host,
                           const char *user,
                           const char *passwd,
                           const char *db,
                           unsigned int port,
                           const char *unix_socket,
                           unsigned long flags);

look at all those arguments. eight of them. she's high maintenance but she delivers, fr fr. 🎀

---

🦋 Description 🦋

Establishes a connection to a database server. that's it, that's the tea. ☕ but keep reading because the details are where the ✨magic✨ lives.

---

🌈 Parameter 🌈

• mysql — a mysql handle, which was previously allocated by mysql_init(3). do NOT try to freestyle this one, bestie, it has to come from mysql_init(3) first or it's just a sad little pointer with no dreams. 😭
• host — can be either a host name or an IP address. if you pass the NULL value or the string "localhost" to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol. and since version 3.3.0 you can also drop a comma separated list of hosts in here for simple fail over, in case one or more of those hosts are just not available (rude of them, honestly). 🧚
• user — the user name. If NULL or an empty string "" is specified, the current user will be used. lowkey convenient.
• passwd — If provided or NULL, the server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password was provided or not). so like, one username, two personalities, depending on whether you brought a password. main character energy tbh. 👑
• db — if provided will specify the default database to be used when performing queries. give her a home base.
• port — specifies the port number to attempt to connect to the server. 🔌
• unix_socket — specifies the socket or named pipe that should be used.
• flags — the flags allows various connection options to be set. here's the full roster, no gatekeeping:
  • CLIENT_FOUND_ROWS — Return the number of matched rows instead of number of changed rows.
  • CLIENT_NO_SCHEMA — Forbids the use of database.tablename.column syntax and forces the SQL parser to generate an error.
  • CLIENT_COMPRESS — Use compression protocol.
  • CLIENT_IGNORE_SPACE — Allows spaces after function names. All function names will become reserved words.
  • CLIENT_LOCAL_FILES — Allows LOAD DATA LOCAL statements.
  • CLIENT_MULTI_STATEMENTS — Allows the client to send multiple statements in one command. Statements will be divided by a semicolon.
  • CLIENT_MULTI_RESULTS — Indicates that the client is able to handle multiple result sets from stored procedures or multi statements. This option will be automatically set if CLIENT_MULTI_STATEMENTS is set.
  • CLIENT_REMEMBER_OPTIONS — Remembers options passed to mysql_optionsv(3) if a connect attempt failed. If MYSQL_OPTIONS_RECONNECT option was set to true, options will be saved and used for reconnection.

---

💜 Return value 💜

returns a connection handle (same as passed for 1st parameter) or NULL on error. and if you get that NULL? don't panic, just check the mysql_errno(3) and mysql_error(3) functions for more information. they will tell you exactly what went wrong. 🕵️‍♀️

---

🎀 Notes 🎀

• The password doesn't need to be encrypted before executing mysql_real_connect(). This will be handled in the client server protocol. so like, don't do extra credit that nobody asked for. 🙈
• The connection handle can't be reused for establishing a new connection. It must be closed and reinitialized before. one handle, one connection, no takebacks. 💀
• mysql_real_connect() must complete successfully before you can execute any other API functions beside mysql_optionsv(3). this is not a suggestion, bestie. it's a rule.
• host parameter may contain multiple host/port combinations (supported since version 3.3.0). The following syntax is required:
  • hostname and port must be separated by a colon (:)
  • IPv6 addresses must be enclosed within square brackets
  • hostname:port pairs must be be separated by a comma (,)
  • if only one host:port was specified, the host string needs to end with a comma.
  • if no port was specified, the default port will be used.

Examples for failover host string:

host=[::1]:3306,192.168.0.1:3306,test.example.com

host=127.0.0.1:3306,

⚠️ note that trailing comma in the single-host example — that's not a typo, that's the rule. she's picky and we respect her. 💅

---

⭐ See also ⭐

• mysql_init(3)
• mysql_close(3)
• mariadb_reconnect(3)
• mysql_error(3)
• mysql_errno(3)

---

and that's the whole page, bestie!! you just read all of it, no skimming, I'm so proud. 🥹✨

Version 3.4 of the MariaDB Connector/C manual, and that's a wrap — go forth and connect responsibly, you absolute icon. 💖🎀🦋