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

包详细信息