just-cdb 0.2.0

High-performance CDB reader for SOFiSTiK® databases with SQL query interface

A high-performance, completely self-contained CDB reader for SOFiSTiK® databases with a built-in SQL query engine.

Features

An elegant, modern CDB reader designed to make extracting structural engineering data simple, robust, and fast:

• Lightweight & Self-Contained: Completely free of commercial dependencies. Read and parse CDB files anywhere without heavy background installations or dynamic linking issues.
• Run Anywhere (Windows, macOS, Linux): Built with native cross-platform capability from day one. Run analyses, automate reporting, or inspect files seamlessly on your Macbook, a Linux cloud server, or standard Windows PCs.
• Instant SQL Queries: Forget writing complex binary parsing logic. This tool automatically mounts structural CDB data into an easy-to-query format, letting you use standard SQL filters, joins, and aggregations (e.g., extracting specific node coordinates or material properties).
• Instant Loading & Memory Efficient: Employs ultra-fast virtual memory mapping and lazy loading. Even multi-gigabyte files open instantly because it only decodes the specific categories your code or query asks for.
• Simple Command-Line & Python APIs: Comes with a user-friendly command-line interface (CLI) to quickly inspect file info, list categories, or export data to Markdown and JSON, alongside a clean Python API for your custom workflows.

Installation

We recommend using uv for Python package management.

If you want to use the just-cdb CLI globally on your system:

uv tool install just-cdb

Install it directly into your Python project:

uv add just-cdb

// or via pip
pip install just-cdb

You can run the CLI instantly without installing it:

uvx just-cdb

CLI Usage

After installation, the command line interface just-cdb is instantly available.

1. Show Metadata

Get key details about any CDB database file:

just-cdb info path/to/database.cdb

Output:

CDB File Information:
- Source             : path/to/database.cdb
- File Size          : 5_684_212 bytes
- CDBase Version     : v12.7.0.32
- Flags              : 0x00000001
- Records            : 1_420 / 2_500 (used / max)
- Total Pages (Keys) : 14
- Chain Head Block   : 142
- Page Dir Start     : 16
- Next Free Record   : 43

You can also run with the --verbose / -v flag to get a detailed, perfectly aligned breakdown of KWH categories present in the file:

just-cdb info path/to/database.cdb -v

Output:

... (CDB File Information) ...

Content Summary:
- Total Keys (KWH/KWL Pairs) : 14
- Unique Categories (KWH)    : 3

Categories present in this file:
- KWH    0 :      1 key
- KWH   20 :      5 keys
- KWH  100 :      8 keys

2. List All Keys

List all primary category key pairs (KWH / KWL) inside the database directory:

just-cdb keys path/to/database.cdb

3. Extract Raw Records

Retrieve binary payloads for any specific Key Word High (KWH) and Key Word Low (KWL) pair:

just-cdb records path/to/database.cdb 20 0

Output:

Found 1_005 records for Key pair (20, 0)
Record #0 (12_345 bytes): payload=0x68656c6c6f20776f726c6421

You can also use the --raw flag to write the raw binary payloads of all matching records directly to stdout (e.g., to pipe them to another command or save directly to a file):

just-cdb records path/to/database.cdb 20 0 --raw > category_20.bin

4. Query with SQL

Query your CDB structures using robust SQL with custom formats (json, ndjson, markdown, ascii):

just-cdb query path/to/database.cdb "SELECT * FROM node WHERE id > 10" --format markdown

Output:

| id | type | x     | y     |
|----|------|-------|-------|
| 11 | 1    | 12.34 | 56.78 |
| 12 | 2    | 90.12 | 34.56 |

---

Python API Usage

Use just-cdb programmatically inside your Python apps:

from just_cdb import CDBFile, OutputFormat

# Open the CDB file (runs in lazy-loading mode by default)
with CDBFile("path/to/database.cdb") as cdb:
    # 1. Fetch metadata
    header = cdb.get_header()
    print(f"Total pages: {header.total_pages}")

    # 2. Get list of all key pairs (kwh, kwl)
    all_keys = cdb.keys()
    print(f"Available keys: {all_keys}")

    # 3. Retrieve raw record bytes
    records = cdb.get_records(kwh=20, kwl=0)
    for rec in records:
        print(f"Size: {rec.size} bytes, payload: {rec.payload}")

    # 4. Query with SQL (loads referenced tables on demand!)
    rows = cdb.query("SELECT * FROM node WHERE id > 10 LIMIT 3")
    for row in rows:
        print(row)  # Raw dictionary format

    # 5. Format and stream queries directly to standard output or a file
    cdb.query_formatted("SELECT * FROM node", format=OutputFormat.Markdown)

Trademark Disclaimer

SOFiSTiK® is a registered trademark of SOFiSTiK AG. This project is entirely independent and is not affiliated with, sponsored, or endorsed by SOFiSTiK AG.