PHP mysqli_real_connect() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
MySQLi

Definition

In PHP, mysqli_real_connect() opens a MySQL connection on an existing mysqli object created by mysqli_init(), returning true on success and false on failure.

Unlike mysqli_connect() / new mysqli(), real_connect expects a prepared handle so you can call mysqli_options() or mysqli_ssl_set() first. It also accepts client $flags such as MYSQLI_CLIENT_SSL or MYSQLI_CLIENT_COMPRESS.

Syntax

Call mysqli_real_connect() with the values you need. Start with this line.

PHP
$ok = mysqli_real_connect($mysqli, "localhost", "user", "pass", "db");
CallWhat it does
mysqli_real_connect($m, "localhost", "u", "p", "db")Connects an init() handle to the server.
mysqli_real_connect($m, "localhost", "u", "p", "db", 3306)Connects using an explicit port.
mysqli_real_connect($m, "localhost", "u", "p", "db", null, null, MYSQLI_CLIENT_COMPRESS)Connects with a client flag.

Everyday apps can stay on mysqli_connect(). Use init + options + real_connect when you need timeouts, SSL setup or flags before the handshake. Object style is often $mysqli = mysqli_init(); $mysqli->options(...); $mysqli->real_connect(...).

Library declarations
PHP
mysqli_real_connect(mysqli $mysql, ?string $hostname = null, ?string $username = null, ?string $password = null, ?string $database = null, ?int $port = null, ?string $socket = null, int $flags = 0): bool

Parameters

ParameterDescription
mysqlRequired. mysqli object from mysqli_init().
hostnameOptional. Host name or IP. null uses the default host ini setting.
usernameOptional. MySQL user name.
passwordOptional. MySQL password.
databaseOptional. Default database to select.
portOptional. TCP port number.
socketOptional. Socket or named pipe.
flagsOptional. Connection flags such as MYSQLI_CLIENT_SSL.

Return Value

Return ValueDescription
booltrue on success, false on failure (then check mysqli_connect_error()).

PHP Examples

Example 1 — Init Plus Real Connect

Minimal two-step connect with fixed success output.

PHP
<?php
$mysqli = mysqli_init();
$ok = mysqli_real_connect(
    $mysqli,
    "localhost",
    "demo_user",
    "demo_pass",
    "app_db"
);

echo $ok ? "Connected." : mysqli_connect_error(), PHP_EOL;
mysqli_close($mysqli);

How It Works

  1. mysqli_init() creates the handle.
  2. mysqli_real_connect() performs the login.
  3. true means the connection is ready for queries.
  4. Close when finished.

Example 2 — Options Before Real Connect

Set a timeout, then connect — the reason this API exists.

PHP
<?php
$mysqli = mysqli_init();
mysqli_options($mysqli, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

mysqli_real_connect($mysqli, "localhost", "demo_user", "demo_pass", "app_db");
mysqli_set_charset($mysqli, "utf8mb4");

echo mysqli_get_host_info($mysqli), PHP_EOL;
mysqli_close($mysqli);

How It Works

  1. options() must run on the init handle first.
  2. real_connect opens the server with that timeout.
  3. set_charset configures encoding for later escaping/queries.
  4. get_host_info confirms a typical local TCP sample.

Example 3 — Compare With mysqli_connect()

One-step connect for apps that need no pre-connect options.

PHP
<?php
$mysqli = mysqli_connect("localhost", "demo_user", "demo_pass", "app_db");

if (!$mysqli) {
    echo mysqli_connect_error(), PHP_EOL;
    exit;
}

echo "Simple connect path.", PHP_EOL;
mysqli_close($mysqli);

How It Works

  1. mysqli_connect() creates and connects in one call.
  2. new mysqli(. ..) is the object-oriented equivalent.
  3. Switch to init/real_connect only when options or flags are required.
  4. Both paths produce a normal mysqli connection.

Frequently Asked Questions

real_connect needs a mysqli_init() object first and supports pre-connect options/flags. mysqli_connect() does create+connect in one step.
No. Use it when you need options, SSL setup or client flags before connecting.
mysqli_init(), then optional mysqli_options() / mysqli_ssl_set().
Usually mysqli_set_charset(), then query() or prepare().
Use mysqli_connect_error() and mysqli_connect_errno() when real_connect returns false.

Next: mysqli_real_escape_string()

mysqli_real_escape_string() escapes special characters in a string so it can be safely pla.

mysqli_real_escape_string() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful