tessl/npm-oracledb

A Node.js module for Oracle Database access from JavaScript and TypeScript

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Connection Management

Name: tessl/npm-oracledb
Author: tessl

Core database connectivity functionality for creating and managing Oracle Database connections.

Capabilities

Get Connection

Creates a single database connection with specified configuration.

/**
 * Creates a database connection
 * @param config - Connection configuration object
 * @returns Promise resolving to Connection instance
 */
function getConnection(config: ConnectionAttributes): Promise<Connection>;

interface ConnectionAttributes {
  user?: string;
  password?: string;
  newPassword?: string;
  accessToken?: string | AccessTokenCallback;
  connectString?: string;
  connectionClass?: string;
  privilege?: number;
  externalAuth?: boolean;
  stmtCacheSize?: number;
  edition?: string;
  events?: boolean;
  tag?: string;
  shardingKey?: (string | number | Date)[];
  superShardingKey?: (string | number | Date)[];
}

type AccessTokenCallback = (refresh: boolean, accessTokenConfig: AccessTokenConfig) => Promise<AccessToken>;

interface AccessTokenConfig {
  user: string;
  connectString: string;
}

interface AccessToken {
  token: string;
  privateKey?: string;
}

Usage Examples:

const oracledb = require('oracledb');

// Basic connection
const connection = await oracledb.getConnection({
  user: "hr",
  password: "welcome123",
  connectString: "localhost:1521/XE"
});

// Connection with connection class
const connection = await oracledb.getConnection({
  user: "hr",
  password: "welcome123", 
  connectString: "localhost:1521/XE",
  connectionClass: "POOLED"
});

// External authentication
const connection = await oracledb.getConnection({
  externalAuth: true,
  connectString: "localhost:1521/XE"
});

// Always close connections
await connection.close();

Create Pool

Creates a connection pool for scalable database access.

/**
 * Creates a connection pool
 * @param config - Pool configuration object
 * @returns Promise resolving to Pool instance
 */
function createPool(config: PoolAttributes): Promise<Pool>;

interface PoolAttributes extends ConnectionAttributes {
  poolAlias?: string;
  poolIncrement?: number;
  poolMax?: number;
  poolMaxPerShard?: number;
  poolMin?: number;
  poolPingInterval?: number;
  poolPingTimeout?: number;
  poolTimeout?: number;
  queueMax?: number;
  queueTimeout?: number;
  sessionCallback?: string | SessionCallback;
  sodaMetaDataCache?: boolean;
  enableStatistics?: boolean;
}

type SessionCallback = (connection: Connection, requestedTag: string, callbackFn: (error?: Error, connection?: Connection) => void) => void;

Usage Examples:

// Create a connection pool
const pool = await oracledb.createPool({
  user: "hr",
  password: "welcome123",
  connectString: "localhost:1521/XE",
  poolMin: 10,
  poolMax: 20,
  poolIncrement: 5,
  poolTimeout: 300
});

// Get connection from pool
const connection = await pool.getConnection();
await connection.execute('SELECT 1 FROM dual');
await connection.close(); // Returns to pool

// Close the pool
await pool.close();

Get Pool

Retrieves an existing connection pool by alias.

/**
 * Gets an existing pool by alias
 * @param alias - Pool alias (optional, defaults to 'default')
 * @returns Pool instance
 */
function getPool(alias?: string): Pool;

Usage Examples:

// Create pool with alias
await oracledb.createPool({
  user: "hr",
  password: "welcome123",
  connectString: "localhost:1521/XE",
  poolAlias: "hrpool"
});

// Get pool by alias
const pool = oracledb.getPool("hrpool");
const connection = await pool.getConnection();

Initialize Oracle Client

Initializes Oracle Client libraries for thick mode operation.

/**
 * Initializes Oracle Client libraries
 * @param options - Client initialization options
 */
function initOracleClient(options?: InitOracleClientOptions): void;

interface InitOracleClientOptions {
  libDir?: string;
  configDir?: string;
  errorUrl?: string;
  driverName?: string;
}

Usage Examples:

// Initialize Oracle Client (must be called before other operations)
oracledb.initOracleClient({
  libDir: '/usr/lib/oracle/19.3/client64/lib'
});

// Now thick mode features are available
const connection = await oracledb.getConnection(config);

Get Network Service Names

Retrieves network service names from configuration files.

/**
 * Gets network service names from tnsnames.ora
 * @returns Promise resolving to array of service names
 */
function getNetworkServiceNames(): Promise<string[]>;

Usage Examples:

// Get available network service names
const serviceNames = await oracledb.getNetworkServiceNames();
console.log('Available services:', serviceNames);

// Use a service name for connection
const connection = await oracledb.getConnection({
  user: "hr",
  password: "welcome123",
  connectString: serviceNames[0]
});

Database Startup and Shutdown

Administrative functions for starting up and shutting down Oracle Database instances.

/**
 * Starts up an Oracle Database instance
 * @param options - Startup options
 * @returns Promise that resolves when startup is complete
 */
function startup(options?: StartupOptions): Promise<void>;

/**
 * Shuts down an Oracle Database instance
 * @param mode - Shutdown mode
 * @param options - Shutdown options
 * @returns Promise that resolves when shutdown is complete
 */
function shutdown(mode?: number, options?: ShutdownOptions): Promise<void>;

interface StartupOptions {
  force?: boolean;
  restrict?: boolean;
  pfile?: string;
}

interface ShutdownOptions {
  force?: boolean;
}

// Shutdown mode constants
const SHUTDOWN_MODE_DEFAULT = 0;
const SHUTDOWN_MODE_TRANSACTIONAL = 1;
const SHUTDOWN_MODE_TRANSACTIONAL_LOCAL = 2;
const SHUTDOWN_MODE_IMMEDIATE = 3;
const SHUTDOWN_MODE_ABORT = 4;
const SHUTDOWN_MODE_FINAL = 5;

// Startup mode constants  
const STARTUP_MODE_DEFAULT = 0;
const STARTUP_MODE_FORCE = 1;
const STARTUP_MODE_RESTRICT = 2;

Usage Examples:

// Startup database (requires SYSDBA privileges)
const connection = await oracledb.getConnection({
  user: "sys",
  password: "password",
  connectString: "localhost:1521/XE",
  privilege: oracledb.SYSDBA
});

await oracledb.startup();
console.log('Database started successfully');

// Shutdown database gracefully
await oracledb.shutdown(oracledb.SHUTDOWN_MODE_IMMEDIATE);
console.log('Database shut down');

await connection.close();

Connection Class Properties

interface Connection {
  // Connection identification
  action: string;
  clientId: string;
  clientInfo: string;
  module: string;
  
  // Database information
  dbDomain: string;           // read-only
  dbName: string;             // read-only
  oracleServerVersion: number; // read-only
  oracleServerVersionString: string; // read-only
  
  // Connection state
  currentSchema: string;
  stmtCacheSize: number;
  tag: string;
  thin: boolean;              // read-only
  transactionInProgress: boolean; // read-only
  
  // Performance and monitoring
  callTimeout: number;
  maxOpenCursors: number;     // read-only
  warning: ConnectionWarning; // read-only
  
  // Operation context
  dbOp: string;
  ecid: string;
  externalName: string;
  internalName: string;
}

interface ConnectionWarning {
  message: string;
  offset: number;
}

Install with Tessl CLI