# uranio

> Uranio is a type-safe ODM for MongoDB

Latest version **1.4.2** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install uranio
pnpm add uranio
yarn add uranio
bun add uranio
```

Provides the command `uranio`.

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.4.2 |
| Published | 2026-09-24 |
| First published | 2019-04-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 570.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | x71c9 |
| Maintainers | nbl7, x71c9 |

## Links

- npm: https://www.npmjs.com/package/uranio
- Repository: https://github.com/x71c9/uranio
- Homepage: https://github.com/x71c9/uranio#readme
- Issues: https://github.com/x71c9/uranio/issues
- npm.io page: https://npm.io/package/uranio

## Dependencies (7)

- [i0n](https://npm.io/package/i0n.md) ^0.9.0
- [r4y](https://npm.io/package/r4y.md) ^0.9.0
- [w3i](https://npm.io/package/w3i.md) ^0.3.2
- [yaml](https://npm.io/package/yaml.md) ^2.8.2
- [pkg-dir](https://npm.io/package/pkg-dir.md) ^8.0.0
- [inquirer](https://npm.io/package/inquirer.md) ^13.3.0
- [plutonio](https://npm.io/package/plutonio.md) ^0.7.7

## Recent versions

- 1.4.2 (latest) — 2026-09-24
- 1.4.1 — 2026-04-10
- 1.4.0 — 2026-04-10
- 1.3.0 — 2026-03-22
- 1.2.0 — 2026-03-09
- 1.1.9 — 2026-03-09
- 1.1.8 — 2026-02-28
- 1.1.7 — 2026-02-28
- 1.1.6 — 2026-02-25
- 1.1.5 — 2026-02-24
- 1.1.4 — 2026-02-24
- 1.1.3 — 2026-02-24
- 1.1.2 — 2026-02-23
- 1.1.1 — 2026-02-23
- 1.1.0 — 2026-02-23
- … 124 more at https://npm.io/package/uranio/versions

## README

# Uranio

![uranio logo](./img/uranio_logo_1440x220.png)

Uranio is the lightest Typescript Object Document Mapper (ODM) for MongoDB,
and Object Relational Mapping (ORM) for MySQL and PostgreSQL.\
It creates a client for querying collections/tables in a database by just parsing
the types in a repository.

It is the simplest and fastest way to query a database without the need to build
a Data Access Layer (DAL) from the defined types.

## Install

Uranio uses peer dependencies for database SDKs, so you only install what you need:

### For MongoDB users:
```bash
npm install uranio mongodb
```

### For MySQL users:
```bash
npm install uranio mysql2
```

### For PostgreSQL users:
```bash
npm install uranio pg
npm install --save-dev @types/pg
```

## How it works

Run:
```bash
uranio generate -d mongodb
// or
uranio generate -d mysql
// or
uranio generate -d postgresql
```

The above command search for all interfaces in your repository that extends
the `uranio.atom` interface.\
For each of these interfaces it creates a method to query a collection with a
name of the interface.

For example if in your code you have:

```typescript
import uranio from 'uranio';

interface Product extends uranio.atom {
  title: string;
  description: string;
  price: number;
}
```

then Uranio generates a method for querying a collection named `products`:

```typescript
import uranio from 'uranio';

const uri = process.env.MONGO_DATABASE_URI || '';
const dbName = process.env.MONGO_DATABASE_NAME || '';

const urn = uranio.MongoDBClient({uri, dbName});

// Get all products
const products = await urn.products.getAtoms({});

// Create a product
await urn.products.putAtom({
  title: 'Uranio mug',
  description: 'A radioactive mug for your coding breakfast',
  price: 4.99
});
```

### Primary index `_id` for MongoDB

When extending an interface with `uranio.atom` (MongoDB) this add a primary
index attribute `_id` to the interface, so there is no need to add it manually.

```typescript
import uranio from 'uranio';

interface Product extends uranio.atom {
  title: string;
  description: string;
  price: number;
}
// It resolves in:
// {
//  _id: string;
//  title: string;
//  description: string;
//  price: number;
// }
```

## Configuration

### MySQL Client Options

When creating a MySQL client, you can configure additional options:

```typescript
import uranio from 'uranio';

const uri = process.env.MYSQL_DATABASE_URI || '';

// Default: UTC timezone, no connection pool
const urn = uranio.MySQLClient({ uri });

// With connection pool
const urn = uranio.MySQLClient({
  uri,
  usePool: true
});

// Custom timezone (default is UTC '+00:00')
const urn = uranio.MySQLClient({
  uri,
  usePool: true,
  timezone: '+04:00'  // Dubai timezone (GST)
});

// Use local server timezone
const urn = uranio.MySQLClient({
  uri,
  timezone: 'local'
});
```

**Timezone Parameter:**
- **Default**: `'+00:00'` (UTC) - All dates are stored in UTC
- **Custom**: Any valid timezone offset like `'+04:00'` (Dubai), `'+09:00'` (Tokyo)
- **Local**: `'local'` - Uses the database server's timezone

The timezone setting affects how JavaScript `Date` objects are converted when storing to and retrieving from the database. Using UTC (default) is recommended for consistency across different timezones.

### PostgreSQL Client Options

When creating a PostgreSQL client, you can configure additional options:

```typescript
import uranio from 'uranio';

const uri = process.env.POSTGRESQL_DATABASE_URI || '';

// Default: no connection pool
const urn = uranio.PostgreSQLClient({ uri });

// With connection pool (recommended for production)
const urn = uranio.PostgreSQLClient({
  uri,
  usePool: true
});
```

**Connection Pool:**
- Connection pooling is recommended for production environments to manage database connections efficiently
- PostgreSQL handles timezones natively, so no timezone configuration is needed

## Troubleshooting

### Missing Database SDK Error

If you get an error like:
```
Error: Cannot find module 'mongodb'
Error: Cannot find module 'mysql2'
Error: Cannot find module 'pg'
```

This means you haven't installed the required database SDK. Install the SDK for your chosen database:

```bash
# For MongoDB
npm install mongodb

# For MySQL
npm install mysql2

# For PostgreSQL
npm install pg
npm install --save-dev @types/pg
```

### Peer Dependency Warnings

When installing Uranio, npm may show peer dependency warnings. These are expected since Uranio supports multiple databases. You only need to install the SDK for the database you're actually using.

### Credits

Logo credits [https://www.jacopotripodi.com/](https://www.jacopotripodi.com/)

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