startOrAttachEmbeddedPostgres function

Future<ResolvedEmbeddedPostgres?> startOrAttachEmbeddedPostgres(
  1. PostgresDatabaseConfig config, {
  2. bool enableTcp = false,
})

Launches or attaches to the embedded PostgreSQL postmaster backing config's dataPath, returning its resolved connection coordinates.

Returns null when config has no dataPath (it points at an externally-managed server). Relative dataPath values are used as-is (typically already resolved with DatabaseConfig.withResolvedLocalPath).

Uses only the Unix socket by default. enableTcp also enables loopback TCP on the configured port when a database password is configured. Attaching to an existing postmaster keeps its current listeners.

This pulls package:serverpod_embedded_postgres (and its dart:ffi dependencies), so it is deliberately NOT exported from the package barrel - it must never reach a web client. Server-side consumers reach it via package:serverpod_database/embedded.dart.

Implementation

Future<ResolvedEmbeddedPostgres?> startOrAttachEmbeddedPostgres(
  PostgresDatabaseConfig config, {
  bool enableTcp = false,
}) async {
  final dataDir = config._embeddedPostgresDataDir();
  if (dataDir == null) return null;

  final EmbeddedStartResult result;
  try {
    result = await EmbeddedPostgres.startOrAttach(
      EmbeddedPostgresOptions(
        dataDir: dataDir,
        databaseName: config.name,
        username: config.user,
        transport: embeddedTransportFor(config, enableTcp: enableTcp),
        detach: false,
        repairStaleLocks: true,
      ),
    );
  } catch (error, stackTrace) {
    Error.throwWithStackTrace(
      EmbeddedPostgresStartupException(
        formatEmbeddedPostgresFailure(error),
        includeStackTrace: shouldReportEmbeddedPostgresFailure(error),
      ),
      stackTrace,
    );
  }

  return ResolvedEmbeddedPostgres(
    connectivity: config._connectivityFrom(result.handle.endpoint),
    handle: result.handle,
    launched: result.launched,
  );
}