0
# Client Configuration
1
2
Comprehensive configuration options for creating libSQL clients with different connection types, performance settings, and deployment scenarios.
3
4
## Capabilities
5
6
### Client Creation
7
8
Creates a Client instance based on the provided configuration, automatically selecting the appropriate implementation based on URL scheme.
9
10
```typescript { .api }
11
/**
12
* Creates a Client instance based on the provided configuration
13
* @param config - Configuration object specifying connection and behavior options
14
* @returns Platform-appropriate Client implementation (HttpClient, WsClient, or Sqlite3Client)
15
*/
16
function createClient(config: Config): Client;
17
```
18
19
### Configuration Interface
20
21
Complete configuration options for client creation with support for different deployment scenarios.
22
23
```typescript { .api }
24
interface Config {
25
/** Database URL supporting multiple schemes: libsql:, http:, https:, ws:, wss:, file: */
26
url: string;
27
28
/** Authentication token for remote database access */
29
authToken?: string;
30
31
/** Encryption key for database file encryption at rest */
32
encryptionKey?: string;
33
34
/** Remote server URL for embedded replica synchronization */
35
syncUrl?: string;
36
37
/** Synchronization interval in seconds for embedded replicas */
38
syncInterval?: number;
39
40
/** Enable read-your-writes consistency for embedded replicas */
41
readYourWrites?: boolean;
42
43
/** Enable offline writes for embedded replicas */
44
offline?: boolean;
45
46
/** Enable or disable TLS for libsql: URLs (default: true) */
47
tls?: boolean;
48
49
/** Integer representation mode for JavaScript compatibility */
50
intMode?: IntMode;
51
52
/** Custom fetch function for HTTP client (overrides default) */
53
fetch?: Function;
54
55
/** Maximum concurrent requests (default: 20, set to 0 for unlimited) */
56
concurrency?: number | undefined;
57
}
58
```
59
60
### Integer Mode Configuration
61
62
Configure how SQLite integers are represented in JavaScript to handle large numbers correctly.
63
64
```typescript { .api }
65
/**
66
* Integer representation modes for JavaScript compatibility
67
* - "number": JavaScript numbers (double precision floats), throws RangeError for values > 2^53-1
68
* - "bigint": JavaScript bigints (arbitrary precision integers)
69
* - "string": String representation of integers
70
*/
71
type IntMode = "number" | "bigint" | "string";
72
```
73
74
**Usage Examples:**
75
76
```typescript
77
import { createClient } from "@libsql/client";
78
79
// Local SQLite database
80
const localClient = createClient({
81
url: "file:./database.db"
82
});
83
84
// Remote HTTP database
85
const remoteClient = createClient({
86
url: "https://your-database.turso.io",
87
authToken: process.env.TURSO_AUTH_TOKEN
88
});
89
90
// WebSocket connection
91
const wsClient = createClient({
92
url: "wss://your-database.turso.io",
93
authToken: process.env.TURSO_AUTH_TOKEN
94
});
95
96
// Embedded replica (local file that syncs with remote)
97
const replicaClient = createClient({
98
url: "file:./local-replica.db",
99
syncUrl: "libsql://your-database.turso.io",
100
authToken: process.env.TURSO_AUTH_TOKEN,
101
syncInterval: 60000, // sync every minute
102
readYourWrites: true,
103
offline: true
104
});
105
106
// With encryption
107
const encryptedClient = createClient({
108
url: "file:./encrypted.db",
109
encryptionKey: process.env.DB_ENCRYPTION_KEY
110
});
111
112
// Custom integer handling for large numbers
113
const bigintClient = createClient({
114
url: "file:./database.db",
115
intMode: "bigint" // Use bigint for all integers
116
});
117
118
// High concurrency configuration
119
const highConcurrencyClient = createClient({
120
url: "https://your-database.turso.io",
121
authToken: process.env.TURSO_AUTH_TOKEN,
122
concurrency: 100 // Allow up to 100 concurrent requests
123
});
124
125
// Custom fetch function (useful for testing or special environments)
126
const customFetchClient = createClient({
127
url: "https://your-database.turso.io",
128
authToken: process.env.TURSO_AUTH_TOKEN,
129
fetch: customFetchImplementation
130
});
131
```
132
133
### URL Scheme Support
134
135
Different URL schemes automatically select the appropriate client implementation:
136
137
- **`file:`** - Local SQLite files using Sqlite3Client
138
- **`http:`/`https:`** - HTTP connections using HttpClient
139
- **`ws:`/`wss:`** - WebSocket connections using WsClient
140
- **`libsql:`** - Auto-detection based on server capabilities (defaults to WebSocket with TLS)
141
142
### Embedded Replica Configuration
143
144
Special configuration for embedded replicas that provide offline capability:
145
146
```typescript
147
// Embedded replica configuration
148
const replicaConfig = {
149
url: "file:local.db", // Local SQLite file
150
syncUrl: "libsql://remote.db", // Remote database to sync with
151
authToken: "token", // Authentication for remote
152
syncInterval: 60000, // Auto-sync every 60 seconds
153
readYourWrites: true, // Ensure read consistency
154
offline: true // Allow offline operations
155
};
156
```
157
158
### Error Handling
159
160
Configuration errors are thrown as `LibsqlError` instances with specific error codes:
161
162
**Configuration Error Codes:**
163
- `URL_SCHEME_NOT_SUPPORTED` - Unsupported URL scheme (e.g., "ftp://")
164
- `URL_INVALID` - Malformed URL or invalid URL parameters
165
- `URL_PARAM_NOT_SUPPORTED` - Unsupported URL query parameter
166
- `ENCRYPTION_KEY_NOT_SUPPORTED` - Encryption not supported by client type
167
- `WEBSOCKETS_NOT_SUPPORTED` - WebSocket support not available in environment
168
169
**Runtime Error Codes:**
170
- `CLIENT_CLOSED` - Operation attempted on closed client
171
- `TRANSACTION_CLOSED` - Operation attempted on closed transaction
172
- `SYNC_NOT_SUPPORTED` - Sync operation not supported by client type
173
174
```typescript
175
import { createClient, LibsqlError } from "@libsql/client";
176
177
try {
178
const client = createClient({ url: "invalid://url" });
179
} catch (error) {
180
if (error instanceof LibsqlError) {
181
console.log(error.code); // "URL_SCHEME_NOT_SUPPORTED"
182
console.log(error.rawCode); // Numeric error code (when available)
183
}
184
}
185
```