PostgresDevelopmentCluster
Namespace: Ankus.PgConfig
Assembly: Ankus.PgConfig.dll
Manages one persistent, local-only development cluster per PostgreSQL major in an Ankus home. Stopping a server preserves its databases. Existing unowned directories are never initialized or modified.
public sealed class PostgresDevelopmentClusterInheritance: object
Constructors
Section titled “Constructors”PostgresDevelopmentCluster(PostgresInstallation, string?)
Section titled “PostgresDevelopmentCluster(PostgresInstallation, string?)”Describes a development cluster without creating directories or starting processes.
public PostgresDevelopmentCluster(PostgresInstallation installation, string? homeDirectory = null)Parameters:
installation — PostgresInstallation
The PostgreSQL installation that runs the cluster.
homeDirectory — string
The Ankus home, defaulting to ANKUS_HOME or ~/.ankus.
Methods
Section titled “Methods”CreateDatabaseAsync(string, string?, CancellationToken)
Section titled “CreateDatabaseAsync(string, string?, CancellationToken)”Creates a database in the running cluster as another Unix account, or reuses an existing database without modifying it.
public Task<bool> CreateDatabaseAsync(string database, string? runAs, CancellationToken cancellationToken)Parameters:
database — string
The literal database name.
runAs — string
The Unix account and role that creates the database, or null for the cluster’s own role.
cancellationToken — CancellationToken
Cancels database queries and creation.
Returns: Task<bool>
True when a database was created, or false when it already existed.
As cargo pgrx regress –runas runs createdb, psql runs as runAs through
sudo -u and connects as the role of the same name, which owns the new database. That role must exist and
be allowed to create databases. A null account creates the database as the cluster’s postgres role.
CreateDatabaseAsync(string, CancellationToken)
Section titled “CreateDatabaseAsync(string, CancellationToken)”Creates a database in the running cluster, or reuses an existing database without modifying it. Names retain their exact UTF-8 spelling; names exceeding the server’s identifier limit are rejected.
public Task<bool> CreateDatabaseAsync(string database, CancellationToken cancellationToken = default)Parameters:
database — string
The literal database name.
cancellationToken — CancellationToken
Cancels database queries and creation.
Returns: Task<bool>
True when a database was created, or false when it already existed.
DropDatabaseAsync(string, bool, string?, CancellationToken)
Section titled “DropDatabaseAsync(string, bool, string?, CancellationToken)”Drops an exact database from the running development cluster as another Unix account, or leaves an absent database unchanged.
public Task<bool> DropDatabaseAsync(string database, bool force, string? runAs, CancellationToken cancellationToken)Parameters:
database — string
The literal database name. Names exceeding the server’s identifier limit are rejected.
force — bool
Whether PostgreSQL should terminate connections to the selected database before dropping it.
runAs — string
The Unix account and role that drops the database, or null for the cluster’s own role.
cancellationToken — CancellationToken
Cancels database queries and removal.
Returns: Task<bool>
True when a database was dropped, or false when it was already absent.
As cargo pgrx regress –runas runs dropdb, psql runs as runAs through
sudo -u and connects as the role of the same name, which must own the database or be a superuser.
DropDatabaseAsync(string, bool, CancellationToken)
Section titled “DropDatabaseAsync(string, bool, CancellationToken)”Drops an exact database from the running development cluster, or leaves an absent database unchanged. Other databases and the server remain running. PostgreSQL errors preserve their diagnostics.
public Task<bool> DropDatabaseAsync(string database, bool force = false, CancellationToken cancellationToken = default)Parameters:
database — string
The literal database name. Names exceeding the server’s identifier limit are rejected.
force — bool
Whether PostgreSQL should terminate connections to the selected database before dropping it.
cancellationToken — CancellationToken
Cancels database queries and removal.
Returns: Task<bool>
True when a database was dropped, or false when it was already absent.
GetConnectionStringAsync(string, CancellationToken)
Section titled “GetConnectionStringAsync(string, CancellationToken)”Gets a libpq connection string for the running cluster’s actual port and an exact database name. This does not start the server or create the database.
public Task<string> GetConnectionStringAsync(string database, CancellationToken cancellationToken = default)Parameters:
database — string
The literal database name, not a connection string.
cancellationToken — CancellationToken
Cancels status and port discovery.
Returns: Task<string>
Connection settings suitable for psql or another libpq client.
IsRunningAsync(CancellationToken)
Section titled “IsRunningAsync(CancellationToken)”Reports whether the managed cluster is running. A missing cluster is stopped and is not created.
public Task<bool> IsRunningAsync(CancellationToken cancellationToken = default)Parameters:
cancellationToken — CancellationToken
Cancels the native status query.
Returns: Task<bool>
True when pg_ctl reports a running server.
ReadServerLog(CancellationToken)
Section titled “ReadServerLog(CancellationToken)”Refreshes and reads this cluster’s retained diagnostics without starting or stopping a server.
public string ReadServerLog(CancellationToken cancellationToken = default)Parameters:
cancellationToken — CancellationToken
Cancels diagnostic collection.
Returns: string
Native stderr and this server’s retained Windows event messages, or an empty missing log.
StartAsync(PostgresDevelopmentOptions?, CancellationToken)
Section titled “StartAsync(PostgresDevelopmentOptions?, CancellationToken)”Initializes a missing cluster and starts it, preserving existing databases and an already running server. Failed or canceled startup stops any server launched by this operation while retaining initialized data.
public Task<bool> StartAsync(PostgresDevelopmentOptions? options = null, CancellationToken cancellationToken = default)Parameters:
options — PostgresDevelopmentOptions
Port, timeout, instrumentation, and literal PostgreSQL configuration settings.
cancellationToken — CancellationToken
Cancels initialization or startup.
Returns: Task<bool>
True when a server was started, or false when it was already running.
StopAsync(CancellationToken)
Section titled “StopAsync(CancellationToken)”Stops a running managed server with fast shutdown, preserving its data. A missing or stopped cluster is unchanged.
public Task<bool> StopAsync(CancellationToken cancellationToken = default)Parameters:
cancellationToken — CancellationToken
Cancels the shutdown command.
Returns: Task<bool>
True when a running server was stopped.
Properties
Section titled “Properties”DataDirectory
Section titled “DataDirectory”Gets the persistent data directory for this PostgreSQL major.
public string DataDirectory { get; }Value: string
LogFilePath
Section titled “LogFilePath”Gets the retained server log path outside the data directory. On Windows, ReadServerLog refreshes the snapshot with stderr and this server’s Application events.
public string LogFilePath { get; }Value: string