rhosocial-activerecord-firebird ($\rho_{\mathbf{AR}\text{-firebird}}$)

Firebird Backend for rhosocial-activerecord

Embedded & Server Modes · BLOB & Domains · Sync & Async

Note: This is a backend implementation for rhosocial-activerecord. It cannot be used standalone.

Why This Backend?

1. Firebird-Specific Optimizations

2. True Sync-Async Parity

Same API surface for both sync and async operations:

# Sync
users = User.query().where(User.c.age >= 18).all()

# Async - just add await
users = await User.query().where(User.c.age >= 18).all()

3. Built for Production

• Connection pooling with configurable pool sizes
• Transaction support with proper isolation levels
• Error mapping from Firebird error codes to Python exceptions
• Type adapters for Firebird-specific data types

Quick Start

Installation

pip install rhosocial-activerecord-firebird

Basic Usage

from rhosocial.activerecord.model import ActiveRecord
from rhosocial.activerecord.backend.impl.firebird import FirebirdBackend
from rhosocial.activerecord.backend.impl.firebird.config import FirebirdConnectionConfig
from typing import Optional

class User(ActiveRecord):
    __table_name__ = "users"
    id: Optional[int] = None
    name: str
    email: str

# Configure
config = FirebirdConnectionConfig(
    host="localhost",
    port=3050,
    database="/var/lib/firebird/2.5/data/myapp.fdb",
    username="SYSDBA",
    password="masterkey"
)
User.configure(config, FirebirdBackend)

# Use
user = User(name="Alice", email="alice@example.com")
user.save()

# Query with parameter binding
results = User.query().where("email = ?", ("alice@example.com",)).all()

💡 AI Prompt: "How do I configure connection pooling for Firebird?"

Firebird-Specific Features

BLOB & Text Types

Native handling of Firebird BLOB subtypes:

class Document(ActiveRecord):
    __table_name__ = "documents"
    id: int
    title: str
    content: bytes  # BLOB SUB_TYPE 0
    body: str       # BLOB SUB_TYPE TEXT

Domains

Reusable column type definitions:

# DDL-level domain support
User.query().where(
    "CREATE DOMAIN EMAIL_ADDRESS AS VARCHAR(255)"
).all()

Sequences (Generators)

Firebird's generator-based sequences:

class Ticket(ActiveRecord):
    __table_name__ = "tickets"
    ticket_no: int  # NEXT VALUE FOR ticket_seq

Stored Procedures

Native PSQL procedure execution:

# Call a stored procedure
result = User.query().where(
    "SELECT * FROM get_user_stats(?)",
    (1,),
).all()

Requirements

• Python: 3.11+ (including 3.13t/3.14t free-threaded builds)
• Core: rhosocial-activerecord>=1.0.0
• Driver: firebird-driver>=2.0.0

Firebird Version Compatibility

Recommended: Firebird 3.0+ for optimal feature support.

Get Started with AI Code Agents

This project supports AI-assisted development. Clone and open in your preferred tool:

git clone https://github.com/rhosocial/python-activerecord-firebird.git
cd python-activerecord-firebird

Example AI Prompts

• "How do I configure connection pooling for Firebird?"
• "Show me how to use BLOB fields"
• "How do I create and use domains?"
• "Call a stored procedure with parameters"

For Any LLM

Feed the documentation files in docs/ to your preferred LLM for context-aware assistance.

Testing

⚠️ CRITICAL: Tests MUST run serially. Do NOT use pytest -n auto or parallel execution.

# Run all tests
PYTHONPATH=src pytest tests/

# Run specific feature tests
PYTHONPATH=src pytest tests/rhosocial/activerecord_firebird_test/feature/basic/
PYTHONPATH=src pytest tests/rhosocial/activerecord_firebird_test/feature/query/

See the Testing Documentation for details.

Documentation

• Getting Started — Installation and configuration
• Firebird Features — Firebird-specific capabilities
• Type Adapters — Data type handling
• Transaction Support — Transaction management

Comparison with Other Backends

💡 AI Prompt: "When should I choose Firebird over PostgreSQL for my project?"

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

Apache License 2.0 — Copyright © 2026 vistart