0
# Adapter Configuration
1

2
Comprehensive configuration options for the SQLite adapter, enabling fine-grained control over database behavior, schema generation, and integration with Payload's features.
3

4
## Capabilities
5

6
### SQLite Adapter Factory
7

8
Creates a configured SQLite database adapter for PayloadCMS.
9

10
```typescript { .api }
11
/**
12
 * Creates a SQLite database adapter for PayloadCMS
13
 * @param args - Configuration options for the adapter
14
 * @returns DatabaseAdapterObj with SQLite-specific functionality
15
 */
16
function sqliteAdapter(args: SQLiteAdapterArgs): DatabaseAdapterObj<SQLiteAdapter>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { sqliteAdapter } from '@payloadcms/db-sqlite';
23

24
// Basic configuration
25
const adapter = sqliteAdapter({
26
  client: {
27
    url: './payload.db',
28
  },
29
});
30

31
// Advanced configuration with UUID IDs
32
const advancedAdapter = sqliteAdapter({
33
  client: {
34
    url: process.env.DATABASE_URL,
35
    authToken: process.env.DATABASE_AUTH_TOKEN, // For Turso/LibSQL
36
  },
37
  idType: 'uuid',
38
  allowIDOnCreate: true,
39
  autoIncrement: true,
40
  blocksAsJSON: true,
41
  localesSuffix: '_locale',
42
  relationshipsSuffix: '_rel',
43
  versionsSuffix: '_version',
44
});
45
```
46

47
### Database Connection Configuration
48

49
Configure the LibSQL client connection settings.
50

51
```typescript { .api }
52
interface ClientConfig {
53
  /** Database URL - file path for local SQLite, connection string for remote */
54
  url: string;
55
  /** Authentication token for remote LibSQL databases (Turso) */
56
  authToken?: string;
57
  /** Additional client configuration options */
58
  [key: string]: any;
59
}
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
// Local SQLite file
66
const localConfig = {
67
  client: {
68
    url: './data/payload.db',
69
  },
70
};
71

72
// Turso (LibSQL) remote database  
73
const tursoConfig = {
74
  client: {
75
    url: 'libsql://your-database.turso.io',
76
    authToken: process.env.TURSO_AUTH_TOKEN,
77
  },
78
};
79

80
// In-memory database (development/testing)
81
const memoryConfig = {
82
  client: {
83
    url: ':memory:',
84
  },
85
};
86
```
87

88
### ID Type Configuration
89

90
Configure how primary keys are generated and managed.
91

92
```typescript { .api }
93
/**
94
 * ID type configuration options
95
 * @typedef {'number' | 'uuid'} IDType
96
 */
97
interface IDConfiguration {
98
  /** Primary key type - 'number' for integers, 'uuid' for UUID strings */
99
  idType?: 'number' | 'uuid';
100
  /** Allow custom ID specification during document creation */
101
  allowIDOnCreate?: boolean;
102
  /** Enable AUTOINCREMENT for integer IDs to prevent reuse */
103
  autoIncrement?: boolean;
104
}
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
// Numeric IDs with auto-increment (default)
111
const numericIds = sqliteAdapter({
112
  client: { url: './payload.db' },
113
  idType: 'number',
114
  autoIncrement: true,
115
});
116

117
// UUID IDs with custom ID support
118
const uuidIds = sqliteAdapter({
119
  client: { url: './payload.db' },
120
  idType: 'uuid',
121
  allowIDOnCreate: true,
122
});
123
```
124

125
### Schema Customization
126

127
Configure schema generation and table naming conventions.
128

129
```typescript { .api }
130
interface SchemaConfiguration {
131
  /** Store blocks as JSON columns instead of normalized tables */
132
  blocksAsJSON?: boolean;
133
  /** Custom suffix for locale tables (default: '_locales') */
134
  localesSuffix?: string;
135
  /** Custom suffix for relationship tables (default: '_rels') */
136
  relationshipsSuffix?: string;
137
  /** Custom suffix for version tables (default: '_v') */
138
  versionsSuffix?: string;
139
  /** Schema name for namespaced databases */
140
  schemaName?: string;
141
  /** Output file path for generated schema code */
142
  generateSchemaOutputFile?: string;
143
}
144
```
145

146
**Usage Examples:**
147

