Skip to main content
Version: 🚧 Canary

💾 Database Drivers

Database drivers provide a consistent interface for data persistence in NodeBlocks applications. They abstract the database connection and operations, allowing you to use different databases without changing your business logic.

🎯 Overview​

Database drivers in NodeBlocks are factory functions that create configured database instances. They provide:

  • Consistent interface across different database types
  • Simple configuration with connection strings and database names
  • Flexible implementation for custom database adapters

📋 Available Database Drivers​

MongoDB Driver​

The MongoDB driver creates a configured MongoDB database instance for use with NodeBlocks services.

getMongoClient​

Creates MongoDB database client with specified connection URL and database name.

Parameters:

  • url: string - MongoDB connection string (e.g., mongodb://localhost:27017)
  • dbName: string - Database name to connect to within the MongoDB instance

Returns: Db - MongoDB database instance for performing database operations

Usage:

import { getMongoClient } from '@nodeblocks/backend-sdk/drivers';

const db = getMongoClient('mongodb://localhost:27017', 'myapp');

// Access collections
const usersCollection = db.collection('users');
const postsCollection = db.collection('posts');

Example with Environment Variables:

import { getMongoClient } from '@nodeblocks/backend-sdk/drivers';

const db = getMongoClient(
  process.env.MONGODB_URL || 'mongodb://localhost:27017',
  process.env.DB_NAME || 'myapp'
);

// Use with services
const userService = services.userService({
  users: db.collection('users'),
  identity: db.collection('identity')
});

Example with MongoDB Atlas:

import { getMongoClient } from '@nodeblocks/backend-sdk/drivers';

const db = getMongoClient(
  'mongodb+srv://username:password@cluster.mongodb.net/myapp',
  'myapp'
);

withMongo​

Curried utility for creating authenticated MongoDB connections with automatic collection access.

Purpose: Provides a flexible, composable way to connect to MongoDB with authentication, supporting partial application for reusable connection factories.

Parameters:

  • dbUrl: string - MongoDB connection URL
  • dbName: string - Database name to connect to
  • dbUser: string - Username for authentication
  • dbPassword: string - Password for authentication
  • collectionName: string - Collection name to access

Returns: Promise<{ [collectionName]: Collection }> - Object containing the requested collection

Usage Examples:

import { withMongo } from '@nodeblocks/backend-sdk/drivers';

// Full application - get users collection
const users = await withMongo(
  'mongodb://localhost:27017',
  'myapp',
  'admin',
  'password',
  'users'
);
// Returns: { users: Collection }

// Curried usage - create reusable connection factory
const connectToMyApp = withMongo('mongodb://localhost:27017', 'myapp');
const users = await connectToMyApp('admin', 'password', 'users');
const orders = await connectToMyApp('admin', 'password', 'orders');

// Factory with authentication
const connectWithAuth = withMongo('mongodb://localhost:27017', 'myapp', 'admin', 'password');
const posts = await connectWithAuth('posts');
const comments = await connectWithAuth('comments');

// Fully curried for maximum flexibility
const postsCollection = await withMongo('mongodb://localhost:27017')('myapp')('admin')('password')('posts');

Integration with Services:

import { services } from '@nodeblocks/backend-sdk';
import { withMongo } from '@nodeblocks/backend-sdk/drivers';

// Connect and get collections
const { users } = await withMongo('mongodb://localhost:27017', 'myapp', 'admin', 'password', 'users');

// Use with service
const userService = services.userService({
  users,
  identity: (await withMongo('mongodb://localhost:27017', 'myapp', 'admin', 'password', 'identity')).identity
});

Benefits:

  • Composable: Supports partial application for reusable connection patterns
  • Type Safe: Full TypeScript support with proper typing
  • Flexible: Works with any MongoDB deployment (local, Atlas, etc.)
  • Secure: Handles authentication parameters properly
  • Convenient: Returns collections in service-ready format

🔧 Using Database Drivers​

With Services​

Pass database collections to services through the data stores parameter:

import { services } from '@nodeblocks/backend-sdk';
import { withMongo } from '@nodeblocks/backend-sdk/drivers';

const connectToDatabase = withMongo('mongodb://localhost:27017', 'dev', 'user', 'password');

express()
  .use(
    services.userService(
      {
        ...(await connectToDatabase('users')),
        ...(await connectToDatabase('identity')),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
      }
    )
  )
  .listen(8089);

🔗 Related Documentation​