Refactor: Move v2 database metadata schema creation to async Database worker #13100

TL;DR

In Create.php, there is a TODO to move the v2 metadata schema creation to the Databases background worker. Currently, the metadata collection (database_{sequence}) is created synchronously inside the HTTP request (line 204), blocking the API response until the DDL operation completes. This is inconsistent with how Collections, Attributes, and Indexes are handled (all async via workers).

Detailed Context

The TODO (line 37-38):

// TODO: use database worker for for creating the v2 schema if not present
// it is considered that the v2 metadata schema is already created during server start in the http.php

Source permalink

The synchronous call (line 204):

$this->createMetadataCollection($dbForProject, $database);

Source permalink

What happens today:

1. User hits POST /v1/databases.
2. A document is saved to the databases collection.
3. createMetadataCollection() runs synchronously — it executes a DDL query (createCollection) on the project database, blocking the HTTP response.
4. It also assumes the target database cluster already has the base Utopia "v2 schema" initialized from the http.php boot script.

Why this is a problem:

• API Latency: DDL I/O blocks the response. Every other schema operation (attributes, indexes, collections) is already async via workers — database creation is the odd one out.
• Assumption Gap: If a dynamically provisioned or externally added database cluster is targeted post-boot, it won't have the v2 base schema, causing failures.

Proposed Solution

1. Create.php: Remove $this->createMetadataCollection(). Enqueue a DatabaseMessage with a new type DATABASE_TYPE_CREATE_DATABASE via $publisherForDatabase (similar to how Delete.php dispatches DATABASE_TYPE_DELETE_DATABASE).

2. Workers/Databases.php: Add a new handler for DATABASE_TYPE_CREATE_DATABASE. Move the createMetadataCollection logic here. Add v2 schema verification on the target DSN before creating the metadata collection.

3. app/init/constants.php: Add DATABASE_TYPE_CREATE_DATABASE constant.

Related Files

• Create.php (HTTP Action)
• Workers/Databases.php (Background Worker)
• Delete.php (Reference for queue dispatch pattern)

I have explored the codebase and would love to work on this refactor. Happy to submit a PR if this approach aligns with the core team's vision!