---
title: "ConnectionPool"
manual: "TYPO3 Explained"
version: "11.5"
permalink: "https://docs.typo3.org/permalink/t3coreapi:database-connection-pool@11.5"
source: "ApiOverview/Database/ConnectionPool/Index.rst"
rendered: "2026-10-21T15:30:00+00:00"
---

> [!WARNING]
> **Attention**
>
> TYPO3 v11 has reached end-of-life as of October 31th 2024 and
> is no longer being maintained. Use the version switcher on the top
> left of this page to select documentation for a supported version of TYPO3.
>
> Need more time before upgrading?
> You can purchase Extended Long Term Support (ELTS) for TYPO3 v11 here:
> [TYPO3 ELTS](https://typo3.com/services/extended-support-elts).

# ConnectionPool {#database-connection-pool}

TYPO3's interface for executing queries via Doctrine DBAL starts with
a request to the `ConnectionPool` for a `QueryBuilder` or a
`Connection` object and passing the table name to be queried:

**EXT:my_extension/Classes/Domain/Repository/MyTableRepository.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Domain\Repository;

use TYPO3\CMS\Core\Database\ConnectionPool;

final class MyTableRepository
{
    private const TABLE_NAME = 'tx_myextension_domain_model_mytable';

    private ConnectionPool $connectionPool;

    public function __construct(ConnectionPool $connectionPool)
    {
        $this->connectionPool = $connectionPool;
    }

    public function findSomething()
    {
        // Get a query builder for a table
        $queryBuilder = $this->connectionPool
            ->getQueryBuilderForTable(self::TABLE_NAME);

        // Or get a connection for a table
        $connection = $this->connectionPool
            ->getConnectionForTable(self::TABLE_NAME);
    }
}

```

The `QueryBuilder` is the default object used by extension
authors to express complex queries, while a `Connection` instance can be
used as a shortcut to handle some simple query cases.

## Pooling {#pooling}

TYPO3 can handle multiple connections to different database endpoints at the
same time. This can be configured for each individual table in
`$GLOBALS['TYPO3_CONF_VARS']` (see [database configuration](https://docs.typo3.org/permalink/t3coreapi:database-configuration@11.5) for details). This makes it possible to run tables on
different databases without an extension developer having to worry about it.

The `ConnectionPool` implements this feature: It looks for configured
table-to-database mapping and can return a `Connection` or a
`QueryBuilder` instance for that specific connection. These objects know
internally which target connection they are dealing with and will quote field
names accordingly, for instance.

### Beware {#beware}

However, the transparency of tables for different database endpoints is limited.

Executing a table `JOIN` between two tables that reference different
connections will result in an exception. This restriction may in practice lead
to implicit "groups" of tables that must to point to a single connection when an
extension or the TYPO3 Core joins these tables.

This can be problematic when several different extensions use, for instance, the
Core category or collection API with their mm table joins between Core internal
tables and their extension counterparts.

That situation is not easy to deal with. At the time of writing the Core
development will implement eventually some non-join fallbacks for typical cases
that would be good to decouple, though.

> [!TIP]
> In the case joins cannot be decoupled, but still need to run affected tables
> on different databases, and when the code can not be easily adapted, some
> DBMS like PostgreSQL allow these queries to be executed by having their own
> connection handlers to various other endpoints.