AlphScan Aurora

TypeScript module for connecting to Aurora PostgreSQL database on AWS with automatic connection management.

Features

• Automatic Database Connection: All repository methods automatically establish database connections if not already connected
• Base58 Address Support: Full support for Alephium Base58 addresses across all repository classes
• Connection Resilience: Automatic reconnection and connection status monitoring
• TypeScript Support: Full TypeScript support with proper type definitions
• AWS Aurora Integration: Optimized for Aurora PostgreSQL with IAM authentication support

Database Connection Management

The module now includes automatic database connection handling. All repository methods will automatically establish a connection if one is not already established:

import { DatabaseConnection, defaultConfig } from 'alphscan-aurora';
import { KnownAddressRepository } from 'alphscan-aurora';

// Create database connection
const dbConnection = new DatabaseConnection(defaultConfig);

// Create repository - no need to manually connect first
const knownAddressRepo = new KnownAddressRepository(dbConnection);

// The repository will automatically connect when needed
try {
  const addresses = await knownAddressRepo.findAll();
  console.log('Found addresses:', addresses);
} catch (error) {
  console.error('Error:', error);
}

Connection Status

You can check the connection status at any time:

// Check if currently connected
const isConnected = knownAddressRepo.isConnected();

// Get detailed connection status
const status = knownAddressRepo.getConnectionStatus();
console.log('Connection status:', status);
// Output: { connected: true, host: 'your-host', port: 5432, database: 'your-db' }

Database Migrations

Database schema changes are managed through migration scripts located in the migrations/ directory. Migrations are organized chronologically with date prefixes to ensure proper execution order.

Running Migrations

# Run all migrations in order
npx ts-node migrations/run-all-migrations.ts

# Run individual migrations
npx ts-node migrations/2024-08-30-001-migrate-token-price-unique-constraint.ts
npx ts-node migrations/2024-08-30-002-add-refTokenDecimals-to-token-prices.ts
npx ts-node migrations/2024-08-30-003-create-token-price-change-table.ts
npx ts-node migrations/2024-08-30-004-rename-token-price-change-to-token-prices-change.ts

See migrations/README.md for detailed migration documentation and best practices.

Base58 Address Support

All repository classes now support Alephium Base58 addresses:

// Create a known address with Base58 address
const newAddress = await knownAddressRepo.create({
  address: '24A147AwvMrjRJMQmBk549NVAEXpAxmp3NxNyw9Br9tdV',
  label: 'My Alephium Address',
  plugin: 'my-plugin'
});

// Find by Base58 address
const found = await knownAddressRepo.findByAddress('24A147AwvMrjRJMQmBk549NVAEXpAxmp3NxNyw9Br9tdV');

Installation

npm install alphscan-aurora

Usage

import { DatabaseConnection, defaultConfig } from 'alphscan-aurora';
import { KnownAddressRepository } from 'alphscan-aurora';

// Configure database connection
const config = {
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT || '5432', 10),
  database: process.env.DB_NAME || 'test',
  user: process.env.DB_USER || 'postgres',
  password: process.env.DB_PASSWORD,
  ssl: true,
  useIAMAuth: process.env.USE_IAM_AUTH === 'true'
};

// Create connection
const dbConnection = new DatabaseConnection(config);

// Create repository
const knownAddressRepo = new KnownAddressRepository(dbConnection);

// Use repository methods - connection is automatic
const addresses = await knownAddressRepo.findAll();

Repository Classes

• KnownAddressRepository - Manage known addresses with Base58 support
• AddressRepository - Core address management
• LinkedAddressRepository - Address relationship tracking
• ANSRepository - Alephium Name Service management
• BalanceRepository - Token balance tracking
• BalanceAlphRepository - ALPH-specific balance management
• TokenPriceRepository - Token price data

Error Handling

The module provides comprehensive error handling for database connection issues:

try {
  const result = await knownAddressRepo.findByAddress('24A147AwvMrjRJMQmBk549NVAEXpAxmp3NxNyw9Br9tdV');
} catch (error) {
  if (error.message.includes('Database connection failed')) {
    console.error('Connection issue:', error.message);
  } else {
    console.error('Other error:', error.message);
  }
}

Environment Variables

DB_HOST=your-aurora-host
DB_PORT=5432
DB_NAME=your-database
DB_USER=your-username
DB_PASSWORD=your-password
USE_IAM_AUTH=true
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key