How to Connect Joomla with an SQL Server

Last Updated on August 13, 2026

Can you connect Joomla 5 or Joomla 6 to Microsoft SQL Server? There is an important distinction to understand before trying the code from older Joomla tutorials.

Joomla 5 and Joomla 6 cannot use Microsoft SQL Server as the main Joomla database. Current Joomla 6 documentation lists MySQL, MariaDB, and PostgreSQL as supported database systems. SQL Server support was dropped when Joomla 4 was introduced.

However, this does not mean you cannot connect a Joomla 5 or Joomla 6 website to an external Microsoft SQL Server database. If another application, business system, ERP, CRM, or legacy database uses SQL Server, you can create a separate PHP connection from your Joomla extension or application and read or write data there.

In this updated tutorial, we will explain the difference between Joomla’s own database and an external SQL Server database, why the old JDatabase::getInstance() example should no longer be used, and how to approach an external SQL Server connection with modern PHP.

Let’s See: How to Change Joomla Database Prefix

Can Joomla 5 and Joomla 6 Connect Directly to SQL Server?

If by “connect Joomla with SQL Server” you mean using SQL Server as the database that stores Joomla’s core tables, the answer is no for Joomla 5 and Joomla 6.

Joomla 6 currently supports:

• MySQL
• MariaDB
• PostgreSQL

The current Joomla 6 technical requirements specify supported versions for MySQL, MariaDB, and PostgreSQL and do not list Microsoft SQL Server as a supported Joomla database.

SQL Server support was removed when Joomla 4 was introduced. Joomla’s upgrade documentation explicitly states that SQL Server support was dropped as part of the Joomla 3.10 to 4.0 transition.

Therefore, an older tutorial that tells you to change the Joomla database driver to sqlsrv in configuration.php is not a valid Joomla 5 or Joomla 6 installation method.

If you are working with Joomla 5 or Joomla 6 and want to understand the current database requirements, you may also want to read our Joomla 5 Tutorial for Beginners.

Connecting Joomla to an External SQL Server Database

There is, however, another common requirement.

Suppose your Joomla website uses MySQL or MariaDB, but your company already has an application whose data is stored in Microsoft SQL Server. You may want Joomla to retrieve customer information, products, orders, inventory, reports, or other data from that external database.

In this situation, you do not replace Joomla’s database connection. Instead, your Joomla extension or PHP application creates a separate connection to SQL Server.

The architecture looks like this:

Joomla 5 / Joomla 6
        |
        | Joomla Database
        v
MySQL / MariaDB / PostgreSQL

        +

        | External PHP connection
        v

Microsoft SQL Server
        |
        +-- Customers
        +-- Products
        +-- Orders
        +-- Other business data

This approach keeps Joomla’s own database connection unchanged while allowing your custom functionality to communicate with an external SQL Server database.

Why the Old Joomla SQL Server Code Is Outdated

The original version of this tutorial used code similar to:

$option = array();
$option['driver'] = 'sqlsrv';
$option['host'] = 'server';
$option['user'] = 'user';
$option['password'] = 'pass';
$option['database'] = 'db';
$option['prefix'] = '';

$db = &JDatabase::getInstance($option);

This is old Joomla code and should not be used as a Joomla 5 or Joomla 6 solution.

The old JDatabase API belongs to older Joomla versions. Joomla’s database API has evolved, and Joomla 5/6 extension development should use the current database abstraction and dependency-injection APIs when working with Joomla’s supported database.

Joomla’s current documentation recommends obtaining the database service through Joomla’s dependency-injection container rather than relying on old static database methods.

More importantly, even replacing the old class name with a modern Joomla database class does not make SQL Server a supported Joomla database. The Joomla database abstraction layer should be used with the database systems supported by the Joomla version you are developing for.

How to Connect Joomla 5 or Joomla 6 to an External SQL Server

If you need to access an external SQL Server database, the connection should be handled separately from Joomla’s core database connection.

Step 1: Confirm Your SQL Server Details

