PrivateRadar.DbBackup 1.0.5

PrivateRadar.DbBackup

A .NET 10 library for backing up PostgreSQL databases to AWS S3.

Features

• Backup PostgreSQL databases using pg_dump
• Upload backups directly to AWS S3
• Support for custom S3 paths and automatic timestamped backups
• Uses the PrivateRadar.Aws library for S3 operations
• Periodic background service for automatic scheduled backups via AddDbBackupService

Installation

Install the package via NuGet:

dotnet add package PrivateRadar.DbBackup

Prerequisites

• .NET 10.0 or higher
• PostgreSQL client tools (pg_dump) must be installed and available in PATH
• AWS credentials configured for S3 access
• PrivateRadar.Aws package (automatically installed as a dependency)

Usage

Basic Example

using Microsoft.Extensions.Logging;
using PrivateRadar.Aws;
using PrivateRadar.DbBackup;

// Create logger
using var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());
var logger = loggerFactory.CreateLogger<Program>();

// Initialize S3 service from PrivateRadar.Aws
var s3Logger = loggerFactory.CreateLogger<S3>();
var s3 = new S3(s3Logger);

// Create backup service
var backupService = new PostgresBackupService(
    host: "localhost",
    port: 5432,
    database: "mydb",
    username: "postgres",
    password: "mypassword",
    bucketName: "my-backup-bucket",
    s3: s3
);

// Backup with custom S3 key
var s3Key = await backupService.BackupToS3Async("backups/mydb_manual_backup.sql");
Console.WriteLine($"Backup uploaded to: {s3Key}");

// Backup with automatic timestamp
var timestampedKey = await backupService.BackupToS3WithTimestampAsync("backups/");
Console.WriteLine($"Backup uploaded to: {timestampedKey}");

Using Configuration Object

using PrivateRadar.DbBackup;

var config = new PostgresBackupConfiguration
{
    Host = "localhost",
    Port = 5432,
    Database = "mydb",
    Username = "postgres",
    Password = "mypassword",
    BucketName = "my-backup-bucket",
    KeyPrefix = "backups/"
};

// Use the configuration to create the service
var backupService = new PostgresBackupService(
    config.Host,
    config.Port,
    config.Database,
    config.Username,
    config.Password,
    config.BucketName,
    s3
);

Environment Variables for Password

For better security, you can omit the password parameter and set the PGPASSWORD environment variable:

// Set environment variable
Environment.SetEnvironmentVariable("PGPASSWORD", "mypassword");

// Create service without password
var backupService = new PostgresBackupService(
    host: "localhost",
    port: 5432,
    database: "mydb",
    username: "postgres",
    password: null,  // Will use PGPASSWORD environment variable
    bucketName: "my-backup-bucket",
    s3: s3
);

API Reference

PostgresBackupService

Constructor

public PostgresBackupService(
    string host,
    int port,
    string database,
    string username,
    string? password,
    string bucketName,
    IS3 s3)

Parameters:

• host - PostgreSQL server hostname or IP address
• port - PostgreSQL port (typically 5432)
• database - Database name to backup
• username - Database username
• password - Database password (optional if using PGPASSWORD environment variable)
• bucketName - S3 bucket name where backups will be stored
• s3 - Instance of IS3 from PrivateRadar.Aws

Methods

BackupToS3Async

public async Task<string> BackupToS3Async(string s3Key, CancellationToken cancellationToken = default)

Creates a backup and uploads it to S3 with the specified key.

Parameters:

• s3Key - The S3 key (path) where the backup will be stored
• cancellationToken - Optional cancellation token

Returns: The S3 key of the uploaded backup

BackupToS3WithTimestampAsync

public async Task<string> BackupToS3WithTimestampAsync(string? keyPrefix = null, TimestampFormat timestampFormat = TimestampFormat.DateOnly, CancellationToken cancellationToken = default)

Creates a backup and uploads it to S3 with an automatically generated timestamped filename.

Parameters:

• keyPrefix - Optional prefix for the S3 key (e.g., "backups/")
• timestampFormat - Timestamp format for the filename: TimestampFormat.DateOnly (default, e.g., 2024-02-15) or TimestampFormat.DateAndTime (e.g., 2024-02-15_143022)
• cancellationToken - Optional cancellation token

Returns: The S3 key of the uploaded backup

Example output (DateOnly): backups/mydb_backup_2024-02-15.backup

Example output (DateAndTime): backups/mydb_backup_2024-02-15_143022.backup

PostgresBackupConfiguration

A configuration class for PostgreSQL backup settings.

Properties:

• Host (required) - PostgreSQL host
• Port - PostgreSQL port (default: 5432)
• Database (required) - Database name
• Username (required) - Database username
• Password - Database password (optional)
• BucketName (required) - S3 bucket name
• KeyPrefix - Optional prefix for S3 keys

DbBackupBackgroundService

A hosted background service that periodically backs up a PostgreSQL database to AWS S3. Register it in one line using the AddDbBackupService extension method:

// Program.cs
builder.Services.AddDbBackupService(connectionString);

Configuration keys (appsettings.json):

{
  "DbBackup": {
    "IntervalHours": 6,
    "BucketName": "my-backup-bucket",
    "KeyPrefix": "backups/",
    "TimestampFormat": "DateOnly"
  }
}

• DbBackup:IntervalHours - How often to run a backup (in hours, default: 24)
• DbBackup:BucketName - S3 bucket name for storing backups
• DbBackup:KeyPrefix - Optional prefix for S3 keys (e.g., "backups/")
• DbBackup:TimestampFormat - Optional timestamp format for the backup filename: DateOnly (default, e.g., 2024-02-15) or DateAndTime (e.g., 2024-02-15_143022)

Requirements

PostgreSQL Client Tools

The library requires pg_dump to be installed and accessible in the system PATH.

Installation:

• Ubuntu/Debian: sudo apt-get install postgresql-client
• RHEL/CentOS: sudo yum install postgresql
• macOS: brew install postgresql
• Windows: Download from PostgreSQL official website

AWS Credentials

AWS credentials must be configured for S3 access. This can be done through:

• AWS credentials file (~/.aws/credentials)
• Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
• IAM roles (when running on EC2/ECS)

License

MIT

Related Packages

• PrivateRadar.Aws - AWS utilities for .NET