real_connect

In this article, we will discuss the real_connect() method in PHP, which is used to establish a connection to a MySQL database. (The procedural equivalent is mysqli_real_connect().)

This page covers what makes real_connect() different from a plain mysqli_connect(), the full parameter list, how to enable SSL and other connection flags, and the most common pitfalls.

What is real_connect() and why use it?

The real_connect() method opens a connection to a MySQL server, just like mysqli_connect(). The key difference is that real_connect() operates on a connection handle you have already created with mysqli_init(), instead of creating and connecting in a single step.

That extra step matters because it gives you a window between creating the handle and connecting, where you can configure options that can only be set before the connection is established. Use real_connect() (rather than mysqli_connect()) when you need to:

• Set connection options with mysqli_options() — for example a connect timeout (MYSQLI_OPT_CONNECT_TIMEOUT) or local infile support.
• Enable an SSL/TLS connection with ssl_set() and the MYSQLI_CLIENT_SSL flag.
• Pass client flags such as MYSQLI_CLIENT_COMPRESS or MYSQLI_CLIENT_FOUND_ROWS.
• Open a persistent connection by prefixing the host with p:.

If you don't need any of that, the simpler mysqli_connect() is perfectly fine.

Basic usage

real_connect() always follows a two-step pattern: create the handle, then connect. Here is the object-oriented approach:

<?php
$mysqli = mysqli_init();

if (!$mysqli) {
    die('mysqli_init failed');
}

if (!$mysqli->real_connect('localhost', 'username', 'password', 'database')) {
    die('Connect Error (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error);
}

echo 'Success... ' . $mysqli->host_info . "\n";

$mysqli->close();
?>

We first create a MySQLi handle with mysqli_init() and verify it succeeded. We then call real_connect() on the $mysqli object to connect. If it fails, we report the error with connect_errno and connect_error and stop; on success we print the host info and finally release the connection with close().

Parameters

real_connect() accepts the following parameters, all optional, in this order:

Note: with the OO API the handle is the object, so the first argument is the host. With the procedural mysqli_real_connect($link, $host, ...), the link is passed first.

Setting options before connecting

This is the main reason real_connect() exists. Configure the handle with mysqli_options() between init and real_connect:

<?php
$mysqli = mysqli_init();

// These can only be set before connecting:
$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);
$mysqli->options(MYSQLI_INIT_COMMAND, "SET autocommit = 0");

if (!$mysqli->real_connect('localhost', 'username', 'password', 'database')) {
    die('Connect Error (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error);
}

echo 'Connected with a 5-second timeout.';
$mysqli->close();
?>

Connecting with SSL and client flags

The seventh parameter is a bitmask of client flags. To require an encrypted connection, configure the certificates with ssl_set() and pass MYSQLI_CLIENT_SSL:

<?php
$mysqli = mysqli_init();

$mysqli->ssl_set(null, null, '/path/to/ca-cert.pem', null, null);

$mysqli->real_connect(
    'db.example.com', 'username', 'password', 'database',
    3306, null,
    MYSQLI_CLIENT_SSL
);

echo 'Encrypted connection established.';
$mysqli->close();
?>

Common flags you can combine with |:

• MYSQLI_CLIENT_SSL — use SSL/TLS encryption.
• MYSQLI_CLIENT_COMPRESS — use the compressed protocol.
• MYSQLI_CLIENT_FOUND_ROWS — return matched rows instead of changed rows.

Persistent connections

Prefixing the host with p: reuses an existing connection from the pool across requests instead of opening a new one each time, which can reduce connection overhead on busy servers:

<?php
$mysqli = mysqli_init();
$mysqli->real_connect('p:localhost', 'username', 'password', 'database');
?>

Common pitfalls

• Forgetting mysqli_init(). real_connect() must be called on a handle returned by mysqli_init(). Calling it on a freshly constructed new mysqli() that is already connected will fail.
• Checking the wrong error property. Before a connection exists, use connect_errno / connect_error, not errno / error.
• Setting options too late. Options like the connect timeout have no effect once the connection is open — they must be set before real_connect().

Conclusion

The real_connect() method establishes a MySQL connection from a handle you created with mysqli_init(), giving you a chance to configure timeouts, SSL, and client flags that a one-shot mysqli_connect() cannot. Once connected, you can run statements with query() and select a database with select_db().

Practice