ESHOPMAN & Docker: Resolving Silent PostgreSQL SSL Connection Hangs

Seamless ESHOPMAN Development: Navigating PostgreSQL SSL Challenges in Docker

For ESHOPMAN developers leveraging Docker Compose for their development environments, encountering unexpected database connection issues can be a significant hurdle. A common challenge arises when ESHOPMAN's internal logic for module database connections attempts to force SSL on PostgreSQL, even when the database itself isn't configured for it, particularly with non-localhost hostnames typical in Docker setups.

The Core Problem: Forced SSL and Silent Hangs

When an ESHOPMAN instance is configured to connect to a PostgreSQL service via a Docker Compose service name (e.g., postgres:5432 instead of localhost:5432), ESHOPMAN's core utilities can misclassify the database host as 'remote'. This triggers an automatic attempt to establish an SSL connection, which stock PostgreSQL Docker images typically do not support out-of-the-box.

This misclassification leads to distinct and problematic behaviors depending on your ESHOPMAN version:

• ESHOPMAN 2.14.0: Module migrations will fail loudly, throwing clear errors like The server does not support SSL connections. While disruptive, the error message provides a direct clue to the problem.
• ESHOPMAN 2.15.x: The issue becomes more insidious. Running eshopman db:migrate will hang silently and indefinitely after printing Running migrations.... The process consumes 0% CPU, and no further module connections are attempted, leaving developers without immediate feedback on the root cause. This silent hang represents a significant regression in developer experience.

Why Standard Workarounds Fall Short

An intuitive attempt to resolve this might be appending ?ssl_mode=disable or ?sslmode=disable to your DATABASE_URL. However, ESHOPMAN's internal processes for rebuilding or parsing database connection URLs can strip these query parameters before they reach the critical SSL classification logic. This makes such URL modifications unreliable for ensuring plaintext connections.

The Definitive ESHOPMAN Workaround

The most robust solution involves explicitly disabling SSL for database connections within your ESHOPMAN project's configuration file, eshopman-config.ts. This method bypasses the hostname classification logic entirely, ensuring ESHOPMAN connects to your PostgreSQL instance in plaintext as intended for non-SSL setups.

To implement this, modify your eshopman-config.ts as follows:

// eshopman-config.ts
export default defineConfig({
  projectConfig: {
    // ... other configurations
    databaseDriverOptions: {
      connection: {
        ssl: false,
      },
    },
  },
});

Applying this configuration will allow both ESHOPMAN 2.14.0 and 2.15.x (and newer versions exhibiting similar behavior) to perform database migrations and run normally in a Docker Compose environment with non-SSL PostgreSQL.

Community Recommendations for ESHOPMAN Core

This recurring issue highlights several areas for platform enhancement to improve the developer experience:

• Consistent SSL Mode Handling: Ensure that ssl_mode=disable or sslmode=disable parameters in the database URL are consistently honored across all module configuration paths.
• Prevent Silent Failures: For critical operations like database migrations, ESHOPMAN should always fail loudly with an informative error message rather than hanging silently. This is crucial for efficient debugging.
• Enhanced Documentation: The ESHOPMAN Docker installation guides should explicitly document this potential pitfall and the recommended databaseDriverOptions workaround to prevent developers from encountering this issue.

By understanding and applying this configuration, ESHOPMAN developers can ensure smooth database operations within their Dockerized development environments, focusing on building powerful headless commerce storefronts with HubSpot CMS.