148
```typescript
149
const customSchema = sqliteAdapter({
150
  client: { url: './payload.db' },
151
  blocksAsJSON: true, // Store complex blocks as JSON
152
  localesSuffix: '_translations',
153
  relationshipsSuffix: '_relationships',
154
  versionsSuffix: '_versions',
155
  generateSchemaOutputFile: './src/db/schema.ts',
156
});
157
```
158

159
### Transaction Configuration
160

161
Configure SQLite transaction behavior and isolation levels.
162

163
```typescript { .api }
164
interface TransactionConfiguration {
165
  /** Transaction options - false to disable, object for configuration */
166
  transactionOptions?: false | SQLiteTransactionConfig;
167
}
168

169
interface SQLiteTransactionConfig {
170
  /** Transaction mode */
171
  mode?: 'deferred' | 'immediate' | 'exclusive';
172
  /** Additional transaction options */
173
  [key: string]: any;
174
}
175
```
176

177
**Usage Examples:**
178

179
```typescript
180
// Default transactions
181
const defaultTx = sqliteAdapter({
182
  client: { url: './payload.db' },
183
  // transactionOptions not specified - uses defaults
184
});
185

186
// Disabled transactions
187
const noTx = sqliteAdapter({
188
  client: { url: './payload.db' },
189
  transactionOptions: false,
190
});
191

192
// Custom transaction mode
193
const customTx = sqliteAdapter({
194
  client: { url: './payload.db' },
195
  transactionOptions: {
196
    mode: 'immediate',
197
  },
198
});
199
```
200

201
### Schema Hooks
202

203
Transform the database schema before and after Payload's schema generation.
204

205
```typescript { .api }
206
type SQLiteSchemaHook = (args: SQLiteSchemaHookArgs) => Promise<SQLiteSchema> | SQLiteSchema;
207

208
interface SQLiteSchemaHookArgs {
209
  /** Function to extend existing table definitions */
210
  extendTable: typeof extendDrizzleTable;
211
  /** Current schema state with tables and relations */
212
  schema: SQLiteSchema;
213
}
214

215
interface SQLiteSchema {
216
  /** Database relations */
217
  relations: Record<string, GenericRelation>;
218
  /** Database tables */
219
  tables: Record<string, SQLiteTableWithColumns<any>>;
220
}
221

222
interface SchemaHookConfiguration {
223
  /** Hooks executed before Payload's schema generation */
224
  beforeSchemaInit?: SQLiteSchemaHook[];
225
  /** Hooks executed after Payload's schema generation */
226
  afterSchemaInit?: SQLiteSchemaHook[];
227
}
228
```
229

230
**Usage Examples:**
231

232
```typescript
233
const withHooks = sqliteAdapter({
234
  client: { url: './payload.db' },
235
  beforeSchemaInit: [
236
    // Add custom tables before Payload generates its schema
237
    ({ schema, extendTable }) => {
238
      return {
239
        ...schema,
240
        tables: {
241
          ...schema.tables,
242
          customTable: sqliteTable('custom', {
243
            id: integer('id').primaryKey(),
244
            data: text('data'),
245
          }),
246
        },
247
      };
248
    },
249
  ],
250
  afterSchemaInit: [
251
    // Modify Payload tables after generation
252
    ({ schema, extendTable }) => {
253
      const usersTable = schema.tables.users;
254
      if (usersTable) {
255
        // Add custom column to users table
256
        return extendTable(usersTable, {
257
          customField: text('custom_field'),
258
        });
259
      }
260
      return schema;
261
    },
262
  ],
263
});
264
```
265

266
### Development and Debugging
267

268
Configuration options for development workflows and debugging.
269

270
```typescript { .api }
271
interface DevelopmentConfiguration {
272
  /** Drizzle ORM logger for SQL query debugging */
273
  logger?: DrizzleConfig['logger'];
274
  /** Enable schema push mode for development */
275
  push?: boolean;
276
}
277
```
278

279
**Usage Examples:**
280

281
```typescript
282
// Development configuration with logging
283
const devAdapter = sqliteAdapter({
284
  client: { url: './payload.db' },
285
  logger: true, // Log all SQL queries
286
  push: true, // Enable schema push mode
287
});
288

289
// Custom logger
290
const customLogger = sqliteAdapter({
291
  client: { url: './payload.db' },
292
  logger: {
293
    logQuery: (query, params) => {
294
      console.log('SQL:', query);
295
      console.log('Params:', params);
296
    },
297
  },
298
});
299
```