baktainer/API_DOCUMENTATION.md

Baktainer API Documentation

Overview

Baktainer provides a comprehensive Ruby API for automated database backups in Docker environments. This documentation covers all public classes, methods, and configuration options.

Core Classes

Baktainer::Configuration

Manages application configuration with environment variable support and validation.

Constructor

config = Baktainer::Configuration.new(env_vars = ENV)

Methods

#docker_url

Returns the Docker API URL.

Returns: String

#ssl_enabled?

Checks if SSL is enabled for Docker connections.

Returns: Boolean

#compress?

Checks if backup compression is enabled.

Returns: Boolean

#ssl_options

Returns SSL configuration options for Docker client.

Returns: Hash

#to_h

Returns configuration as a hash.

Returns: Hash

#validate!

Validates configuration and raises errors for invalid values.

Returns: self Raises: Baktainer::ConfigurationError

Configuration Options

Option	Environment Variable	Default	Description
docker_url	BT_DOCKER_URL	unix:///var/run/docker.sock	Docker API endpoint
cron_schedule	BT_CRON	0 0 * * *	Backup schedule
threads	BT_THREADS	4	Thread pool size
log_level	BT_LOG_LEVEL	info	Logging level
backup_dir	BT_BACKUP_DIR	/backups	Backup directory
compress	BT_COMPRESS	true	Enable compression
ssl_enabled	BT_SSL	false	Enable SSL
ssl_ca	BT_CA	nil	CA certificate
ssl_cert	BT_CERT	nil	Client certificate
ssl_key	BT_KEY	nil	Client key

Example

config = Baktainer::Configuration.new
puts config.docker_url
puts config.compress?
puts config.to_h

Baktainer::BackupStrategy

Abstract base class for database backup strategies.

Methods

#backup_command(options = {})

Abstract method to generate backup command.

Parameters:

• options (Hash): Database connection options

Returns: Hash with :env and :cmd keys Raises: NotImplementedError

#validate_backup_content(content)

Abstract method to validate backup content.

Parameters:

• content (String): Backup file content

Raises: NotImplementedError

#required_auth_options

Returns required authentication options.

Returns: Array<Symbol>

#requires_authentication?

Checks if authentication is required.

Returns: Boolean

Baktainer::MySQLBackupStrategy

MySQL database backup strategy.

Methods

#backup_command(options = {})

Generates MySQL backup command.

Parameters:

• options (Hash): Required keys: :login, :password, :database

Returns: Hash

Example:

strategy = Baktainer::MySQLBackupStrategy.new(logger)
command = strategy.backup_command(
  login: 'root',
  password: 'secret',
  database: 'mydb'
)
# => { env: [], cmd: ['mysqldump', '-u', 'root', '-psecret', 'mydb'] }

Baktainer::PostgreSQLBackupStrategy

PostgreSQL database backup strategy.

Methods

#backup_command(options = {})

Generates PostgreSQL backup command.

Parameters:

• options (Hash): Required keys: :login, :password, :database
• options[:all] (Boolean): Optional, use pg_dumpall if true

Returns: Hash

Example:

strategy = Baktainer::PostgreSQLBackupStrategy.new(logger)
command = strategy.backup_command(
  login: 'postgres',
  password: 'secret',
  database: 'mydb'
)
# => { env: ['PGPASSWORD=secret'], cmd: ['pg_dump', '-U', 'postgres', '-d', 'mydb'] }

Baktainer::SQLiteBackupStrategy

SQLite database backup strategy.

Methods

#backup_command(options = {})

Generates SQLite backup command.

Parameters:

• options (Hash): Required keys: :database

Returns: Hash

Example:

strategy = Baktainer::SQLiteBackupStrategy.new(logger)
command = strategy.backup_command(database: '/data/mydb.sqlite')
# => { env: [], cmd: ['sqlite3', '/data/mydb.sqlite', '.dump'] }

Baktainer::BackupStrategyFactory

Factory for creating backup strategies.

Class Methods

#create_strategy(engine, logger)

Creates a backup strategy for the specified engine.

Parameters:

• engine (String/Symbol): Database engine type
• logger (Logger): Logger instance

Returns: Baktainer::BackupStrategy Raises: Baktainer::UnsupportedEngineError

#supported_engines

Returns list of supported database engines.

Returns: Array<String>

#supports_engine?(engine)

Checks if engine is supported.

Parameters:

• engine (String/Symbol): Database engine type

Returns: Boolean

#register_strategy(engine, strategy_class)

Registers a custom backup strategy.

Parameters:

• engine (String): Engine name
• strategy_class (Class): Strategy class inheriting from BackupStrategy

Example:

factory = Baktainer::BackupStrategyFactory
strategy = factory.create_strategy('mysql', logger)
puts factory.supported_engines
# => ['mysql', 'mariadb', 'postgres', 'postgresql', 'sqlite', 'mongodb']

Baktainer::BackupMonitor

Monitors backup operations and tracks performance metrics.

Constructor

monitor = Baktainer::BackupMonitor.new(logger)

Methods

#start_backup(container_name, engine)

Starts monitoring a backup operation.

Parameters:

• container_name (String): Container name
• engine (String): Database engine

#complete_backup(container_name, file_path, file_size = nil)

Records successful backup completion.

Parameters:

• container_name (String): Container name
• file_path (String): Backup file path
• file_size (Integer): Optional file size

#fail_backup(container_name, error_message)

Records backup failure.

Parameters:

• container_name (String): Container name
• error_message (String): Error message

#get_metrics_summary

Returns overall backup metrics.

Returns: Hash

#get_container_metrics(container_name)

Returns metrics for specific container.

