PHPackages                             patchlevel/rango - 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. patchlevel/rango

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

patchlevel/rango
================

Rango

1.0.x-dev(2mo ago)565[1 PRs](https://github.com/patchlevel/rango/pulls)1MITPHPPHP ~8.3.0 || ~8.4.0 || ~8.5.0CI passing

Since Feb 21Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/patchlevel/rango)[ Packagist](https://packagist.org/packages/patchlevel/rango)[ Docs](https://github.com/patchlevel/hydrator)[ RSS](/packages/patchlevel-rango/feed)WikiDiscussions 1.0.x Synced 1mo ago

READMEChangelog (2)Dependencies (9)Versions (4)Used By (1)

Rango
=====

[](#rango)

 [![](logo.png)](logo.png)

Rango is a high-performance PHP library that reimplements the **MongoDB PHP API** on top of **PostgreSQL** using the power of `JSONB`.

It provides a drop-in compatible API, allowing you to use familiar MongoDB-style operations while storing your data in a reliable PostgreSQL database. This is ideal for applications that want to leverage PostgreSQL's ACID compliance and ecosystem without giving up the flexible document-based development experience of MongoDB.

🚀 Why Rango?
------------

[](#-why-rango)

- **PostgreSQL Reliability**: Benefit from PostgreSQL's mature engine, backups, and ACID transactions.
- **JSONB Performance**: Rango leverages PostgreSQL's binary JSON format (`JSONB`) for efficient storage and indexing.
- **Seamless Migration**: Switch between PostgreSQL and MongoDB with minimal code changes.
- **Hybrid Power**: Mix relational and document data within the same database.

📦 Installation
--------------

[](#-installation)

```
composer require patchlevel/rango
```

🛠 How it Works
--------------

[](#-how-it-works)

Rango translates MongoDB queries into optimized PostgreSQL SQL statements.

- **Databases** are mapped to **PostgreSQL Schemas**.
- **Collections** are mapped to **PostgreSQL Tables** with a single `data` column of type `JSONB`.
- **Indexes** are created as **GIN or B-tree indexes** on the JSONB field.
- **Queries** are translated using PostgreSQL's rich set of JSONB operators (like `@>`, `?`, `->>`).

🚦 Quick Start
-------------

[](#-quick-start)

```
use Patchlevel\Rango\Client;

// Connect to PostgreSQL using a standard PDO DSN
$client = new Client('pgsql:host=localhost;port=5432;dbname=app;user=postgres;password=postgres');

// Select database and collection (auto-created on first write)
$collection = $client->selectDatabase('test')->selectCollection('users');

// Insert a document (automatically generates an _id if missing)
$collection->insertOne([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'tags' => ['php', 'postgres'],
    'metadata' => ['logins' => 0]
]);

// Find documents using MongoDB syntax
$users = $collection->find([
    'tags' => 'php',
    'metadata.logins' => ['$lt' => 10]
]);

foreach ($users as $user) {
    echo "Found: " . $user['name'] . " (" . $user['_id'] . ")\n";
}

// Atomic updates
$collection->updateOne(
    ['email' => 'john@example.com'],
    ['$inc' => ['metadata.logins' => 1]]
);
```

✨ Supported Features
--------------------

[](#-supported-features)

### CRUD Operations

[](#crud-operations)

CategorySupported Methods**Create**`insertOne`, `insertMany`**Read**`find`, `findOne`, `countDocuments`, `distinct`**Update**`updateOne`, `updateMany`, `replaceOne`, `bulkWrite`**Delete**`deleteOne`, `deleteMany`**Atomic**`findOneAndUpdate`, `findOneAndReplace`, `findOneAndDelete`### Query Operators

[](#query-operators)

CategoryOperators**Comparison**`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`**Logical**`$and`, `$or`, `$nor`, `$not`**Element**`$exists`, `$type`**Evaluation**`$regex`, `$mod`**Array**`$all`, `$size`, `$elemMatch`Projection supports dot-notation in both inclusion and exclusion (e.g. `['profile.stats.score' => 0]`).

### Aggregation Framework

[](#aggregation-framework)

FeatureDetails**Stages**`$match`, `$sort`, `$limit`, `$skip`, `$project`, `$unwind`, `$group`, `$lookup` (Join)**Accumulators**`$sum`, `$avg`, `$min`, `$max`, `$first`, `$last`### Update Operators

[](#update-operators)

CategoryOperators**Field**`$set`, `$setOnInsert`, `$inc`, `$mul`, `$unset`, `$rename`, `$min`, `$max`, `$currentDate` (incl. dot-notation)**Array**`$push` (inc. `$each`), `$pull`, `$addToSet`, `$pop`**Bitwise**`$bit` (`and`, `or`, `xor`)### Management

[](#management)

- **Index Management**: `createIndex`, `dropIndex`, `listIndexes`.
- **Schema Management**: `listDatabases`, `listCollections`, `renameCollection`, `drop`.

⚠️ Current Limitations
----------------------

[](#️-current-limitations)

While Rango covers the most common use cases, some MongoDB features are not yet implemented:

- **Geospatial queries** (`$near`, `$geoWithin`, etc.)
- **Capped collections**
- **Text search** (MongoDB-specific syntax)
- **Complex Aggregation expressions** (only basic accumulators are supported)

👩‍💻 Development
---------------

[](#‍-development)

### Prerequisites

[](#prerequisites)

- PHP 8.3+
- Docker & Docker Compose (for integration tests)

### Running Tests

[](#running-tests)

We test Rango against **both** a real MongoDB and PostgreSQL to ensure 100% compatibility.

```
docker compose up -d
vendor/bin/phpunit
```

---

Built with ❤️ by the patchlevel team.

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance87

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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 ~0 days

Total

2

Last Release

81d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/470138?v=4)[David Badura](/maintainers/DavidBadura)[@DavidBadura](https://github.com/DavidBadura)

---

Top Contributors

[![DavidBadura](https://avatars.githubusercontent.com/u/470138?v=4)](https://github.com/DavidBadura "DavidBadura (28 commits)")

---

Tags

postgresmongodb

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/patchlevel-rango/health.svg)

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

###  Alternatives

[mongodb/mongodb

MongoDB driver library

1.6k64.0M546](/packages/mongodb-mongodb)[doctrine/mongodb-odm

PHP Doctrine MongoDB Object Document Mapper (ODM) provides transparent persistence for PHP objects to MongoDB.

1.1k23.3M302](/packages/doctrine-mongodb-odm)[phpbu/phpbu

PHP Backup utility.

1.3k89.0k4](/packages/phpbu-phpbu)[scienta/doctrine-json-functions

A set of extensions to Doctrine that add support for json query functions.

58723.9M36](/packages/scienta-doctrine-json-functions)[apix/cache

A thin PSR-6 cache wrapper with a generic interface to various caching backends emphasising cache taggging and indexing to Redis, Memcached, PDO/SQL, APC and other adapters.

114542.8k6](/packages/apix-cache)[rybakit/phive-queue

$queue->push('I can be popped off after', '10 minutes');

16441.5k1](/packages/rybakit-phive-queue)

PHPackages © 2026

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