0
# @prisma/internals
1

2
The `@prisma/internals` package provides essential internal utilities and APIs for the Prisma ecosystem. This package serves as the foundational layer for Prisma CLI operations, offering comprehensive functionality for schema processing, code generation, database operations, and system integration.
3

4
## Package Information
5

6
- **Name:** `@prisma/internals`
7
- **Type:** TypeScript/JavaScript library
8
- **Language:** TypeScript
9
- **Installation:** `npm install @prisma/internals`
10

11
## Core Imports
12

13
```typescript { .api }
14
// Common CLI utilities
15
import {
16
  loadSchemaContext,
17
  getSchemaWithPath,
18
  inferDirectoryConfig,
19
  type SchemaContext,
20
  type DirectoryConfig
21
} from '@prisma/internals'
22

23
// Engine operations
24
import {
25
  formatSchema,
26
  getConfig,
27
  getDMMF,
28
  validate,
29
  lintSchema
30
} from '@prisma/internals'
31

32
// Generator system
33
import {
34
  Generator,
35
  getGenerators,
36
  type GeneratorConfig,
37
  type GeneratorOptions
38
} from '@prisma/internals'
39

40
// Database operations
41
import {
42
  canConnectToDatabase,
43
  createDatabase,
44
  dropDatabase
45
} from '@prisma/internals'
46

47
// Utilities and helpers
48
import {
49
  resolveBinary,
50
  highlightDatamodel,
51
  logger,
52
  handlePanic
53
} from '@prisma/internals'
54
```
55

56
## Basic Usage
57

58
### Loading and Processing Schema
59

60
```typescript
61
import { loadSchemaContext, getSchemaWithPath } from '@prisma/internals'
62

63
// Load schema context with all configuration
64
const context = await loadSchemaContext({
65
  cwd: process.cwd(),
66
  allowNull: false
67
})
68

69
// Get schema with specific path
70
const schemaResult = await getSchemaWithPath(
71
  './prisma/schema.prisma',
72
  undefined,
73
  { cwd: process.cwd() }
74
)
75
```
76

77
### Engine Operations
78

79
```typescript
80
import { formatSchema, getDMMF, validate } from '@prisma/internals'
81

82
// Format Prisma schema
83
const formattedSchemas = await formatSchema({
84
  schemas: schemaResult.schemas
85
})
86

87
// Generate DMMF (Data Model Meta Format)
88
const dmmf = await getDMMF({
89
  datamodel: schemaResult.schemas,
90
  previewFeatures: ['typedSql']
91
})
92

93
// Validate schema
94
validate({
95
  schemas: schemaResult.schemas,
96
  cwd: process.cwd()
97
})
98
```
99

100
### Generator Management
101

102
```typescript
103
import { getGenerators, Generator } from '@prisma/internals'
104

105
// Get all generators from schema
106
const generators = await getGenerators({
107
  schemaPath: './prisma/schema.prisma',
108
  cwd: process.cwd()
109
})
110

111
// Initialize and run generators
112
for (const generator of generators) {
113
  await generator.init()
114
  await generator.generate()
115
}
116
```
117

118
## Architecture
119

120
The `@prisma/internals` package is organized into several functional domains:
121

122
### Core Components
123

124
1. **CLI Framework** - Command-line interface utilities and argument parsing
125
2. **Schema Engine** - WASM-based schema operations (formatting, validation, DMMF generation)
126
3. **Generator System** - Code generator management and execution
127
4. **Database Interface** - Database connectivity and management operations
128
5. **Binary Resolution** - Engine binary path resolution and platform detection
129
6. **File System Layer** - Cross-platform file operations and utilities
130
7. **Error Handling** - Comprehensive error management including panic recovery
131
8. **Tracing System** - Distributed tracing and observability support
132

133
### Data Flow
134

135
```
136
CLI Commands → Schema Loading → Engine Operations → Code Generation → Database Operations
137
     ↓              ↓                ↓                    ↓                ↓
138
File System ← Error Handling ← Binary Resolution ← Tracing ← Platform Utils
139
```
140

141
## Capabilities
142

143
### CLI Utilities and Command Framework
144
Comprehensive command-line interface utilities including argument parsing, schema loading, and configuration management. [→ CLI Utilities](./cli-utilities.md)
145

146
```typescript { .api }
147
// Load schema context with full configuration
148
const context = await loadSchemaContext(options?)
149
// Parse command arguments safely  
150
const result = arg(argv, spec, stopAtPositional?, permissive?)
151
// Get directory configuration for views, SQL, and migrations
152
const dirs = inferDirectoryConfig(schemaContext?, config?, cwd?)
153
```
154

