sqlx-firebirdsql 0.1.0

Firebird SQL driver for SQLx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

# sqlx-firebirdsql

A [Firebird](https://firebirdsql.org/) database driver for [SQLx](https://github.com/launchbadge/sqlx), the async Rust SQL toolkit.

Built on top of [firebirust](https://crates.io/crates/firebirust) (a pure-Rust Firebird client library), this crate integrates Firebird as a first-class SQLx database backend.

## Features

- Async connections via Tokio
- Connection pooling (`FirebirdPool`)
- Transactions
- Migrations (`migrate` feature)
- `Any` driver support (`any` feature)
- Type-safe query parameter binding with `?` placeholders

## Connection URL

```
firebird://user:password@host:port/path/to/database.fdb
```

The default connection parameters are:

| Parameter          | Default      |
|--------------------|--------------|
| Host               | `localhost`  |
| Port               | `3050`       |
| Username           | `SYSDBA`     |
| Password           | `masterkey`  |
| Wire crypt         | `true`       |
| Auth plugin        | `Srp256`     |

## Usage

Add the dependency to your `Cargo.toml`:

```toml
[dependencies]
sqlx-firebirdsql = "0.1"
sqlx-core = { version = "0.9.0-alpha.1", features = ["_rt-tokio"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
```

### Connecting and querying

```rust
use sqlx_core::connection::ConnectOptions;
use sqlx_core::executor::Executor;
use sqlx_core::row::Row;
use sqlx_firebirdsql::FirebirdConnectOptions;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let opts = FirebirdConnectOptions::new()
        .host("localhost")
        .port(3050)
        .username("SYSDBA")
        .password("masterkey")
        .database("/tmp/my_database.fdb");

    let mut conn = opts.connect().await?;

    conn.execute("CREATE TABLE test (id INTEGER NOT NULL, name VARCHAR(100))".into())
        .await?;

    Ok(())
}
```

### Connecting with a URL

```rust
use std::str::FromStr;
use sqlx_core::connection::ConnectOptions;
use sqlx_firebirdsql::FirebirdConnectOptions;

let opts = FirebirdConnectOptions::from_str(
    "firebird://SYSDBA:masterkey@localhost:3050//tmp/my_database.fdb"
)?;
let mut conn = opts.connect().await?;
```

## Type Mapping

### Core types

| Rust type                  | Firebird type(s)                    |
|----------------------------|-------------------------------------|
| `bool`                     | BOOLEAN                             |
| `i8`, `i16`               | SMALLINT                            |
| `i32`                      | INTEGER                             |
| `i64`                      | BIGINT                              |
| `u8`                       | SMALLINT                            |
| `u16`                      | INTEGER                             |
| `u32`                      | BIGINT                              |
| `u64`                      | BIGINT (Decode only; may overflow)  |
| `f32`                      | FLOAT                               |
| `f64`                      | DOUBLE PRECISION                    |
| `&str`, `String`           | VARCHAR, CHAR                       |
| `&[u8]`, `Vec<u8>`        | BLOB                                |

### `chrono` feature

Requires the `chrono` Cargo feature flag.

| Rust type                       | Firebird type(s) |
|---------------------------------|-------------------|
| `chrono::NaiveDate`             | DATE              |
| `chrono::NaiveTime`             | TIME              |
| `chrono::NaiveDateTime`         | TIMESTAMP         |
| `chrono::DateTime<chrono::Utc>` | TIMESTAMP         |

### `rust_decimal` feature

Requires the `rust_decimal` Cargo feature flag.

| Rust type              | Firebird type(s)          |
|------------------------|---------------------------|
| `rust_decimal::Decimal` | NUMERIC, DECIMAL, DECFLOAT |

### Nullable

`Option<T>` is supported where `T` implements `Type`. An `Option<T>` represents a potentially `NULL` value from Firebird.

## Feature Flags

| Feature         | Description                                      |
|-----------------|--------------------------------------------------|
| `any`           | Enable the SQLx `Any` database driver            |
| `json`          | Enable JSON serialization support                |
| `migrate`       | Enable database migrations                       |
| `offline`       | Enable offline query checking                    |
| `chrono`        | Enable `chrono` date/time type conversions       |
| `rust_decimal`  | Enable `rust_decimal` numeric type conversions   |

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT License ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.