cdb-converter

Convert Pro Cycling Manager CDB database files to and from SQLite, straight from the command line or your own code. Lightweight, isomorphic (Node.js and the browser), and zero-configuration.

The conversion is lossless: a full cdb → sqlite → cdb round-trip preserves every table, column, data type, and flag — so you can edit a save in any SQLite tool and load it back into the game. Optionally, it can reconstruct the save's relationships as real PRIMARY KEY / FOREIGN KEY constraints, turning the export into a normalized database you can explore with JOINs and ER-diagram tools.

Note

Based on agfor/pcmdbedit — many thanks to agfor for the foundational work.

Contents

• Features
• Getting started
• Command line
• Library usage
  • CDB to SQLite
  • Normalized schema
  • SQLite to CDB
  • Compression
  • Browser
• API reference
• Supported data types
• How metadata is preserved
• Compatibility
• Performance & size
• Samples

Features

• CDB ↔ SQLite — convert between the binary CDB format and standard SQLite databases.
• CLI included — convert files without writing any code; direction is auto-detected.
• Lossless round-trip — table flags, column order, and data types survive an export/reopen cycle.
• Optional relational schema — reconstruct PRIMARY KEY / FOREIGN KEY constraints for JOINs and ER diagrams, without breaking the round-trip.
• Isomorphic — runs in Node.js and in the browser via sql.js.
• Lightweight — the library's own code is ~28 kB, with only pako and sql.js as dependencies.
• TypeScript-first — native type definitions and full IDE support.
• Tree-shakeable — pure functions, no side effects, ESM + CommonJS builds.

Getting started

npm install cdb-converter

Note

Requires Node.js 22 or newer. In the browser, sql.js loads its WebAssembly runtime on demand.

The fastest way to try it is the CLI:

npx cdb-converter save.cdb

Command line

The package ships a cdb-converter command. The conversion direction is auto-detected from the input file extension.

# CDB → SQLite (default output: save.sqlite)
npx cdb-converter save.cdb
# SQLite → CDB (default output: save.cdb)
npx cdb-converter save.sqlite
# Provide an explicit output path (directories are created as needed)
npx cdb-converter save.cdb data/save.sqlite
# Reconstruct PRIMARY KEY / FOREIGN KEY constraints (CDB → SQLite only)
npx cdb-converter save.cdb save.sqlite --normalize
# Help / version
npx cdb-converter --help
npx cdb-converter --version

Input extension	Direction	Default output
.cdb	CDB → SQLite	<input>.sqlite
.sqlite / .db	SQLite → CDB	<input>.cdb

Option	Effect
-n, --normalize	(CDB → SQLite only) reconstruct PK/FK constraints from PCM naming conventions. See Normalized schema.
--index-fk	Implies --normalize; also indexes every FK column for faster JOINs (roughly doubles output size).

Library usage

CDB to SQLite

importfsfrom"node:fs";importinitSqlJsfrom"sql.js";import{cdbToSql}from"cdb-converter";constSQL=awaitinitSqlJs();// Read and convert a CDB fileconstcdbBuffer=fs.readFileSync("save.cdb");constdb=cdbToSql(cdbBuffer,SQL);// Query it like any SQLite databaseconstresult=db.exec("SELECT * FROM Teams LIMIT 5");console.log(result[0].values);// Export to a .sqlite filefs.writeFileSync("save.sqlite",db.export());

Important

You must pass the initialized sql.js module returned by initSqlJs(). This library does not initialize sql.js for you: that setup is asynchronous and environment-specific (the caller decides how the wasm file is loaded in Node.js or the browser).

Normalized schema

By default the SQLite output is a flat mirror of the CDB tables, with no relational constraints. Pass { normalize: true } to reconstruct PRIMARY KEY and FOREIGN KEY constraints from the PCM naming conventions (ID{table} identity columns and fkID{target} references), turning the export into a proper relational database — ready for JOINs, entity-relationship diagrams, and schema introspection tools.

constdb=cdbToSql(cdbBuffer,SQL,{normalize: true});// Relationships are now navigable:db.exec(` SELECT c.gene_sz_name, t.gene_sz_name FROM DYN_cyclist c JOIN DYN_team t ON c.fkIDteam = t.IDteam`);

Notes:

• Round-trip safe. Constraints are declarative metadata only; sqlToCdb ignores them, so a normalized database still converts back to a byte-identical CDB. The flag is only meaningful in the CDB → SQLite direction.
• Foreign keys are not enforced.PRAGMA foreign_keys is left OFF so orphaned references (common in real saves) never block the conversion.
• Best-effort. Columns whose relationship cannot be inferred simply get no constraint. Primary keys are downgraded to a plain index when the data is not unique.
• Foreign-key indexes are opt-in. Pass { normalize: true, indexForeignKeys: true } to also index every FK column for faster JOINs. These indexes roughly double the output size and conversion time, so normalize alone leaves them out — the schema is fully relational either way.

// Lean: constraints only (~+40% size)cdbToSql(cdbBuffer,SQL,{normalize: true});// Heavier, faster JOINs: also index FK columns (~2x size)cdbToSql(cdbBuffer,SQL,{normalize: true,indexForeignKeys: true});

SQLite to CDB

