Net4x.DapperLibrary.Docker 1.9.9

DapperLibrary.Docker

Helpers to provision and use transient Docker database containers for integration tests and local development. The project provides installers, runtime checks and Testcontainers-based container wrappers to create disposable database instances (SQL Server, PostgreSQL, MySQL, Oracle, Firebird) and helpers to copy/restore database backups into containers.

Overview

• Purpose: make it easy to run database instances in Docker for automated tests or local runs without requiring a permanent DB server installation.
• Approach: use a small runtime layer that detects Docker, can attempt to install Docker (platform-specific guidance), and uses Testcontainers / provider-specific builders to start containers and return IDapperContext instances wired to the container.

Main components

• DockerInstaller � convenience class that can check whether the Docker CLI is available (IsInstalled) and on some platforms attempts an automated install flow. On Windows it downloads the Docker Desktop installer and launches it (requires elevation). On Linux it runs the official install script. macOS requires manual installation.

• DockerRun � detects whether a local Docker daemon is reachable using Docker.DotNet (supports Unix socket and named pipe) and exposes IsRunning() / IsRunningAsync() helpers.

• DockerImage � small helper that checks whether a given Docker image exists locally (uses docker image inspect) and returns boolean result. Used to determine whether to pull an image before starting a container.

• SqlDockerContainers<TBuilder> (base class) � common logic for SQL-based containers using Testcontainers builders. It will pull images when not present, start/stop containers and create IDapperContext instances using provider-specific builders.

• Provider-specific container classes

  • MsSqlDockerContainers � helpers for SQL Server containers and a GetDapperContextUsingDockerContainer that returns a SqlDapperContext tied to the Testcontainers MsSqlContainer. Includes logic to restore a backup into the container via MsSqlContainerExtensions.RestoreDatabaseFromBackupAsync.
  • PostgresDockerContainers � starts a PostgreSQL container and returns a PostgresDapperContext.
  • MySqlDockerContainers � starts a MySQL container and returns a MySqlDapperContext.
  • OracleDockerContainers � starts an Oracle container (via Testcontainers Oracle) and returns an OracleDapperContext.
  • FirebirdDockerContainers � Firebird support if available in the build.

• Extensions and helpers

  • DockerContainerExtensions.CopyFileIntoContainerUsingDockerCopy � uses docker exec/docker cp to copy a local backup file into a container path (used mainly by SQL Server restore helpers).
  • MsSqlContainerExtensions.RestoreDatabaseFromBackupAsync � copies a backup into a SQL Server container and triggers a restore operation via the container's attached IDapperContext.

Usage (typical test bootstrap)

1. Ensure Docker is available and running. The library exposes helpers but does not fully manage Docker Desktop lifecycle for you:

   if (!DockerRun.Instance.IsRunning())
   {
       // either instruct developer/CI to start Docker or call DockerInstaller.Instance.EnsureIsInstalled()
   }
   

2. Start a container and obtain an IDapperContext bound to it (example for SQL Server):

   var (ctx, container) = MsSqlDockerContainers.Instance.GetDapperContextUsingDockerContainer();
   // Use ctx for integration tests, then dispose
   ctx.Dispose(); // will stop and dispose the container
   

3. Use restore helper if you need to load a .bak file into the container:

   var container = /* started Testcontainers MsSqlContainer */;
   await container.RestoreDatabaseFromBackupAsync(ctx, "localpath/to/backup.bak", "TargetDbName");
   

Notes and recommendations

• Testcontainers dependency: the code uses DotNet.Testcontainers (Testcontainers.MsSql, Testcontainers.PostgreSql, Testcontainers.MySql, etc.) to manage container lifecycles. Include compatible package versions for your target runtime.
• Platform differences:
  • Windows: Docker Desktop installer path is downloaded and launched by DockerInstaller and may require administrator privileges.
  • Linux: the installer runs the official get.docker.com script and requires sudo to complete.
  • macOS: user must install Docker Desktop manually.
• The helpers will pull container images when missing; this can take time on CI or first-run.
• Calling GetDapperContextUsingDockerContainer returns a context that will attempt to stop & dispose the container when the context is disposed (helps keep tests isolated).
• Copying large backup files into containers uses the docker CLI (docker cp) under the hood. Ensure the CLI is available on PATH and the current user has permissions to interact with Docker.

Security and CI

• In CI environments prefer pre-pulled images or caching to reduce test startup time.
• Running the install flows (automatic installers) requires elevated privileges and is not suitable for most CI setups � prefer pre-configured runners with Docker already installed.

Extensibility

• Add or override Docker images by setting the DockerImage property on provider container singletons before calling GetDapperContextUsingDockerContainer.
• Implement custom builders by extending the base SqlDockerContainers<TBuilder> patterns for other database engines.

License / Contributing

See repository root for license and contribution guidelines.