tessl/npm-prisma--internals

Comprehensive internal utility library for Prisma's CLI operations, schema management, generator handling, and engine interactions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Database Operations

Name: tessl/npm-prisma--internals
Author: tessl

The database operations domain provides essential database connectivity testing and management functionality across different database providers, utilizing the Prisma schema engine for reliable database interactions.

Functions

Database Connectivity

`canConnectToDatabase(connectionString, cwd?, schemaEnginePath?)`

Tests database connectivity using the provided connection string to verify that the database is accessible and properly configured.

function canConnectToDatabase(
  connectionString: string,
  cwd?: string,
  schemaEnginePath?: string
): Promise<ConnectionResult>

Parameters:

connectionString: string - Database connection string (URL format)
cwd?: string - Working directory (default: process.cwd())
schemaEnginePath?: string - Optional path to schema engine binary

Returns: Promise<ConnectionResult> - True if successful connection, error object if failed

ConnectionResult Type:

type ConnectionResult = true | { error: string; code?: string }

Example:

// Test PostgreSQL connection
const result = await canConnectToDatabase(
  'postgresql://user:password@localhost:5432/mydb'
)

if (result === true) {
  console.log('✓ Database connection successful')
} else {
  console.error('✗ Database connection failed:', result.error)
  if (result.code) {
    console.error('Error code:', result.code)
  }
}

// Test with custom working directory and engine path
const customResult = await canConnectToDatabase(
  'mysql://user:pass@localhost:3306/testdb',
  './my-project',
  '/custom/path/to/schema-engine'
)

Supported Database Providers:

