English v2

English | Japanese

fbconverter v2.0.0 English guide

fbconverter is a Windows tool that reads the schema and data from a Firebird database and creates a new database for another Firebird version. See the Japanese v2.0.0 guide for the Japanese edition.

Download and supported Firebird versions

Download the WIN32 or WIN64 ZIP from GitHub Releases and extract the entire archive. To use the GUI, run fbconverter.exe.

Package	Included Firebird Embedded destinations
WIN32	1.5, 2.0, 2.1, 2.5, 3.0, 4.0, 5.0
WIN64	2.1, 2.5, 3.0, 4.0, 5.0

You can select Firebird server versions 1.0, 1.5, 2.0, 2.1, 2.5, 3.0, 4.0, or 5.0 as the source. Firebird 1.0 was tested with 1.0.3. The WIN64 package uses the bundled Firebird 2.5.4 x64 client to connect to 1.0, 1.5, and 2.0 servers. Select the version of the source server when configuring the migration. The CLI and MCP tool create local Embedded databases.

For 3.0 → 4.0 and 5.0, and for 4.0 → 5.0, the tests compared column definitions and values, including BOOLEAN, INT128, 38-digit NUMERIC and DECIMAL, DECFLOAT, and time zone types. Test results

Migrate from the CLI

This PowerShell example migrates a Shift_JIS database on a Firebird 2.5 server to a UTF-8 database using Firebird 5.0 Embedded.

.\fbconverter.exe --convert --source 'C:\data\source.fdb' --destination 'C:\data\migrated.fdb' `
  --source-version 2.5 --destination-version 5.0 --source-host localhost `
  --source-charset SJIS_0208 --destination-charset UTF8 | Out-Host
$LASTEXITCODE

Set --source to the path as seen by the source Firebird server and --destination to the path of the new local file. The default connection is localhost:3050. Use --source-port to set the port and --source-user to set the username. For a direct local connection, use --source-local in place of a hostname. Set the FBCONVERTER_SOURCE_PASSWORD environment variable when a password is needed.

Exit code	Meaning
0	Migration succeeded
1	Migration failed
2	Invalid arguments or destination file already exists

An existing destination file is preserved. The Logs: line shows the log directory. Use --work-dir to set the parent of the working directory or --single-thread to run with one thread. For the complete list of arguments, run .\fbconverter.exe --help | Out-Host.

Use an MCP client

The bundled fbconverter_mcp.py is a local stdio MCP server that runs the fbconverter.exe in the same directory. It requires Python 3.11 or later and uv. On first launch, uv downloads the dependencies.

For clients that use the mcpServers configuration format, replace the path below with the actual path to the extracted script.

{
  "mcpServers": {
    "fbconverter": {
      "command": "uv",
      "args": ["run", "--script", "C:/tools/fbconverter/fbconverter_mcp.py"]
    }
  }
}

Example arguments for convert_database.

{
  "source": "C:/data/source.fdb",
  "destination": "C:/data/migrated.fdb",
  "source_version": "2.5",
  "destination_version": "5.0",
  "source_host": "localhost",
  "source_charset": "SJIS_0208",
  "destination_charset": "UTF8"
}

The tool returns the destination path, CLI exit code, log directory, standard output, and standard error. If the destination already exists, it returns a tool error with exit code 2 and preserves the file. Set FBCONVERTER_SOURCE_PASSWORD in the MCP server's environment when a password is needed. Use FBCONVERTER_EXE in the same environment to select another executable.

Firebird 2.1.7 EUC fix

The original Firebird 2.1 fbintl.dll can underestimate the output buffer size when converting EUCJ_0208 to Unicode. This can cause error -924 on connection or -802 when creating a column that uses EUC. Firebird 2.1.7, the final release in the 2.1 series, shipped without the CORE-2095 fix. CORE-2095 patch

Both v2.0.0 packages include a backported Embedded/2.1/intl/fbintl.dll. Selecting Firebird 2.1 Embedded as the destination uses this DLL. When connecting to a Firebird 2.1 source database using EUC, the source server's fbintl.dll also needs the fix. The backport source and build instructions are in Sources/source-2.0.0.tar.gz inside each ZIP.