# ts-firebird

> Promisify node-firebird

Latest version **1.2.0** (published 2025-10-07) · ISC license · 0 weekly downloads

## Install

```sh
npm install ts-firebird
pnpm add ts-firebird
yarn add ts-firebird
bun add ts-firebird
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2025-10-07 |
| First published | 2023-05-27 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Vladimir Lastovka |
| Maintainers | last1971 |
| Keywords | type-script, node-firebird |

## Links

- npm: https://www.npmjs.com/package/ts-firebird
- Repository: https://github.com/last1971/ts-firebird
- Homepage: https://github.com/last1971/ts-firebird#readme
- Issues: https://github.com/last1971/ts-firebird/issues
- npm.io page: https://npm.io/package/ts-firebird

## Recent versions

- 1.2.0 (latest) — 2025-10-07
- 1.1.2 — 2023-10-14
- 1.1.1 — 2023-10-14
- 1.1.0 — 2023-10-14
- 1.0.11 — 2023-10-14
- 1.0.10 — 2023-10-13
- 1.0.9 — 2023-10-13
- 1.0.8 — 2023-10-13
- 1.0.7 — 2023-10-13
- 1.0.6 — 2023-06-30
- 1.0.5 — 2023-05-31
- 1.0.4 — 2023-05-30
- 1.0.3 — 2023-05-28
- 1.0.2 — 2023-05-27
- 1.0.0 — 2023-05-27

## README

# ts-firebird

A TypeScript wrapper for [node-firebird](https://github.com/hgourvest/node-firebird) with Promise support and connection pool monitoring.

## Features

- 🔄 Promise-based API (async/await)
- 📊 Connection pool with monitoring
- 🔍 Track active transactions and connections
- 🛡️ Automatic cleanup with `rollbackAllTransactions()`
- 📝 Full TypeScript support
- ✅ Comprehensive test coverage

## Installation

```bash
npm install ts-firebird
```

## Quick Start

### Basic Usage

```typescript
import { FirebirdDatabase } from 'ts-firebird';

const db = new FirebirdDatabase();
await db.attach({
    host: 'localhost',
    port: 3050,
    database: '/path/to/database.fdb',
    user: 'SYSDBA',
    password: 'masterkey'
});

// Execute query
const result = await db.query('SELECT * FROM USERS WHERE ID = ?', [1]);

// With transaction
const tx = await db.transaction();
await tx.execute('UPDATE USERS SET NAME = ? WHERE ID = ?', ['John', 1]);
await tx.commit();

db.detach();
```

### Connection Pool

```typescript
import { FirebirdPool } from 'ts-firebird';

const pool = new FirebirdPool(5, {
    host: 'localhost',
    port: 3050,
    database: '/path/to/database.fdb',
    user: 'SYSDBA',
    password: 'masterkey'
});

// Get database from pool
const db = await pool.getDatabase();
const tx = await db.transaction();
await tx.query('SELECT * FROM USERS', []);
await tx.commit(true); // auto detach

// Get statistics
console.log('Active transactions:', pool.getActiveTransactionsCount());
console.log('Active connections:', pool.getActiveConnectionsCount());
console.log('Available connections:', pool.getAvailableConnectionsCount());
console.log('Max connections:', pool.getMaxConnections());

// Cleanup hanging transactions
await pool.rollbackAllTransactions();

pool.destroy();
```

## API Reference

### FirebirdPool

#### Constructor
```typescript
new FirebirdPool(max: number, options: Options)
```

#### Methods
- `getDatabase(): Promise<FirebirdDatabase>` - Get database connection from pool
- `getTransaction(isolation?: Isolation): Promise<FirebirdTransaction>` - Get transaction directly
- `getActiveTransactionsCount(): number` - Number of uncommitted transactions
- `getActiveConnectionsCount(): number` - Number of active connections
- `getAvailableConnectionsCount(): number` - Number of available connection slots
- `getMaxConnections(): number` - Maximum pool size
- `getActiveTransactions(): FirebirdTransaction[]` - List of active transactions
- `rollbackAllTransactions(): Promise<void>` - Rollback all hanging transactions
- `destroy(): void` - Destroy pool and close all connections

### FirebirdDatabase

#### Methods
- `attach(options: Options): Promise<FirebirdDatabase>`
- `create(options: Options): Promise<FirebirdDatabase>`
- `attachOrCreate(options: Options): Promise<FirebirdDatabase>`
- `query(query: string, params: any[], detach?: boolean): Promise<any[]>`
- `execute(query: string, params: any[], detach?: boolean): Promise<any[]>`
- `transaction(isolation?: Isolation): Promise<FirebirdTransaction>`
- `detach(): void`

### FirebirdTransaction

#### Methods
- `query(query: string, params: any[], autoCommit?: boolean): Promise<any[]>`
- `execute(query: string, params: any[], autoCommit?: boolean): Promise<any[]>`
- `commit(detach?: boolean): Promise<void>`
- `rollback(detach?: boolean): Promise<void>`
- `detach(): void`

## Monitoring Hanging Connections

One of the key features is the ability to monitor and cleanup hanging transactions:

```typescript
const pool = new FirebirdPool(5, options);

// Check for hanging transactions
setInterval(() => {
    const activeCount = pool.getActiveTransactionsCount();
    const activeConns = pool.getActiveConnectionsCount();

    if (activeCount > 0) {
        console.warn(`Warning: ${activeCount} uncommitted transactions!`);
        console.warn(`Active connections: ${activeConns}/${pool.getMaxConnections()}`);

        // Optionally rollback all
        // await pool.rollbackAllTransactions();
    }
}, 60000); // Check every minute
```

## Isolation Levels

```typescript
import {
    ISOLATION_READ_UNCOMMITTED,
    ISOLATION_READ_COMMITTED,
    ISOLATION_REPEATABLE_READ,
    ISOLATION_SERIALIZABLE
} from 'ts-firebird';

const tx = await db.transaction(ISOLATION_READ_COMMITTED);
```

## Testing

```bash
npm test
```

## License

MIT

## Credits

Built on top of [node-firebird](https://github.com/hgourvest/node-firebird)

---
_Source: https://npm.io/package/ts-firebird · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._