PostgreSQL (postgresql://)
MySQL (mysql://)
SQLite (file:./dev.db)
SQL Server (sqlserver://)
MongoDB (mongodb://)
CockroachDB (cockroachdb://)

Database Management

`createDatabase(connectionString, cwd?, schemaEnginePath?)`

Creates a database if it doesn't already exist. This is useful for setting up new environments or ensuring database availability.

function createDatabase(
  connectionString: string,
  cwd?: string,
  schemaEnginePath?: string
): Promise<boolean>

Parameters:

connectionString: string - Database connection string
cwd?: string - Working directory (default: process.cwd())
schemaEnginePath?: string - Optional path to schema engine binary

Returns: Promise<boolean> - True if database was created, false if it already existed

Example:

// Create PostgreSQL database
const wasCreated = await createDatabase(
  'postgresql://user:password@localhost:5432/new_database'
)

if (wasCreated) {
  console.log('✓ Database created successfully')
} else {
  console.log('ℹ Database already exists')
}

// Create SQLite database
const sqliteCreated = await createDatabase('file:./new_app.db')
console.log(sqliteCreated ? 'SQLite database created' : 'SQLite database exists')

Behavior by Provider:

PostgreSQL/MySQL/SQL Server: Creates database on the server
SQLite: Creates database file if it doesn't exist
MongoDB: Creates database on first document insertion
CockroachDB: Creates database in the cluster

`dropDatabase(connectionString, cwd?, schemaEnginePath?)`

Drops/deletes a database completely. Use with extreme caution as this operation is irreversible.

function dropDatabase(
  connectionString: string,
  cwd?: string,
  schemaEnginePath?: string
): Promise<boolean>

Parameters:

connectionString: string - Database connection string
cwd?: string - Working directory (default: process.cwd())
schemaEnginePath?: string - Optional path to schema engine binary

Returns: Promise<boolean> - True if database was dropped successfully

Example:

// ⚠️ DANGEROUS: This will permanently delete the database
const confirm = await askUserConfirmation('Are you sure you want to drop the database?')

if (confirm) {
  const wasDropped = await dropDatabase(
    'postgresql://user:password@localhost:5432/old_database'
  )
  
  if (wasDropped) {
    console.log('✓ Database dropped successfully')
  } else {
    console.error('✗ Failed to drop database')
  }
}

// Drop test database safely
const testDropped = await dropDatabase('file:./test.db')
console.log(testDropped ? 'Test database cleaned up' : 'Test database not found')

Types and Interfaces

Schema Engine Types

`SchemaEngineLogLine`

Log line format from schema engine stderr output, used for debugging database operations.

interface SchemaEngineLogLine {
  timestamp: string    // ISO timestamp
  level: LogLevel     // Log level (INFO, ERROR, DEBUG, WARN)
  fields: LogFields   // Log fields including message
  target: string      // Log target module
}

LogLevel:

type LogLevel = 'INFO' | 'ERROR' | 'DEBUG' | 'WARN'

LogFields:

interface LogFields {
  message: string              // Main log message
  [key: string]: any          // Additional context fields
}

`SchemaEngineExitCode`

Exit codes returned by the schema engine for different operation results.

enum SchemaEngineExitCode {
  Success = 0,    // Normal successful exit
  Error = 1,      // Abnormal exit with error
  Panic = 101     // Panic exit (internal error)
}

Examples

Database Setup and Validation Workflow

import {
  canConnectToDatabase,
  createDatabase,
  dropDatabase
} from '@prisma/internals'

async function setupDatabaseEnvironment(connectionString: string) {
  console.log('Setting up database environment...')
  
  try {
    // 1. Test initial connectivity (might fail if database doesn't exist)
    console.log('Testing initial connectivity...')
    const initialConnection = await canConnectToDatabase(connectionString)
    
    if (initialConnection === true) {
      console.log('✓ Database already exists and is accessible')
      return true
    }
    
    // 2. If connection failed, try to create the database
    console.log('Creating database...')
    const wasCreated = await createDatabase(connectionString)
    
    if (wasCreated) {
      console.log('✓ Database created successfully')
    } else {
      console.log('ℹ Database already existed')
    }
    
    // 3. Test connectivity after creation
    console.log('Testing connectivity after creation...')
    const finalConnection = await canConnectToDatabase(connectionString)
    
    if (finalConnection === true) {
      console.log('✓ Database is ready for use')
      return true
    } else {
      throw new Error(`Database creation succeeded but connection failed: ${finalConnection.error}`)
    }
    
  } catch (error) {
    console.error('Database setup failed:', error)
    throw error
  }
}

// Usage
await setupDatabaseEnvironment('postgresql://user:pass@localhost:5432/myapp')

Multi-Environment Database Management

import {
  canConnectToDatabase,
  createDatabase,
  dropDatabase
} from '@prisma/internals'

interface DatabaseConfig {
  name: string
  url: string
  temporary?: boolean
}

async function manageMultipleDatabases(configs: DatabaseConfig[]) {
  const results = []
  
  for (const config of configs) {
    console.log(`\nProcessing ${config.name}...`)
    
    try {
      // Test connectivity
      const canConnect = await canConnectToDatabase(config.url)
      
      if (canConnect === true) {
        console.log(`✓ ${config.name}: Connected successfully`)
        results.push({ name: config.name, status: 'connected' })
      } else {
        console.log(`⚠ ${config.name}: Connection failed - ${canConnect.error}`)
        
        // Try to create if it doesn't exist
        console.log(`Creating ${config.name}...`)
        const created = await createDatabase(config.url)
        
        if (created) {
          console.log(`✓ ${config.name}: Created successfully`)
          results.push({ name: config.name, status: 'created' })
        } else {
          console.log(`ℹ ${config.name}: Already existed, but connection still fails`)
          results.push({ name: config.name, status: 'error', error: canConnect.error })
        }
      }
      
    } catch (error) {
      console.error(`✗ ${config.name}: Fatal error - ${error.message}`)
      results.push({ name: config.name, status: 'fatal', error: error.message })
    }
  }
  
  // Cleanup temporary databases
  for (const config of configs.filter(c => c.temporary)) {
    try {
      console.log(`\nCleaning up temporary database: ${config.name}`)
      await dropDatabase(config.url)
      console.log(`✓ ${config.name}: Cleaned up`)
    } catch (error) {
      console.warn(`⚠ Failed to cleanup ${config.name}: ${error.message}`)
    }
  }
  
  return results
}

// Usage with different database types
const databases: DatabaseConfig[] = [
  {
    name: 'Production PostgreSQL',
    url: 'postgresql://user:pass@prod.example.com:5432/myapp'
  },
  {
    name: 'Development MySQL',
    url: 'mysql://dev:pass@localhost:3306/myapp_dev'
  },
  {
    name: 'Test SQLite',
    url: 'file:./test.db',
    temporary: true
  },
  {
    name: 'CI PostgreSQL',
    url: 'postgresql://postgres:postgres@localhost:5432/ci_test',
    temporary: true
  }
]

const results = await manageMultipleDatabases(databases)
console.log('\nDatabase Management Summary:')
results.forEach(result => {
  console.log(`${result.name}: ${result.status}`)
})

Database Health Check Utility

import { canConnectToDatabase } from '@prisma/internals'

interface HealthCheckResult {
  database: string
  status: 'healthy' | 'unhealthy' | 'error'
  responseTime?: number
  error?: string
  timestamp: Date
}

async function performHealthCheck(
  databases: { name: string; url: string }[]
): Promise<HealthCheckResult[]> {
  console.log('Performing database health checks...')
  
  const results = await Promise.allSettled(
    databases.map(async (db) => {
      const startTime = Date.now()
      
      try {
        const canConnect = await canConnectToDatabase(db.url)
        const responseTime = Date.now() - startTime
        
        if (canConnect === true) {
          return {
            database: db.name,
            status: 'healthy' as const,
            responseTime,
            timestamp: new Date()
          }
        } else {
          return {
            database: db.name,
            status: 'unhealthy' as const,
            responseTime,
            error: canConnect.error,
            timestamp: new Date()
          }
        }
      } catch (error) {
        return {
          database: db.name,
          status: 'error' as const,
          error: error.message,
          timestamp: new Date()
        }
      }
    })
  )
  
  return results.map(result => 
    result.status === 'fulfilled' ? result.value : {
      database: 'unknown',
      status: 'error' as const,
      error: 'Promise rejected',
      timestamp: new Date()
    }
  )
}

// Usage
const healthResults = await performHealthCheck([
  { name: 'Primary DB', url: 'postgresql://user:pass@db1.example.com:5432/app' },
  { name: 'Read Replica', url: 'postgresql://user:pass@db2.example.com:5432/app' },
  { name: 'Cache DB', url: 'redis://localhost:6379' }
])

// Generate health report
console.log('\n=== Database Health Report ===')
healthResults.forEach(result => {
  const statusIcon = result.status === 'healthy' ? '✓' : 
                    result.status === 'unhealthy' ? '⚠' : '✗'
  
  console.log(`${statusIcon} ${result.database}: ${result.status.toUpperCase()}`)
  
  if (result.responseTime) {
    console.log(`  Response Time: ${result.responseTime}ms`)
  }
  
  if (result.error) {
    console.log(`  Error: ${result.error}`)
  }
  
  console.log(`  Checked: ${result.timestamp.toISOString()}`)
})

// Set exit code based on health
const hasUnhealthy = healthResults.some(r => r.status !== 'healthy')
if (hasUnhealthy) {
  process.exit(1)
}

Environment-Specific Database Operations

import {
  canConnectToDatabase,
  createDatabase,
  dropDatabase
} from '@prisma/internals'

class DatabaseManager {
  constructor(private baseUrl: string) {}
  
  private getDatabaseUrl(environment: string, suffix?: string): string {
    const dbName = suffix ? `myapp_${environment}_${suffix}` : `myapp_${environment}`
    return this.baseUrl.replace(/\/[^\/]*$/, `/${dbName}`)
  }
  
  async setupEnvironment(environment: string): Promise<void> {
    const mainDbUrl = this.getDatabaseUrl(environment)
    
    console.log(`Setting up ${environment} environment...`)
    
    // Create main database
    await this.ensureDatabase(mainDbUrl, `${environment} main database`)
    
    // Create test database for this environment
    if (environment !== 'production') {
      const testDbUrl = this.getDatabaseUrl(environment, 'test')
      await this.ensureDatabase(testDbUrl, `${environment} test database`)
    }
  }
  
  async teardownEnvironment(environment: string): Promise<void> {
    if (environment === 'production') {
      throw new Error('Cannot teardown production environment')
    }
    
    console.log(`Tearing down ${environment} environment...`)
    
    const mainDbUrl = this.getDatabaseUrl(environment)
    const testDbUrl = this.getDatabaseUrl(environment, 'test')
    
    try {
      await dropDatabase(testDbUrl)
      console.log(`✓ Dropped ${environment} test database`)
    } catch (error) {
      console.warn(`⚠ Could not drop ${environment} test database: ${error.message}`)
    }
    
    try {
      await dropDatabase(mainDbUrl)
      console.log(`✓ Dropped ${environment} main database`)
    } catch (error) {
      console.warn(`⚠ Could not drop ${environment} main database: ${error.message}`)
    }
  }
  
  private async ensureDatabase(url: string, description: string): Promise<void> {
    const canConnect = await canConnectToDatabase(url)
    
    if (canConnect === true) {
      console.log(`✓ ${description}: Already exists and accessible`)
      return
    }
    
    console.log(`Creating ${description}...`)
    const wasCreated = await createDatabase(url)
    
    if (wasCreated) {
      console.log(`✓ ${description}: Created successfully`)
    } else {
      console.log(`ℹ ${description}: Already existed`)
    }
    
    // Verify connectivity after creation
    const finalCheck = await canConnectToDatabase(url)
    if (finalCheck !== true) {
      throw new Error(`Failed to connect to ${description} after creation: ${finalCheck.error}`)
    }
  }
}

// Usage
const dbManager = new DatabaseManager('postgresql://user:pass@localhost:5432/template')

// Setup development environment
await dbManager.setupEnvironment('development')

// Setup staging environment  
await dbManager.setupEnvironment('staging')

// Cleanup old feature branch environment
await dbManager.teardownEnvironment('feature_auth_v2')

Install with Tessl CLI