Question
Production Schema Caching and Metadata Persistence Limits
Rey River
0 reputation · 12 Sept 2020, 00:53 UTC
134.8K views
Loading…
0 reputation · 12 Sept 2020, 00:53 UTC
In CakePHP, metadata caching is typically disabled during development to allow for rapid schema changes, but it is a documented requirement for production environments to prevent redundant DESCRIBE queries on every request.
When migrating from a local environment to production, the application relies on the tmp directory to store these cached schema files. If the production environment implements stricter filesystem permissions or uses a read-only filesystem, the ORM may fail to persist the metadata cache despite the configuration being set to enabled.
This creates a discrepancy where the application functions locally but suffers significant performance degradation or runtime errors in production due to the inability to write to the cache store.
tmp folder?33775 reputation · 12 Sept 2020, 05:53 UTC
When the configured metadata cache engine is unreachable or read-only, CakePHP does not have a secondary "failover" cache engine. Instead, it falls back to runtime schema discovery. If the ORM cannot write the cached schema to the tmp directory or the specified cache store, it will execute DESCRIBE (or equivalent) queries on every single request to determine table structures.
This behavior is silent; the application will continue to function, but performance will degrade significantly as the number of database queries per request increases linearly with the number of tables involved in the operation.
To verify if schema caching is active in a production environment where you cannot inspect the tmp folder, use the following methods:
The most definitive way to verify caching is to monitor the database logs. If caching is failing, you will see repeated schema discovery queries for every request.
cakephpDESCRIBE table_name, SHOW COLUMNS FROM table_name, or SELECT * FROM information_schema.columns... queries.If you can deploy to a staging environment that mirrors production permissions, use the Debug Kit. Check the "Sql Log" panel; schema queries are distinct from your application's business logic queries. If they persist across refreshes, the cache is inactive.
Monitor the request time. A sudden jump in TTFB (Time to First Byte) when moving from a writable local environment to a read-only production environment—without a change in database latency—strongly indicates a failure to persist metadata.
If your production environment uses a read-only filesystem, you must move the metadata cache from the File engine to a persistent memory-based store. Update your app.php or app_local.php:
'CacheExpenses' => [ // Example for metadata/schema cache
'className' => 'Redis',
'duration' => '+1 year',
'server' => 'your-redis-endpoint',
],Missing Diagnostic Detail: Please specify the Cache engine currently configured for your metadata in app.php. If you are using the default File engine on a containerized environment (like AWS Lambda or Google Cloud Run), the tmp directory may be ephemeral or read-only, necessitating a move to Redis or Memcached.
Use comments to ask for clarification. Post a solution as an answer.
33,775 reputation · 12 Sept 2020, 11:07 UTC
One point worth adding to the fallback discussion: rather than letting the first production request absorb the DESCRIBE penalty (or silently discovering the cache is unwritable), CakePHP ships a console command to pre-populate schema metadata during deployment.
bin/cake schema_cache build --connection defaultRunning this as a deploy step has two practical benefits:
A matching bin/cake schema_cache clear should run on any deployment that includes migrations, otherwise the ORM will serve stale column metadata against an altered table.
Assumption: the command exists in CakePHP 3.6+ and 4.x/5.x; verify against your version's console command list. For read-only filesystems specifically, pairing this with a non-file engine (Redis, APCu) is the more reliable fix, since tmp permissions become irrelevant.