Do you want to easily use pg_dump from C# but still have great control over how the output is handled?
Look no further!
This library lets you use one of the existing output providers or define your own to handle the output stream in your preferred way - file, memory, network, or anything else you want.
Simple to get started (see Quick Start). Powerful when needed.
pg_dump is the standard PostgreSQL command-line tool used to create backups of a database.
It exports the contents of a database to a file — either as plain SQL text or as a binary archive (tar, custom, or directory formats).
These files can later be used to restore the database exactly as it was.
This library makes it easy to use pg_dump directly from your C# applications, without manually handling command-line arguments, processes, or stream output.
Core Components of this library
— main class to perform database dumps or list databases.
PgClient
DumpAsync() — dump a database to any IOutputProvider.
ListDatabasesAsync() — list all databases on the server. Returns a simple List<string> with the names.
IOutputProvider — interface for handling output (write to file, memory, your own type).
ConnectionOptions options = new ConnectionOptions("localhost", 5432, "postgres", "your_password", "your_database");
PgClient client = new PgClient(options);
FileOutputProvider outputProvider = new FileOutputProvider("dump.tar");
await client.DumpAsync(outputProvider, timeout: TimeSpan.FromMinutes(1));
Dump a database into a memory stream
ConnectionOptions options = new ConnectionOptions("localhost", 5432, "postgres", "your_password", "your_database");
PgClient client = new PgClient(options);
using MemoryStream memoryStream = new MemoryStream();
StreamOutputProvider outputProvider = new StreamOutputProvider(memoryStream);
await client.DumpAsync(outputProvider, timeout: TimeSpan.FromMinutes(1));
// You now have the dump data in memoryStream
Create your own custom output provider
Implement IOutputProvider:
public class MyCustomOutputProvider : IOutputProvider
{
public async Task WriteAsync(Stream inputStream, CancellationToken cancellationToken)
{
// Example: read and process the dump data however you want
using MemoryStream buffer = new MemoryStream();
await inputStream.CopyToAsync(buffer, cancellationToken);
// Do something with buffer...
}
}
Use it:
MyCustomOutputProvider outputProvider = new MyCustomOutputProvider();
await client.DumpAsync(outputProvider, timeout: TimeSpan.FromMinutes(1));
Listing databases
You can also list all databases on the server easily:
outputProvider
The output provider that will receive the pg_dump stream.
You can use built-in ones like FileOutputProvider and StreamOutputProvider, or create your own.
timeout
The maximum allowed time for the dump operation.
If the operation exceeds this time, it will automatically cancel and throw a TimeoutException. (Timeout is enforced even if the provided CancellationToken does not cancel manually.)
format
The desired output format for the dump.
One of:
DumpFormat.Plain (plain SQL text)
DumpFormat.Tar (tar archive)
DumpFormat.Custom (PostgreSQL custom binary format) (not tested in the unit tests!)
DumpFormat.Directory (directory with separate files) (not tested in the unit tests!)
Default is DumpFormat.Tar.
cancellationToken
An optional external CancellationToken that you can pass if you want manual control over cancellation.
If canceled, the operation will throw an OperationCanceledException. (This is combined with the timeout internally.)
⚡ How timeout and cancellationToken work together
Either timeout expiration orcancellationToken cancellation will immediately cancel the operation.
If timeout happens first → you get a TimeoutException.
If cancellation token cancels first → you get an OperationCanceledException.
Safe and reliable in both cases.
Detailed Features
DumpAsync — runs pg_dump and writes output to any stream (file, memory, network, etc.).
ListDatabasesAsync — runs psql and lists all database names cleanly.
Flexible output handling — built-in file and memory output providers, and you can easily create your own.
Proper cancellation and timeout — no stuck processes or infinite hangs.
Safe environment handling — password is passed securely through environment variables.
No assumptions — fully configurable connection options.