Before writing PHP code, collect the connection information provided by your SQL Server administrator.

You normally need:

• SQL Server host: The server name or IP address.
• Port: The SQL Server TCP port, commonly 1433 when using the default configuration.
• Database name: The name of the external database.
• Username: A SQL Server account with the required permissions.
• Password: The password for that account.
• Encryption settings: Depending on your SQL Server and driver configuration.

Do not use your Joomla database credentials unless the SQL Server is actually hosting a separate database and those credentials have been specifically created for it.

If you need to change or understand Joomla database settings, you can also read our guide on changing the Joomla database prefix.

Step 2: Check the PHP SQL Server Driver

PHP needs an appropriate Microsoft SQL Server driver before your Joomla application can communicate with SQL Server.

The commonly used PHP extensions are:

• sqlsrv
• pdo_sqlsrv

The sqlsrv extension provides the Microsoft SQL Server driver for PHP, while pdo_sqlsrv provides SQL Server support through PHP Data Objects (PDO).

For a new custom integration, PDO can be a convenient choice because it provides a familiar database interface and prepared statements.

Before creating an external SQL Server connection, make sure the required Microsoft PHP driver is installed and configured. See Microsoft’s PHP drivers for SQL Server system requirements for current driver and ODBC requirements.

Step 3: Create a Separate SQL Server Connection

For example, an external PHP class can create a PDO connection to SQL Server:

<?php
$server = 'sqlserver.example.com';
$database = 'ExternalDatabase';
$username = 'sql_user';
$password = 'your_password';

$dsn = "sqlsrv:Server={$server};Database={$database}";

try {
    $pdo = new PDO($dsn, $username, $password, [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    ]);

    echo 'SQL Server connection successful.';
} catch (PDOException $e) {
    echo 'SQL Server connection failed.';
}

This connection is not Joomla’s database connection. It is an independent PDO connection created specifically for the external SQL Server database.

For a complete example of using the PDO_SQLSRV driver with SQL Server, see Microsoft’s PDO_SQLSRV driver example.

Step 4: Query the SQL Server Database

Once the connection is established, you can execute queries against the external database.

For example, suppose SQL Server contains a table called Test:

$statement = $pdo->prepare(
    'SELECT id, name FROM Test'
);

$statement->execute();

$results = $statement->fetchAll();

foreach ($results as $row) {
    echo htmlspecialchars($row['name'], ENT_QUOTES, 'UTF-8');
}

Using a prepared statement is preferable when values come from users or other external input. Do not concatenate untrusted values directly into SQL queries.

How to Use SQL Server Data Inside a Joomla Extension

If your goal is to display SQL Server data inside Joomla, the recommended architecture is to put the external database logic inside a Joomla extension rather than modifying Joomla’s core files.

For example, you could create a custom Joomla component that:

1. Connects to SQL Server.
2. Retrieves the required data.
3. Validates the returned information.
4. Passes the data to a Joomla model or service.
5. Displays it through a Joomla view.

This makes the integration easier to maintain when Joomla or the external database changes.

Joomla provides a database abstraction layer for working with Joomla’s supported database systems, and its documentation recommends using that abstraction layer for extension development.

Do Not Change configuration.php to sqlsrv

One of the most important updates to this tutorial is that you should not change the Joomla database driver in configuration.php to sqlsrv in an attempt to make Joomla 5 or Joomla 6 use Microsoft SQL Server.

The configuration.php file contains the connection settings for Joomla’s own supported database. Changing those values to an unsupported database driver can prevent Joomla from connecting to its database correctly.

For example, the following should not be used as a Joomla 5/6 SQL Server configuration:

public $dbtype = 'sqlsrv';

That approach belongs to older Joomla versions that supported SQL Server and should not be presented as a current Joomla 5 or Joomla 6 configuration method.

Joomla Database Connection vs External SQL Server Connection

It is useful to understand the difference between these two connections.

This distinction is important because “connecting Joomla to SQL Server” can mean two completely different things.

Joomla Database Queries in Joomla 5 and Joomla 6

