PHPackages                             rancoud/database - 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. [Testing & Quality](/categories/testing)
4. /
5. rancoud/database

ActiveLibrary[Testing & Quality](/categories/testing)

rancoud/database
================

Database package

7.0.1(2mo ago)420.9k—0%14MITPHPPHP >=8.4.0CI passing

Since Sep 3Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/rancoud/Database)[ Packagist](https://packagist.org/packages/rancoud/database)[ RSS](/packages/rancoud-database/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (30)Used By (4)

Database Package
================

[](#database-package)

[![Packagist PHP Version Support](https://camo.githubusercontent.com/7a73df6d0fcb321b7553a4c94be80c0e061c9451e5af72186e3950527ab4fd8a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f72616e636f75642f6461746162617365)](https://camo.githubusercontent.com/7a73df6d0fcb321b7553a4c94be80c0e061c9451e5af72186e3950527ab4fd8a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f72616e636f75642f6461746162617365)[![Packagist Version](https://camo.githubusercontent.com/bc01066532aa832c49c23b573fd96b18d0c62693ace4f599b5700a996b212f94/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f72616e636f75642f6461746162617365)](https://packagist.org/packages/rancoud/database)[![Packagist Downloads](https://camo.githubusercontent.com/895a5ec10e19d02b92f0702282a0eb8efcc06d1f58ffb825fc4f2386ca5ff51e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f72616e636f75642f6461746162617365)](https://packagist.org/packages/rancoud/database)[![Composer dependencies](https://camo.githubusercontent.com/aae95fbaa83bc6a3f4597f3a75da45ea46ec236fc324617f0e5a2f15e07fe750/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646570656e64656e636965732d302d627269676874677265656e)](https://github.com/rancoud/database/blob/master/composer.json)[![Test workflow](https://camo.githubusercontent.com/81f70e58ad0954e96121111dd3e7d0c21ccc1d815392863f82905ba2e7047617/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f72616e636f75642f64617461626173652f746573742e796d6c3f6272616e63683d6d6173746572)](https://github.com/rancoud/database/actions/workflows/test.yml)[![Codecov](https://camo.githubusercontent.com/5cc3220f7be2fdce4c0b5bd42871ffb67fa8cd5209d046774bdcf4f5a94799d9/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f72616e636f75642f64617461626173653f6c6f676f3d636f6465636f76)](https://codecov.io/gh/rancoud/database)

Request Database (use PDO). Supported drivers: MySQL, PostgreSQL, SQLite.

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

[](#installation)

```
composer require rancoud/database
```

How to use it?
--------------

[](#how-to-use-it)

### Connection to a database

[](#connection-to-a-database)

```
use Rancoud\Database\Configurator;
use Rancoud\Database\Database;

// Create a configurator
$params = [
    'driver'    => 'mysql',
    'host'      => 'localhost',
    'user'      => 'root',
    'password'  => '',
    'database'  => 'test_database'
];
$databaseConf = new Configurator($params);

// No singleton
$database = new Database($databaseConf);

// With named instances
$database = Database::setInstance($databaseConf, 'primary');
```

Examples
--------

[](#examples)

For example we have a table `users` with this schema:

FieldTypeOptionsidint(8)primary key, auto incrementusernamevarchar(255)rankingint(8)In the table we have these data:

idusernameranking1taylor102alison303swifts20### Select methods

[](#select-methods)

The output is always an array.

#### SelectAll

[](#selectall)

Return all rows

```
$results = $database->selectAll("SELECT * FROM users");

// Output be like
[
    ['id' => '1', 'username' => 'taylor', 'ranking' => 10],
    ['id' => '2', 'username' => 'alison', 'ranking' => 30],
    ['id' => '3', 'username' => 'swifts', 'ranking' => 20]
]
```

#### SelectRow

[](#selectrow)

Return only the first row

```
$results = $database->selectRow("SELECT * FROM users");

// Output be like
['id' => '1', 'username' => 'taylor', 'ranking' => 10]
```

#### SelectCol

[](#selectcol)

Return only the first column

```
$results = $database->selectCol("SELECT username FROM users");

// Output be like
[
    'taylor',
    'alison',
    'swifts'
]
```

#### SelectVar

[](#selectvar)

Return only the first value of first line

```
$results = $database->selectVar("SELECT username FROM users WHERE id = 3");

// Output be like
'swifts'
```

#### Select + (Read OR ReadAll)

[](#select--read-or-readall)

Having the statement and use read to get row by row or readAll for all data. Useful when you want to use a specific fetch mode.

```
$statement = $database->select("SELECT * FROM users");
$row = $database->read($statement);

// Output be like
['id' => '1', 'username' => 'taylor', 'ranking' => 10]

$statement = $database->select("SELECT * FROM users");
$rows = $database->readAll($statement);

// Output be like
[
    ['id' => '1', 'username' => 'taylor', 'ranking' => 10],
    ['id' => '2', 'username' => 'alison', 'ranking' => 30],
    ['id' => '3', 'username' => 'swifts', 'ranking' => 20]
]
```

#### Count

[](#count)

Return only the value when using `SELECT COUNT(*) FROM ...`.

```
$count = $database->count("SELECT COUNT(*) FROM users");

// Output be like
3
```

Insert
------

[](#insert)

```
// insert with parameters and get last insert id
$params = ['username' => 'adam', 'ranking' => 100];
$lastInsertId = $database->insert("INSERT INTO users (username, ranking) VALUES (:username, :ranking)", $params, true);

// Output be like
4
```

Update
------

[](#update)

```
// update with parameters and get the number of affected rows
$params = ['username' => 'adam', 'id' => 4];
$affectedRowsCount = $database->update("UPDATE users SET username = :username WHERE id = :id", $params, true);

// Output be like
1
```

Delete
------

[](#delete)

```
// delete with parameters and get the number of affected rows
$params = ['id' => 4];
$affectedRowsCount = $database->delete("DELETE FROM users WHERE id = :id", $params, true);

// Output be like
1
```

Transactions
------------

[](#transactions)

Nested transactions are supported for MySQL, PostgreSQL, SQLite.

```
$database->startTransaction();

if (isOk()) {
    $database->commitTransaction();
} else {
    $database->rollbackTransaction();
}
```

Named instances
---------------

[](#named-instances)

You have to name your instances.
Then you can get them by their name.

```
Database::setInstance($databaseConfA, 'primary');
Database::setInstance($databaseConfB, 'secondary');

/** A few moments later **/

$db = Database::getInstance('secondary');
```

Configurator
------------

[](#configurator)

### Constructor Settings

[](#constructor-settings)

Here is the description of the array passed to the construct

#### Mandatory keys

[](#mandatory-keys)

ParameterTypeDescriptiondriverstringdriver of the database, it will be check with PDO::getAvailableDrivershoststringhostname of the database (port number may be included, e.g `example.org:5342`)userstringuser used to connect to the databasepasswordstringpassword used to connect to the databasedatabasestringname of the database#### Optional keys

[](#optional-keys)

ParameterTypeDefault valueDescriptionsave\_queriesbooltrueall queries will be saved in memory with execution time and the connection timepersistent\_connectionboolfalseuse persistent connectioncharsetstringit depends on the driver (MySQL: `utf8mb4` , PostgreSQL: `UTF8`)set specific database charsetparametersarray\[\]extra parameters used by PDO on connection### Methods

[](#methods)

- createPDOConnection(): PDO
- disablePersistentConnection(): void
- disableSaveQueries(): void
- enablePersistentConnection(): void
- enableSaveQueries(): void
- getCharset(): string
- getDatabase(): string
- getDSN(): string
- getDriver(): string
- getHost(): string
- getParameters(): array
- getParametersForPDO(): array
- getPassword(): string
- getUser(): string
- hasPersistentConnection(): bool
- hasSavedQueries(): bool
- setCharset(charset: string): void
- setDatabase(database: string): void
- setDriver(driver: string): void
- setHost(host: string): void
- setParameter(key: mixed, value: mixed): void
- setParameters(parameters: array): void
- setPassword(password: string): void
- setUser(user: string): void

Database
--------

[](#database)

### Constructor

[](#constructor)

#### Mandatory

[](#mandatory)

ParameterTypeDescriptionconfiguratorConfiguratorDatabase configuration### General Commands

[](#general-commands)

- selectAll(sql: string, \[parameters: array = \[\]\]): array
- selectRow(sql: string, \[parameters: array = \[\]\]): array
- selectCol(sql: string, \[parameters: array = \[\]\]): array
- selectVar(sql: string, \[parameters: array = \[\]\]): mixed
- insert(sql: string, \[parameters: array = \[\]\], \[getLastInsertId: bool = false\]): ?int
- update(sql: string, \[parameters: array = \[\]\], \[getAffectedRowsCount: bool = false\]): ?int
- delete(sql: string, \[parameters: array = \[\]\], \[getAffectedRowsCount: bool = false\]): ?int
- count(sql: string, \[parameters: array = \[\]\]): ?int
- exec(sql: string, \[parameters: array = \[\]\]): void
- select(sql: string, \[parameters: array = \[\]\]): PDOStatement
- read(statement: PDOStatement, \[fetchType: int = PDO::FETCH\_ASSOC\]): mixed
- readAll(statement: PDOStatement, \[fetchType: int = PDO::FETCH\_ASSOC\]): array

### Transactions

[](#transactions-1)

- startTransaction(): void
- completeTransaction(): void
- commitTransaction(): void
- rollbackTransaction(): void

### Errors

[](#errors)

- hasErrors(): bool
- getErrors(): array
- getLastError(): ?array
- cleanErrors(): void

### Save Queries

[](#save-queries)

- hasSavedQueries(): bool
- enableSaveQueries(): void
- disableSaveQueries(): void
- cleanSavedQueries(): void
- getSavedQueries(): array

### Specific Commands

[](#specific-commands)

- truncateTables(...tables: string): void
- dropTables(...tables: string): void
- useSqlFile(filepath: string): void

### Low Level

[](#low-level)

- connect(): void
- disconnect(): void
- getPDO(): ?PDO

### Static Method

[](#static-method)

- setInstance(configurator: Configurator, \[name: string = primary\]\]): self
- hasInstance(\[name: string = primary\]): bool
- getInstance(\[name: string = primary\]): ?self

How to Dev
----------

[](#how-to-dev)

`docker compose build && docker compose run lib composer ci` for launching tests

###  Health Score

62

—

FairBetter than 99% of packages

Maintenance89

Actively maintained with recent releases

Popularity31

Limited adoption so far

Community18

Small or concentrated contributor base

Maturity91

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 73.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~115 days

Recently: every ~122 days

Total

28

Last Release

64d ago

Major Versions

2.0.0 → 3.0.02018-01-27

3.0.4 → 4.0.02020-06-28

4.0.1 → 5.0.02020-07-25

5.0.1 → 6.0.02020-08-03

6.1.1 → 7.0.02025-04-20

PHP version history (4 changes)1.0.0PHP >=7.1.0

3.0.0PHP >=7.2.0

4.0.0PHP >=7.4.0

7.0.0PHP >=8.4.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/829a536bd4f71cadcd0266e272ccaf413e3fc9f2937248c9a2317ef0bf2d25ee?d=identicon)[rancoud](/maintainers/rancoud)

---

Top Contributors

[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (242 commits)")[![rancoud](https://avatars.githubusercontent.com/u/1884186?v=4)](https://github.com/rancoud "rancoud (86 commits)")[![Godnite](https://avatars.githubusercontent.com/u/10619405?v=4)](https://github.com/Godnite "Godnite (3 commits)")

---

Tags

composercoveragedatabasemysqlpackagistpdophpphp7php8phpunitpostgresqlsqlsqlite

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/rancoud-database/health.svg)

```
[![Health](https://phpackages.com/badges/rancoud-database/health.svg)](https://phpackages.com/packages/rancoud-database)
```

###  Alternatives

[phpspec/prophecy

Highly opinionated mocking framework for PHP 5.3+

8.5k551.7M682](/packages/phpspec-prophecy)[brianium/paratest

Parallel testing for PHP

2.5k118.8M754](/packages/brianium-paratest)[beberlei/assert

Thin assertion library for input validation in business models.

2.4k96.9M570](/packages/beberlei-assert)[mikey179/vfsstream

Virtual file system to mock the real file system in unit tests.

1.4k108.0M2.7k](/packages/mikey179-vfsstream)[orchestra/testbench

Laravel Testing Helper for Packages Development

2.2k39.1M32.1k](/packages/orchestra-testbench)[phpspec/phpspec

Specification-oriented BDD framework for PHP 7.1+

1.9k36.7M3.1k](/packages/phpspec-phpspec)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)