Cowris WalletDB Client

Overview

@cowris/walletdb-client is a shared database access package for the Cowris Wallet Service. It provides a unified interface to interact with both the PostgreSQL source of truth and the MongoDB read replica for wallets and transaction data.

This package is intended to be used by internal Cowris services such as services-wallet, enabling them to perform secure, consistent, and high-performance reads and writes across all wallet-related operations.

Tech Stack

• PostgreSQL (Main WalletDB — Source of Truth)
• MongoDB (Read Replica — optimized for fast read access)
• Prisma (ORM for PostgreSQL)
• Mongoose (ODM for MongoDB)
• Node.js (CommonJS module format)

Features

• Connects to Cowris Wallet PostgreSQL via Prisma

• Connects to Cowris MongoDB replica using Mongoose

• Shared models for:

  • Wallets
  • Transactions
  • Funding
  • Withdrawals
  • Reversals
  • Transfers

• Singleton pattern for connection management

• Safe for use across multiple microservices

• Lazy MongoDB initialization (connectMongo())

Installation

npm install @cowris/walletdb-client

Environment Variables

Ensure the following variables are defined in your consumer service’s .env:

# PostgreSQL
WALLET_DATABASE_URL=

# MongoDB
MONGO_WALLETDB_URL=

Setup the database in microservice

Add this under scripts in package.json in the microservice

"setup-prisma:walletdb": "node node_modules/@cowris/walletdb-client/scripts/migrate.js || echo 'Migration failed. Please install the cowris walletdb client. Run `npm install @cowris/walletdb-client` to install it.'"

Usage

1. Import the package

const {
  prisma,
  connectMongo,
  WalletModel,
  TransactionModel,
  FundingModel,
  TransferModel,
  WithdrawalModel,
  ReversalModel,
} = require('@cowris/walletdb-client');

2. Initialize MongoDB connection (only once)

await connectMongo(); // Safe to call multiple times, only connects once

3. Use the Prisma client (PostgreSQL)

const wallet = await prisma.wallet.findMany({
  where: { user_id: 'user_123' },
});

4. Use the Mongoose models (MongoDB)

const mongoWallet = await WalletModel.findOne({ user_id: 'user_123' });

Available Models

| Model | Type | Description | | ------------------ | ------------ | ---------------------------------------------- | | WalletModel | Mongoose | Wallet read replica (MongoDB) | | TransactionModel | Mongoose | Transaction replica (MongoDB) | | FundingModel | Mongoose | Funding details (MongoDB) | | WithdrawalModel | Mongoose | Withdrawal details (MongoDB) | | TransferModel | Mongoose | Transfer details (MongoDB) | | ReversalModel | Mongoose | Reversal details (MongoDB) | | prisma | PrismaClient | PostgreSQL client (CRUD on Wallet/Transaction) |

Schema Locations

• PostgreSQL Schema (Prisma): ./prisma/schema.prisma
• MongoDB Models: ./mongodb/models/*.model.js

Design Consideration

This dual-database architecture allows us to:

• Perform consistent writes to PostgreSQL (the source of truth)
• Enable high-speed reads using MongoDB, reducing query latency

Data is synchronized from PostgreSQL to MongoDB via Change Data Capture (CDC) using Apache Kafka.

Publishing (Internal Only)

To publish a new version after changes:

npm version patch   # or minor / major
npm publish --access public

License

MIT License © Cowris Technologies