MongoDB Introduction (Experimental)

Hysteria ORM provides experimental support for MongoDB, allowing you to define collections, perform CRUD operations, and use a fluent query builder with a similar API to SQL models.

Key Features

• Decorator-based collection definition
• Type-safe queries and models
• Query builder with chaining and filtering
• Session and transaction support (with replica sets)
• Automatic mapping of id to MongoDB _id

Note: MongoDB support is experimental. Some features may be missing or unstable.

Connecting to MongoDB

import { MongoDataSource } from 'hysteria-orm';

// Create instance with configuration
const mongo = new MongoDataSource({
  url: 'mongodb://root:root@localhost:27017',
});

// Establish the connection
await mongo.connect();

If no URL is provided, the MONGO_URL environment variable is used:

// Uses MONGO_URL from environment
const mongo = new MongoDataSource();
await mongo.connect();

Configuration Options

const mongo = new MongoDataSource({
  url: 'mongodb://root:root@localhost:27017',
  logs: true,
  options: {
    // MongoDB driver options (MongoClientOptions)
    maxPoolSize: 10,
    minPoolSize: 5,
  },
});
await mongo.connect();

Secondary Connections

Use MongoDataSource.connectToSecondarySource() for additional connections:

const secondaryMongo = await MongoDataSource.connectToSecondarySource({
  url: 'mongodb://root:root@replica:27017',
});

// Use with collections
const users = await User.find({ connection: secondaryMongo });

Temporary Connections

Use MongoDataSource.useConnection() for connections that auto-close:

await MongoDataSource.useConnection(
  { url: 'mongodb://root:root@localhost:27017' },
  async (mongo) => {
    const users = await User.find();
    // Connection closes automatically
  }
);

Closing Connections

// Close the primary connection
await MongoDataSource.disconnect();

// Close a specific instance
await mongo.disconnect();

Example Usage

import { MongoDataSource } from 'hysteria-orm';
import { User } from './collections/User';

const mongo = new MongoDataSource({
  url: 'mongodb://root:root@localhost:27017',
});
await mongo.connect();

// Now collections use this connection
const users = await User.find();

---

Next: Defining Collections