Parameters:

• container_name (String): Container name

Returns: Hash or nil

#export_metrics(format = :json)

Exports metrics in specified format.

Parameters:

• format (Symbol): Export format (:json or :csv)

Returns: String

Example:

monitor = Baktainer::BackupMonitor.new(logger)
monitor.start_backup('myapp', 'mysql')
monitor.complete_backup('myapp', '/backups/myapp.sql.gz', 1024)
puts monitor.get_metrics_summary

Baktainer::DynamicThreadPool

Dynamic thread pool with automatic sizing and monitoring.

Constructor

pool = Baktainer::DynamicThreadPool.new(
  min_threads: 2,
  max_threads: 20,
  initial_size: 4,
  logger: logger
)

Methods

#post(&block)

Submits a task to the thread pool.

Parameters:

• block (Proc): Task to execute

Returns: Concurrent::Future

#statistics

Returns thread pool statistics.

Returns: Hash

#force_resize(new_size)

Manually resizes the thread pool.

Parameters:

• new_size (Integer): New thread pool size

#shutdown

Shuts down the thread pool.

Example:

pool = Baktainer::DynamicThreadPool.new(logger: logger)
future = pool.post { expensive_operation }
result = future.value
puts pool.statistics
pool.shutdown

Baktainer::DependencyContainer

Dependency injection container for managing application dependencies.

Constructor

container = Baktainer::DependencyContainer.new

Methods

#register(name, &factory)

Registers a service factory.

Parameters:

• name (String/Symbol): Service name
• factory (Proc): Factory block

#singleton(name, &factory)

Registers a singleton service.

Parameters:

• name (String/Symbol): Service name
• factory (Proc): Factory block

#get(name)

Gets a service instance.

Parameters:

• name (String/Symbol): Service name

Returns: Service instance Raises: Baktainer::ServiceNotFoundError

#configure

Configures the container with standard services.

Returns: self

#reset!

Resets all services (useful for testing).

Example:

container = Baktainer::DependencyContainer.new.configure
logger = container.get(:logger)
config = container.get(:configuration)

Baktainer::StreamingBackupHandler

Memory-optimized streaming backup handler for large databases.

Constructor

handler = Baktainer::StreamingBackupHandler.new(logger)

Methods

#stream_backup(container, command, output_path, compress: true, &block)

Streams backup data with memory optimization.

Parameters:

• container (Docker::Container): Docker container
• command (Hash): Backup command
• output_path (String): Output file path
• compress (Boolean): Enable compression
• block (Proc): Optional progress callback

Returns: Integer (total bytes written)

Example:

handler = Baktainer::StreamingBackupHandler.new(logger)
bytes_written = handler.stream_backup(container, command, '/tmp/backup.sql.gz') do |chunk_size|
  puts "Wrote #{chunk_size} bytes"
end

Error Classes

Baktainer::ConfigurationError

Raised when configuration is invalid.

Baktainer::ValidationError

Raised when container validation fails.

Baktainer::UnsupportedEngineError

Raised when database engine is not supported.

Baktainer::ServiceNotFoundError

Raised when requested service is not found in dependency container.

Baktainer::MemoryLimitError

Raised when memory usage exceeds limits during streaming backup.

Usage Examples

Basic Usage

# Create configuration
config = Baktainer::Configuration.new

# Set up dependency container
container = Baktainer::DependencyContainer.new.configure

# Get services
logger = container.get(:logger)
monitor = container.get(:backup_monitor)
thread_pool = container.get(:thread_pool)

# Create backup strategy
strategy = Baktainer::BackupStrategyFactory.create_strategy('mysql', logger)

# Start monitoring
monitor.start_backup('myapp', 'mysql')

# Execute backup
command = strategy.backup_command(login: 'root', password: 'secret', database: 'mydb')
# ... execute backup ...

# Complete monitoring
monitor.complete_backup('myapp', '/backups/myapp.sql.gz')

# Get metrics
puts monitor.get_metrics_summary

Custom Backup Strategy

class CustomBackupStrategy < Baktainer::BackupStrategy
  def backup_command(options = {})
    validate_required_options(options, [:database])
    
    {
      env: [],
      cmd: ['custom-backup-tool', options[:database]]
    }
  end
  
  def validate_backup_content(content)
    unless content.include?('custom-backup-header')
      @logger.warn("Custom backup validation failed")
    end
  end
end

# Register custom strategy
Baktainer::BackupStrategyFactory.register_strategy('custom', CustomBackupStrategy)

# Use custom strategy
strategy = Baktainer::BackupStrategyFactory.create_strategy('custom', logger)

Testing with Dependency Injection

# Override dependencies for testing
container = Baktainer::DependencyContainer.new.configure
mock_logger = double('Logger')
container.override_logger(mock_logger)

# Use mocked logger
logger = container.get(:logger)

Performance Considerations

1. Memory Usage: Use StreamingBackupHandler for large databases to minimize memory usage
2. Thread Pool: Configure appropriate min_threads and max_threads based on your workload
3. Compression: Enable compression for large backups to save disk space
4. Monitoring: Use BackupMonitor to track performance and identify bottlenecks

Thread Safety

All classes are designed to be thread-safe for concurrent backup operations:

• BackupMonitor uses concurrent data structures
• DynamicThreadPool includes proper synchronization
• DependencyContainer singleton services are thread-safe
• StreamingBackupHandler is safe for concurrent use

Logging

All classes accept a logger instance and provide detailed logging at different levels:

• DEBUG: Detailed execution information
• INFO: General operational information
• WARN: Warning conditions
• ERROR: Error conditions

Configure logging level via BT_LOG_LEVEL environment variable.