@aust-wide-tax/db-client v4.1.1

@aust-wide-tax/db-client

A PostgreSQL database client for microservices with automatic schema validation and type safety.

Installation

npm install @aust-wide-tax/db-client

Configuration

Set the following environment variables in your deployment environment:

AUSTWIDE_DB_HOST=your_host
AUSTWIDE_DB_PORT=5432
AUSTWIDE_DB_NAME=your_database
AUSTWIDE_DB_USER=your_user
AUSTWIDE_DB_PASSWORD=your_password
AUSTWIDE_DB_SSL=true  # Optional, for SSL connections

Usage

Basic Usage

import Database from '@aust-wide-tax/db-client';

// Create a new database instance
const db = new Database();

// Use the database
const users = await db.users.find({ role: 'admin' });

Table Operations

// Insert a record
const newUser = await db.users.insert({
  name: 'John Doe',
  email: 'john@example.com'
});

// Find records
const users = await db.users.find({ 
  email: 'john@example.com' 
});

// Update records
const updatedUsers = await db.users.update(
  { id: 1 },  // criteria
  { name: 'Jane Doe' }  // new data
);

// Delete a record
const deletedUser = await db.users.delete(1);

Connection Management

The client uses connection pooling for better performance. Here's how to properly manage connections in your microservice:

// database.ts
import Database from '@aust-wide-tax/db-client';

// Create a single instance for your service
export const db = new Database();

// userService.ts
export class UserService {
    constructor(private db: Database) {}

    async getUser(id: number) {
        return await this.db.users.find({ id });
    }
}

// index.ts (main service file)
import { db } from './database';
import { UserService } from './userService';

const userService = new UserService(db);

// Handle graceful shutdown
process.on('SIGTERM', async () => {
    console.log('Shutting down...');
    await db.shutdown();
    process.exit(0);
});

Best Practices

1. Create a Single Instance:

   // ✅ GOOD: Create one instance and reuse it
   const db = new Database();

2. Don't Shutdown After Every Operation:

   // ❌ BAD: Don't do this
   async function getUser(id: number) {
       const db = new Database();
       const user = await db.users.find({ id });
       await db.shutdown();  // Don't do this!
       return user;
   }

3. Handle Service Shutdown:

   // ✅ GOOD: Shutdown only when the service is stopping
   process.on('SIGTERM', async () => {
       await db.shutdown();
   });

Features

• Automatic schema validation
• Type safety with TypeScript
• Dynamic table access
• Connection pooling
• SQL injection protection
• Support for complex queries
• Graceful connection management

License

MIT