startOrAttachEmbeddedPostgres function

Future<ResolvedEmbeddedPostgres?> startOrAttachEmbeddedPostgres(PostgresDatabaseConfig config)

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).

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,
) async {
  final dataDir = config._embeddedPostgresDataDir();
  if (dataDir == null) return null;

  final EmbeddedStartResult result;
  try {
    final configuredPassword = config.password.isEmpty ? null : config.password;
    result = await EmbeddedPostgres.startOrAttach(
      EmbeddedPostgresOptions(
        dataDir: dataDir,
        databaseName: config.name,
        username: config.user,
        transport: hasUnixSocketSupport()
            ? UnixTransport(initialPassword: configuredPassword)
            : TcpTransport(password: configuredPassword),
        detach: false,
        repairStaleLocks: true,
      ),
    );
  } catch (error, stackTrace) {
    Error.throwWithStackTrace(
      EmbeddedPostgresStartupException(
        formatEmbeddedPostgresFailure(error),
        includeStackTrace: shouldReportEmbeddedPostgresFailure(error),
      ),
      stackTrace,
    );
  }

  return ResolvedEmbeddedPostgres(
    connectivity: config._connectivityFrom(result.handle.endpoint),
    stop: result.launched ? () => result.handle.stop() : null,
  );
}