PHPackages                             ndtan/dbf - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. ndtan/dbf

ActiveLibrary[Database & ORM](/categories/database)

ndtan/dbf
=========

Single-file PHP Database Framework — secure, PRO & Enterprise+ features.

v0.1.0(10mo ago)1165MITPHPPHP >=8.1CI passing

Since Aug 25Pushed 10mo agoCompare

[ Source](https://github.com/nguyenduytan/NDT-DBF)[ Packagist](https://packagist.org/packages/ndtan/dbf)[ RSS](/packages/ndtan-dbf/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

 [  ![NDT DBF logo](./assets/brand/logo.png)  ](https://ndtan.net)

**NDT DBF** — A single‑file PHP Database Framework (PRO · Enterprise+).
Secure by default, compact API, works as *one file* or via **Composer/PSR‑4**.

 [Website & Docs](https://ndtan.net) · [Download single file](https://github.com/nguyenduytan/NDT-DBF/blob/main/src/DBF.php) · [Donate](https://www.paypal.com/paypalme/copbeo)

 [![Build Status](https://github.com/nguyenduytan/NDT-DBF/actions/workflows/ci.yml/badge.svg)](https://github.com/nguyenduytan/NDT-DBF/actions) [![Total Downloads](https://camo.githubusercontent.com/41b27adffa20b2565e2e0805d5d07c9fcc8d4b568e014b80ea225b7e373b3f93/68747470733a2f2f706f7365722e707567782e6f72672f6e6474616e2f6462662f646f776e6c6f616473)](https://packagist.org/packages/ndtan/dbf) [![Latest Stable Version](https://camo.githubusercontent.com/137d6fb89e3dafaae5bdb0f31efb482f7cf3317cf23fe27e20ab6747acc67e15/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e6474616e2f6462662e7376673f6c6162656c3d737461626c65)](https://packagist.org/packages/ndtan/dbf) [![License](https://camo.githubusercontent.com/88e1dabf4d223df0950e0985948e231325fefca9fa7fe9e446cf8b1c5e9d9e47/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e)](https://packagist.org/packages/ndtan/dbf)

---

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
    - [Composer](#composer)
    - [Single file](#single-file)
- [Connection Setup](#connection-setup)
    - [URI/DSN (one line)](#uridsn-one-line)
    - [Array config](#array-config)
    - [Existing PDO](#existing-pdo)
    - [Master/Replica](#masterreplica)
- [Quick Start](#quick-start)
- [Query Builder](#query-builder)
    - [Basic select](#basic-select)
    - [Where conditions](#where-conditions)
    - [Join / Group / Having / Order / Limit](#join--group--having--order--limit)
    - [CRUD](#crud)
    - [Upsert](#upsert)
    - [Aggregates & Pluck](#aggregates--pluck)
    - [Keyset pagination](#keyset-pagination)
- [Enterprise+ Features](#enterprise-features)
    - [Transactions + Deadlock retry](#transactions--deadlock-retry)
    - [Readonly/Maintenance mode](#readonlymaintenance-mode)
    - [Soft Delete guard](#soft-delete-guard)
    - [Middleware / Policy / Metrics](#middleware--policy--metrics)
    - [Per-query timeout](#per-query-timeout)
    - [Test Mode](#test-mode)
- [Raw SQL](#raw-sql)
- [Security](#security)
- [Debugging & Logging](#debugging--logging)
- [Tests & CI](#tests--ci)
- [Contributing](#contributing)
- [License](#license)
- [Donate](#donate)

---

Features
--------

[](#features)

- ⚡️ **Lightweight & single file**: no third-party deps (PDO only)
- 🔐 **Secure by default**: prepared statements, per-driver identifier quoting, IN-list guard
- 🧱 **Query Builder**: `select / where / orWhere / whereIn / between / null / join / group / having / order / limit / offset`
- 🧾 **Full CRUD**: `insert`, `insertMany`, `insertGet` (PG/SQLite `RETURNING`)
- 🔁 **Cross-dialect Upsert**: MySQL (`ON DUP KEY`), PG/SQLite (`ON CONFLICT`), safe fallback
- 💳 **Transactions**: exponential backoff + jitter on deadlock
- 🚦 **Readonly/Maintenance mode**: block DML when system is frozen
- 🪶 **Soft Delete**: `withTrashed() / onlyTrashed() / restore() / forceDelete()`
- 🧭 **Master/Replica routing**: auto/manual read-write split
- ⏱️ **Per-query timeout** (best-effort for MySQL/PG)
- 🧩 **Middleware & Policy hooks** + **Logger** & **Metrics hook**
- 📊 **Aggregates & Sugar**: `sum()`, `avg()`, `min()`, `max()`, `pluck()`
- 🧪 **Test Mode**: build SQL **without executing** (great for unit tests/previews)
- 📚 **Keyset pagination** helper

Supports **MySQL/MariaDB**, **PostgreSQL**, **SQLite**, **SQL Server**.

---

Requirements
------------

[](#requirements)

- PHP **>= 8.1**
- Extension: **PDO** (+ respective drivers: `pdo_mysql`, `pdo_pgsql`, `pdo_sqlite`, `pdo_sqlsrv`)

---

Installation
------------

[](#installation)

### Composer

[](#composer)

```
composer require ndtan/dbf
```

```