0
# Prisma Adapter PlanetScale
1

2
Prisma's driver adapter for PlanetScale's serverless database driver. This adapter enables HTTP-based database communication with PlanetScale databases through Prisma ORM, providing improved connection reliability and performance for serverless and edge environments.
3

4
## Package Information
5

6
- **Package Name**: @prisma/adapter-planetscale
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @prisma/adapter-planetscale`
10

11
## Core Imports
12

13
```typescript
14
import { PrismaPlanetScale } from "@prisma/adapter-planetscale";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { PrismaPlanetScale } = require("@prisma/adapter-planetscale");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { PrismaPlanetScale } from "@prisma/adapter-planetscale";
27
import { PrismaClient } from "@prisma/client";
28

29
// Create adapter with PlanetScale configuration
30
const adapter = new PrismaPlanetScale({
31
  url: process.env.DATABASE_URL,
32
  fetch: fetch // Use built-in fetch (Node.js 18+) or provide your own
33
});
34

35
// Initialize Prisma Client with the adapter
36
const prisma = new PrismaClient({ adapter });
37

38
// Use Prisma Client as normal with full type-safety
39
const users = await prisma.user.findMany();
40
```
41

42
## Architecture
43

44
The PlanetScale adapter is built around several key components:
45

46
- **Factory Pattern**: `PrismaPlanetScale` (alias for `PrismaPlanetScaleAdapterFactory`) creates adapter instances
47
- **Adapter Implementation**: `PrismaPlanetScaleAdapter` implements Prisma's `SqlDriverAdapter` interface
48
- **Connection Management**: HTTP-based connections through PlanetScale's serverless driver
49
- **Transaction Support**: Full transaction support with mutex-based synchronization
50
- **Type Conversion**: Automatic conversion between PlanetScale and Prisma data types
51
- **Error Handling**: Comprehensive MySQL error code mapping with structured error types
52

53
## Capabilities
54

55
### Adapter Factory
56

57
Creates PlanetScale adapter instances with flexible configuration options.
58

59
```typescript { .api }
60
/**
61
 * Factory class for creating PlanetScale adapters
62
 */
63
class PrismaPlanetScale {
64
  readonly provider: "mysql";
65
  readonly adapterName: string;
66
  
67
  /**
68
   * Create adapter factory with PlanetScale configuration or client instance
69
   * @param arg - PlanetScale configuration object or existing client instance
70
   */
71
  constructor(arg: Config | Client);
72
  
73
  /**
74
   * Connect and create a new adapter instance
75
   * @returns Promise resolving to configured adapter
76
   */
77
  connect(): Promise<PrismaPlanetScaleAdapter>;
78
}
79
```
80

81
### Database Operations
82

83
Core database operation capabilities through the adapter interface.
84

85
```typescript { .api }
86
class PrismaPlanetScaleAdapter {
87
  readonly provider: "mysql";
88
  readonly adapterName: string;
89
  
90
  /**
91
   * Execute a raw SQL query and return result set
92
   * @param query - SQL query with parameters and type information
93
   * @returns Promise resolving to query results with column metadata
94
   */
95
  queryRaw(query: SqlQuery): Promise<SqlResultSet>;
96
  
97
  /**
98
   * Execute a raw SQL statement and return affected row count
99
   * @param query - SQL query with parameters and type information
100
   * @returns Promise resolving to number of affected rows
101
   */
102
  executeRaw(query: SqlQuery): Promise<number>;
103
  
104
  /**
105
   * Get connection information for the current database connection
106
   * @returns Connection metadata including schema name and capabilities
107
   */
108
  getConnectionInfo(): ConnectionInfo;
109
  
110
  /**
111
   * Start a new database transaction with optional isolation level
112
   * @param isolationLevel - Transaction isolation level (optional)
113
   * @returns Promise resolving to transaction instance
114
   */
115
  startTransaction(isolationLevel?: IsolationLevel): Promise<Transaction>;
116
  
117
  /**
118
   * Execute a SQL script (currently not implemented)
119
   * @param script - SQL script to execute
120
   * @returns Promise that throws "Not implemented yet" error
121
   */
122
  executeScript(script: string): Promise<void>;
123
  
124
  /**
125
   * Clean up adapter resources
126
   * @returns Promise resolving when cleanup is complete
127
   */
128
  dispose(): Promise<void>;
129
  
130
  /**
131
   * Access the underlying PlanetScale client instance
132
   * @returns The PlanetScale client used by this adapter
133
   */
134
  underlyingDriver(): Client;
135
}
136
```
137

138
### Transaction Management
139

140
Full transaction support with commit/rollback capabilities.
141

142
```typescript { .api }
143
interface Transaction {
144
  readonly options: TransactionOptions;
145
  
146
  /**
147
   * Execute a raw SQL query within the transaction
148
   * @param query - SQL query with parameters and type information
149
   * @returns Promise resolving to query results
150
   */
151
  queryRaw(query: SqlQuery): Promise<SqlResultSet>;
152
  
153
  /**
154
   * Execute a raw SQL statement within the transaction
155
   * @param query - SQL query with parameters and type information
156
   * @returns Promise resolving to number of affected rows
157
   */
158
  executeRaw(query: SqlQuery): Promise<number>;
159
  
160
  /**
161
   * Commit the transaction, making all changes permanent
162
   * @returns Promise resolving when commit is complete
163
   */
164
  commit(): Promise<void>;
165
  
166
  /**
167
   * Rollback the transaction, undoing all changes
168
   * @returns Promise resolving when rollback is complete
169
   */
170
  rollback(): Promise<void>;
171
}
172
```
173

174

175

176
## Types
177

178
```typescript { .api }
179
/**
180
 * SQL query structure with parameters and type information
181
 */