155
### Engine Commands and Schema Operations
156
Schema processing using WASM engines for formatting, validation, and DMMF generation. [→ Engine Commands](./engine-commands.md)
157

158
```typescript { .api }
159
// Format Prisma schema files
160
const formatted = await formatSchema({ schemas }, formattingOptions?)
161
// Generate Data Model Meta Format
162
const dmmf = await getDMMF(options)
163
// Validate schema without generating DMMF
164
validate(options)
165
// Extract configuration from schema
166
const config = await getConfig(options)
167
```
168

169
### Generator System and Management
170
Complete generator lifecycle management including initialization, execution, and cleanup. [→ Generators](./generators.md)
171

172
```typescript { .api }
173
// Get all generators from schema
174
const generators = await getGenerators(options)
175
// Get single generator (useful for testing)
176
const generator = await getGenerator(options)
177
// Abstract base class for generators
178
abstract class Generator {
179
  abstract init(): Promise<void>
180
  abstract generate(): Promise<void>
181
}
182
```
183

184
### Database Operations
185
Database connectivity testing and management operations across different providers. [→ Database Operations](./database-operations.md)
186

187
```typescript { .api }
188
// Test database connectivity
189
const canConnect = await canConnectToDatabase(connectionString, cwd?, enginePath?)
190
// Create database if it doesn't exist
191
const created = await createDatabase(connectionString, cwd?, enginePath?)
192
// Drop/delete database
193
const dropped = await dropDatabase(connectionString, cwd?, enginePath?)
194
```
195

196
### File System and Utility Functions
197
Cross-platform file system operations, environment handling, and general utilities. [→ Utilities](./utilities.md)
198

199
```typescript { .api }
200
// Load environment variables from files
201
const env = loadEnvFile(path)
202
// Cross-platform path utilities
203
const posixPath = pathToPosix(path)
204
// Format milliseconds to human readable
205
const formatted = formatms(ms)
206
// Safe JavaScript identifier validation
207
const isValid = isValidJsIdentifier(name)
208
```
209

210
### Binary Resolution and Platform Utilities
211
Engine binary path resolution and platform-specific operations. [→ Binary Resolution](./binary-resolution.md)
212

213
```typescript { .api }
214
// Resolve engine binary path
215
const binaryPath = await resolveBinary(name, proposedPath?)
216
// Get binary target for current platform
217
const target = getBinaryTargetForCurrentPlatform()
218
// Binary type enumeration
219
enum BinaryType { QueryEngine, SchemaEngine, ... }
220
```
221

222
### Syntax Highlighting
223
Code syntax highlighting for Prisma schemas, SQL, and TypeScript. [→ Syntax Highlighting](./syntax-highlighting.md)
224

225
```typescript { .api }
226
// Highlight Prisma datamodel syntax
227
const highlighted = highlightDatamodel(str)
228
// Highlight SQL syntax
229
const sqlHighlighted = highlightSql(str) 
230
// Highlight TypeScript/JavaScript syntax
231
const tsHighlighted = highlightTS(str)
232
```
233

234
### Tracing and Observability
235
Distributed tracing support with OpenTelemetry integration for monitoring and debugging. [→ Tracing](./tracing.md)
236

237
```typescript { .api }
238
// Tracing helper interface
239
interface TracingHelper {
240
  isEnabled(): boolean
241
  getTraceParent(context?: Context): string
242
  runInChildSpan<R>(options: ExtendedSpanOptions, callback: SpanCallback<R>): R
243
}
244
// Engine tracing types
245
type EngineSpan = { id: string, name: string, startTime: HrTime, ... }
246
```
247

248
### Error Handling and Panic Management
249
Comprehensive error handling including Rust panic recovery and error reporting. [→ Error Handling](./error-handling.md)
250

251
```typescript { .api }
252
// Custom Rust panic error class
253
class RustPanic extends Error {
254
  constructor(message: string, rustStack: string, request: any, area: ErrorArea)
255
}
256
// Type guards for error detection
257
const isRustPanic = (e: Error): e is RustPanic
258
const isWasmPanic = (error: Error): error is WasmPanic
259
// Panic reporting
260
const reportId = await sendPanic(options)
261
```
262

263
---
264

265
This package provides 173 public exports organized across 9 functional domains, serving as the foundational infrastructure for the entire Prisma ecosystem. Each domain offers specialized functionality while maintaining seamless integration with the broader Prisma toolchain.