If you are actually trying to query Joomla’s own database, you should use Joomla’s current database API instead of creating a second connection manually.

For example, in a Joomla extension, the database service can be obtained through Joomla’s dependency-injection container:

use Joomla\CMS\Factory;
use Joomla\Database\DatabaseInterface;
$db = Factory::getContainer()->get(DatabaseInterface::class);

You can then create and execute queries using Joomla’s database abstraction layer.

Joomla’s current documentation describes the database abstraction layer and dependency-injection approach for database access.

Do not copy older examples that use:

$db = Factory::getDbo();

Joomla’s documentation identifies this older approach as deprecated.

Security Tips for an External SQL Server Connection

Connecting to an external database introduces additional security considerations.

Use a Dedicated Database User

Create a dedicated SQL Server account for the Joomla integration rather than using an administrator account.

Give the account only the permissions it actually needs. For example, if Joomla only needs to read customer information, the account may only require SELECT permission.

Do Not Hard-Code Passwords in Public Code

Avoid placing production database passwords directly inside files that may accidentally be committed to Git or exposed publicly.

Store credentials securely and make sure configuration files are protected from public access.

Use Prepared Statements

When external values are included in SQL queries, use prepared statements and parameters.

This helps reduce the risk of SQL injection and makes your database code safer and easier to maintain.

Use Encrypted Connections When Required

If SQL Server is hosted on another server, configure the connection according to your organization’s security requirements. Encryption and certificate validation should be considered, particularly when database traffic crosses an untrusted network.

Common Problems When Connecting Joomla to SQL Server

SQL Server Driver Not Found

If PHP reports that the SQL Server PDO driver is unavailable, check whether pdo_sqlsrv or the appropriate Microsoft SQL Server PHP extension is installed and enabled for the PHP version used by your Joomla website.

Connection Refused

A connection refusal can be caused by an incorrect hostname, port, firewall rule, SQL Server configuration, or network restriction.

Make sure the Joomla server can actually reach the SQL Server host and port.

Authentication Failed

Check the SQL Server username, password, authentication mode, and permissions. A valid network connection does not necessarily mean that the database user is authorized to access the requested database.

Joomla Stops Working After Changing the Database Driver

If you changed Joomla’s configuration.php database settings to use sqlsrv, restore the correct supported Joomla database configuration.

Do not attempt to migrate Joomla’s core database to SQL Server simply by changing the database driver. Joomla 5 and Joomla 6 do not support SQL Server as the Joomla database engine.

Should You Use SQL Server or Joomla’s Database?

If you are developing a normal Joomla website, use the database supported by Joomla and let Joomla manage its own database connection.

An external SQL Server connection makes sense when you need to integrate Joomla with an existing system that already stores information in SQL Server.

For example, you might have:

• An ERP system running on Microsoft SQL Server.
• A company CRM containing customer records.
• A legacy Windows application using SQL Server.
• An inventory system that Joomla needs to read.
• An internal reporting database.

In these situations, Joomla can act as the web interface while the external application remains responsible for its own database.

Conclusion

The original Joomla SQL Server connection code commonly found in older tutorials is no longer appropriate for Joomla 5 and Joomla 6. Microsoft SQL Server is not a supported database engine for Joomla 5 or Joomla 6, and SQL Server support was removed when Joomla 4 was introduced.

However, you can still connect Joomla 5 or Joomla 6 to an external SQL Server database when building a custom integration. The important difference is that SQL Server remains a separate database, while Joomla continues to use its supported database system.

For Joomla’s own database operations, use Joomla’s current database abstraction layer and dependency-injection approach. For an external SQL Server system, use an appropriate PHP SQL Server driver, such as PDO_SQLSRV, and keep that connection separate from Joomla’s core database connection.

If you are maintaining an older Joomla installation, make sure you are running a supported Joomla version. You can also read our guide on How to Update Joomla to the latest version.

This approach gives you a cleaner and more maintainable Joomla integration while avoiding deprecated Joomla database APIs and unsupported database configurations.