PSFirebird

A PowerShell module for managing Firebird database environments, databases, and utilities on Windows and Linux.

Features

• Download and run multiple Firebird environments without installation.
• Supports official releases (v3, v4, v5) and snapshot builds (v6 development).
• Create, inspect, and remove Firebird databases.
• Run SQL scripts and queries using Firebird's isql utility.
• Backup and restore Firebird databases (local and remote).
• Convert databases between Firebird versions using high-speed backup/restore streaming.
• Read and write Firebird configuration files.
• Test database validity for health checks and CI/CD pipelines.
• Remote database support via connection strings (host:path, inet://, inet6://).

Requirements

• PowerShell 7.4 or later
• Windows or Linux (Debian-based for Linux)

Connection Strings

Most database commands accept a -Database parameter that supports Firebird connection string formats:

Format	Example
Local path	/data/mydb.fdb or C:\data\mydb.fdb
Legacy host:path	myserver:/data/mydb.fdb
Legacy host/port:path	myserver/3051:/data/mydb.fdb
URI inet://host/path	inet://myserver/data/mydb.fdb
URI inet4://host/path	inet4://myserver/data/mydb.fdb
URI inet6://[host]/path	inet6://[::1]/data/mydb.fdb
Shared memory	xnet://security.db

Commands that support remote databases: Backup-FirebirdDatabase, Restore-FirebirdDatabase, Convert-FirebirdDatabase, Get-FirebirdDatabase, Get-FirebirdDatabaseStatistics, Test-FirebirdDatabase, New-FirebirdDatabase, Invoke-FirebirdIsql, Read-FirebirdDatabase, Lock-FirebirdDatabase, Unlock-FirebirdDatabase.

Commands that require local databases: Remove-FirebirdDatabase.

Installation

Run the following command to install this package using PowerShellGet:

Install-Module -Name PSFirebird

Using in GitHub Actions

A complete example of using PSFirebird in a CI/CD workflow is available in .github/workflows/example.yml.

This workflow demonstrates:

• Installing PSFirebird from the PowerShell Gallery
• Creating a Firebird environment for testing
• Creating and configuring databases
• Running SQL queries

The example runs on both Windows and Linux platforms using a matrix build strategy.

PSFirebird automatically uses GITHUB_TOKEN when it is available, increasing the rate limit to 5,000 requests/hour. To enable this in your GitHub Actions workflows, add GITHUB_TOKEN: ${{ github.token }} to the job or step env.

Multi-step workflows

PowerShell objects do not persist between separate run: steps. Use the FIREBIRD_ENVIRONMENT environment variable to share the environment path across steps — all PSFirebird cmdlets will use it automatically when no -Environment parameter is provided.

- name: Create Firebird Environment
  run: |
    $fbEnv = New-FirebirdEnvironment -Version '5.0.3'
    # Persist the path so subsequent steps can use it without -Environment
    "FIREBIRD_ENVIRONMENT=$($fbEnv.Path)" >> $env:GITHUB_ENV

- name: Create database
  run: |
    # $env:FIREBIRD_ENVIRONMENT is automatically used as the default environment
    New-FirebirdDatabase -Database '/tmp/test.fdb'

- name: Run query
  run: |
    'SELECT 1 FROM RDB$DATABASE;' | Invoke-FirebirdIsql -Database '/tmp/test.fdb'

Usage

Command summary

Command	Description
Environment commands
New-FirebirdEnvironment	Download and set up a Firebird environment.
Get-FirebirdEnvironment	Get information about a Firebird environment.
Remove-FirebirdEnvironment	Remove a Firebird environment directory.
Use-FirebirdEnvironment	Set the default Firebird environment for a given context.
Database commands
New-FirebirdDatabase	Create a new Firebird database.
Get-FirebirdDatabase	Get information about a Firebird database.
Get-FirebirdDatabaseStatistics	Collect statistics for a Firebird database.
Test-FirebirdDatabase	Test if a Firebird database is valid and accessible.
Remove-FirebirdDatabase	Safely remove a Firebird database file.
Read-FirebirdDatabase	Read detailed info from a Firebird database.
Invoke-FirebirdIsql	Execute SQL statements using Firebird isql.
Instance commands
Start-FirebirdInstance	Start a Firebird server process.
Get-FirebirdInstance	Get information about running Firebird server processes.
Stop-FirebirdInstance	Stop a running Firebird server process.
Service commands
New-FirebirdService	Register a Firebird environment as a system service.
Get-FirebirdService	Get information about registered Firebird services.
Remove-FirebirdService	Remove a Firebird system service.
Configuration commands
Read-FirebirdConfiguration	Read settings from a Firebird configuration file.
Write-FirebirdConfiguration	Update settings in a Firebird configuration file.
Backup and restore commands
Backup-FirebirdDatabase	Create a backup file from a Firebird database.
Restore-FirebirdDatabase	Restore a Firebird database from a backup file.
Convert-FirebirdDatabase	Perform backup and restore operations using streaming.
Lock-FirebirdDatabase	Lock a database for filesystem copy.
Unlock-FirebirdDatabase	Unlock a database after filesystem copy.
Release commands
Find-FirebirdRelease	Find the download URL and metadata for an official Firebird release.
Find-FirebirdSnapshotRelease	Find the latest snapshot build for a Firebird branch.
Utility commands
Get-FirebirdVersion	Parse a Firebird version string into a structured object.

Environment commands

New-FirebirdEnvironment

Download and set up a Firebird environment.

New-FirebirdEnvironment -Version <semver> [-Path <string>] [-RuntimeIdentifier <string>] [-Force] [<CommonParameters>]
New-FirebirdEnvironment -Branch <string> [-Path <string>] [-RuntimeIdentifier <string>] [-Force] [<CommonParameters>]

Downloads and extracts Firebird binaries to a directory. Two modes are supported:

• -Version — downloads an official release (e.g. 5.0.3, 4.0.6, 3.0.13).
• -Branch — downloads the latest snapshot build for a development branch (e.g. master for Firebird 6.x). Available branches: master, v5.0-release, v4.0.

Use -Path to indicate the target folder. If no path is given, a temporary directory is used.

Use -Force to overwrite an existing environment.

Note that most commands require an -Environment as argument. See Use-FirebirdEnvironment to avoid repetitions.

# Example: Create a Firebird 5 environment
$fb5 = New-FirebirdEnvironment -Version '5.0.3' -Path '/tmp/firebird5'
Use-FirebirdEnvironment -Environment $fb5 {
    $db5 = New-FirebirdDatabase -Database '/tmp/test.fdb' -Force
    Read-FirebirdDatabase -Database $db5
}

# Example: Install the latest Firebird 6 development snapshot
$fb6 = New-FirebirdEnvironment -Branch 'master' -Path '/tmp/firebird6'

NOTICE: This command queries the GitHub API to retrieve the download URL for the specified version. GitHub enforces a rate limit of 60 requests per hour for unauthenticated requests.

• To raise this limit to 5,000 requests per hour, define the API_GITHUB_ACCESS_TOKEN environment variable with a valid access token.
• In GitHub Actions, add GITHUB_TOKEN: ${{ github.token }} to your job or step env to use the built-in token (both variables are equivalent).

Get-FirebirdEnvironment

Get information about a Firebird environment.

Get-FirebirdEnvironment -Path <string> [<CommonParameters>]

Returns a FirebirdEnvironment object with details about the specified or current environment.

# Example: Get environment info for a specific path
Get-FirebirdEnvironment -Path '/tmp/firebird5'

Remove-FirebirdEnvironment

Remove a Firebird environment directory.

Remove-FirebirdEnvironment [-Path] <string> [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

Removes a previously created Firebird environment directory after verifying it contains a valid Firebird installation (checks for the gstat binary).

Use -Force to suppress confirmation prompts.

# Example: Remove a Firebird environment
Remove-FirebirdEnvironment -Path '/tmp/firebird-5.0.2' -Force

Use-FirebirdEnvironment

Set the default Firebird environment for a given context.

Use-FirebirdEnvironment -Environment <FirebirdEnvironment> -ScriptBlock <scriptblock> [<CommonParameters>]

Temporarily sets the default Firebird environment for all commands executed within the provided script block.

You can pass the environment as pipeline input. However, due to a limitation in PowerShell's parameter binding with pipeline inputs, you must explicitly specify the -ScriptBlock argument in this case.

Alternatively, you can set the FIREBIRD_ENVIRONMENT environment variable to a Firebird installation path. This will be used as a fallback when no context environment is available and no -Environment parameter is provided.

# Example: Use a specific environment for a set of commands
$fb5 | Use-FirebirdEnvironment -ScriptBlock {
    New-FirebirdDatabase -Database '/tmp/test.fdb'  # No -Environment needed here
    Backup-FirebirdDatabase -Database '/tmp/test.fdb' -BackupFilePath '/tmp/backup.fbk'
}

# Example: Set a default environment using an environment variable
$env:FIREBIRD_ENVIRONMENT = '/tmp/firebird5'
New-FirebirdDatabase -Database '/tmp/test.fdb'  # Uses the environment from $env:FIREBIRD_ENVIRONMENT

Database commands

New-FirebirdDatabase

Create a new Firebird database.

New-FirebirdDatabase -Database <string> [-Credential <PSCredential>] [-User <string>] [-Password <string>] [-PageSize <int>] [-Charset <string>] [-Environment <FirebirdEnvironment>] [-Force] [<CommonParameters>]

Creates a new Firebird database file. You can specify the following database options:

• -Credential (a PSCredential object; overrides -User and -Password when specified)
• -User (default: SYSDBA)
• -Password (default: masterkey)
• -PageSize (default: 8192)
• -Charset (default: UTF8)

Use -Force ⚠️ to overwrite an existing database.

# Example: Create a new database with custom options
New-FirebirdDatabase -Database '/tmp/newdb.fdb'

# Example: Create a database using PSCredential
New-FirebirdDatabase -Database '/tmp/newdb.fdb' -Credential (Get-Credential)

Get-FirebirdDatabase

Get information about a Firebird database.

Get-FirebirdDatabase [-Database] <FirebirdDatabase> [-Environment <FirebirdEnvironment>] [<CommonParameters>]

Returns a FirebirdDatabase object with details such as page size and ODS version. Supports both local and remote databases via connection strings.

Supports pipeline input from Get-ChildItem via the FullName property.

# Example: Get database info
Get-FirebirdDatabase -Database '/tmp/mydb.fdb'

# Example: Get info for a remote database
Get-FirebirdDatabase -Database 'myserver:/data/mydb.fdb'

# Example: Get info for all databases in a directory
Get-ChildItem *.fdb | Get-FirebirdDatabase

Get-FirebirdDatabaseStatistics

Collect statistics for a Firebird database.

Get-FirebirdDatabaseStatistics [-Database] <FirebirdDatabase> [-TableName <string[]>] [-Environment <FirebirdEnvironment>] [<CommonParameters>]

Runs the gstat utility with the -a (analyze all tables) and -r (record versions) flags to collect detailed statistics for the database, then parses the output into a structured object.

The returned object has two array properties:

• tables — one record per table with page layout, record counts, version info, and fill distribution.
• indices — one record per index with depth, node counts, key lengths, clustering factor, and fill distribution.

Use -TableName to restrict the analysis to one or more specific tables and their indices.

# Example: Get statistics for all tables
Get-FirebirdDatabaseStatistics -Database '/tmp/mydb.fdb'

# Example: Get statistics for specific tables only
Get-FirebirdDatabaseStatistics -Database '/tmp/mydb.fdb' -TableName 'CUSTOMERS', 'ORDERS'

Test-FirebirdDatabase

Test if a Firebird database is valid and accessible.

Test-FirebirdDatabase [-Database] <FirebirdDatabase> [-Environment <FirebirdEnvironment>] [<CommonParameters>]

Checks if the specified database file exists and can be read by gstat. Returns $true if the database is valid and accessible, $false otherwise. Useful for CI/CD pipelines and health checks.

# Example: Test a database
if (Test-FirebirdDatabase -Database '/tmp/mydb.fdb') {
    Write-Host 'Database is valid'
}

Remove-FirebirdDatabase

Safely remove a Firebird database file.

Remove-FirebirdDatabase [-Database] <FirebirdDatabase> [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

Removes a local Firebird database file after verifying it is not locked for backup (no .delta file present). This command only supports local databases.

Use -Force to suppress confirmation prompts.

# Example: Remove a database
Remove-FirebirdDatabase -Database '/tmp/mydb.fdb' -Force

Read-FirebirdDatabase

Read detailed info from a Firebird database.

Read-FirebirdDatabase -Database <string> [-Environment <FirebirdEnvironment>] [<CommonParameters>]

Reads and returns properties from MON$DATABASE and RDB$DATABASE for the specified database.

# Example: Read database properties
Read-FirebirdDatabase -Database '/tmp/mydb.fdb'

Invoke-FirebirdIsql

Execute SQL statements using Firebird isql.

Invoke-FirebirdIsql -Database <FirebirdDatabase> -Sql <string> [-Environment <FirebirdEnvironment>] [<CommonParameters>]

Executes SQL statements against a Firebird database using the isql utility. Accepts SQL from the pipeline.

# Example: Run a SQL query
Invoke-FirebirdIsql -Database '/tmp/mydb.fdb' -Sql 'SELECT * FROM RDB$DATABASE;'

# Example: Using pipeline input
'SELECT COUNT(*) FROM MY_TABLE;' | Invoke-FirebirdIsql -Database '/tmp/mydb.fdb'

Instance commands

Start-FirebirdInstance

Start a Firebird server process.

Start-FirebirdInstance [-Port <int>] [-Environment <FirebirdEnvironment>] [<CommonParameters>]

Launches a Firebird server process from the specified environment and returns a FirebirdInstance object. The server runs on the specified port (default: 3050).

# Example: Start a Firebird server on custom port
$fb5 = Get-FirebirdEnvironment -Path '/tmp/firebird5'
$instance = Start-FirebirdInstance -Port 3051 -Environment $fb5

Note: The archive-extracted Firebird security database ships with no users. TCP connections require SYSDBA to be initialized first via an embedded connection (which bypasses authentication). Example:

$fb5 = New-FirebirdEnvironment -Version '5.0.3'
$db  = New-FirebirdDatabase -Database '/tmp/test.fdb' -Environment $fb5

# Initialize SYSDBA password for TCP connections -- Do this once before starting the server.
"CREATE USER SYSDBA PASSWORD 'masterkey';" |
    Invoke-FirebirdIsql -Database $db -Environment $fb5

$instance = Start-FirebirdInstance -Port 3051 -Environment $fb5

Get-FirebirdInstance

Get information about running Firebird server processes.

Get-FirebirdInstance [<CommonParameters>]

Returns information about all running Firebird processes including process ID, path, version, command line, start time, and port number.

# Example: List all running Firebird instances
Get-FirebirdInstance

# Example: Find instances on a specific port
Get-FirebirdInstance | Where-Object { $_.Port -eq 3051 }

Stop-FirebirdInstance

Stop a running Firebird server process.

Stop-FirebirdInstance -Id <int> [<CommonParameters>]

Terminates a Firebird server process by process ID. Can accept pipeline input from Get-FirebirdInstance or any object with an Id property.

# Example: Stop a specific Firebird instance
Stop-FirebirdInstance -Id 1234

# Example: Stop all running Firebird instances
Get-FirebirdInstance | Stop-FirebirdInstance

# Example: Stop instances on a specific port
Get-FirebirdInstance | Where-Object { $_.Port -eq 3051 } | Stop-FirebirdInstance

Service commands

New-FirebirdService

Register a Firebird environment as a system service.

New-FirebirdService -Environment <FirebirdEnvironment> [-Port <int>] [-Name <string>] [-NoStart] [-WhatIf] [-Confirm] [<CommonParameters>]

Installs a Firebird server as a system service (Windows Service Manager on Windows, systemd on Linux). The listening port is configured in the environment's firebird.conf via RemoteServicePort.

Use -Port to set the TCP listening port (default: 3050).

Use -Name to set a custom service name. If not specified, the name defaults to Firebird-{MajorVersion} (e.g., Firebird-5).

Use -NoStart to register the service without starting it.

Requires elevated privileges (Administrator on Windows, root on Linux).

# Example: Install Firebird 5 as a service on port 3055
$fb5 = New-FirebirdEnvironment -Version '5.0.3'
New-FirebirdService -Environment $fb5 -Port 3055

# Example: Run multiple Firebird versions side by side
$fb3 = New-FirebirdEnvironment -Version '3.0.13'
$fb4 = New-FirebirdEnvironment -Version '4.0.6'
$fb5 = New-FirebirdEnvironment -Version '5.0.3'
New-FirebirdService -Environment $fb3 -Port 3053
New-FirebirdService -Environment $fb4 -Port 3054
New-FirebirdService -Environment $fb5 -Port 3055

Get-FirebirdService

Get information about registered Firebird services.

Get-FirebirdService [-Name <string>] [<CommonParameters>]

Returns details of Firebird services registered on the system, including the service name, status, port, and environment path.

# Example: List all Firebird services
Get-FirebirdService

# Example: Get a specific service
Get-FirebirdService -Name 'Firebird-5'

Remove-FirebirdService

Remove a Firebird system service.

Remove-FirebirdService [-Name] <string> [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
Remove-FirebirdService -Environment <FirebirdEnvironment> [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

Stops and unregisters a Firebird service from the system. Accepts pipeline input from Get-FirebirdService.

You can specify the service by -Name or by -Environment (which derives the default name).

Use -Force to suppress confirmation prompts.

# Example: Remove a service by name
Remove-FirebirdService -Name 'Firebird-5' -Force

# Example: Remove a service by environment
Remove-FirebirdService -Environment $fb5 -Force

# Example: Remove all Firebird services
Get-FirebirdService | Remove-FirebirdService -Force

Configuration commands

Read-FirebirdConfiguration

Read settings from a Firebird configuration file.

Read-FirebirdConfiguration -Path <string> [<CommonParameters>]

Reads all active (non-commented) configuration entries from a Firebird config file and returns them as a hashtable.

# Example: Read configuration
Read-FirebirdConfiguration -Path '/opt/firebird/firebird.conf'

Write-FirebirdConfiguration

Update settings in a Firebird configuration file.

Write-FirebirdConfiguration -Path <string> -Configuration <hashtable> [-WhatIf] [-Confirm] [<CommonParameters>]

Updates, adds, or comments out configuration entries in the file based on the provided hashtable. Use $null as a value to comment out a key.

# Example: Update a configuration value
Write-FirebirdConfiguration -Path '/opt/firebird/firebird.conf' -Configuration @{ 'Key' = 'Value' }

# Example: Comment out a configuration key
Write-FirebirdConfiguration -Path '/opt/firebird/firebird.conf' -Configuration @{ 'Key' = $null }

Backup and restore commands

⚠️ Caution when restoring databases

Do not use -Force option with production databases.

This option exists for convenience in test scenarios only. Never overwrite a production database since a failure in the process (e.g., due to a corrupt backup) may cause a potential data loss.

Always restore a backup to a different database file. The Restore-FirebirdDatabase command’s default behavior of appending a .restore suffix when no database file is specified is a good practice.

The backup, restore, and convert commands authenticate through the Firebird utilities. In a fresh shell, set ISC_USER and ISC_PASSWORD to the database owner or SYSDBA before using them.

Backup-FirebirdDatabase

Create a backup file from a Firebird database.

Backup-FirebirdDatabase [-Database] <FirebirdDatabase> [[-BackupFilePath] <String>] [-Environment <FirebirdEnvironment>] [-Force] [-Transportable] [-WhatIf] [-Confirm] [-RemainingArguments <Object>] [<CommonParameters>]
Backup-FirebirdDatabase [-Database] <FirebirdDatabase> -AsCommandLine [-Environment <FirebirdEnvironment>] [-Force] [-Transportable] [-RemainingArguments <Object>] [<CommonParameters>]

Use -Database to specify the source database, and -BackupFilePath to define the target backup file. If not specified, the backup file defaults to the database name with a .fbk extension.

The -AsCommandLine option outputs a gbak command line equivalent for the same operation.

The backup file must not already exist. Use the -Force option to overwrite it if necessary.

By default, all backups are created as non-transportable, resulting in approximately 5% faster performance. Use the -Transportable option if you plan to restore the database on a different system.

Any extra arguments provided to this cmdlet will be forwarded to the gbak command.

# Example: Create a transportable backup.
Backup-FirebirdDatabase -Database '/tmp/mydb.fdb' -BackupFile '/backups/mydb.fbk' -Transportable

# Example: Backup a remote database.
Backup-FirebirdDatabase -Database 'myserver:/data/mydb.fdb' -BackupFile '/backups/mydb.fbk'

Restore-FirebirdDatabase

Restore a Firebird database from a backup file.

Restore-FirebirdDatabase [-BackupFilePath] <string> [[-Database] <FirebirdDatabase>] [-Environment <FirebirdEnvironment>] [-Force] [-WhatIf] [-Confirm] [-RemainingArguments <Object>] [<CommonParameters>]
Restore-FirebirdDatabase -AsCommandLine -Database <FirebirdDatabase> [-Environment <FirebirdEnvironment>] [-Force] [-RemainingArguments <Object>] [<CommonParameters>]

Use -BackupFilePath to specify the source backup file, and -Database to define the target database. If not specified, the database defaults to the backup file name with a .restored.fdb extension.

The -AsCommandLine option outputs a gbak command line equivalent for the same operation. In this case you must specify a -Database to restore to.

The database must not already exist. Use the -Force ⚠️ option to overwrite it if necessary.

Any extra arguments provided to this cmdlet will be forwarded to the gbak command.

# Example: restore a Firebird database from backup.
Restore-FirebirdDatabase -BackupFile '/backups/mydb.fbk' -Database '/tmp/mydb.restored.fdb'

Convert-FirebirdDatabase

Perform backup and restore operations using streaming.

Convert-FirebirdDatabase -SourceDatabase <string> -TargetDatabase <string> [-SourceEnvironment <FirebirdEnvironment>] [-TargetEnvironment <FirebirdEnvironment>] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

Start two gbak instances (one to perform the backup and the other to restore) by piping the output of the first directly into the second. This enables a full backup/restore cycle without creating intermediate files.

Use this when migrating across major Firebird versions (with different On-Disk-Structure formats) or during routine maintenance by performing a full backup and restore in the same version.

The target database must not already exist. Use the -Force ⚠️ option to overwrite it if necessary.

# Example: Convert a Firebird database from v3 to v5
$env:ISC_USER = 'SYSDBA'
$env:ISC_PASSWORD = 'masterkey'

$fb3 = New-FirebirdEnvironment -Version '3.0.13'
$fb5 = New-FirebirdEnvironment -Version '5.0.3'

Convert-FirebirdDatabase -SourceDatabase '/tmp/mydb3.fdb' `
                         -SourceEnvironment $fb3 `
                         -TargetDatabase '/tmp/mydb5.fdb' `
                         -TargetEnvironment $fb5

# Example: Convert a v5 database to v6 using the latest snapshot
$fb6 = New-FirebirdEnvironment -Branch 'master'

Convert-FirebirdDatabase -SourceDatabase '/tmp/mydb5.fdb' `
                         -SourceEnvironment $fb5 `
                         -TargetDatabase '/tmp/mydb6.fdb' `
                         -TargetEnvironment $fb6

Lock-FirebirdDatabase

Lock a database for filesystem copy.

Lock-FirebirdDatabase [-Database] <FirebirdDatabase> [-Environment <FirebirdEnvironment>] [-WhatIf] [-Confirm] [-RemainingArguments <Object>] [<CommonParameters>]

Locks a Firebird database for safe filesystem-level copying.

Any extra arguments provided to this cmdlet will be forwarded to the nbackup command.

# Example: Lock a database for copy
Lock-FirebirdDatabase -Database '/tmp/mydb.fdb' -Environment $fb5

Unlock-FirebirdDatabase

Unlock a database after filesystem copy.

Unlock-FirebirdDatabase [-Database] <FirebirdDatabase> [-Environment <FirebirdEnvironment>] [-WhatIf] [-Confirm] [-RemainingArguments <Object>] [<CommonParameters>]

Unlocks a Firebird database after a filesystem-level copy.

If the database is missing a .delta file, it will attempt to fix it using the nbackup -fixup option.

Any extra arguments provided to this cmdlet will be forwarded to the nbackup command.

# Example: Unlock a database after copy
Unlock-FirebirdDatabase -Database '/tmp/mydb.fdb' -Environment $fb5

Release commands

Find-FirebirdRelease

Find the download URL and metadata for an official Firebird release.

Find-FirebirdRelease -Version <semver> [-RuntimeIdentifier <string>] [<CommonParameters>]

Queries the GitHub API for FirebirdSQL/firebird releases and returns a structured object with the download URL, file name, version, and SHA-256 digest for the matching asset. The SHA-256 digest is available for releases published from July 2025 onward; older releases return $null.

This function exposes the same GitHub release lookup logic used internally by New-FirebirdEnvironment, allowing external consumers to resolve release URLs without installing Firebird locally.

# Example: Find the Firebird 5.0.2 release for Linux x64
$release = Find-FirebirdRelease -Version '5.0.2' -RuntimeIdentifier 'linux-x64'
$release.Url       # https://github.com/FirebirdSQL/firebird/releases/download/v5.0.2/Firebird-5.0.2.1613-0-linux-x64.tar.gz
$release.FileName  # Firebird-5.0.2.1613-0-linux-x64.tar.gz
$release.Version   # 5.0.2
$release.Sha256    # a1b2c3d4... (or $null for older releases)

# Example: Find the Firebird 4.0.5 release for Windows x64
Find-FirebirdRelease -Version '4.0.5' -RuntimeIdentifier 'win-x64'

Find-FirebirdSnapshotRelease

Find the latest snapshot build for a Firebird branch.

Find-FirebirdSnapshotRelease -Branch <string> [-RuntimeIdentifier <string>] [<CommonParameters>]

Queries the GitHub API for FirebirdSQL/snapshots releases and returns a structured object with the download URL, file name, SHA-256 digest, branch, and upload timestamp.

Asset discovery is done by substring matching rather than filename reconstruction, making the function robust to upstream naming changes.

Available branches:

Branch	Description	Tag
master	Firebird 6.x development builds	snapshot-master
v5.0-release	Firebird 5.x next-patch builds	snapshot-v5.0-release
v4.0	Firebird 4.x next-patch builds	snapshot-v4.0

# Example: Get the latest Firebird 5 snapshot for amd64
$snap = Find-FirebirdSnapshotRelease -Branch 'v5.0-release'
$snap.FileName   # Firebird-5.0.4.1803-4daf29e-linux-x64.tar.gz
$snap.Url        # https://github.com/FirebirdSQL/snapshots/releases/download/...
$snap.Sha256     # 6741e2d89aadc6acce...

# Example: Get the Firebird 6 development build for arm64
Find-FirebirdSnapshotRelease -Branch 'master' -RuntimeIdentifier 'linux-arm64'

Utility commands

Get-FirebirdVersion

Parse a Firebird version string into a structured object.

Get-FirebirdVersion [-VersionString] <string> [<CommonParameters>]

Parses version strings produced by Firebird tools (gstat -z, isql -z, etc.) into a structured object with platform, version, build number, server name, and snapshot flag. Accepts pipeline input.

The IsSnapshot property is $true for snapshot/test builds (version strings using the -T prefix, e.g. WI-T6.0.0.1887), and $false for official releases (using the -V prefix).

# Example: Parse a version string from gstat output
$v = Get-FirebirdVersion 'LI-V5.0.3.1683 Firebird 5.0'
$v.Platform    # Linux
$v.Version     # 5.0.3 (as [semver])
$v.Build       # 1683
$v.ServerName  # Firebird 5.0
$v.IsSnapshot  # False

# Example: Parse a Firebird 6 snapshot version string
$v = Get-FirebirdVersion 'WI-T6.0.0.1887 Firebird 6.0 2e18929'
$v.Platform    # Windows
$v.Version     # 6.0.0
$v.IsSnapshot  # True

# Example: Parse a Windows version string via pipeline
'WI-V4.0.5.3140 Firebird 4.0' | Get-FirebirdVersion

# Example: Parse just a version prefix (no server name)
Get-FirebirdVersion 'LI-V3.0.12.33787'

Development notes

• Keep one function per file, unless the functions are closely related.
• Include verbose messages that may help with future debugging.
  • Just the minimum necessary for a useful debugging analysis.
  • Always use the Write-VerboseMark function to produce verbose messages. This adds a quick link to the source of the message.
• Ensure all conditional and loop statements include a Write-VerboseMark call to output appropriate messages for debugging.
  • This ensures better traceability of conditional logic during execution.
  • Skip this rule for guard statements (if statements that ONLY throw an exception for a given condition)

Testing

Run the included Pester (v5+) tests:

# Run all tests
Invoke-Pester

# Run only fast unit tests (no network or Firebird downloads)
Invoke-Pester -Tag 'Unit'

# Run only integration tests (requires network access)
Invoke-Pester -Tag 'Integration'

Contributing

Contributions, issues, and feature requests are welcome! Please open an issue or submit a pull request.

---

Appendix — Platform and Version Support Matrix

The table below shows which combinations of Firebird version and operating system are tested in CI and supported by this module.

Firebird version	ubuntu-22.04 (linux-x64)	ubuntu-24.04-arm (linux-arm64)	windows-2022 (win-x64)	windows-11-arm (win-arm64)
3.x (e.g. 3.0.13)	✅	❌ ¹	✅	❌ ²
4.x (e.g. 4.0.6)	✅	❌ ¹	✅	❌ ²
5.x (e.g. 5.0.3)	✅	✅	✅	❌ ²
master (FB 6.x snapshot)	✅	✅	✅	✅

Legend: ✅ tested and supported  ·  ❌ not supported (see notes below)

Notes

¹ Firebird 3 and 4 on Ubuntu 24.04 (arm64) Firebird 3.x and 4.x binaries link against the legacy ncurses 5 ABI (libncurses.so.5, libtinfo.so.5). Ubuntu 24.04 removed the libncurses5 and libtinfo5 packages from its repos. Because those libraries cannot be obtained at install time, FB3 and FB4 cannot run on ubuntu-24.04-arm (and more generally on any Ubuntu 24.04 host). Firebird 5 and later link against ncurses 6, which is pre-installed on all supported distros.

² Firebird 3, 4, and 5 on Windows ARM64 The official Firebird project does not publish Windows ARM64 (win-arm64) binaries for any release prior to Firebird 6. Native ARM64 Windows support is only available through the master development snapshot (Firebird 6.x). Earlier versions would need to run under x64 emulation, which is not tested or supported by this module.

Additional implementation notes

• Firebird 3 and 4 linux-arm64 archive layout. The arm64 tar archives for FB3 and FB4 place binaries directly inside the top-level firebird/ directory (flat layout). FB5+ arm64 archives and all x64 archives use a nested buildroot.tar.gz that must be extracted separately. New-FirebirdEnvironment handles this automatically.

• Cross-version database conversion (Convert-FirebirdDatabase). The module uses Firebird 3 as the oldest source in cross-version tests. On platforms where FB3 is unsupported (ubuntu-24.04-arm, windows-11-arm), the CrossVersion test suite is skipped.