importfsfrom"node:fs";importinitSqlJsfrom"sql.js";import{sqlToCdb}from"cdb-converter";constSQL=awaitinitSqlJs();// Load a SQLite database and convert back to CDBconstsqliteBuffer=fs.readFileSync("save.sqlite");constdb=newSQL.Database(sqliteBuffer);constcdbBuffer=sqlToCdb(db);// automatically compressedfs.writeFileSync("save.cdb",Buffer.from(cdbBuffer));

Compression

The library handles CDB compression (zlib deflate) transparently, but the helpers are exposed if you need them directly:

import{compressCdb,decompressCdb}from"cdb-converter";constcompressed=compressCdb(cdbData);constdecompressed=decompressCdb(compressed);// accepts compressed or raw input

Browser

<scriptsrc="https://cdn.jsdelivr.net/npm/sql.js@1.14.1/dist/sql-wasm.js"></script><scripttype="module">import{cdbToSql}from"https://cdn.jsdelivr.net/npm/cdb-converter/+esm";constSQL=awaitinitSqlJs({locateFile: (file)=>`https://cdn.jsdelivr.net/npm/sql.js@1.14.1/dist/${file}`,});// Read a CDB from a file inputconstfile=document.getElementById("cdb-input").files[0];constcdbBuffer=awaitfile.arrayBuffer();constdb=cdbToSql(cdbBuffer,SQL);console.log(db.exec("SELECT * FROM sqlite_master WHERE type='table'"));</script>

API reference

cdbToSql(cdbBuffer, SQL, options?): Database

Convert CDB binary data into a SQLite database instance.

• cdbBuffer — ArrayBuffer | Uint8Array, raw CDB data (compressed or uncompressed).
• SQL — SqlJsStatic, the module returned by initSqlJs().
• options.normalize — boolean (default false). Reconstruct PK/FK constraints from PCM naming conventions. See Normalized schema.
• options.indexForeignKeys — boolean (default false). When normalizing, also index every FK column for faster JOINs (roughly doubles the output size).
• returns — a sql.jsDatabase with the CDB tables loaded.

sqlToCdb(db): ArrayBuffer

Convert a SQLite database back to CDB binary format (automatically compressed).

• db — a sql.jsDatabase instance.
• returns — compressed CDB binary data as an ArrayBuffer.

compressCdb(data): ArrayBuffer

Compress CDB data using zlib deflate. Accepts ArrayBuffer | Uint8Array.

decompressCdb(data): ArrayBuffer

Decompress CDB data, transparently handling both compressed and already-uncompressed input.

Lower-level building blocks (CDBReader, CDBWriter), enums (ChunkType, DataType, Magic), and all TypeScript types are also exported from the package root.

Supported data types

Every CDB data type is preserved during conversion:

Type	Description	Example
INTEGER	32-bit signed	42
FLOAT	IEEE 754 float32	3.14
STRING	UTF-8 text	"cyclist"
BOOLEAN	Bit-packed	true / false
INTEGER_BYTE	8-bit signed	-128 to 127
INTEGER_SHORT	16-bit unsigned	0 to 65535
FLOAT_LIST	Array of floats	(1.5,2.3,3.7)
INTEGER_LIST	Array of integers	(10,20,30)

How metadata is preserved

The library uses a special DB_STRUCTURE table to round-trip CDB metadata that has no native SQLite equivalent:

CREATETABLEDB_STRUCTURE (
TableName TEXT'274',
ID INTEGER,
Flags INTEGER
)

Each table's flags (their exact meaning is unknown but must be preserved) are stored in the Flags column, so they are written into the .sqlite file itself and survive an export()/reopen cycle. Column indices and data types are encoded into each column's declared type annotation. Together this makes cdb → sqlite → cdb lossless even when the SQLite database is saved to disk and reopened in a separate process.

Compatibility

The CDB parser is format-driven, not version-specific, so it is not tied to a single Pro Cycling Manager release. Lossless round-trip conversion (cdb → sqlite → cdb) is tested against the official databases of:

Version	Status
Pro Cycling Manager 2014	✅ tested
Pro Cycling Manager 2018	✅ tested
Pro Cycling Manager 2019	✅ tested
Pro Cycling Manager 2021	✅ tested
Pro Cycling Manager 2025	✅ tested

Performance & size

A full cdb → sqlite → cdb round-trip on a real ~60k-row database stays well under half a second, and the library's own code adds only ~28 kB — the SQLite WASM runtime is the real weight, and you would pay for it with any SQLite-in-JS approach.

Normalization is opt-in and costs only what you ask for (measured against the default conversion, ~60k rows):

Mode	Conversion time	Output size
Default (flat)	baseline	baseline
normalize	+~10%	+~40%
normalize + indexForeignKeys	+~40%	+~130%

See bench/README.md for the full per-fixture numbers, the bundle breakdown, and how to reproduce them (npm run bench).

Samples

Runnable examples live in the samples folder:

• Browser — convert a .cdb file to SQLite directly in the browser.
• Node.js — CDB to SQLite — convert a .cdb file into a .sqlite file.
• Node.js — SQLite to CDB — convert a .sqlite or .db file back into a .cdb file.

License

MIT — see LICENSE for details.