@framers/sql-storage-adapter 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +363 -0
- package/dist/adapters/baseStorageAdapter.d.ts +204 -0
- package/dist/adapters/baseStorageAdapter.d.ts.map +1 -0
- package/dist/adapters/baseStorageAdapter.js +364 -0
- package/dist/adapters/baseStorageAdapter.js.map +1 -0
- package/dist/adapters/betterSqliteAdapter.d.ts +64 -0
- package/dist/adapters/betterSqliteAdapter.d.ts.map +1 -0
- package/dist/adapters/betterSqliteAdapter.js +206 -0
- package/dist/adapters/betterSqliteAdapter.js.map +1 -0
- package/dist/adapters/capacitorSqliteAdapter.d.ts +33 -0
- package/dist/adapters/capacitorSqliteAdapter.d.ts.map +1 -0
- package/dist/adapters/capacitorSqliteAdapter.js +95 -0
- package/dist/adapters/capacitorSqliteAdapter.js.map +1 -0
- package/dist/adapters/postgresAdapter.d.ts +180 -0
- package/dist/adapters/postgresAdapter.d.ts.map +1 -0
- package/dist/adapters/postgresAdapter.js +271 -0
- package/dist/adapters/postgresAdapter.js.map +1 -0
- package/dist/adapters/sqlJsAdapter.d.ts +28 -0
- package/dist/adapters/sqlJsAdapter.d.ts.map +1 -0
- package/dist/adapters/sqlJsAdapter.js +136 -0
- package/dist/adapters/sqlJsAdapter.js.map +1 -0
- package/dist/adapters/supabase.d.ts +58 -0
- package/dist/adapters/supabase.d.ts.map +1 -0
- package/dist/adapters/supabase.js +385 -0
- package/dist/adapters/supabase.js.map +1 -0
- package/dist/database.d.ts +124 -0
- package/dist/database.d.ts.map +1 -0
- package/dist/database.js +136 -0
- package/dist/database.js.map +1 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +25 -0
- package/dist/index.js.map +1 -0
- package/dist/resolver.d.ts +24 -0
- package/dist/resolver.d.ts.map +1 -0
- package/dist/resolver.js +91 -0
- package/dist/resolver.js.map +1 -0
- package/dist/types/context.d.ts +221 -0
- package/dist/types/context.d.ts.map +1 -0
- package/dist/types/context.js +9 -0
- package/dist/types/context.js.map +1 -0
- package/dist/types/events.d.ts +225 -0
- package/dist/types/events.d.ts.map +1 -0
- package/dist/types/events.js +8 -0
- package/dist/types/events.js.map +1 -0
- package/dist/types/extensions.d.ts +73 -0
- package/dist/types/extensions.d.ts.map +1 -0
- package/dist/types/extensions.js +7 -0
- package/dist/types/extensions.js.map +1 -0
- package/dist/types/limitations.d.ts +46 -0
- package/dist/types/limitations.d.ts.map +1 -0
- package/dist/types/limitations.js +154 -0
- package/dist/types/limitations.js.map +1 -0
- package/dist/types.d.ts +235 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +18 -0
- package/dist/types.js.map +1 -0
- package/dist/utils/cloudBackup.d.ts +219 -0
- package/dist/utils/cloudBackup.d.ts.map +1 -0
- package/dist/utils/cloudBackup.js +289 -0
- package/dist/utils/cloudBackup.js.map +1 -0
- package/dist/utils/dataExport.d.ts +77 -0
- package/dist/utils/dataExport.d.ts.map +1 -0
- package/dist/utils/dataExport.js +212 -0
- package/dist/utils/dataExport.js.map +1 -0
- package/dist/utils/dataImport.d.ts +54 -0
- package/dist/utils/dataImport.d.ts.map +1 -0
- package/dist/utils/dataImport.js +324 -0
- package/dist/utils/dataImport.js.map +1 -0
- package/dist/utils/migration.d.ts +89 -0
- package/dist/utils/migration.d.ts.map +1 -0
- package/dist/utils/migration.js +184 -0
- package/dist/utils/migration.js.map +1 -0
- package/dist/utils/parameterUtils.d.ts +9 -0
- package/dist/utils/parameterUtils.d.ts.map +1 -0
- package/dist/utils/parameterUtils.js +17 -0
- package/dist/utils/parameterUtils.js.map +1 -0
- package/dist/utils/syncManager.d.ts +342 -0
- package/dist/utils/syncManager.d.ts.map +1 -0
- package/dist/utils/syncManager.js +533 -0
- package/dist/utils/syncManager.js.map +1 -0
- package/package.json +108 -0
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @packageDocumentation
|
|
3
|
+
* Core type definitions for the SQL storage adapter abstraction.
|
|
4
|
+
*
|
|
5
|
+
* This package provides a unified interface for SQL storage across multiple platforms,
|
|
6
|
+
* with automatic fallback mechanisms and runtime detection.
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* Supported storage capability flags.
|
|
10
|
+
*
|
|
11
|
+
* These flags indicate what features are available for each adapter implementation.
|
|
12
|
+
* Consumers should check these capabilities before attempting operations that may
|
|
13
|
+
* not be universally supported.
|
|
14
|
+
*/
|
|
15
|
+
export type StorageCapability = 'sync' | 'transactions' | 'wal' | 'locks' | 'persistence' | 'streaming' | 'batch' | 'prepared' | 'concurrent' | 'json' | 'arrays';
|
|
16
|
+
/**
|
|
17
|
+
* Parameter payload accepted by storage statements.
|
|
18
|
+
*
|
|
19
|
+
* Parameters can be provided in multiple formats:
|
|
20
|
+
* - Named parameters: `{ name: 'John', age: 30 }` for statements like `WHERE name = @name`
|
|
21
|
+
* - Positional parameters: `['John', 30]` for statements like `WHERE name = ? AND age = ?`
|
|
22
|
+
* - No parameters: `undefined` or `null` for parameterless queries
|
|
23
|
+
*/
|
|
24
|
+
export type StorageParameters = undefined | null | Record<string, unknown> | Array<string | number | null | Uint8Array | unknown>;
|
|
25
|
+
/**
|
|
26
|
+
* Result metadata for mutation statements (INSERT, UPDATE, DELETE).
|
|
27
|
+
*/
|
|
28
|
+
export interface StorageRunResult {
|
|
29
|
+
/** Number of rows affected by the statement. */
|
|
30
|
+
changes: number;
|
|
31
|
+
/** Row identifier (if available) returned by the underlying engine. */
|
|
32
|
+
lastInsertRowid?: string | number | null;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Batch operation descriptor for bulk operations.
|
|
36
|
+
*/
|
|
37
|
+
export interface BatchOperation {
|
|
38
|
+
/** SQL statement to execute */
|
|
39
|
+
statement: string;
|
|
40
|
+
/** Parameters for this specific operation */
|
|
41
|
+
parameters?: StorageParameters;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Result of a batch operation execution.
|
|
45
|
+
*/
|
|
46
|
+
export interface BatchResult {
|
|
47
|
+
/** Number of successfully executed operations */
|
|
48
|
+
successful: number;
|
|
49
|
+
/** Number of failed operations */
|
|
50
|
+
failed: number;
|
|
51
|
+
/** Individual results for each operation (if adapter supports it) */
|
|
52
|
+
results?: StorageRunResult[];
|
|
53
|
+
/** Errors for failed operations (if any) */
|
|
54
|
+
errors?: Array<{
|
|
55
|
+
index: number;
|
|
56
|
+
error: Error;
|
|
57
|
+
}>;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Options accepted when opening a storage adapter.
|
|
61
|
+
*/
|
|
62
|
+
export interface StorageOpenOptions {
|
|
63
|
+
/** Absolute path to the primary database file (when applicable). */
|
|
64
|
+
filePath?: string;
|
|
65
|
+
/** Connection string (PostgreSQL, etc.). */
|
|
66
|
+
connectionString?: string;
|
|
67
|
+
/** Optional flag to force read-only mode. */
|
|
68
|
+
readOnly?: boolean;
|
|
69
|
+
/** Arbitrary adapter-specific options bag. */
|
|
70
|
+
adapterOptions?: Record<string, unknown>;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Core SQL storage adapter interface.
|
|
74
|
+
*
|
|
75
|
+
* Every adapter implementation must fulfill this contract to ensure
|
|
76
|
+
* compatibility across different SQL backends. Check the `capabilities`
|
|
77
|
+
* property to determine which optional features are supported.
|
|
78
|
+
*
|
|
79
|
+
* ## Error Handling
|
|
80
|
+
* All methods should throw meaningful errors when operations fail.
|
|
81
|
+
* Adapters should not silently fail or return undefined on errors.
|
|
82
|
+
*
|
|
83
|
+
* ## Thread Safety
|
|
84
|
+
* Adapters should document their thread-safety guarantees. SQLite adapters
|
|
85
|
+
* typically don't support concurrent writes, while PostgreSQL does.
|
|
86
|
+
*/
|
|
87
|
+
export interface StorageAdapter {
|
|
88
|
+
/** Identifier for logging/diagnostics (e.g., 'better-sqlite3', 'postgres'). */
|
|
89
|
+
readonly kind: string;
|
|
90
|
+
/** Capability flags indicating supported features. */
|
|
91
|
+
readonly capabilities: ReadonlySet<StorageCapability>;
|
|
92
|
+
/**
|
|
93
|
+
* Opens the underlying connection or initializes the backing store.
|
|
94
|
+
*
|
|
95
|
+
* @throws {Error} If connection cannot be established
|
|
96
|
+
* @example
|
|
97
|
+
* await adapter.open({ filePath: '/path/to/db.sqlite3' });
|
|
98
|
+
*/
|
|
99
|
+
open(options?: StorageOpenOptions): Promise<void>;
|
|
100
|
+
/**
|
|
101
|
+
* Executes a mutation statement (INSERT, UPDATE, DELETE).
|
|
102
|
+
*
|
|
103
|
+
* @param statement - SQL statement to execute
|
|
104
|
+
* @param parameters - Optional parameters for the statement
|
|
105
|
+
* @returns Metadata about affected rows
|
|
106
|
+
* @throws {Error} If statement execution fails
|
|
107
|
+
* @example
|
|
108
|
+
* const result = await adapter.run('INSERT INTO users (name) VALUES (?)', ['John']);
|
|
109
|
+
* console.log(`Inserted with ID: ${result.lastInsertRowid}`);
|
|
110
|
+
*/
|
|
111
|
+
run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
|
|
112
|
+
/**
|
|
113
|
+
* Retrieves a single row (or null if none found).
|
|
114
|
+
*
|
|
115
|
+
* @param statement - SQL SELECT statement
|
|
116
|
+
* @param parameters - Optional parameters for the statement
|
|
117
|
+
* @returns First row or null if no results
|
|
118
|
+
* @throws {Error} If query execution fails
|
|
119
|
+
* @example
|
|
120
|
+
* const user = await adapter.get<User>('SELECT * FROM users WHERE id = ?', [123]);
|
|
121
|
+
*/
|
|
122
|
+
get<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T | null>;
|
|
123
|
+
/**
|
|
124
|
+
* Retrieves all rows returned by the statement.
|
|
125
|
+
*
|
|
126
|
+
* WARNING: For large result sets, this loads everything into memory.
|
|
127
|
+
* Consider using streaming (if supported) for large queries.
|
|
128
|
+
*
|
|
129
|
+
* @param statement - SQL SELECT statement
|
|
130
|
+
* @param parameters - Optional parameters for the statement
|
|
131
|
+
* @returns Array of all matching rows (empty array if none)
|
|
132
|
+
* @throws {Error} If query execution fails
|
|
133
|
+
* @example
|
|
134
|
+
* const users = await adapter.all<User>('SELECT * FROM users WHERE age > ?', [18]);
|
|
135
|
+
*/
|
|
136
|
+
all<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T[]>;
|
|
137
|
+
/**
|
|
138
|
+
* Executes a script containing multiple SQL statements.
|
|
139
|
+
*
|
|
140
|
+
* Statements are typically delimited by semicolons. This is useful for
|
|
141
|
+
* running migrations or initialization scripts. No results are returned.
|
|
142
|
+
*
|
|
143
|
+
* @param script - SQL script with multiple statements
|
|
144
|
+
* @throws {Error} If any statement in the script fails
|
|
145
|
+
* @example
|
|
146
|
+
* await adapter.exec(`
|
|
147
|
+
* CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
|
|
148
|
+
* CREATE INDEX idx_users_name ON users(name);
|
|
149
|
+
* `);
|
|
150
|
+
*/
|
|
151
|
+
exec(script: string): Promise<void>;
|
|
152
|
+
/**
|
|
153
|
+
* Executes a callback within a database transaction.
|
|
154
|
+
*
|
|
155
|
+
* The transaction is automatically committed on success or rolled back
|
|
156
|
+
* on error. Nested transactions may not be supported by all adapters.
|
|
157
|
+
*
|
|
158
|
+
* @param fn - Async callback to execute within the transaction
|
|
159
|
+
* @returns Result of the callback function
|
|
160
|
+
* @throws {Error} Transaction is rolled back and error is re-thrown
|
|
161
|
+
* @example
|
|
162
|
+
* const result = await adapter.transaction(async (trx) => {
|
|
163
|
+
* await trx.run('INSERT INTO accounts (balance) VALUES (?)', [100]);
|
|
164
|
+
* await trx.run('INSERT INTO logs (action) VALUES (?)', ['account_created']);
|
|
165
|
+
* return { success: true };
|
|
166
|
+
* });
|
|
167
|
+
*/
|
|
168
|
+
transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
|
|
169
|
+
/**
|
|
170
|
+
* Closes the underlying connection and releases resources.
|
|
171
|
+
*
|
|
172
|
+
* After calling close(), the adapter should not be used again.
|
|
173
|
+
* Always close adapters when done to prevent resource leaks.
|
|
174
|
+
*
|
|
175
|
+
* @example
|
|
176
|
+
* try {
|
|
177
|
+
* await adapter.open();
|
|
178
|
+
* // ... use adapter ...
|
|
179
|
+
* } finally {
|
|
180
|
+
* await adapter.close();
|
|
181
|
+
* }
|
|
182
|
+
*/
|
|
183
|
+
close(): Promise<void>;
|
|
184
|
+
/**
|
|
185
|
+
* Executes multiple operations in a batch (if supported).
|
|
186
|
+
*
|
|
187
|
+
* This is more efficient than executing operations individually,
|
|
188
|
+
* especially for bulk inserts. Check if 'batch' capability is present.
|
|
189
|
+
*
|
|
190
|
+
* @param operations - Array of operations to execute
|
|
191
|
+
* @returns Batch execution results
|
|
192
|
+
* @throws {Error} If adapter doesn't support batch operations
|
|
193
|
+
* @example
|
|
194
|
+
* if (adapter.capabilities.has('batch')) {
|
|
195
|
+
* const result = await adapter.batch([
|
|
196
|
+
* { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Alice'] },
|
|
197
|
+
* { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Bob'] }
|
|
198
|
+
* ]);
|
|
199
|
+
* }
|
|
200
|
+
*/
|
|
201
|
+
batch?(operations: BatchOperation[]): Promise<BatchResult>;
|
|
202
|
+
/**
|
|
203
|
+
* Returns a prepared statement for repeated execution (if supported).
|
|
204
|
+
*
|
|
205
|
+
* Prepared statements improve performance for frequently executed queries
|
|
206
|
+
* and provide better protection against SQL injection. Check if 'prepared'
|
|
207
|
+
* capability is present.
|
|
208
|
+
*
|
|
209
|
+
* @param statement - SQL statement to prepare
|
|
210
|
+
* @returns Prepared statement handle
|
|
211
|
+
* @throws {Error} If adapter doesn't support prepared statements
|
|
212
|
+
*/
|
|
213
|
+
prepare?<T = unknown>(statement: string): PreparedStatement<T>;
|
|
214
|
+
}
|
|
215
|
+
/**
|
|
216
|
+
* Prepared statement interface for repeated query execution.
|
|
217
|
+
*/
|
|
218
|
+
export interface PreparedStatement<T = unknown> {
|
|
219
|
+
run(parameters?: StorageParameters): Promise<StorageRunResult>;
|
|
220
|
+
get(parameters?: StorageParameters): Promise<T | null>;
|
|
221
|
+
all(parameters?: StorageParameters): Promise<T[]>;
|
|
222
|
+
finalize(): Promise<void>;
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* Shape of adapter factories returned by resolver modules.
|
|
226
|
+
*/
|
|
227
|
+
export type StorageAdapterFactory = () => Promise<StorageAdapter>;
|
|
228
|
+
/**
|
|
229
|
+
* Error thrown when no adapter can be resolved.
|
|
230
|
+
*/
|
|
231
|
+
export declare class StorageResolutionError extends Error {
|
|
232
|
+
readonly causes: unknown[];
|
|
233
|
+
constructor(message: string, causes?: unknown[]);
|
|
234
|
+
}
|
|
235
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @packageDocumentation
|
|
3
|
+
* Core type definitions for the SQL storage adapter abstraction.
|
|
4
|
+
*
|
|
5
|
+
* This package provides a unified interface for SQL storage across multiple platforms,
|
|
6
|
+
* with automatic fallback mechanisms and runtime detection.
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* Error thrown when no adapter can be resolved.
|
|
10
|
+
*/
|
|
11
|
+
export class StorageResolutionError extends Error {
|
|
12
|
+
constructor(message, causes = []) {
|
|
13
|
+
super(message);
|
|
14
|
+
this.causes = causes;
|
|
15
|
+
this.name = 'StorageResolutionError';
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
//# sourceMappingURL=types.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6PH;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe,EAAW,SAAoB,EAAE;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QADqB,WAAM,GAAN,MAAM,CAAgB;QAE1D,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF"}
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cloud backup utilities for S3, R2, and other object storage providers.
|
|
3
|
+
*
|
|
4
|
+
* This module provides automatic scheduled backups and restore functionality
|
|
5
|
+
* for SQL databases using S3-compatible storage (AWS S3, Cloudflare R2, MinIO, etc.).
|
|
6
|
+
*
|
|
7
|
+
* Features:
|
|
8
|
+
* - Automatic scheduled backups with configurable intervals
|
|
9
|
+
* - Gzip compression to reduce storage costs
|
|
10
|
+
* - Retention policies (automatic cleanup of old backups)
|
|
11
|
+
* - JSON and SQL export formats
|
|
12
|
+
* - Manual backup/restore on demand
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```typescript
|
|
16
|
+
* import { S3Client } from '@aws-sdk/client-s3';
|
|
17
|
+
* import { createCloudBackupManager } from '@framers/sql-storage-adapter';
|
|
18
|
+
*
|
|
19
|
+
* const s3Client = new S3Client({ region: 'us-east-1' });
|
|
20
|
+
* const manager = createCloudBackupManager(db, s3Client, 'my-backups', {
|
|
21
|
+
* interval: 3600000, // 1 hour
|
|
22
|
+
* maxBackups: 24,
|
|
23
|
+
* options: { compression: 'gzip', format: 'json' }
|
|
24
|
+
* });
|
|
25
|
+
*
|
|
26
|
+
* manager.start(); // Auto-schedule backups
|
|
27
|
+
* await manager.backupNow(); // Manual backup
|
|
28
|
+
* await manager.restore('backups/db-2024-01-15.json.gz');
|
|
29
|
+
* ```
|
|
30
|
+
*
|
|
31
|
+
* @module cloudBackup
|
|
32
|
+
*/
|
|
33
|
+
import type { StorageAdapter } from '../types';
|
|
34
|
+
/** Supported backup export formats */
|
|
35
|
+
export type BackupFormat = 'json' | 'sql';
|
|
36
|
+
/** Supported compression algorithms */
|
|
37
|
+
export type CompressionType = 'gzip' | 'none';
|
|
38
|
+
/**
|
|
39
|
+
* Generic interface for cloud storage providers.
|
|
40
|
+
*
|
|
41
|
+
* Implement this interface to support custom storage backends
|
|
42
|
+
* beyond S3-compatible services.
|
|
43
|
+
*/
|
|
44
|
+
export interface CloudStorageProvider {
|
|
45
|
+
/**
|
|
46
|
+
* Upload data to cloud storage
|
|
47
|
+
* @param key - The storage key/path for the backup
|
|
48
|
+
* @param data - The backup data (string or Buffer)
|
|
49
|
+
*/
|
|
50
|
+
upload(key: string, data: string | Buffer): Promise<void>;
|
|
51
|
+
/**
|
|
52
|
+
* Download data from cloud storage
|
|
53
|
+
* @param key - The storage key/path to download
|
|
54
|
+
* @returns The backup data
|
|
55
|
+
*/
|
|
56
|
+
download(key: string): Promise<string | Buffer>;
|
|
57
|
+
/**
|
|
58
|
+
* List available backups in cloud storage
|
|
59
|
+
* @param prefix - Optional prefix to filter backups
|
|
60
|
+
* @returns Array of backup keys
|
|
61
|
+
*/
|
|
62
|
+
list(prefix?: string): Promise<string[]>;
|
|
63
|
+
/**
|
|
64
|
+
* Delete a backup from cloud storage
|
|
65
|
+
* @param key - The storage key/path to delete
|
|
66
|
+
*/
|
|
67
|
+
delete(key: string): Promise<void>;
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Configuration options for backup creation
|
|
71
|
+
*/
|
|
72
|
+
export interface BackupOptions {
|
|
73
|
+
/** Backup format (json or sql) - default: 'json' */
|
|
74
|
+
format?: BackupFormat;
|
|
75
|
+
/** Compression type - default: 'gzip' */
|
|
76
|
+
compression?: CompressionType;
|
|
77
|
+
/** Tables to include (undefined = all tables) */
|
|
78
|
+
tables?: string[];
|
|
79
|
+
/** Prefix for backup keys - default: 'backups/' */
|
|
80
|
+
prefix?: string;
|
|
81
|
+
/** Include timestamp in backup key - default: true */
|
|
82
|
+
includeTimestamp?: boolean;
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Configuration for automatic scheduled backups
|
|
86
|
+
*/
|
|
87
|
+
export interface ScheduledBackupConfig {
|
|
88
|
+
/** Backup interval in milliseconds (e.g., 3600000 = 1 hour) */
|
|
89
|
+
interval: number;
|
|
90
|
+
/** Maximum number of backups to keep (older backups auto-deleted) */
|
|
91
|
+
maxBackups?: number;
|
|
92
|
+
/** Backup creation options */
|
|
93
|
+
options?: BackupOptions;
|
|
94
|
+
/** Callback invoked on successful backup */
|
|
95
|
+
onSuccess?: (key: string) => void;
|
|
96
|
+
/** Callback invoked on backup error */
|
|
97
|
+
onError?: (error: Error) => void;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* S3-compatible cloud storage provider.
|
|
101
|
+
*
|
|
102
|
+
* Works with AWS S3, Cloudflare R2, MinIO, and other S3-compatible services.
|
|
103
|
+
* Uses the AWS SDK v3 for S3 operations.
|
|
104
|
+
*
|
|
105
|
+
* @example
|
|
106
|
+
* ```typescript
|
|
107
|
+
* import { S3Client } from '@aws-sdk/client-s3';
|
|
108
|
+
*
|
|
109
|
+
* const s3Client = new S3Client({ region: 'us-east-1' });
|
|
110
|
+
* const provider = new S3StorageProvider(s3Client, 'my-bucket');
|
|
111
|
+
*
|
|
112
|
+
* await provider.upload('backups/test.json', JSON.stringify(data));
|
|
113
|
+
* const backups = await provider.list('backups/');
|
|
114
|
+
* ```
|
|
115
|
+
*/
|
|
116
|
+
export declare class S3StorageProvider implements CloudStorageProvider {
|
|
117
|
+
private client;
|
|
118
|
+
private bucket;
|
|
119
|
+
/**
|
|
120
|
+
* @param client - AWS SDK S3Client instance
|
|
121
|
+
* @param bucket - S3 bucket name
|
|
122
|
+
*/
|
|
123
|
+
constructor(client: {
|
|
124
|
+
send: (command: unknown) => Promise<unknown>;
|
|
125
|
+
}, bucket: string);
|
|
126
|
+
upload(key: string, data: string | Buffer): Promise<void>;
|
|
127
|
+
download(key: string): Promise<string>;
|
|
128
|
+
list(prefix?: string): Promise<string[]>;
|
|
129
|
+
delete(key: string): Promise<void>;
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* Cloud backup manager for automatic scheduled backups.
|
|
133
|
+
*/
|
|
134
|
+
export declare class CloudBackupManager {
|
|
135
|
+
private adapter;
|
|
136
|
+
private storage;
|
|
137
|
+
private config;
|
|
138
|
+
private intervalId?;
|
|
139
|
+
constructor(adapter: StorageAdapter, storage: CloudStorageProvider, config: ScheduledBackupConfig);
|
|
140
|
+
/**
|
|
141
|
+
* Create a backup and upload to cloud storage.
|
|
142
|
+
*/
|
|
143
|
+
backup(options?: BackupOptions): Promise<string>;
|
|
144
|
+
/**
|
|
145
|
+
* Restore from a cloud backup.
|
|
146
|
+
*/
|
|
147
|
+
restore(key: string): Promise<void>;
|
|
148
|
+
/**
|
|
149
|
+
* List all backups in cloud storage.
|
|
150
|
+
*/
|
|
151
|
+
listBackups(prefix?: string): Promise<string[]>;
|
|
152
|
+
/**
|
|
153
|
+
* Delete old backups exceeding maxBackups limit.
|
|
154
|
+
*/
|
|
155
|
+
private cleanupOldBackups;
|
|
156
|
+
/**
|
|
157
|
+
* Start automatic scheduled backups.
|
|
158
|
+
*/
|
|
159
|
+
start(): void;
|
|
160
|
+
/**
|
|
161
|
+
* Stop automatic scheduled backups.
|
|
162
|
+
*/
|
|
163
|
+
stop(): void;
|
|
164
|
+
/**
|
|
165
|
+
* Perform a backup immediately (manual trigger).
|
|
166
|
+
*/
|
|
167
|
+
backupNow(options?: BackupOptions): Promise<string>;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Create a cloud backup manager with S3-compatible storage.
|
|
171
|
+
*
|
|
172
|
+
* This is the main factory function for setting up cloud backups.
|
|
173
|
+
* It creates an S3StorageProvider and CloudBackupManager configured
|
|
174
|
+
* with your database and S3-compatible storage.
|
|
175
|
+
*
|
|
176
|
+
* @param adapter - The StorageAdapter instance to backup
|
|
177
|
+
* @param s3Client - AWS SDK S3Client (works with S3, R2, MinIO, etc.)
|
|
178
|
+
* @param bucket - The S3 bucket name
|
|
179
|
+
* @param config - Scheduled backup configuration
|
|
180
|
+
* @returns CloudBackupManager instance ready to start
|
|
181
|
+
*
|
|
182
|
+
* @example AWS S3
|
|
183
|
+
* ```typescript
|
|
184
|
+
* import { S3Client } from '@aws-sdk/client-s3';
|
|
185
|
+
* import { createCloudBackupManager } from '@framers/sql-storage-adapter';
|
|
186
|
+
*
|
|
187
|
+
* const s3 = new S3Client({ region: 'us-east-1' });
|
|
188
|
+
* const manager = createCloudBackupManager(db, s3, 'my-bucket', {
|
|
189
|
+
* interval: 60 * 60 * 1000, // 1 hour
|
|
190
|
+
* maxBackups: 24,
|
|
191
|
+
* options: { compression: 'gzip' }
|
|
192
|
+
* });
|
|
193
|
+
*
|
|
194
|
+
* manager.start();
|
|
195
|
+
* ```
|
|
196
|
+
*
|
|
197
|
+
* @example Cloudflare R2
|
|
198
|
+
* ```typescript
|
|
199
|
+
* import { S3Client } from '@aws-sdk/client-s3';
|
|
200
|
+
*
|
|
201
|
+
* const r2 = new S3Client({
|
|
202
|
+
* region: 'auto',
|
|
203
|
+
* endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
|
|
204
|
+
* credentials: {
|
|
205
|
+
* accessKeyId: process.env.R2_ACCESS_KEY_ID,
|
|
206
|
+
* secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
|
|
207
|
+
* },
|
|
208
|
+
* });
|
|
209
|
+
*
|
|
210
|
+
* const manager = createCloudBackupManager(db, r2, 'backups', {
|
|
211
|
+
* interval: 24 * 60 * 60 * 1000, // Daily
|
|
212
|
+
* maxBackups: 7
|
|
213
|
+
* });
|
|
214
|
+
* ```
|
|
215
|
+
*/
|
|
216
|
+
export declare function createCloudBackupManager(adapter: StorageAdapter, s3Client: {
|
|
217
|
+
send: (command: unknown) => Promise<unknown>;
|
|
218
|
+
}, bucket: string, config: ScheduledBackupConfig): CloudBackupManager;
|
|
219
|
+
//# sourceMappingURL=cloudBackup.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cloudBackup.d.ts","sourceRoot":"","sources":["../../src/utils/cloudBackup.ts"],"names":[],"mappings":"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"}
|