182
interface SqlQuery {
183
  /** SQL statement text */
184
  sql: string;
185
  /** Query parameter values */
186
  args: any[];
187
  /** Parameter type information */
188
  argTypes: ArgType[];
189
}
190

191
/**
192
 * Query result set with column metadata
193
 */
194
interface SqlResultSet {
195
  /** Column names in result order */
196
  columnNames: string[];
197
  /** Column type information */
198
  columnTypes: ColumnType[];
199
  /** Result data rows */
200
  rows: any[][];
201
  /** Last inserted ID (for INSERT operations) */
202
  lastInsertId?: string | number;
203
}
204

205
/**
206
 * Database connection information
207
 */
208
interface ConnectionInfo {
209
  /** Database schema name */
210
  schemaName?: string;
211
  /** Whether relation joins are supported */
212
  supportsRelationJoins: boolean;
213
}
214

215
/**
216
 * Transaction configuration options
217
 */
218
interface TransactionOptions {
219
  /** Whether to use phantom queries for transaction handling */
220
  usePhantomQuery: boolean;
221
}
222

223
/**
224
 * Transaction isolation levels
225
 */
226
type IsolationLevel = 
227
  | "READ UNCOMMITTED"
228
  | "READ COMMITTED" 
229
  | "REPEATABLE READ"
230
  | "SERIALIZABLE";
231

232
/**
233
 * PlanetScale column type definitions
234
 */
235
type PlanetScaleColumnType = 
236
  | "NULL" | "INT8" | "UINT8" | "INT16" | "UINT16" | "INT24" | "UINT24"
237
  | "INT32" | "UINT32" | "INT64" | "UINT64" | "FLOAT32" | "FLOAT64"
238
  | "TIMESTAMP" | "DATE" | "TIME" | "DATETIME" | "YEAR" | "DECIMAL"
239
  | "TEXT" | "BLOB" | "VARCHAR" | "VARBINARY" | "CHAR" | "BINARY"
240
  | "BIT" | "ENUM" | "SET" | "TUPLE" | "GEOMETRY" | "JSON"
241
  | "EXPRESSION" | "HEXNUM" | "HEXVAL" | "BITNUM";
242

243
/**
244
 * Deferred promise for external resolution/rejection control
245
 */
246
interface Deferred<T> {
247
  /** Resolve the deferred promise with a value */
248
  resolve(value: T | PromiseLike<T>): void;
249
  /** Reject the deferred promise with an error */
250
  reject(reason: unknown): void;
251
}
252

253
/**
254
 * Argument scalar type definitions from driver-adapter-utils
255
 */
256
type ArgScalarType = 'int' | 'bigint' | 'float' | 'double' | 'decimal' | 'boolean' | 'char' | 'text' | 'bytes' | 'json' | 'enum' | 'datetime' | 'date' | 'time';
257

258
/**
259
 * Argument type metadata from driver-adapter-utils
260
 */
261
interface ArgType {
262
  /** Scalar type classification */
263
  scalarType: ArgScalarType;
264
  /** Database-specific type identifier */
265
  dbType: string;
266
}
267

268
/**
269
 * Column type enumeration from driver-adapter-utils
270
 */
271
type ColumnType = 'int32' | 'int64' | 'float' | 'double' | 'numeric' | 'boolean' | 'char' | 'text' | 'date' | 'time' | 'datetime' | 'json' | 'enum' | 'bytes' | 'uuid' | 'xml';
272

273
/**
274
 * PlanetScale configuration object (from @planetscale/database)
275
 */
276
interface Config {
277
  /** Database connection URL */
278
  url: string;
279
  /** Custom fetch implementation (optional, defaults to global fetch) */
280
  fetch?: typeof fetch;
281
  /** Additional PlanetScale client options */
282
  [key: string]: any;
283
}
284

285
/**
286
 * PlanetScale client instance (from @planetscale/database)  
287
 */
288
interface Client {
289
  /** Client configuration */
290
  config: Config;
291
  /** Execute SQL query */
292
  execute(sql: string, args: any[], options?: any): Promise<any>;
293
  /** Get connection instance */
294
  connection(): Connection;
295
}
296

297
/**
298
 * PlanetScale connection instance (from @planetscale/database)
299
 */  
300
interface Connection {
301
  /** Execute SQL query on connection */
302
  execute(sql: string, args?: any[], options?: any): Promise<any>;
303
  /** Start transaction on connection */
304
  transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
305
}
306
307
```