Smart Loaders: Fewer Database Queries for Faster Pages¶

User Guide¶

CopeX GmbH
Web: https://copex.io
Email: office@copex.io

Inhaltsverzeichnis / Table of Contents¶

Abschnitt / Section	Seite
1 Was es macht / What it does	3
2 Wann sinnvoll / When to use	3
3 Voraussetzungen / Requirements	4
4 Installation	4
5 Aktivierung / Activation	5
6 Verwendung / Usage	5
7 Was tun bei Problemen / Troubleshooting	7
8 Für Entwickler / For Developers	8

1 What it does¶

Reduces the number of database queries on category, product, and cart pages. A typical Magento shop queries several hundred records individually for a category page with 24 products — images, prices, stock, URL paths, links. Smart Loaders bundles these into a few large queries.

The principle: as soon as Magento loads a product list, Smart Loaders detects the product IDs and pre-loads all associated data (images, prices, stock, URLs, category links, bundle options, etc.) in a single pass. When Magento subsequently asks for this data for each product individually, the already-filled memory delivers the answer — no further database query.

The same principle applies to the cart: MSI stock queries that Magento executes individually for each cart item are replaced by a single prepared batch query.

2 When to use¶

Category pages are slow even with warm caches
Database CPU is high during normal shop usage
Cart page feels sluggish
Query log shows many similar queries per page

3 Requirements¶

Magento 2.4.6 or higher
PHP 8.1 or higher (compatible with 8.2, 8.3, 8.4, 8.5)
copex/module-performance-suite — required core module
copex/module-core >1.1.0
Optional: magento/module-inventory-sales-api for MSI stock queries in the cart

4 Installation¶

composer require copex/module-preloaders
bin/magento module:enable CopeX_Preloaders
bin/magento setup:upgrade

Alternatively, install the complete suite:

composer require copex/performance-suite-bundle

5 Activation¶

'copex' => [
    'performance' => [
        'enabled' => true,
        'preloaders_enabled' => true,
    ],
],

Optional tuning:

'copex' => [
    'performance' => [
        'min_batch_size' => 3,   // Minimum product IDs before preloading fires
        'chunk_size' => 500,     // Max product IDs per query
    ],
],

6 Usage¶

Smart Loaders works entirely in the background — no manual steps required. The module is active immediately after enabling and flushing the cache.

Measuring the improvement:

bin/magento copex:performance:benchmark --url=/category/sale.html

Prints a comparison table: query count and load time with and without preloaders.

Pre-loaded data includes: stock status, product images, prices, discount rules, URLs, related/upsell/crosssell links, category and website assignments, custom options, bundle options, and MSI stock queries for the cart.

7 Troubleshooting¶

Kill switch:

'copex' => ['performance' => ['preloaders_enabled' => false]]

Disables all preloaders immediately. Flush cache. Shop runs as before.

For the complete kill switch:

'copex' => ['performance' => ['enabled' => false]]

Automatic self-protection: If a preloader throws an exception, it is disabled for the rest of the request and the error is logged to var/log/copex-performance.log. On the next request, it is attempted again.

Preloader is running but no improvement visible:

Run bin/magento copex:performance:benchmark to confirm
Check min_batch_size — if too high, small collections are skipped
Verify OPcache is active

8 For Developers¶

Implement PreloaderInterface or TypeAwarePreloaderInterface and register in the PreloaderPool via di.xml. TypeAwarePreloaderInterface declares via getSupportedTypes() which contexts (list, cart, wishlist, pdp) the preloader applies to. See source of copex/module-performance-suite for details.

CopeX GmbH — Web: https://copex.io — Email: office@copex.io